Extend documentation

README.rst

@@ -266,161 +266,193 @@ Fields
 Functions
 ^^^^^^^^^
 
-:: 
+alpha
+  ``%alpha{text}``:  This function first ASCIIfies the given text, then all
+  non alphabet characters are replaced with whitespaces.
+
+  **Example:** ``%alpha{a1b23c}`` → ``a b c``
+
+alphanum
+  ``%alphanum{text}``:  This function first ASCIIfies the given text, then all
+  non alpanumeric characters are replaced with whitespaces.
+
+  **Example:** ``%alphanum{après-évêque1}`` → ``apres eveque1``
+
+asciify
+  ``%asciify{text}``:  Translate non-ASCII characters to their ASCII
+  equivalents. For example, “café” becomes “cafe”. Uses the mapping provided
+  by the unidecode module.
+
+  **Example:** ``%asciify{äÄöÖüÜ}`` → ``aeAeoeOeueUe``
+
+delchars
+  ``%delchars{text,chars}``:  Delete every single character of “chars“ in
+  “text”.
+
+  **Example:** ``%delchars{Schubert, ue}`` → ``Schbrt``
 
-    alpha
-        -----
+deldupchars
+  ``%deldupchars{text,chars}``:  Search for duplicate characters and replace
+  with only one occurrance of this characters.
 
-        %alpha{text}
-            This function first ASCIIfies the given text, then all non alphabet
-            characters are replaced with whitespaces.
+  **Example:** ``%deldupchars{a---b___c...d}`` → ``a-b_c.d``; ``%deldupchars{a
+  ---b___c, -}`` → ``a-b___c``
 
-        alphanum
-        --------
+first
+  ``%first{text}`` or ``%first{text,count,skip}`` or
+  ``%first{text,count,skip,sep,join}``:  Returns the first item, separated by
+  ``;``. You can use ``%first{text,count,skip}``, where count is the number of
+  items (default 1) and skip is number to skip (default 0). You can also use
+  ``%first{text,count,skip,sep,join}`` where ``sep`` is the separator, like
+  ``;`` or ``/`` and join is the text to concatenate the items.
 
-        %alphanum{text}
-            This function first ASCIIfies the given text, then all non alpanumeric
-            characters are replaced with whitespaces.
+  **Example:** ``%first{Alice / Bob / Eve,2,0, / , & }`` → ``Alice & Bob``
 
-        asciify
-        -------
+if
+  ``%if{condition,trueval}`` or ``%if{condition,trueval,falseval}``:  If
+  condition is nonempty (or nonzero, if it’s a number), then returns the
+  second argument. Otherwise, returns the third argument if specified (or
+  nothing if ``falseval`` is left off).
 
-        %asciify{text}
-            Translate non-ASCII characters to their ASCII equivalents. For
-            example, “café” becomes “cafe”. Uses the mapping provided by the
-            unidecode module.
+  **Example:** ``x%if{false,foo}`` → ``x``
 
-        delchars
-        --------
+ifdef
+  ``%ifdef{field}``, ``%ifdef{field,trueval}`` or
+  ``%ifdef{field,trueval,falseval}``:  If field exists, then return
+  ``trueval`` or field (default). Otherwise, returns ``falseval``. The field
+  should be entered without ``$``.
 
-        %delchars{text,chars}
-            Delete every single character of “chars“ in “text”.
+  **Example:** ``%ifdef{compilation,Compilation}``
 
-        deldupchars
-        -----------
+ifdefempty
+  ``%ifdefempty{field,text}`` or ``%ifdefempty{field,text,falsetext}``:  If
+  field exists and is empty, then return ``truetext``. Otherwise, returns
+  ``falsetext``. The field should be entered without ``$``.
 
-        %deldupchars{text,chars}
-            Search for duplicate characters and replace with only one occurrance
-            of this characters.
+  **Example:** ``%ifdefempty{compilation,Album,Compilation}``
 
-        first
-        -----
+ifdefnotempty
+  ``%ifdefnotempty{field,text}`` or ``%ifdefnotempty{field,text,falsetext}``:
+  If field is not empty, then return ``truetext``. Otherwise, returns
+  ``falsetext``. The field should be entered without ``$``.
 
-        %first{text} or %first{text,count,skip} or
-        %first{text,count,skip,sep,join}
-            Returns the first item, separated by ; . You can use
-            %first{text,count,skip}, where count is the number of items (default
-            1) and skip is number to skip (default 0). You can also use
-            %first{text,count,skip,sep,join} where sep is the separator, like ; or
-            / and join is the text to concatenate the items.
+  **Example:** ``%ifdefnotempty{compilation,Compilation,Album}``
 
-        if
-        --
+initial
+  ``%initial{text}``:  Get the first character of a text in lowercase. The
+  text is converted to ASCII. All non word characters are erased.
 
-        %if{condition,truetext} or %if{condition,truetext,falsetext}
-            If condition is nonempty (or nonzero, if it’s a number), then returns
-            the second argument. Otherwise, returns the third argument if
-            specified (or nothing if falsetext is left off).
+  **Example:** ``%initial{Schubert}`` → ``s``
 
-        ifdef
-        -----
+left
+  ``%left{text,n}``:  Return the first “n” characters of “text”.
 
-        %ifdef{field}, %ifdef{field,text} or %ifdef{field,text,falsetext}
-            If field exists, then return truetext or field (default). Otherwise,
-            returns falsetext. The field should be entered without $.
+  **Example:** ``%left{Schubert, 3}`` → ``Sch``
 
-        ifdefempty
-        ----------
+lower
+  ``%lower{text}``:  Convert “text” to lowercase.
 
-        %ifdefempty{field,text} or %ifdefempty{field,text,falsetext}
-            If field exists and is empty, then return truetext. Otherwise, returns
-            falsetext. The field should be entered without $.
+  **Example:** ``%lower{SCHUBERT}`` → ``schubert``
 
-        ifdefnotempty
-        -------------
+nowhitespace
+  ``%nowhitespace{text,replace}``:  Replace all whitespace characters with
+  ``replace``. By default: a dash (``-``)
 
-        %ifdefnotempty{field,text} or %ifdefnotempty{field,text,falsetext}
-            If field is not empty, then return truetext. Otherwise, returns
-            falsetext. The field should be entered without $.
+  **Example:** ``%nowhitespace{a b}`` → ``a-b``; ``%nowhitespace{a b, _}`` →
+  ``a_b``
 
-        initial
-        -------
+num
+  ``%num{number,count}``:  Pad decimal number with leading zeros.
 
-        %initial{text}
-            Get the first character of a text in lowercase. The text is converted
-            to ASCII. All non word characters are erased.
+  **Example:** ``%num{7,3}`` → ``007``
 
-        left
-        ----
+replchars
+  ``%replchars{text,chars,replace}``:  Replace the characters “chars” in
+  “text” with “replace”.
 
-        %left{text,n}
-            Return the first “n” characters of “text”.
+  **Example:** ``%replchars{Schubert,-,ue}`` → ``Sch-b-rt``
 
-        lower
-        -----
+right
+  ``%right{text,n}``:  Return the last “n” characters of “text”.
 
-        %lower{text}
-            Convert “text” to lowercase.
+  **Example:** ``%right{Schubert,3}`` → ``ert``
 
-        nowhitespace
-        ------------
+sanitize
+  ``%sanitize{text}``:  Delete characters that are not allowed in most file
+  systems.
 
-        %nowhitespace{text,replace}
-            Replace all whitespace characters with replace. By default: a dash (-)
-            %nowhitespace{$track,_}
+  **Example:** ``%sanitize{x:*?<>|/~&x}`` → ``xx``
 
-        num
-        ---
+shorten
+  ``%shorten{text}`` or ``%shorten{text,max_size}``:  Shorten “text” on word
+  boundarys.
 
-        %num{number,count}
-            Pad decimal number with leading zeros.
-            %num{$track,3}
+  **Example:** ``%shorten{Lorem ipsum dolor sit, 10}`` → ``Lorem``
 
-        replchars
-        ---------
+time
+  ``%time{date_time,format,curformat}``:  Return the date and time in any
+  format accepted by ``strftime``. For example, to get the year, use
+  ``%time{$added,%Y}``.
 
-        %replchars{text,chars,replace}
-            Replace the characters “chars” in “text” with “replace”.
-            %replchars{text,ex,-} > t--t
+  **Example:** ``%time{30 Nov 2024,%Y,%d %b %Y}`` → ``2024``
 
-        right
-        -----
+title
+  ``%title{text}``:  Convert “text” to Title Case.
 
-        %right{text,n}
-            Return the last “n” characters of “text”.
+  **Example:** ``%title{franz schubert}`` → ``Franz Schubert``
 
-        sanitize
-        --------
+upper
+  ``%upper{text}``:  Convert “text” to UPPERCASE.
 
-        %sanitize{text}
-            Delete in most file systems not allowed characters.
+  **Example:** ``%upper{foo}`` → ``FOO``
 
-        shorten
-        -------
+Template Symbols (or Variables)
+  In path templates, symbols or varialbes such as ``$title``
+  (any name with the prefix ``$``) are replaced by the corresponding value.
 
-        %shorten{text} or %shorten{text,max_size}
-            Shorten “text” on word boundarys.
-            %shorten{$title,32}
+  Because ``$`` is used to delineate a field reference, you can use ``$$`` to emit
+  a dollars sign. As with `Python template strings`_, ``${title}`` is equivalent
+  to ``$title``; you can use this if you need to separate a field name from the
+  text that follows it.
 
-        time
-        ----
+.. _Python template strings: https://docs.python.org/library/string.html#template-strings
 
-        %time{date_time,format,curformat}
-            Return the date and time in any format accepted by strftime. For
-            example, to get the year some music was added to your library, use
-            %time{$added,%Y}.
+Template Functions (or Macros)
+  Path templates also support *function calls*, which can be used to transform
+  text and perform logical manipulations. The syntax for function calls is like
+  this: ``%func{arg,arg}``. For example, the ``upper`` function makes its argument
+  upper-case, so ``%upper{lorem ipsum}`` will be replaced with ``LOREM IPSUM``.
+  You can, of course, nest function calls and place variable references in
+  function arguments, so ``%upper{$title}`` becomes the upper-case version of the
+  title.
 
-        title
-        -----
+Syntax Details
+  The characters ``$``, ``%``, ``{``, ``}``, and ``,`` are “special” in the path
+  template syntax. This means that, for example, if you want a ``%`` character to
+  appear in your paths, you’ll need to be careful that you don’t accidentally
+  write a function call. To escape any of these characters (except ``{``, and
+  ``,`` outside a function argument), prefix it with a ``$``.  For example,
+  ``$$`` becomes ``$``; ``$%`` becomes ``%``, etc. The only exceptions are:
 
-        %title{text}
-            Convert “text” to Title Case.
+  * ``${``, which is ambiguous with the variable reference syntax (like
+    ``${title}``). To insert a ``{`` alone, it's always sufficient to just type
+    ``{``.
+  * commas are used as argument separators in function calls. Inside of a
+    function’s argument, use ``$,`` to get a literal ``,`` character. Outside of
+    any function argument, escaping is not necessary: ``,`` by itself will
+    produce ``,`` in the output.
 
-        upper
-        -----
+  If a value or function is undefined, the syntax is simply left unreplaced. For
+  example, if you write ``$foo`` in a path template, this will yield ``$foo`` in
+  the resulting paths because "foo" is not a valid field name. The same is true of
+  syntax errors like unclosed ``{}`` pairs; if you ever see template syntax
+  constructs leaking into your paths, check your template for errors.
 
-        %upper{text}
-            Convert “text” to UPPERCASE.
+  If an error occurs in the Python code that implements a function, the function
+  call will be expanded to a string that describes the exception so you can debug
+  your template. For example, the second parameter to ``%left`` must be an
+  integer; if you write ``%left{foo,bar}``, this will be expanded to something
+  like ``<ValueError: invalid literal for int()>``.
 
 The following example assumes that the folder ``/home/xyz/messy-leadsheets``
 contains the following three MuseScore files: ``folsom prison blues.mscz``,

README_template.rst

@@ -231,7 +231,9 @@ Fields
 Functions
 ^^^^^^^^^
 
-{{ cli('musescore-manager --list-functions') | literal }}
+{{ cli('tmep-doc --functions-rst') }}
+
+{{ cli('tmep-doc --introduction-rst') }}
 
 The following example assumes that the folder ``/home/xyz/messy-leadsheets``
 contains the following three MuseScore files: ``folsom prison blues.mscz``,