markup.scm: Improve documentation.

diff --git a/scm/markup.scm b/scm/markup.scm
index 9adb50a2bbeff6187bb2e64f0f8e88a36ac414a5..dd0fc84893c0cdc7f897ee93a8d3009e5eadaa7d 100644 (file)
--- a/scm/markup.scm
+++ b/scm/markup.scm
@@ -73,7 +73,6 @@ register COMMAND-markup and its signature,
 Syntax:
   (define-markup-command (COMMAND layout props . arguments)
                                  argument-types
-                                 [ #:category category ]
                                  [ #:properties properties ]
     \"documentation string\"
     ...command body...)
@@ -84,14 +83,29 @@ Syntax:
                                  function)
 
 where:
-  argument-types is a list of type predicates for arguments
-  category is either a symbol or a symbol list
-  properties a list of (property default-value) lists or COMMANDx-markup elements
-    (when a COMMANDx-markup is found, the properties of the said commandx are
-    added instead). No check is performed against cyclical references!
-
-  The specified properties are available as let-bound variables in the
-  command body.
+  `argument-types' is a list of type predicates for arguments
+  `properties' a list of (property default-value) lists
+
+The specified properties are available as let-bound variables in the
+command body, using the respective `default-value' as fallback in case
+`property' is not found in `props'.  `props' itself is left unchanged:
+if you want defaults specified in that manner passed down into other
+markup functions, you need to adjust `props' yourself.
+
+The autogenerated documentation makes use of some optional
+specifications that are otherwise ignored:
+
+After `argument-types', you may also specify
+                                 [ #:category category ]
+where:
+  `category' is either a symbol or a symbol list specifying the
+             category for this markup command in the docs.
+
+As an element of the `properties' list, you may directly use a
+COMMANDx-markup symbol instead of a `(prop value)' list to indicate
+that this markup command is called by the newly defined command,
+adding its properties to the documented properties of the new
+command.  There is no protection against circular definitions.
 "
   (let* ((command (if (pair? command-and-args) (car command-and-args) command-and-args))
          (args (if (pair? command-and-args) (cdr command-and-args) '()))
@@ -155,8 +169,8 @@ where:
 
 (defmacro*-public define-markup-list-command
   (command-and-args signature #:key (properties '()) #:rest body)
-  "Same as `define-markup-command, but defines a command that, when
-interpreted, returns a list of stencils instead os a single one"
+  "Same as `define-markup-command', but defines a command that, when
+interpreted, returns a list of stencils instead of a single one"
   (let* ((command (if (pair? command-and-args) (car command-and-args) command-and-args))
          (args (if (pair? command-and-args) (cdr command-and-args) '()))
          (command-name (string->symbol (format #f "~a-markup-list" command)))