doc

HACKING.md

@@ -42,9 +42,10 @@ Testing from the command line
 Catching changes in behaviour
 -----------------------------
 
-Some bugs not caught by the test suite may show up in the diffs of the
-generated documentation. Check out PAX World in the top-level
-directory, where the ASDF files are with
+Some bugs not caught by the test suite may be caught by transcription
+consistency checking or show up in the diffs of the generated
+documentation. Check out PAX World in the top-level directory, where
+the ASDF files are with
 
     git clone https://github.com/melisgl/mgl-pax-world.git world/
 

README

@@ -18,7 +18,8 @@ PAX provides for this is DEFSECTION:
   (@foo-random-examples section))
 ```
 
-Like this one, sections can have docstrings and references to
+Like this one, sections can have docstrings and
+references to
 definitions (e.g. `(UNIFORM-RANDOM FUNCTION)`). These docstrings and
 references are the glue. To support interactive development, PAX
 
@@ -42,42 +43,38 @@ code, not vice versa, and there is no support for chunking.
 
 PAX automatically recognizes and marks up code with
 backticks and links code to their definitions.
-The following @TRANSCRIPTS show the lines of the output (prefixed
-with `..`) generated:
+Take, for instance, SBCL's ABORT function, whose docstring is
+written in the usual style, uppercasing names of symbols:
 
 ```
-(document "&KEY arguments such as :IF-EXISTS are common." :format :markdown)
-.. `&KEY` arguments such as `:IF-EXISTS` are common.
-
-(document "AND denotes a macro and a type specifier.
-Here we focus on the macro AND." :format :markdown)
-.. `AND`([`0`][4954] [`1`][330f]) denotes a macro and a type specifier.
-.. Here we focus on the macro [`AND`][4954].
-..
-..   [330f]: http://www.lispworks.com/documentation/HyperSpec/Body/t_and.htm "AND TYPE"
-..   [4954]: http://www.lispworks.com/documentation/HyperSpec/Body/m_and.htm "AND MGL-PAX:MACRO"
+(docstring #'abort)
+=> "Transfer control to a restart named ABORT, signalling a CONTROL-ERROR if
+   none exists."
 ```
 
-These features are designed to handle the most common style of
-docstrings with minimal additional markup. The following is the
-output of `(mgl-pax:document #'abort :format :markdown)`.
-
-    - \[function\] **\ABORT** *\&OPTIONAL \CONDITION*
-
-        Transfer control to a restart named `ABORT`, signalling a
-        [`\CONTROL-ERROR`][6bc0] if none exists.
-
-      [6bc0]: http://www.lispworks.com/documentation/HyperSpec/Body/e_contro.htm "\CONTROL-ERROR \CONDITION"
-
-Note that the docstring of the ABORT function was not written with
-PAX in mind. The above markdown is rendered as
+Note how in the generated documentation, ABORT is set with a
+monospace font, while `CONTROL-ERROR` is autolinked:
 
 - \[function\] **ABORT** *\&OPTIONAL CONDITION*
 
     Transfer control to a restart named `ABORT`, signalling a
-    \[`CONTROL-ERROR`\]\[6bc0\] if none exists.
+    [`CONTROL-ERROR`][6bc0] if none exists.
+
+[6bc0]: http://www.lispworks.com/documentation/HyperSpec/Body/e_contro.htm "CONTROL-ERROR CONDITION"
 
-[6bc0]: http://www.lispworks.com/documentation/HyperSpec/Body/e_contro.htm "\\CONTROL-ERROR \\CONDITION"
+In the following transcript, the above output is
+rendered from the raw markdown:
+
+```
+(document #'abort :format :markdown)
+.. - [function] **ABORT** *&OPTIONAL CONDITION*
+..
+..     Transfer control to a restart named `ABORT`, signalling a [`CONTROL-ERROR`][7c2c] if
+..     none exists.
+..
+..   [7c2c]: http://www.lispworks.com/documentation/HyperSpec/Body/e_contro.htm "CONTROL-ERROR (MGL-PAX:CLHS CONDITION)"
+..
+```
 
 ##### A Complete Example
 
@@ -383,6 +380,25 @@ Now let's examine the most important pieces.
     The bottom line is that if you rely on DEFSECTION to do the
     exporting, then you'd better use DEFINE-PACKAGE.
 
+- [macro] DEFINE-GLOSSARY-TERM NAME (&KEY TITLE URL (DISCARD-DOCUMENTATION-P \*DISCARD-DOCUMENTATION-P\*)) &OPTIONAL DOCSTRING
+
+    Define a global variable with NAME, and set it to a GLOSSARY-TERM object. TITLE, URL and DOCSTRING are markdown strings or
+    NIL. Glossary terms are DOCUMENTed in the lightweight bullet +
+    locative + name/title style. See the glossary entry @NAME for an
+    example.
+
+    When a glossary term is linked to in documentation, its TITLE will
+    be the link text instead of the name of the symbol (as with
+    SECTIONs).
+
+    Glossary entries with a non-NIL URL are like external links: they
+    are linked to their URL in the generated documentation. These offer
+    a more reliable alternative to using markdown reference links and
+    are usually not included in SECTIONs.
+
+    When DISCARD-DOCUMENTATION-P (defaults to *DISCARD-DOCUMENTATION-P*)
+    is true, DOCSTRING will not be recorded to save memory.
+
 ### Parsing
 
 When @NAVIGATING-IN-EMACS or @GENERATING-DOCUMENTATION, references
@@ -469,25 +485,6 @@ To the DREF::@LOCATIVE-TYPES defined by DRef, PAX adds a few of its own.
     GLOSSARY-TERM is EXPORTABLE-LOCATIVE-TYPE-P but not exported by
     default (see EXPORTABLE-REFERENCE-P).
 
-- [macro] DEFINE-GLOSSARY-TERM NAME (&KEY TITLE URL (DISCARD-DOCUMENTATION-P \*DISCARD-DOCUMENTATION-P\*)) &OPTIONAL DOCSTRING
-
-    Define a global variable with NAME, and set it to a GLOSSARY-TERM object. TITLE, URL and DOCSTRING are markdown strings or
-    NIL. Glossary terms are DOCUMENTed in the lightweight bullet +
-    locative + name/title style. See the glossary entry @NAME for an
-    example.
-
-    When a glossary term is linked to in documentation, its TITLE will
-    be the link text instead of the name of the symbol (as with
-    SECTIONs).
-
-    Glossary entries with a non-NIL URL are like external links: they
-    are linked to their URL in the generated documentation. These offer
-    a more reliable alternative to using markdown reference links and
-    are usually not included in SECTIONs.
-
-    When DISCARD-DOCUMENTATION-P (defaults to *DISCARD-DOCUMENTATION-P*)
-    is true, DOCSTRING will not be recorded to save memory.
-
 - [locative] DISLOCATED
 
     Refers to a symbol in a non-specific context. Useful for preventing
@@ -1048,9 +1045,8 @@ links, is generated from docstrings of all kinds
 of Lisp definitions and PAX SECTIONs.
 
 If @EMACS-SETUP has been done, the Elisp function `mgl-pax-document`
-displays documentation as a single HTML page generated by PAX via
-Slime. For example, to view the documentation of this very SECTION,
-one can do:
+generates and displays documentation as a single HTML page. For
+example, to view the documentation of this very SECTION, one can do:
 
     M-x mgl-pax-document
     View Documentation of: pax::@browsing-live-documentation
@@ -1060,16 +1056,18 @@ or w3m is not used, then sections registered in @PAX-WORLD are
 listed. If there is a w3m buffer, then entering the empty string
 displays that buffer.
 
-If we enter `function` instead, then a [disambiguation
-page](pax:function) (note that this and other `pax:` links only work
-in Emacs) will be shown with the documentation of the FUNCTION class
-and the FUNCTION locative. One may then follow the links on the page
-to navigate to a page with the documentation the desired definition.
+If we enter `function` instead, then a disambiguation page will be
+shown with the documentation of the FUNCTION class and the FUNCTION
+locative. One may then follow the links on the page to navigate to a
+page with the documentation the desired definition. If you are
+browsing live documentation right now, then the disambiguation page
+is like this: FUNCTION. In offline documentation, multiple links
+are shown instead as described in @AMBIGUOUS-UNSPECIFIED-LOCATIVE.
 
 Alternatively, a DREF::@LOCATIVE may be entered as part of the
 argument to `mgl-pax-document` as in `function class`, which gives
-[this result](pax:function%20class). Finally, the definition of
-DEFSECTION in the context of a single-page @PAX-MANUAL can be
+this result. Finally, the definition of DEFSECTION
+in the context of a single-page @PAX-MANUAL can be
 [viewed](pax:pax::@pax-manual#pax:defsection%20pax:macro) by
 entering `pax::@pax-manual#pax:defsection pax:macro`.
 
@@ -1471,16 +1469,18 @@ To override the title:
 
 These examples all render as SECTION, linking to both
 definitions of the @NAME `SECTION`, the `CLASS` and the
-`LOCATIVE`.
+`LOCATIVE`. Note that the rendered output is a single link to a
+disambiguation page when @BROWSING-LIVE-DOCUMENTATION, while
+multiple, numbered links are generated in offline documentation.
 
 - `[SECTION][]` (*name, explicit link*)
 
 - `SECTION` (*name, autolink*)
 
 To override the title:
 
-- `[see this][section]` (*title + name, explicit link*) renders
-  as: see this.
+- `[see this][section]` (*title + name, explicit link*) renders as:
+  see this.
 
 
 #### Explicit and Autolinking
@@ -2412,9 +2412,8 @@ Transcription support in Emacs can be enabled by loading
     EVAL is printed to a string and compared to the source value. Hence,
     any change to unreadable values will break consistency checks. This
     is most troublesome with instances of classes with the default
-    PRINT-OBJECT method printing the memory address. See @ no remedy for
-    that, except for customizing PRINT-OBJECT or not transcribing that
-    kind of stuff.
+    PRINT-OBJECT method printing the memory address. See
+    @TRANSCRIPT-FINER-GRAINED-CONSISTENCY-CHECKS.
 
     **Errors**
 
@@ -2779,9 +2778,9 @@ export the symbols `A` and `AN`.
 
 ### Extending DOCUMENT
 
-For all definitions that it encounters, DOCUMENT calls DOCUMENT\*
-to generate documentation. The following utilities are for writing
-new DOCUMENT-OBJECT\* methods, which emit markdown.
+For all definitions that it encounters, DOCUMENT calls
+DOCUMENT-OBJECT\* to generate documentation. The following utilities
+are for writing new DOCUMENT-OBJECT\* methods, which emit markdown.
 
 - [variable] *FORMAT*
 
@@ -2840,11 +2839,11 @@ new DOCUMENT-OBJECT\* methods, which emit markdown.
 
     Backslash escape markdown constructs in STRING.
 
-    - If ESCPAPE-INLINE, then escape ``*_`[]\`` characters.
+    - If ESCAPE-INLINE, then escape ``*_`[]\`` characters.
 
-    - If ESCPAPE-HTML, then escape `<&` characters.
+    - If ESCAPE-HTML, then escape `<&` characters.
 
-    - If ESCPAPE-BLOCK, then escape whatever is necessary to avoid
+    - If ESCAPE-BLOCK, then escape whatever is necessary to avoid
       starting a new markdown block (e.g. a paragraph, heading, etc).