diff --git a/HACKING.md b/HACKING.md
index 1f8aad5d..262d7191 100644
--- a/HACKING.md
+++ b/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/
diff --git a/README b/README
index 9ae65170..472abb6d 100644
--- a/README
+++ b/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,7 +1469,9 @@ 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*)
@@ -1479,8 +1479,8 @@ definitions of the @NAME `SECTION`, the `CLASS` and the
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).
diff --git a/README.md b/README.md
index 63f3dfb7..884dc0c9 100644
--- a/README.md
+++ b/README.md
@@ -86,7 +86,8 @@ PAX provides for this is [`DEFSECTION`][72b4]:
(@foo-random-examples section))
```
-Like this one, sections can have docstrings and references to
+Like this one, sections can have docstrings and
+[references][5225] to
definitions (e.g. `(UNIFORM-RANDOM FUNCTION)`). These docstrings and
references are the glue. To support interactive development, PAX
@@ -110,42 +111,38 @@ code, not vice versa, and there is no support for chunking.
PAX automatically recognizes and [marks up code][f1ab] with
backticks and [links code][1865] to their definitions.
-The following [Transcripts][6300] show the lines of the output (prefixed
-with `..`) generated:
+Take, for instance, SBCL's [`ABORT`][479a] 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)`.
+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.
-
- [6bc0]: http://www.lispworks.com/documentation/HyperSpec/Body/e_contro.htm "\CONTROL-ERROR \CONDITION"
+- \[function\] **ABORT** *\&OPTIONAL CONDITION*
-Note that the docstring of the [`ABORT`][479a] function was not written with
-PAX in mind. The above markdown is rendered as
+ Transfer control to a restart named `ABORT`, signalling a
+ [`CONTROL-ERROR`][6bc0] if none exists.
-- \[function\] **ABORT** *[`&OPTIONAL`][4336] CONDITION*
+[6bc0]: http://www.lispworks.com/documentation/HyperSpec/Body/e_contro.htm "CONTROL-ERROR CONDITION"
- Transfer control to a restart named `ABORT`, signalling a
- \[`CONTROL-ERROR`\]\[6bc0\] if none exists.
+In the following [transcript][6300], the above output is
+rendered from the raw markdown:
-[6bc0]: http://www.lispworks.com/documentation/HyperSpec/Body/e_contro.htm "\\CONTROL-ERROR \\CONDITION"
+```
+(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
@@ -471,6 +468,27 @@ 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`][8251] object. `TITLE`, `URL` and `DOCSTRING` are markdown strings or
+ `NIL`. Glossary terms are [`DOCUMENT`][432c]ed in the lightweight bullet +
+ locative + name/title style. See the glossary entry [name][88cf] 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
+ [`SECTION`][5fac]s).
+
+ 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 `SECTION`s.
+
+ When `DISCARD-DOCUMENTATION-P` (defaults to [`*DISCARD-DOCUMENTATION-P*`][730f])
+ is true, `DOCSTRING` will not be recorded to save memory.
+
### 5.1 Parsing
@@ -569,27 +587,6 @@ To the [Locative Types][bf0f] defined by DRef, PAX adds a few of its own.
`GLOSSARY-TERM` is [`EXPORTABLE-LOCATIVE-TYPE-P`][c930] but not exported by
default (see [`EXPORTABLE-REFERENCE-P`][e51f]).
-
-
-- [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`][8251] object. `TITLE`, `URL` and `DOCSTRING` are markdown strings or
- `NIL`. Glossary terms are [`DOCUMENT`][432c]ed in the lightweight bullet +
- locative + name/title style. See the glossary entry [name][88cf] 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
- [`SECTION`][5fac]s).
-
- 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 `SECTION`s.
-
- When `DISCARD-DOCUMENTATION-P` (defaults to [`*DISCARD-DOCUMENTATION-P*`][730f])
- is true, `DOCSTRING` will not be recorded to save memory.
-
- [locative] **DISLOCATED**
@@ -1188,9 +1185,8 @@ browser. HTML documentation, complete with [Codification][f1ab] and
of Lisp definitions and PAX [`SECTION`][5fac]s.
If [Emacs Setup][8541] 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
@@ -1200,16 +1196,18 @@ or w3m is not used, then sections registered in [PAX World][1281] 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`][119e] class
-and the [`FUNCTION`][ba62] 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`][119e] class and the [`FUNCTION`][ba62]
+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`([`0`][119e] [`1`][81f7]). In offline documentation, multiple links
+are shown instead as described in [Ambiguous Unspecified Locative][2f82].
Alternatively, a [locative][7ac8] 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`][72b4] in the context of a single-page [PAX Manual][2415] can be
+[this result][119e]. Finally, the definition of [`DEFSECTION`][72b4]
+in the context of a single-page [PAX Manual][2415] can be
[viewed](pax:pax::@pax-manual#pax:defsection%20pax:macro) by
entering `pax::@pax-manual#pax:defsection pax:macro`.
@@ -1651,7 +1649,9 @@ To override the title:
These examples all render as [`SECTION`][5fac], linking to both
definitions of the [name][88cf] `SECTION`, the `CLASS` and the
-`LOCATIVE`.
+`LOCATIVE`. Note that the rendered output is a single link to a
+disambiguation page when [Browsing Live Documentation][a595], while
+multiple, numbered links are generated in offline documentation.
- `[SECTION][]` (*name, explicit link*)
@@ -1659,8 +1659,8 @@ definitions of the [name][88cf] `SECTION`, the `CLASS` and the
To override the title:
-- `[see this][section]` (*title + name, explicit link*) renders
- as: [see this][5fac].
+- `[see this][section]` (*title + name, explicit link*) renders as:
+ [see this][5fac].
@@ -2682,9 +2682,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`][3f2e] method printing the memory address. See @ no remedy for
- that, except for customizing `PRINT-OBJECT` or not transcribing that
- kind of stuff.
+ [`PRINT-OBJECT`][3f2e] method printing the memory address. See
+ [Finer-Grained Consistency Checks][6e18].
**Errors**
@@ -3089,9 +3088,9 @@ export the symbols `A` and `AN`.
### 10.3 Extending `DOCUMENT`
-For all definitions that it encounters, [`DOCUMENT`][432c] calls DOCUMENT\*
-to generate documentation. The following utilities are for writing
-new [`DOCUMENT-OBJECT*`][8269] methods, which emit markdown.
+For all definitions that it encounters, [`DOCUMENT`][432c] calls
+[`DOCUMENT-OBJECT*`][8269] to generate documentation. The following utilities
+are for writing new `DOCUMENT-OBJECT*` methods, which emit markdown.
@@ -3162,11 +3161,11 @@ new [`DOCUMENT-OBJECT*`][8269] 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).
@@ -3306,6 +3305,7 @@ they are presented.
[2ca9]: #x-28MGL-PAX-3AOUTPUT-REFLINK-20FUNCTION-29 "MGL-PAX:OUTPUT-REFLINK FUNCTION"
[2d48]: #x-28MGL-PAX-3AWITH-DISLOCATED-NAMES-20MGL-PAX-3AMACRO-29 "MGL-PAX:WITH-DISLOCATED-NAMES MGL-PAX:MACRO"
[2e45]: #x-28MGL-PAX-3A-40DOCUMENTABLES-20MGL-PAX-3ASECTION-29 "Documentables"
+ [2f82]: #x-28MGL-PAX-3A-40AMBIGUOUS-UNSPECIFIED-LOCATIVE-20MGL-PAX-3ASECTION-29 "Ambiguous Unspecified Locative"
[3026]: #x-28MGL-PAX-3AESCAPE-MARKDOWN-20FUNCTION-29 "MGL-PAX:ESCAPE-MARKDOWN FUNCTION"
[3076]: https://github.com/redline6561/colorize/ "Colorize"
[32da]: dref/README.md#x-28DREF-3ASOURCE-LOCATION-20FUNCTION-29 "DREF:SOURCE-LOCATION FUNCTION"
@@ -3324,7 +3324,6 @@ they are presented.
[4143]: http://www.lispworks.com/documentation/HyperSpec/Body/f_stgeq_.htm "STRING= (MGL-PAX:CLHS FUNCTION)"
[4317]: http://www.lispworks.com/documentation/HyperSpec/Body/f_cerror.htm "CERROR (MGL-PAX:CLHS FUNCTION)"
[432c]: #x-28MGL-PAX-3ADOCUMENT-20FUNCTION-29 "MGL-PAX:DOCUMENT FUNCTION"
- [4336]: http://www.lispworks.com/documentation/HyperSpec/Body/03_da.htm '"3.4.1" (MGL-PAX:CLHS MGL-PAX:SECTION)'
[43bd]: dref/README.md#x-28DREF-3A-40REFERENCE-20MGL-PAX-3AGLOSSARY-TERM-29 "reference"
[443b]: http://www.lispworks.com/documentation/HyperSpec/Body/v_pr_cas.htm "*PRINT-CASE* (MGL-PAX:CLHS VARIABLE)"
[4796]: dref/README.md#x-28LAMBDA-20MGL-PAX-3ALOCATIVE-29 "LAMBDA MGL-PAX:LOCATIVE"
diff --git a/TODO.org b/TODO.org
index 18a5bdb1..17dc30ee 100644
--- a/TODO.org
+++ b/TODO.org
@@ -19,7 +19,6 @@ link. See EXTERNAL-LOCATIVE-P and co.
* MAYBE remove some markup in :PLAIN format?
* MAYBE get variable initforms from source?
Or fall back on this for deficient ARGLISTs. Will be really slow.
-* MAYBE document glossary-term class and slots?
* MAYBE add format control character locative?
* MAYBE add loop keyword locative?
* MAYBE move towards literate programming
@@ -88,7 +87,7 @@ Package apropos could take advantage?
* compare DRef to the Definitions library
Pros of DRef:
- Supports string names (called designators in Definitions). PAX needs
- to distuinguish those from symbol-based ones.
+ to distinguish those from symbol-based ones.
- Operations such as ARGLIST (~ DEFINITIONS:ARGUMENTS) can be
specialized on normal objects for RESOLVEable definitions. In
Definitions, operations are always specialized on a DEFINITION
@@ -118,3 +117,6 @@ Pros of Definitions:
These can be added to DRef if needed.
* BUG transcript: "debugger invoked on" is treated like output
* MAYBE DREF-APROPOS: allow :LOCATIVE-TYPES to match subclasses?
+* MAYBE generate offline documentation for everything in quicklisp?
+Like https://quickref.common-lisp.net/index-per-library.html, but more
+useful?
diff --git a/dref/README b/dref/README
index 237979c5..38e7f5cf 100644
--- a/dref/README
+++ b/dref/README
@@ -1312,7 +1312,7 @@ the details, see the Elisp function `slime-goto-source-location`.
Make a Swank source location. The ultimate reference is `slime.el`.
When SNIPPET is provided, the match nearest to FILE-POSITION is
determined (see the Elisp `slime-isearch` and
- SOURCE-LOCATION-FILE-POSITION-OFFSET).
+ SOURCE-LOCATION-ADJUSTED-FILE-POSITION).
- [function] SOURCE-LOCATION-P OBJECT
diff --git a/dref/README.md b/dref/README.md
index d93a81a2..0f2b65dd 100644
--- a/dref/README.md
+++ b/dref/README.md
@@ -1586,7 +1586,7 @@ the details, see the Elisp function `slime-goto-source-location`.
Make a Swank source location. The ultimate reference is `slime.el`.
When `SNIPPET` is provided, the match nearest to `FILE-POSITION` is
determined (see the Elisp `slime-isearch` and
- SOURCE-LOCATION-FILE-POSITION-OFFSET).
+ [`SOURCE-LOCATION-ADJUSTED-FILE-POSITION`][daac]).
@@ -1800,6 +1800,7 @@ the details, see the Elisp function `slime-goto-source-location`.
[d83a]: #x-28SETF-20MGL-PAX-3ALOCATIVE-29 "SETF MGL-PAX:LOCATIVE"
[d930]: #x-28DREF-3ADREF-20CLASS-29 "DREF:DREF CLASS"
[da93]: #x-28DREF-3A-40DREF-LOCATIVES-20MGL-PAX-3ASECTION-29 "DRef Locatives"
+ [daac]: #x-28DREF-EXT-3ASOURCE-LOCATION-ADJUSTED-FILE-POSITION-20FUNCTION-29 "DREF-EXT:SOURCE-LOCATION-ADJUSTED-FILE-POSITION FUNCTION"
[dae6]: http://www.lispworks.com/documentation/HyperSpec/Body/f_string.htm "STRING (MGL-PAX:CLHS FUNCTION)"
[db03]: http://www.lispworks.com/documentation/HyperSpec/Body/f_eql.htm "EQL (MGL-PAX:CLHS FUNCTION)"
[db68]: http://www.lispworks.com/documentation/HyperSpec/Body/f_pkg_na.htm "PACKAGE-NAME (MGL-PAX:CLHS FUNCTION)"
diff --git a/dref/src/full/source-location.lisp b/dref/src/full/source-location.lisp
index 344ab27f..f2ac3946 100644
--- a/dref/src/full/source-location.lisp
+++ b/dref/src/full/source-location.lisp
@@ -7,7 +7,7 @@
"Make a Swank source location. The ultimate reference is `slime.el`.
When SNIPPET is provided, the match nearest to FILE-POSITION is
determined (see the Elisp `slime-isearch` and
- SOURCE-LOCATION-FILE-POSITION-OFFSET)."
+ SOURCE-LOCATION-ADJUSTED-FILE-POSITION)."
(list :location
(cond ((and file buffer)
(list :buffer-and-file buffer (namestring file)))
diff --git a/src/base/document-early.lisp b/src/base/document-early.lisp
index 305e635c..4834fbc1 100644
--- a/src/base/document-early.lisp
+++ b/src/base/document-early.lisp
@@ -85,9 +85,9 @@
(defsection @extending-document (:title "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."
(*format* variable)
(with-heading macro)
(documenting-reference macro)
diff --git a/src/base/locatives-early.lisp b/src/base/locatives-early.lisp
index 5a3d485e..104261d4 100644
--- a/src/base/locatives-early.lisp
+++ b/src/base/locatives-early.lisp
@@ -5,7 +5,6 @@
(defsection @pax-locatives (:title "PAX Locatives")
(section locative)
(glossary-term locative)
- (define-glossary-term macro)
(dislocated locative)
(argument locative)
(include locative)
diff --git a/src/base/pax.lisp b/src/base/pax.lisp
index c01e4065..b800e17a 100644
--- a/src/base/pax.lisp
+++ b/src/base/pax.lisp
@@ -86,7 +86,8 @@
(@foo-random-examples section))
```
- Like this one, sections can have docstrings and references to
+ Like this one, sections can have docstrings and
+ [references][dref::@dref-manual] to
definitions (e.g. `(UNIFORM-RANDOM FUNCTION)`). These docstrings and
references are the glue. To support interactive development, PAX
@@ -110,42 +111,38 @@
PAX automatically recognizes and [marks up code][@codification] with
backticks and [links code][@linking-to-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*
+ Note how in the generated documentation, ABORT is set with a
+ monospace font, while `\CONTROL-ERROR` is autolinked:
- Transfer control to a restart named `ABORT`, signalling a
- [`\CONTROL-ERROR`][6bc0] if none exists.
+ - \[function\] **\ABORT** *\\&OPTIONAL \CONDITION*
- [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
+ Transfer control to a restart named `ABORT`, signalling a
+ [`\CONTROL-ERROR`][6bc0] if none exists.
- - \[function\] **\ABORT** *\&OPTIONAL \CONDITION*
+ [6bc0]: http://www.lispworks.com/documentation/HyperSpec/Body/e_contro.htm "CONTROL-ERROR CONDITION"
- Transfer control to a restart named `ABORT`, signalling a
- \[`\CONTROL-ERROR`\]\[6bc0\] if none exists.
+ In the following [transcript][@transcripts], the above output is
+ rendered from the raw markdown:
- [6bc0]: http://www.lispworks.com/documentation/HyperSpec/Body/e_contro.htm "\CONTROL-ERROR \CONDITION"
+ ```
+ (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
@@ -322,4 +319,5 @@
(defsection macro)
(*discard-documentation-p* variable)
(define-package macro)
+ (define-glossary-term macro)
(@parsing section))
diff --git a/src/document/browse.lisp b/src/document/browse.lisp
index 6bffdabf..a97b748e 100644
--- a/src/document/browse.lisp
+++ b/src/document/browse.lisp
@@ -9,9 +9,8 @@
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
@@ -21,16 +20,18 @@
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][function class]. 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`.
diff --git a/src/document/document.lisp b/src/document/document.lisp
index c77cfc29..95ef343e 100644
--- a/src/document/document.lisp
+++ b/src/document/document.lisp
@@ -1980,15 +1980,17 @@
(:title "Ambiguous Unspecified Locative")
"""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][section].""")
+ - `\[see this][section]` (*title + name, explicit link*) renders as:
+ [see this][section].""")
(defsection @explicit-and-autolinking (:title "Explicit and Autolinking")
"The examples in the previous sections are marked with *explicit
diff --git a/src/document/markdown.lisp b/src/document/markdown.lisp
index f76666af..95409f72 100644
--- a/src/document/markdown.lisp
+++ b/src/document/markdown.lisp
@@ -78,11 +78,11 @@
(escape-html t) (escape-block t))
"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)."
(flet ((blank-line-until-p (pos)
(loop for i downfrom (1- pos) downto 0
diff --git a/src/navigate/locatives.lisp b/src/navigate/locatives.lisp
index def198c9..973b0287 100644
--- a/src/navigate/locatives.lisp
+++ b/src/navigate/locatives.lisp
@@ -6,7 +6,6 @@
"To the DREF::@LOCATIVE-TYPES defined by DRef, PAX adds a few of its own."
(section locative)
(glossary-term locative)
- (define-glossary-term macro)
(dislocated locative)
(argument locative)
(include locative)
diff --git a/src/transcribe/transcribe.lisp b/src/transcribe/transcribe.lisp
index 2946f71e..04a5f699 100644
--- a/src/transcribe/transcribe.lisp
+++ b/src/transcribe/transcribe.lisp
@@ -382,9 +382,8 @@
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**