From: tilly-Q <nattilypigeonfowl@gmail.com>
Date: Mon, 12 May 2014 21:02:12 +0000 (-0400)
Subject: Added documentation for the batchaddmedia gmg tool to the mediagoblin docs.
X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=8524a6bdc575312b35df6e6aa3118ed139303d72;p=mediagoblin.git

Added documentation for the batchaddmedia gmg tool to the mediagoblin docs.
---

diff --git a/docs/source/siteadmin/commandline-upload.rst b/docs/source/siteadmin/commandline-upload.rst
index be19df58..d67c19dd 100644
--- a/docs/source/siteadmin/commandline-upload.rst
+++ b/docs/source/siteadmin/commandline-upload.rst
@@ -39,3 +39,54 @@ You can also pass in the `--celery` option if you would prefer that
 your media be passed over to celery to be processed rather than be
 processed immediately.
 
+============================
+Command-line batch uploading
+============================
+
+There's another way to submit media, and it can be much more powerful, although
+it is a bit more complex.
+
+  ./bin/gmg batchaddmedia admin /path/to/your/metadata.csv
+
+This is an example of what a script may look like. The important part here is
+that you have to create the 'metadata.csv' file.::
+
+  media:location,dcterms:title,dcterms:creator,dcterms:type
+  "http://www.example.net/path/to/nap.png","Goblin taking a nap",,"Image"
+  "http://www.example.net/path/to/snore.ogg","Goblin Snoring","Me","Audio"
+
+The above is an example of a very simple metadata.csv file. The batchaddmedia
+script would read this and attempt to upload only two pieces of media, and would
+be able to automatically name them appropriately.
+
+The csv file
+============
+The media:location column
+-------------------------
+The media:location column is the one column that is absolutely necessary for 
+uploading your media. This gives a path to each piece of media you upload. This
+can either a path to a local file or a direct link to remote media (with the 
+link in http format). As you can see in the example above the (fake) media was
+stored remotely on "www.example.net".
+
+Other columns
+-------------
+Other columns can be used to provide detailed metadata about each media entry.
+Our metadata system accepts any information provided for in the 
+`RDFa Core Initial Context`_, and the batchupload script recognizes all of the
+resources provided within it.
+
+.. _RDFa Core Initial Context: http://www.w3.org/2011/rdfa-context/rdfa-1.1
+
+The uploader may include the metadata for each piece of media, or
+leave them blank if they want to. A few columns from `Dublin Core`_ are
+notable because the batchaddmedia script uses them to set the default
+information of uploaded media entries.
+
+.. _Dublin Core: http://wiki.dublincore.org/index.php/User_Guide
+
+- **dc:title** sets a title for your media entry. If this is left blank, the media entry will be named according to the filename of the file being uploaded.
+- **dc:description** sets a description of your media entry. If this is left blank the media entry's description will not be filled in.
+- **dc:rights** will set a license for your media entry `if` the data provided is a valid URI. If this is left blank 'All Rights Reserved' will be selected.
+
+You can of course, change these values later. 
diff --git a/mediagoblin/gmg_commands/batchaddmedia.py b/mediagoblin/gmg_commands/batchaddmedia.py
index 7ba8db1e..75e7b7c5 100644
--- a/mediagoblin/gmg_commands/batchaddmedia.py
+++ b/mediagoblin/gmg_commands/batchaddmedia.py
@@ -32,15 +32,21 @@ from jsonschema.exceptions import ValidationError
 def parser_setup(subparser):
     subparser.description = """\
 This command allows the administrator to upload many media files at once."""
+    subparser.epilog = _(u"""For more information about how to properly run this
+script (and how to format the metadata csv file), read the MediaGoblin
+documentation page on command line uploading 
+<http://docs.mediagoblin.org/siteadmin/commandline-upload.html>""")
     subparser.add_argument(
         'username',
-        help="Name of user these media entries belong to")
+        help=_(u"Name of user these media entries belong to"))
     subparser.add_argument(
-        'metadata_path')
+        'metadata_path',
+        help=_(
+u"""Path to the csv file containing metadata information."""))
     subparser.add_argument(
         '--celery',
         action='store_true',
-        help="Don't process eagerly, pass off to celery")
+        help=_(u"Don't process eagerly, pass off to celery"))
 
 
 def batchaddmedia(args):