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**