Update AUTHORS.txt, CHANGES.txt and docs according to #2320

AUTHORS.txt

@@ -15,6 +15,7 @@
 * `Casey M. Bessette <https://github.com/caseybessette>`_
 * `Chris Lee <https://github.com/clee>`_
 * `Chris Warrick <https://github.com/Kwpolska>`_
+* `Christopher Arndt <https:/github.com/SpotlightKid>`_
 * `Claudio Canepa <https://github.com/ccanepa>`_
 * `Damien Tournoud <https://github.com/damz>`_
 * `Damián Avila <https://github.com/damianavila>`_

CHANGES.txt

@@ -4,6 +4,8 @@ New in master
 Features
 --------
 
+* Template-based shortcodes now receive positional arguments too (Issue #2319)
+
 Bugfixes
 --------
 

docs/extending.txt

@@ -560,38 +560,76 @@ Some (hopefully all) markup compilers support shortcodes in these forms::
     {{% foo %}}  # No arguments
     {{% foo bar %}}  # One argument, containing "bar"
     {{% foo bar baz=bat %}}  # Two arguments, one containing "bar", one called "baz" containing "bat"
-
-    {{% foo %}}Some text{{% /foo %}} # one argument called "data" containing "Some text"
-
-So, if you are creating a plugin that generates markup, it may be a good idea to register it as a shortcode
-in addition of a restructured text directive or markdown extension, thus making it available to all markups.
-
-To implement your own shortcodes from a plugin, you can call ``Nikola.register_shortcode(name, f)`` with the following
-arguments:
-
-name:
-    name of the shortcode (foo in the examples above)
-f:
+
+    {{% foo %}}Some text{{% /foo %}}  # one argument called "data" containing "Some text"
+
+So, if you are creating a plugin that generates markup, it may be a good idea
+to register it as a shortcode in addition of to restructured text directive or
+markdown extension, thus making it available to all markup formats.
+
+To implement your own shortcodes from a plugin, you can call
+``Nikola.register_shortcode(name, func)`` with the following arguments:
+
+``name``:
+    Name of the shortcode ("foo" in the examples above)
+``func``:
     A function that will handle the shortcode
-
-The shortcode handler should take *at least* the following named arguments:
 
-site:
+The shortcode handler **must** accept the following named arguments (or
+variable keyword arguments):
+
+``site``:
     An instance of the Nikola class, to access site state
-
-data:
-    If the shortcut is used as opening/closing tags, it will be the text between them, otherwise None
-
-If the shortcode tag has arguments of the form "foo=bar" they will be passed as named arguments. Everything else
-will be passed as positional arguments in the function call.
+
+``data``:
+    If the shortcut is used as opening/closing tags, it will be the text
+    between them, otherwise ``None``.
+
+If the shortcode tag has arguments of the form ``foo=bar`` they will be
+passed as named arguments. Everything else will be passed as positional
+arguments in the function call.
 
 So, for example::
 
-    {{% foo bar baz=bat beep %}}Some text{{% /foo %}}
-
-Will cause a call like this::
+    {{% raw %}}{{% foo bar baz=bat beep %}}Some text{{% /foo %}}{{% /raw %}}
+
+Assuming you registered ``foo_handler`` as the handler function for the
+shortcode named ``foo``, this will result in the following call when the above
+shortcode is encountered::
+
+    foo_handler("bar", "beep", baz="bat", data="Some text", site=whatever)
+
+Template-based Shortcodes
+-------------------------
+
+Another way to define a new shortcode is to add a template file to the
+``shortcodes`` directory of your site. The template file must have the
+shortcode name as the basename and the extension ``.tmpl``. For example, if you
+want to add a new shortcode named ``foo``, create the template file as
+``shortcodes/foo.tmpl``.
+
+When the shortcode is encountered, the matching template will be rendered with
+its context provided by the arguments given in the shortcode. Keyword arguments
+are passed directly, i.e. the key becomes the variable name in the template
+namespace with a matching string value. Non-keyword arguments are passed as
+string values in a tuple named ``_args``. As for normal shortcodes with a
+handler function, ``site`` and ``data`` will be added to the keyword arguments.
+
+Example:
+
+The following shortcode::
+
+    {{% raw %}}{{% foo bar="baz" spam %}}{{% /raw %}}
+
+With a template in ``shortcodes/foo.tmpl`` with this content (using Jinja2
+syntax in this example)::
+
+    <div class="{{ _args[0] if _args else 'ham' }}">{{ bar }}</div>
+
+Will result in this output::
+
+    <div class="spam">baz</div>
 
-     foo_handler("bar", "beep", baz="bat", data="Some text", site=whatever)
 
 State and Cache
 ===============
@@ -601,7 +639,7 @@ Sometimes your plugins will need to cache things to speed up further actions. He
 * If it's a file, put it somewhere in ```self.site.config['CACHE_FOLDER']``` (defaults to ```cache/```.
 * If it's a value, use ```self.site.cache.set(key, value)``` to set it and ```self.site.cache.get(key)``` to get it.
   The key should be a string, the value should be json-encodable (so, be careful with datetime objects)
-  
+
 The values and files you store there can **and will** be deleted sometimes by the user. They should always be
 things you can reconstruct without lossage. They are throwaways.
 

docs/manual.txt

@@ -854,12 +854,16 @@ chart
 Template-based shortcodes
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you put a template in ``shortcodes/`` called ``mycode.tmpl`` then Nikola will create a shortcode
-called ``mycode`` you can use. Any options you pass to the shortcode will be available as variables
-for that template. If you use the shortcode as paired, then the contents between the paired tags will
-be available in the ``data`` variable.
+If you put a template in ``shortcodes/`` called ``mycode.tmpl`` then Nikola
+will create a shortcode called ``mycode`` you can use. Any options you pass to
+the shortcode will be available as variables for that template. Non-keyword
+options will be passed in a tuple varaible named ``_args``.
 
-If you want to access the Nikola object, it will be available as ``site``. Use with care :-)
+If you use the shortcode as paired, then the contents between the paired tags
+will be available in the ``data`` variable. If you want to access the Nikola
+object, it will be available as ``site``. Use with care :-)
+
+See :doc:`extending` for detailed information.
 
 For example, if your ``shortcodes/foo.tmpl`` contains this::
 
@@ -873,6 +877,8 @@ Then the output file will contain::
 
     This uses the bar variable: bla
 
+
+
 Redirections
 ------------