diff --git a/README.md b/README.md index 4f1de31..5c14100 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ - + # PAX Manual ## Table of Contents @@ -66,7 +66,7 @@ - [10.5 Glossary Terms][d1dc] ###### \[in package MGL-PAX with nicknames PAX\] - + ## 1 Introduction *What if documentation really lived in the code?* @@ -225,7 +225,7 @@ The [transcript][6300] in the code block tagged with `cl-transcript` is automatically checked for up-to-dateness when documentation is generated. - + ## 2 Emacs Setup Load `src/mgl-pax.el` in Emacs, and maybe set up some key bindings. @@ -258,12 +258,12 @@ functions, a [HUNCHENTOOT][1d5a] web server is started. See [Navigating Sources in Emacs][3386], [Generating Documentation][2c93] and [Transcribing with Emacs][f5bd] for how to use the relevant features. - + - [function] **INSTALL-PAX-ELISP** *TARGET-DIR* Copy `mgl-pax.el` distributed with this package to `TARGET-DIR`. - + ## 3 Links and Systems Here is the [official @@ -276,7 +276,7 @@ library][5225] (bundled in the same repository). See [DRef's HTML documentation](http://melisgl.github.io/mgl-pax-world/dref-manual.html) - + ### 3.1 The mgl-pax ASDF System - Version: 0.2.4 @@ -296,7 +296,7 @@ documentation](http://melisgl.github.io/mgl-pax-world/dref-manual.html) - Bug tracker: [https://github.com/melisgl/mgl-pax/issues](https://github.com/melisgl/mgl-pax/issues) - Source control: [GIT](https://github.com/melisgl/mgl-pax.git) - + ### 3.2 The mgl-pax/full ASDF System - Description: MGL-PAX with all features preloaded except MGL-PAX/WEB. @@ -307,7 +307,7 @@ documentation](http://melisgl.github.io/mgl-pax-world/dref-manual.html) - Mailto: [mega@retes.hu](mailto:mega@retes.hu) - + ## 4 Background As a user, I frequently run into documentation that's incomplete @@ -376,12 +376,12 @@ few thousand lines later PAX was born. Since then, locatives and references were factored out into the [DRef][5225] library to let PAX focus on `M-.` and documentation. - + ## 5 Basics Now let's examine the most important pieces. - + - [macro] **DEFSECTION** *NAME (&KEY (PACKAGE '\*PACKAGE\*) (READTABLE '\*READTABLE\*) (EXPORT T) TITLE LINK-TITLE-TO (DISCARD-DOCUMENTATION-P \*DISCARD-DOCUMENTATION-P\*)) &BODY ENTRIES* Define a documentation section and maybe export referenced symbols. @@ -434,14 +434,14 @@ Now let's examine the most important pieces. When `DISCARD-DOCUMENTATION-P` (defaults to [`*DISCARD-DOCUMENTATION-P*`][730f]) is true, `ENTRIES` will not be recorded to save memory. - + - [variable] **\*DISCARD-DOCUMENTATION-P\*** *NIL* The default value of [`DEFSECTION`][72b4]'s `DISCARD-DOCUMENTATION-P` argument. One may want to set `*DISCARD-DOCUMENTATION-P*` to true before building a binary application. - + - [macro] **DEFINE-PACKAGE** *PACKAGE &REST OPTIONS* This is like [`CL:DEFPACKAGE`][9b43] but silences warnings and errors @@ -456,7 +456,7 @@ 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 @@ -476,7 +476,7 @@ Now let's examine the most important pieces. When `DISCARD-DOCUMENTATION-P` (defaults to [`*DISCARD-DOCUMENTATION-P*`][730f]) is true, `DOCSTRING` will not be recorded to save memory. - + ### 5.1 Parsing When [Navigating Sources in Emacs][3386] or [Generating Documentation][2c93], references @@ -484,7 +484,7 @@ are parsed from the buffer content or docstrings, respectively. In either case, [name][88cf]s are extracted from [word][d7b0]s and then turned into [DRef names][5fc4] to form [DRef references][43bd] maybe with locatives found next to the [word][d7b0]. - + - [glossary-term] **word** A *word* is a string from which we want to extract a [name][88cf]. When @@ -492,7 +492,7 @@ either case, [name][88cf]s are extracted from [word][d7b0]s and then turned into `slime-symbol-at-point`. When [Generating Documentation][2c93], it is a non-empty string between whitespace characters in a docstring. - + - [glossary-term] **name** A *name* is a string that denotes a possible [DRef @@ -547,12 +547,12 @@ either case, [name][88cf]s are extracted from [word][d7b0]s and then turned into if they contain at least one lowercase character. - + ## 6 PAX Locatives To the [Locative Types][bf0f] defined by DRef, PAX adds a few of its own. - + - [locative] **SECTION** Refers to a [`SECTION`][5fac] defined by [`DEFSECTION`][72b4]. @@ -560,7 +560,7 @@ To the [Locative Types][bf0f] defined by DRef, PAX adds a few of its own. `SECTION` is [`EXPORTABLE-LOCATIVE-TYPE-P`][c930] but not exported by default (see [`EXPORTABLE-REFERENCE-P`][e51f]). - + - [locative] **GLOSSARY-TERM** Refers to a [`GLOSSARY-TERM`][8251] defined by [`DEFINE-GLOSSARY-TERM`][8ece]. @@ -568,7 +568,7 @@ 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]). - + - [locative] **DISLOCATED** Refers to a symbol in a non-specific context. Useful for preventing @@ -586,7 +586,7 @@ To the [Locative Types][bf0f] defined by DRef, PAX adds a few of its own. `DISLOCATED` references do not [`RESOLVE`][63b4]. - + - [locative] **ARGUMENT** An alias for [`DISLOCATED`][e391], so that one can refer to an argument of @@ -607,7 +607,7 @@ To the [Locative Types][bf0f] defined by DRef, PAX adds a few of its own. `ARGUMENT` references do not [`RESOLVE`][63b4]. - + - [locative] **INCLUDE** *SOURCE &KEY LINE-PREFIX HEADER FOOTER HEADER-NL FOOTER-NL* This pseudolocative refers to a region of a file. `SOURCE` can be a @@ -668,7 +668,7 @@ To the [Locative Types][bf0f] defined by DRef, PAX adds a few of its own. `INCLUDE` is not [`EXPORTABLE-LOCATIVE-TYPE-P`][c930], and `INCLUDE` references do not [`RESOLVE`][63b4]. - + - [locative] **DOCSTRING** `DOCSTRING` is a pseudolocative for including the parse tree of the @@ -696,7 +696,7 @@ To the [Locative Types][bf0f] defined by DRef, PAX adds a few of its own. There is no way to [`LOCATE`][8f19] `DOCSTRING`s, so nothing to [`RESOLVE`][63b4] either. - + - [locative] **GO** *(NAME LOCATIVE)* Redirect to a definition in the context of the [reference][43bd] @@ -734,7 +734,7 @@ To the [Locative Types][bf0f] defined by DRef, PAX adds a few of its own. ``` - + - [locative] **CLHS** *&OPTIONAL NESTED-LOCATIVE* Refers to sections or definitions in the Common Lisp Hyperspec. @@ -811,7 +811,7 @@ To the [Locative Types][bf0f] defined by DRef, PAX adds a few of its own. `CLHS` references do not [`RESOLVE`][63b4]. - + ## 7 Navigating Sources in Emacs Integration into [SLIME][6be7]'s [`M-.`][cb15] (`slime-edit-definition`) allows @@ -861,7 +861,7 @@ See [Emacs Setup][8541]. In addition, the Elisp command section containing the definition with `point` in it. See [Browsing Live Documentation][a595]. - + ### 7.1 The mgl-pax/navigate ASDF System - Description: Slime `M-.` support for MGL-PAX. @@ -872,13 +872,13 @@ section containing the definition with `point` in it. See - Mailto: [mega@retes.hu](mailto:mega@retes.hu) - + ## 8 Generating Documentation - + ### 8.1 The `DOCUMENT` Function - + - [function] **DOCUMENT** *DOCUMENTABLE &KEY (STREAM T) PAGES (FORMAT :PLAIN)* Write `DOCUMENTABLE` in `FORMAT` to `STREAM` diverting some output to `PAGES`. @@ -918,7 +918,7 @@ section containing the definition with `point` in it. See For the details, see the following sections, starting with [Documentables][2e45]. Also see [Writing Extensions][c4ce] and [`DOCUMENT-OBJECT*`][8269]. - + #### 8.1.1 Documentables - The `DOCUMENTABLE` argument may be a [`DREF`][d930] or anything else @@ -934,7 +934,7 @@ section containing the definition with `point` in it. See objects in it are documented in depth-first order. - + #### 8.1.2 Return Values If `PAGES` are `NIL`, then [`DOCUMENT`][432c] - like [`CL:FORMAT`][ad78] - returns a @@ -955,7 +955,7 @@ written to, then its output designator is the first element of the returned list. The rest of the designators correspond to the non-empty pages in the `PAGES` argument of `DOCUMENT` in that order. - + #### 8.1.3 Pages The `PAGES` argument of [`DOCUMENT`][432c] is to create multi-page documents @@ -1048,7 +1048,7 @@ displayed in the signature will be a link to this `URI`. See ``` - + #### 8.1.4 Package and Readtable While generating documentation, symbols may be read (e.g. from @@ -1084,7 +1084,7 @@ printed, for printing of the arglist and the docstring. In the above, the `` marks the place where `*PACKAGE*` and `*READTABLE*` are bound. - + ##### Home Section The home section of an object is a [`SECTION`][5fac] that contains the @@ -1121,13 +1121,13 @@ intended home section of a definition among multiple containing sections with high probability. However, for names which are not symbols, there is no package system to advantage of. - + - [variable] **\*DOCUMENT-NORMALIZE-PACKAGES\*** *T* Whether to print `[in package ]` in the documentation when the package changes. - + ### 8.2 The mgl-pax/document ASDF System - Description: Documentation generation support for MGL-PAX. @@ -1138,7 +1138,7 @@ symbols, there is no package system to advantage of. - Mailto: [mega@retes.hu](mailto:mega@retes.hu) - + ### 8.3 Browsing Live Documentation Documentation can be browsed live in Emacs or with an external @@ -1179,7 +1179,7 @@ way as in [Navigating Sources in Emacs][3386]. The convenience function `mgl-pax-document-current-definition` documents the definition with point in it. - + #### 8.3.1 PAX URLs A PAX URL consists of a REFERENCE and an optional `FRAGMENT` @@ -1195,7 +1195,7 @@ where REFERENCE names either possibly makes what to document ambiguous. - + #### 8.3.2 Apropos The Elisp functions `mgl-pax-apropos`, `mgl-pax-apropos-all`, and @@ -1213,7 +1213,7 @@ non-symbol and those with symbol [name][88cf]s. The non-symbol group is sorted by locative type then by name. The symbol group is sorted by name then by locative type. - + #### 8.3.3 Emacs Setup for Browsing Make sure [Emacs Setup][8541] has been done. In particular, set @@ -1256,7 +1256,7 @@ To bind `C-.' globally: ...) ``` - + #### 8.3.4 Browsing with w3m With [w3m's default key bindings][1743], moving the cursor between links involves @@ -1287,7 +1287,7 @@ In addition, the following PAX-specific key bindings are available: page. - + #### 8.3.5 Browsing with Other Browsers When the value of the Elisp variable `mgl-pax-browser-function` @@ -1310,19 +1310,19 @@ the same (see [`*DOCUMENT-FANCY-HTML-NAVIGATION*`][6ab0]). Finally, note that the `URL`s exposed by the web server are subject to change. - + - [variable] **\*BROWSE-HTML-STYLE\*** *:CHARTER* The HTML style to use for browsing live documentation. Affects only non-w3m browsers. See [`*DOCUMENT-HTML-DEFAULT-STYLE*`][90fa] for the possible values. - + ### 8.4 Markdown Support The [markdown][a317] in docstrings is processed with the [3BMD][1904] library. - + #### 8.4.1 Markdown in Docstrings - Docstrings can be indented in any of the usual styles. PAX @@ -1380,7 +1380,7 @@ docstrings are equivalent: \#Return are in the whitespace group. - + #### 8.4.2 Syntax Highlighting For syntax highlighting, Github's [fenced code blocks][1322] markdown @@ -1398,7 +1398,7 @@ is optional and defaults to `common-lisp`. See the documentation of [3BMD][1904] and [Colorize][3076] for the details. - + #### 8.4.3 MathJax Displaying pretty mathematics in TeX format is supported via @@ -1420,10 +1420,10 @@ with a backslash to scare MathJax off. Escaping all those backslashes in TeX fragments embedded in Lisp strings can be a pain. [Pythonic String Reader][d3fc] can help with that. - + ### 8.5 Codification - + - [variable] **\*DOCUMENT-UPPERCASE-IS-CODE\*** *T* When true, [interesting][7445] [name][88cf]s extracted from [codifiable][b89a] [word][d7b0]s @@ -1454,7 +1454,7 @@ strings can be a pain. [Pythonic String Reader][d3fc] can help with that. example looks in a docstring. Note that the backslash is discarded even if `*DOCUMENT-UPPERCASE-IS-CODE*` is false. - + - [glossary-term] **codifiable** A [word][d7b0] is *codifiable* iff @@ -1467,7 +1467,7 @@ strings can be a pain. [Pythonic String Reader][d3fc] can help with that. but not `Classes` or `aTe`. - + - [glossary-term] **interesting** A [name][88cf] is *interesting* iff @@ -1480,7 +1480,7 @@ strings can be a pain. [Pythonic String Reader][d3fc] can help with that. See [Package and Readtable][ab7e]. - + - [variable] **\*DOCUMENT-DOWNCASE-UPPERCASE-CODE\*** *NIL* If true, then all Markdown inline code (that is, `stuff between @@ -1511,7 +1511,7 @@ strings can be a pain. [Pythonic String Reader][d3fc] can help with that. Press `\\M-.` in Emacs. - + ### 8.6 Linking to Code In this section, we describe all ways of linking to code @@ -1523,14 +1523,14 @@ textual context, determining the locative. In a nutshell, if `M-.` works without popping up a list of choices, then the documentation will contain a single link.* - + - [variable] **\*DOCUMENT-LINK-CODE\*** *T* Enable the various forms of links in docstrings described in [Linking to Code][1865]. See the following sections for a description of how to use linking. - + #### 8.6.1 Specified Locative The following examples all render as [`DOCUMENT`][432c]. @@ -1557,7 +1557,7 @@ this form may be used: explicit link*) renders as: [see this][432c]. - + #### 8.6.2 Unspecified Locative When only an [name][88cf] is provided without a locative, all @@ -1576,7 +1576,7 @@ number of methods. Furthermore, filter out all references with `LOCATIVE-TYPE` [`LOCATIVE`][0b3a] if there are references with other `LOCATIVE-TYPE`s. - + ##### Unambiguous Unspecified Locative In the following examples, although no locative is specified, @@ -1593,7 +1593,7 @@ To override the title: as: [see this][432c]. - + ##### Ambiguous Unspecified Locative These examples all render as [`SECTION`][5fac], linking to both @@ -1612,7 +1612,7 @@ To override the title: [see this][5fac]. - + #### 8.6.3 Explicit and Autolinking The examples in the previous sections are marked with *explicit @@ -1620,7 +1620,7 @@ link* or *autolink*. Explicit links are those with a Markdown reference link spelled out explicitly, while autolinks are those without. - + #### 8.6.4 Preventing Autolinking In the common case, when [`*DOCUMENT-UPPERCASE-IS-CODE*`][f25f] is true, @@ -1637,10 +1637,10 @@ autolinked, the backslash must be within backticks like this: This renders as `DOCUMENT`. Alternatively, the [`DISLOCATED`][e391] or the [`ARGUMENT`][8710] locative may be used as in `[DOCUMENT][dislocated]`. - + #### 8.6.5 Unresolvable Links - + - [condition] **UNRESOLVABLE-REFLINK** *[WARNING][bcb6]* When [`DOCUMENT`][432c] encounters an [explicit @@ -1660,17 +1660,17 @@ This renders as `DOCUMENT`. Alternatively, the [`DISLOCATED`][e391] or the [`*ERROR-OUTPUT*`][66c6]. Otherwise, it behaves as `OUTPUT-REFLINK`. - + - [function] **OUTPUT-REFLINK** *&OPTIONAL CONDITION* Invoke the `OUTPUT-REFLINK` restart. See [`UNRESOLVABLE-REFLINK`][64be]. - + - [function] **OUTPUT-LABEL** *&OPTIONAL CONDITION* Invoke the `OUTPUT-LABEL` restart. See [`UNRESOLVABLE-REFLINK`][64be]. - + #### 8.6.6 Suppressed Links [Autolinking][b3cc] of code (i.e. @@ -1695,7 +1695,7 @@ allow their titles to be displayed properly. Finally, [autolinking][b3cc] to `T` or `NIL` is suppressed (see [`*DOCUMENT-LINK-TO-HYPERSPEC*`][875e]). - + #### 8.6.7 Local References To declutter the generated output by reducing the number of @@ -1733,10 +1733,10 @@ is made irrespective of any local references. linked to all non-local references. - + ### 8.7 Linking to the Hyperspec - + - [variable] **\*DOCUMENT-LINK-TO-HYPERSPEC\*** *T* If true, link symbols found in code to the Common Lisp Hyperspec @@ -1754,20 +1754,20 @@ linked to all non-local references. Note that linking explicitly with the [`CLHS`][ed5f] locative is not subject to the value of this variable. - + - [variable] **\*DOCUMENT-HYPERSPEC-ROOT\*** *"http://www.lispworks.com/documentation/HyperSpec/"* A URL of the Common Lisp Hyperspec. The default value is the canonical location. When [invoked from Emacs][a595], the Elisp variable `common-lisp-hyperspec-root` is in effect. - + ### 8.8 Linking to Sections The following variables control how to generate section numbering, table of contents and navigation links. - + - [variable] **\*DOCUMENT-LINK-SECTIONS\*** *T* When true, HTML anchors are generated before the headings (e.g. of @@ -1776,14 +1776,14 @@ table of contents and navigation links. translated to links with the section title being the name of the link. - + - [variable] **\*DOCUMENT-MAX-NUMBERING-LEVEL\*** *3* A non-negative integer. In their hierarchy, sections on levels less than this value get numbered in the format of `3.1.2`. Setting it to 0 turns numbering off. - + - [variable] **\*DOCUMENT-MAX-TABLE-OF-CONTENTS-LEVEL\*** *3* An integer that determines the depth of the table of contents. @@ -1800,14 +1800,14 @@ table of contents and navigation links. If [`*DOCUMENT-LINK-SECTIONS*`][1b28] is true, then the tables will link to the sections. - + - [variable] **\*DOCUMENT-TEXT-NAVIGATION\*** *NIL* If true, then before each heading a line is printed with links to the previous, parent and next section. Needs [`*DOCUMENT-LINK-SECTIONS*`][1b28] to be on to work. - + - [variable] **\*DOCUMENT-FANCY-HTML-NAVIGATION\*** *T* If true and the output format is HTML, then headings get a @@ -1817,10 +1817,10 @@ table of contents and navigation links. component is normally hidden, it is visible only when the mouse is over the heading. Needs [`*DOCUMENT-LINK-SECTIONS*`][1b28] to be on to work. - + ### 8.9 Miscellaneous Variables - + - [variable] **\*DOCUMENT-URL-VERSIONS\*** *(2 1)* A list of versions of PAX URL formats to support in the @@ -1872,7 +1872,7 @@ table of contents and navigation links. ``` - + - [variable] **\*DOCUMENT-MIN-LINK-HASH-LENGTH\*** *4* Recall that markdown reference style links (like `[label][id]`) are @@ -1890,7 +1890,7 @@ table of contents and navigation links. This variable has no effect on the HTML generated from markdown, but it can make markdown output more readable. - + - [variable] **\*DOCUMENT-MARK-UP-SIGNATURES\*** *T* When true, some things such as function names and arglists are @@ -1909,7 +1909,7 @@ table of contents and navigation links. Also, in HTML `**foo**` will be a link to that very entry and `[function]` may turn into a link to sources. - + - [variable] **\*DOCUMENT-BASE-URL\*** *NIL* When `*DOCUMENT-BASE-URL*` is non-`NIL`, this is prepended to all @@ -1920,14 +1920,14 @@ table of contents and navigation links. explicit HTML links (e.g. ``) in Markdown are not affected. - + ### 8.10 Utilities for Generating Documentation Two convenience functions are provided to serve the common case of having an ASDF system with some readmes and a directory with for the HTML documentation and the default CSS stylesheet. - + - [function] **UPDATE-ASDF-SYSTEM-READMES** *OBJECT ASDF-SYSTEM &KEY (URL-VERSIONS \*DOCUMENT-URL-VERSIONS\*) (FORMATS '(:MARKDOWN))* Convenience function to generate up to two readme files in the @@ -1953,10 +1953,10 @@ HTML documentation and the default CSS stylesheet. defaults to using the uglier, version 1 style of `URL` for the sake of github. - + #### 8.10.1 HTML Output - + - [function] **UPDATE-ASDF-SYSTEM-HTML-DOCS** *SECTIONS ASDF-SYSTEM &KEY PAGES (TARGET-DIR (ASDF/SYSTEM:SYSTEM-RELATIVE-PATHNAME ASDF-SYSTEM "doc/")) (UPDATE-CSS-P T) (STYLE \*DOCUMENT-HTML-DEFAULT-STYLE\*)* Generate pretty HTML documentation for a single ASDF system, @@ -1984,7 +1984,7 @@ HTML documentation and the default CSS stylesheet. See the following variables, which control HTML generation. - + - [variable] **\*DOCUMENT-HTML-DEFAULT-STYLE\*** *:DEFAULT* The HTML style to use. It's either `STYLE` is either `:DEFAULT` or @@ -1998,14 +1998,14 @@ See the following variables, which control HTML generation. [`*BROWSE-HTML-STYLE*`][e527] for how to control the style used for [Browsing Live Documentation][a595]. - + - [variable] **\*DOCUMENT-HTML-MAX-NAVIGATION-TABLE-OF-CONTENTS-LEVEL\*** *NIL* `NIL` or a non-negative integer. If non-`NIL`, it overrides [`*DOCUMENT-MAX-NUMBERING-LEVEL*`][f12d] in the dynamic HTML table of contents on the left of the page. - + - [variable] **\*DOCUMENT-HTML-HEAD\*** *NIL* Stuff to be included in the `` of the generated HTML. @@ -2019,7 +2019,7 @@ See the following variables, which control HTML generation. argument, the HTML stream, where it must write the output. - + - [variable] **\*DOCUMENT-HTML-SIDEBAR\*** *NIL* Stuff to be included in the HTML sidebar. @@ -2035,7 +2035,7 @@ See the following variables, which control HTML generation. argument, the HTML stream, where it must write the output. - + - [variable] **\*DOCUMENT-HTML-TOP-BLOCKS-OF-LINKS\*** *NIL* A list of blocks of links to be displayed on the sidebar on the left, @@ -2045,13 +2045,13 @@ See the following variables, which control HTML generation. LABEL)` elements, where `URI` maybe a string or an object being [`DOCUMENT`][432c]ed or a `REFERENCE` thereof. - + - [variable] **\*DOCUMENT-HTML-BOTTOM-BLOCKS-OF-LINKS\*** *NIL* Like [`*DOCUMENT-HTML-TOP-BLOCKS-OF-LINKS*`][e216], only it is displayed below the table of contents. - + #### 8.10.2 Github Workflow It is generally recommended to commit generated readmes (see @@ -2085,7 +2085,7 @@ This way the HTML documentation will be available at It is probably a good idea to add sections like the [Links and Systems][ba74] section to allow jumping between the repository and the gh-pages site. - + - [function] **MAKE-GITHUB-SOURCE-URI-FN** *ASDF-SYSTEM GITHUB-URI &KEY GIT-VERSION* This function is a backward-compatibility wrapper around @@ -2093,7 +2093,7 @@ to allow jumping between the repository and the gh-pages site. All arguments are passed on to `MAKE-GIT-SOURCE-URI-FN`, leaving `URI-FORMAT-STRING` at its default, which is suitable for github. - + - [function] **MAKE-GIT-SOURCE-URI-FN** *ASDF-SYSTEM GIT-FORGE-URI &KEY GIT-VERSION (URI-FORMAT-STRING "~A/blob/~A/~A#L~S")* Return a function suitable as `:SOURCE-URI-FN` of a page spec (see @@ -2130,7 +2130,7 @@ to allow jumping between the repository and the gh-pages site. non-standard git forge, such as Sourcehut or Gitlab, simply pass a suitable `URI-FORMAT-STRING` matching the URI scheme of your forge. - + #### 8.10.3 PAX World PAX World is a registry of documents, which can generate @@ -2138,7 +2138,7 @@ cross-linked HTML documentation pages for all the registered documents. There is an official [PAX World](https://melisgl.github.io/mgl-pax-world/). - + - [function] **REGISTER-DOC-IN-PAX-WORLD** *NAME SECTIONS PAGE-SPECS* Register `SECTIONS` and `PAGE-SPECS` under `NAME` (a symbol) in PAX @@ -2163,7 +2163,7 @@ For example, this is how PAX registers itself: ``` - + - [function] **UPDATE-PAX-WORLD** *&KEY (DOCS \*REGISTERED-PAX-WORLD-DOCS\*) DIR UPDATE-CSS-P (STYLE \*DOCUMENT-HTML-DEFAULT-STYLE\*)* Generate HTML documentation for all `DOCS`. Files are created in @@ -2178,7 +2178,7 @@ For example, this is how PAX registers itself: If necessary a default page spec is created for every section. - + ### 8.11 Overview of Escaping Let's recap how escaping [Codification][f1ab], @@ -2218,7 +2218,7 @@ Note that in the example marked with `*`, the single backslash, that would normally turn autolinking off, is ignored because it is in an explicit link. - + ### 8.12 Output Details By default, [`DREF`][d930]s are documented in the following format. @@ -2288,7 +2288,7 @@ as the arglist. There is no docstring. printed as the arglist. There is no docstring. - + ### 8.13 Documentation Generation Implementation Notes Documentation Generation is supported on ABCL, AllegroCL, CLISP, @@ -2302,7 +2302,7 @@ for [Browsing Live Documentation][a595] because the current implementation relies on Swank to list definitions of symbols (as [`VARIABLE`][6c83], [`FUNCTION`][ba62], etc), and that simply doesn't work. - + ## 9 Transcripts What are transcripts for? When writing a tutorial, one often wants @@ -2348,7 +2348,7 @@ can be enabled with: (in-readtable pythonic-string-syntax) - + ### 9.1 The mgl-pax/transcribe ASDF System - Description: Transcription support for MGL-PAX. @@ -2360,7 +2360,7 @@ can be enabled with: - Mailto: [mega@retes.hu](mailto:mega@retes.hu) - + ### 9.2 Transcribing with Emacs Typical transcript usage from within Emacs is simple: add a lisp @@ -2452,10 +2452,10 @@ The dynamic environment of the transcription is determined by the Transcription support in Emacs can be enabled by loading `src/mgl-pax.el`. See [Emacs Setup][8541]. - + ### 9.3 Transcript API - + - [function] **TRANSCRIBE** *INPUT OUTPUT &KEY UPDATE-ONLY (INCLUDE-NO-OUTPUT UPDATE-ONLY) (INCLUDE-NO-VALUE UPDATE-ONLY) (ECHO T) (CHECK-CONSISTENCY \*TRANSCRIBE-CHECK-CONSISTENCY\*) DEFAULT-SYNTAX (INPUT-SYNTAXES \*TRANSCRIBE-SYNTAXES\*) (OUTPUT-SYNTAXES \*TRANSCRIBE-SYNTAXES\*) DYNENV* Read forms from `INPUT` and write them (iff `ECHO`) to `OUTPUT` @@ -2667,12 +2667,12 @@ Transcription support in Emacs can be enabled by loading is called with a single argument: a thunk (a function of no arguments). See [Controlling the Dynamic Environment][6b59] for an example. - + - [variable] **\*TRANSCRIBE-CHECK-CONSISTENCY\*** *NIL* The default value of [`TRANSCRIBE`][f1f0]'s `CHECK-CONSISTENCY` argument. - + - [variable] **\*TRANSCRIBE-SYNTAXES\*** *((:DEFAULT (:OUTPUT "..") (:NO-VALUE "=> ; No value") (:READABLE "=>") (:UNREADABLE "==>") (:UNREADABLE-CONTINUATION "-->")) (:COMMENTED-1 (:OUTPUT ";..") (:NO-VALUE ";=> ; No value") (:READABLE ";=>") @@ -2710,35 +2710,35 @@ Transcription support in Emacs can be enabled by loading See `TRANSCRIBE` for how the actual syntax to be used is selected. - + - [condition] **TRANSCRIPTION-ERROR** *[ERROR][d162]* Represents syntactic errors in the `SOURCE` argument of [`TRANSCRIBE`][f1f0] and also serves as the superclass of [`TRANSCRIPTION-CONSISTENCY-ERROR`][a249]. - + - [condition] **TRANSCRIPTION-CONSISTENCY-ERROR** *[TRANSCRIPTION-ERROR][b81d]* A common superclass for [`TRANSCRIPTION-OUTPUT-CONSISTENCY-ERROR`][8492] and [`TRANSCRIPTION-VALUES-CONSISTENCY-ERROR`][238c]. - + - [condition] **TRANSCRIPTION-OUTPUT-CONSISTENCY-ERROR** *[TRANSCRIPTION-CONSISTENCY-ERROR][a249]* Signalled (with [`CERROR`][4317]) by [`TRANSCRIBE`][f1f0] when invoked with `:CHECK-CONSISTENCY` and the output of a form is not the same as what was parsed. - + - [condition] **TRANSCRIPTION-VALUES-CONSISTENCY-ERROR** *[TRANSCRIPTION-CONSISTENCY-ERROR][a249]* Signalled (with [`CERROR`][4317]) by [`TRANSCRIBE`][f1f0] when invoked with `:CHECK-CONSISTENCY` and the values of a form are inconsistent with their parsed representation. - + ### 9.4 Transcript Consistency Checking The main use case for consistency checking is detecting @@ -2770,7 +2770,7 @@ notoriously unportable pretty printer is used or when unreadable objects are printed with their `#<>` syntax, especially when [`PRINT-UNREADABLE-OBJECT`][9439] is used with `:IDENTITY T`. - + #### 9.4.1 Finer-Grained Consistency Checks To get around this problem, consistency checking of output, @@ -2804,7 +2804,7 @@ output. ==> # - + #### 9.4.2 Controlling the Dynamic Environment The dynamic environment in which forms in the transcript are @@ -2841,23 +2841,23 @@ A more involved solution could rebind global variables set in transcripts, unintern symbols created or even create a temporary package for evaluation. - + #### 9.4.3 Utilities for Consistency Checking - + - [function] **SQUEEZE-WHITESPACE** *STRING* Replace consecutive whitespace characters with a single space in `STRING`. This is useful to do undo the effects of pretty printing when building comparison functions for [`TRANSCRIBE`][f1f0]. - + - [function] **DELETE-TRAILING-WHITESPACE** *STRING* Delete whitespace characters after the last non-whitespace character in each line in `STRING`. - + - [function] **DELETE-COMMENTS** *STRING &KEY (PATTERN ";")* For each line in `STRING` delete the rest of the line after and @@ -2887,16 +2887,16 @@ package for evaluation. ``` - + ## 10 Writing Extensions - + ### 10.1 Adding New Locatives Once everything in [Adding New Locatives][3cf3] has been done, there are only a couple of PAX generic functions left to extend. - + - [generic-function] **DOCUMENT-OBJECT\*** *OBJECT STREAM* Write `OBJECT` in [`*FORMAT*`][3da8] to `STREAM`. @@ -2904,7 +2904,7 @@ there are only a couple of PAX generic functions left to extend. not [`RESOLVE`][63b4]able, else on the type of object it resolves to. This function is for extension only. Don't call it directly. - + - [generic-function] **EXPORTABLE-REFERENCE-P** *PACKAGE SYMBOL LOCATIVE-TYPE LOCATIVE-ARGS* Return true iff `SYMBOL` is to be exported from @@ -2927,7 +2927,7 @@ there are only a couple of PAX generic functions left to extend. ``` - + - [generic-function] **EXPORTABLE-LOCATIVE-TYPE-P** *LOCATIVE-TYPE* Return true iff symbols in references with @@ -2944,7 +2944,7 @@ Also note that due to the [Home Section][bdd5] logic, especially for locative types with string names, [`DREF-EXT:DOCSTRING*`][9fd4] should probably return a non-`NIL` package. - + ### 10.2 Locative Aliases [`DEFINE-LOCATIVE-ALIAS`][548e] can be used to help [`M-.`][3386] and [autolinking][b3cc] @@ -2985,20 +2985,20 @@ locative can reduce the need for explicit linking. Since these are unlikely to be universally helpful, make sure not to export the symbols `A` and `AN`. - + ### 10.3 Extending `DOCUMENT` 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. - + - [variable] **\*FORMAT\*** Bound by [`DOCUMENT`][432c] to its `FORMAT` argument, this allows markdown output to depend on the output format. - + - [macro] **WITH-HEADING** *(STREAM OBJECT TITLE &KEY LINK-TITLE-TO) &BODY BODY* Write a markdown heading with `TITLE` to `STREAM`. Nested `WITH-HEADING`s @@ -3006,7 +3006,7 @@ are for writing new `DOCUMENT-OBJECT*` methods, which emit markdown. anchors based on the [definition of][8f19] `OBJECT`. `LINK-TITLE-TO` behaves like the `LINK-TITLE-TO` argument of [`DEFSECTION`][72b4]. - + - [macro] **DOCUMENTING-REFERENCE** *(STREAM &KEY REFERENCE NAME PACKAGE READTABLE ARGLIST) &BODY BODY* Write `REFERENCE` to `STREAM` as described in @@ -3035,14 +3035,14 @@ are for writing new `DOCUMENT-OBJECT*` methods, which emit markdown. extent][36e9] of `BODY`. - + - [macro] **WITH-DISLOCATED-NAMES** *NAMES &BODY BODY* For each name in `NAMES`, establish a [local reference][4c96] with the [`DISLOCATED`][e391] locative, which [prevents autolinking][8c16]. - + - [function] **DOCUMENT-DOCSTRING** *DOCSTRING STREAM &KEY (INDENTATION " ") EXCLUDE-FIRST-LINE-P (PARAGRAPHP T)* Write `DOCSTRING` to `STREAM`, [sanitizing the markdown][7bf5] from it, performing [Codification][f1ab] and @@ -3050,7 +3050,7 @@ are for writing new `DOCUMENT-OBJECT*` methods, which emit markdown. prefix is not added to the first line if `EXCLUDE-FIRST-LINE-P`. If `PARAGRAPHP`, then add a newline before and after the output. - + - [function] **ESCAPE-MARKDOWN** *STRING &KEY (ESCAPE-INLINE T) (ESCAPE-HTML T) (ESCAPE-BLOCK T)* Backslash escape markdown constructs in `STRING`. @@ -3063,14 +3063,14 @@ are for writing new `DOCUMENT-OBJECT*` methods, which emit markdown. starting a new markdown block (e.g. a paragraph, heading, etc). - + - [function] **PRIN1-TO-MARKDOWN** *OBJECT &KEY (ESCAPE-INLINE T) (ESCAPE-HTML T) (ESCAPE-BLOCK T)* Like [`PRIN1-TO-STRING`][18e1], but bind [`*PRINT-CASE*`][443b] depending on [`*DOCUMENT-DOWNCASE-UPPERCASE-CODE*`][a5ee] and [`*FORMAT*`][3da8], and [`ESCAPE-MARKDOWN`][3026]. - + ### 10.4 Sections [`SECTION`][5fac] objects rarely need to be dissected since @@ -3078,47 +3078,47 @@ are for writing new `DOCUMENT-OBJECT*` methods, which emit markdown. that one wants to subclass them and maybe redefine how they are presented. - + - [class] **SECTION** [`DEFSECTION`][72b4] stores its `NAME`, `TITLE`, [`PACKAGE`][1d5a], [`READTABLE`][d646] and `ENTRIES` arguments in [`SECTION`][5fac] objects. - + - [reader] **SECTION-NAME** *SECTION (:NAME)* The name of the global variable whose value is this [`SECTION`][5fac] object. - + - [reader] **SECTION-PACKAGE** *SECTION (:PACKAGE)* [`*PACKAGE*`][5ed1] will be bound to this package when generating documentation for this section. - + - [reader] **SECTION-READTABLE** *SECTION (:READTABLE)* [`*READTABLE*`][b79a] will be bound to this when generating documentation for this section. - + - [reader] **SECTION-TITLE** *SECTION (:TITLE)* A markdown string or `NIL`. Used in generated documentation. - + - [function] **SECTION-LINK-TITLE-TO** *SECTION* - + - [function] **SECTION-ENTRIES** *SECTION* A list of markdown docstrings and [`XREF`][1538]s in the order they occurred in [`DEFSECTION`][72b4]. - + ### 10.5 Glossary Terms [`GLOSSARY-TERM`][8251] objects rarely need to be dissected since @@ -3126,24 +3126,24 @@ presented. plausible that one wants to subclass them and maybe redefine how they are presented. - + - [class] **GLOSSARY-TERM** See [`DEFINE-GLOSSARY-TERM`][8ece]. - + - [reader] **GLOSSARY-TERM-NAME** *GLOSSARY-TERM (:NAME)* The name of the global variable whose value is this [`GLOSSARY-TERM`][8251] object. - + - [reader] **GLOSSARY-TERM-TITLE** *GLOSSARY-TERM (:TITLE)* A markdown string or `NIL`. Used in generated documentation (see [Output Details][af6f]). - + - [reader] **GLOSSARY-TERM-URL** *GLOSSARY-TERM (:URL)* A string or `NIL`. diff --git a/dref/README.md b/dref/README.md index c3896d3..4502bac 100644 --- a/dref/README.md +++ b/dref/README.md @@ -1,4 +1,4 @@ - + # DRef Manual ## Table of Contents @@ -24,7 +24,7 @@ - [7.5 Source Locations][a078] ###### \[in package DREF\] - + ## 1 Introduction *What if definitions were first-class objects?* @@ -100,7 +100,7 @@ Finally, existing definitions can be queried with [`DEFINITIONS`][e196] and ``` - + ## 2 Locatives and References After the [Introduction][ad80], here we get into the details. Of special @@ -120,7 +120,7 @@ interest are: [Operations][5dd9] ([`ARGLIST`][e6bd], [`DOCSTRING`][affc], [`SOURCE-LOCATION`][32da]) know how to deal with references (discussed in the [Extending DRef][68fb]). - + - [class] **XREF** An `XREF` (cross-reference) may represent some @@ -129,7 +129,7 @@ with references (discussed in the [Extending DRef][68fb]). [malformed][b6c4]. The subclass [`DREF`][d930] represents definitions that exist. - + - [class] **DREF** *[XREF][1538]* [`DREF`][d930]s can be thought of as referring to @@ -142,7 +142,7 @@ with references (discussed in the [Extending DRef][68fb]). [Extending DRef][68fb]) and to confine locative validation to `LOCATE`. - + - [function] **XREF** *NAME LOCATIVE* A shorthand for `(MAKE-INSTANCE 'XREF :NAME NAME :LOCATIVE LOCATIVE)`. @@ -150,7 +150,7 @@ with references (discussed in the [Extending DRef][68fb]). not be defined, and the [`LOCATIVE-ARGS`][2444] need not be valid. Use [`LOCATE`][8f19] or the [`DREF`][7e92] function to create [`DREF`][d930] objects. - + - [function] **XREF=** *XREF1 XREF2* See if `XREF1` and `XREF2` have the same [`XREF-NAME`][b88e] and [`XREF-LOCATIVE`][f486] @@ -158,7 +158,7 @@ with references (discussed in the [Extending DRef][68fb]). [`DREF`][d930]s. However, two [`XREF`][1538]s different under `XREF=` may denote the same [`DREF`][d930]s. - + - [function] **LOCATE** *OBJECT &OPTIONAL (ERRORP T)* Return a [`DREF`][d930] representing the definition given by the arguments. @@ -213,12 +213,12 @@ with references (discussed in the [Extending DRef][68fb]). Can be extended via [`LOCATE*`][76c4]. - + - [function] **DREF** *NAME LOCATIVE &OPTIONAL (ERRORP T)* Shorthand for `(LOCATE (XREF NAME LOCATIVE) ERRORP)`. - + - [function] **RESOLVE** *OBJECT &OPTIONAL (ERRORP T)* If `OBJECT` is an [`XREF`][1538], then return the first-class object @@ -266,22 +266,22 @@ with references (discussed in the [Extending DRef][68fb]). Can be extended via [`RESOLVE*`][d3b3]. - + - [condition] **LOCATE-ERROR** *[ERROR][d162]* Signalled by [`LOCATE`][8f19] when the definition cannot be found, and `ERRORP` is true. - + - [condition] **RESOLVE-ERROR** *[ERROR][d162]* Signalled by [`RESOLVE`][63b4] when the object defined cannot be returned, and `ERRORP` is true. - + ## 3 Listing Definitions - + - [function] **DEFINITIONS** *NAME &KEY (LOCATIVE-TYPES (LISP-LOCATIVE-TYPES))* Return all definitions of `NAME` that match `LOCATIVE-TYPES` @@ -297,7 +297,7 @@ with references (discussed in the [Extending DRef][68fb]). Can be extended via [`MAP-DEFINITIONS`][0e9c]. - + - [function] **DREF-APROPOS** *NAME &KEY PACKAGE EXTERNAL-ONLY CASE-SENSITIVE (LOCATIVE-TYPES '(:LISP))* Return a list of [`DREF`][d930]s corresponding to existing @@ -384,39 +384,39 @@ with references (discussed in the [Extending DRef][68fb]). Can be extended via [`MAP-NAMES`][811f]. - + - [function] **LOCATIVE-TYPES** Return a list of non-[alias][94d1] locative types. This is the [`UNION`][d6c7] of [`LISP-LOCATIVE-TYPES`][30ad] and [`PSEUDO-LOCATIVE-TYPES`][c340]. - + - [function] **LISP-LOCATIVE-TYPES** Return the locative types that correspond to Lisp definitions except [`UNKNOWN`][a951]. These are the ones defined with [`DEFINE-LOCATIVE-TYPE`][b6c4]. - + - [function] **PSEUDO-LOCATIVE-TYPES** Return the locative types that correspond to non-Lisp definitions plus [`UNKNOWN`][a951]. These are the ones defined with [`DEFINE-PSEUDO-LOCATIVE-TYPE`][68b4]. - + - [function] **LOCATIVE-ALIASES** Return the list of locatives aliases, defined with [`DEFINE-LOCATIVE-ALIAS`][548e]. - + ## 4 Operations The following functions take a single object definition as their argument. They may try to [`LOCATE`][8f19] the definition of the object, which may signal a [`LOCATE-ERROR`][6334] condition. - + - [function] **ARGLIST** *OBJECT* Return the arglist of the definition of `OBJECT` or `NIL` if the @@ -460,7 +460,7 @@ signal a [`LOCATE-ERROR`][6334] condition. Can be extended via [`ARGLIST*`][0a96] - + - [function] **DOCSTRING** *OBJECT* Return the docstring from the definition of `OBJECT`. @@ -479,7 +479,7 @@ signal a [`LOCATE-ERROR`][6334] condition. Can be extended via [`DOCSTRING*`][9fd4]. - + - [function] **SOURCE-LOCATION** *OBJECT &KEY ERRORP* Return the Swank source location for the [defining form][23a8] @@ -495,7 +495,7 @@ signal a [`LOCATE-ERROR`][6334] condition. Can be extended via [`SOURCE-LOCATION*`][444d]. - + ## 5 Locative Types The following are the [locative type][a11d]s supported out of the @@ -512,10 +512,10 @@ Even if there is no such CL type, the [`ARGLIST`][e6bd], the [`DOCSTRING`][affc] the [`SOURCE-LOCATION`][32da] of the defining form is usually recorded unless otherwise noted. - + ### 5.1 Locatives for Variables - + - [locative] **VARIABLE** *&OPTIONAL INITFORM* Refers to a global special variable. @@ -529,7 +529,7 @@ otherwise noted. `VARIABLE` references do not [`RESOLVE`][63b4]. - + - [locative] **CONSTANT** *&OPTIONAL INITFORM* Refers to a constant variable defined with [`DEFCONSTANT`][8934]. `INITFORM`, @@ -539,10 +539,10 @@ otherwise noted. `CONSTANT` references do not [`RESOLVE`][63b4]. - + ### 5.2 Locatives for Macros - + - [locative] **MACRO** Refers to a global macro, typically defined with [`DEFMACRO`][14cb], or to a @@ -550,7 +550,7 @@ otherwise noted. `MACRO` references do not [`RESOLVE`][63b4]. - + - [locative] **SYMBOL-MACRO** Refers to a global symbol macro, defined with [`DEFINE-SYMBOL-MACRO`][46c0]. @@ -568,7 +568,7 @@ otherwise noted. `SYMBOL-MACRO` references do not [`RESOLVE`][63b4]. - + - [locative] **COMPILER-MACRO** Refers to a compiler macro, typically defined with @@ -576,7 +576,7 @@ otherwise noted. `COMPILER-MACRO` references do not [`RESOLVE`][63b4]. - + - [locative] **SETF** *&OPTIONAL METHOD* Refers to a [setf expander][35a2] (see [`DEFSETF`][66dc] and [`DEFINE-SETF-EXPANDER`][d2cb]) @@ -592,10 +592,10 @@ otherwise noted. References to setf functions [`RESOLVE`][63b4] to the function object. Setf expander references do not `RESOLVE`. - + ### 5.3 Locatives for Functions - + - [locative] **FUNCTION** Refers to a global function, typically defined with [`DEFUN`][f472]. The @@ -609,14 +609,14 @@ otherwise noted. ``` - + - [locative] **GENERIC-FUNCTION** Refers to a [`GENERIC-FUNCTION`][efe2], typically defined with [`DEFGENERIC`][c7f7]. The [name][5fc4] must be a [`SYMBOL`][e5af] (see the [`SETF`][d83a] locative for how to reference [setf functions][99b0]). - + - [locative] **METHOD** *METHOD-QUALIFIERS METHOD-SPECIALIZERS* Refers to `METHOD`s named by [`SYMBOL`][e5af]s (for [`SETF`][a138] methods, @@ -639,7 +639,7 @@ otherwise noted. `METHOD` is not [`EXPORTABLE-LOCATIVE-TYPE-P`][c930]. - + - [locative] **METHOD-COMBINATION** Refers to a [`METHOD-COMBINATION`][9b70], defined with @@ -647,7 +647,7 @@ otherwise noted. `METHOD-COMBINATION` references do not [`RESOLVE`][63b4]. - + - [locative] **ACCESSOR** *CLASS-NAME* Refers to an `:ACCESSOR` in a [`DEFCLASS`][ead6]: @@ -664,17 +664,17 @@ otherwise noted. Somewhat arbitrarily, `ACCESSOR` references [`RESOLVE`][63b4] to the writer method but can be [`LOCATE`][8f19]d with either. - + - [locative] **READER** *CLASS-NAME* Like [`ACCESSOR`][00d4], but refers to a `:READER` method in a [`DEFCLASS`][ead6]. - + - [locative] **WRITER** *CLASS-NAME* Like [`ACCESSOR`][00d4], but refers to a `:WRITER` method in a [`DEFCLASS`][ead6]. - + - [locative] **STRUCTURE-ACCESSOR** *&OPTIONAL STRUCTURE-CLASS-NAME* Refers to an accessor function generated by [`DEFSTRUCT`][eac1]. @@ -686,10 +686,10 @@ otherwise noted. [`DREF-APROPOS`][65b4] will return `FUNCTION`([`0`][119e] [`1`][81f7]) references instead. On such platforms, `STRUCTURE-ACCESSOR` references do not [`RESOLVE`][63b4]. - + ### 5.4 Locatives for Types and Declarations - + - [locative] **TYPE** This locative can refer to any Lisp type and [compound type @@ -709,7 +709,7 @@ otherwise noted. `TYPE` references do not [`RESOLVE`][63b4]. - + - [locative] **CLASS** Naturally, `CLASS` is the locative type for [`CLASS`][1f37]es. @@ -721,7 +721,7 @@ otherwise noted. ``` - + - [locative] **DECLARATION** Refers to a declaration, used in [`DECLARE`][1574], [`DECLAIM`][ebea] and [`PROCLAIM`][d3e1]. @@ -739,21 +739,21 @@ otherwise noted. Also, [`SOURCE-LOCATION`][32da] on declarations currently only works on SBCL. - + ### 5.5 Locatives for the Condition System - + - [locative] **CONDITION** `CONDITION` is the locative type for [`CONDITION`][83e1]s. - + - [locative] **RESTART** A locative to refer to the definition of a restart defined by [`DEFINE-RESTART`][bb23]. - + - [macro] **DEFINE-RESTART** *SYMBOL LAMBDA-LIST &BODY DOCSTRING* Associate a definition with the name of a restart, which must be a symbol. @@ -772,10 +772,10 @@ otherwise noted. Note that while there is a [`CL:RESTART`][38e4] class, its instances have no docstring or source location. - + ### 5.6 Locatives for Packages and Readtables - + - [locative] **ASDF/SYSTEM:SYSTEM** Refers to a registered `ASDF:SYSTEM`. @@ -783,7 +783,7 @@ otherwise noted. `ASDF:SYSTEM` is not [`EXPORTABLE-LOCATIVE-TYPE-P`][c930]. - + - [locative] **PACKAGE** Refers to a [`PACKAGE`][1d5a], defined by [`DEFPACKAGE`][9b43] or [`MAKE-PACKAGE`][6e6e]. @@ -791,7 +791,7 @@ otherwise noted. `PACKAGE` is not [`EXPORTABLE-LOCATIVE-TYPE-P`][c930]. - + - [locative] **READTABLE** Refers to a named [`READTABLE`][d646] defined with @@ -802,10 +802,10 @@ otherwise noted. `READTABLE` references [`RESOLVE`][63b4] to `FIND-READTABLE` on their [name][5fc4]. - + ### 5.7 DRef Locatives - + - [locative] **LOCATIVE** This is the locative for [locative type][a11d]s defined with @@ -819,7 +819,7 @@ otherwise noted. ``` - + - [locative] **UNKNOWN** *DSPEC* This [pseudo locative type][c340] is to allow `PAX` @@ -843,7 +843,7 @@ otherwise noted. [`ARGLIST`][e6bd] and [`DOCSTRING`][affc] return `NIL` for `UNKNOWN`s, but [`SOURCE-LOCATION`][32da] works. - + - [locative] **LAMBDA** *&KEY ARGLIST ARGLIST-TYPE DOCSTRING DOCSTRING-PACKAGE FILE FILE-POSITION SNIPPET &ALLOW-OTHER-KEYS* A [pseudo locative type][c340] that carries its @@ -873,10 +873,10 @@ otherwise noted. See the [`PAX:INCLUDE`][5cd7] locative for an example. - + ## 6 Glossary - + - [glossary-term] **name** Names are symbols or strings which name [functions][ba62], [types][926d], [packages][4dd7], @@ -884,7 +884,7 @@ otherwise noted. See [`XREF-NAME`][b88e] and [`DREF-NAME`][1cf6]. - + - [glossary-term] **locative** Locatives specify a *type* of definition such as @@ -898,7 +898,7 @@ otherwise noted. See [`XREF-LOCATIVE`][f486] and [`DREF-LOCATIVE`][3d59]. - + - [glossary-term] **locative type** The locative type is the part of a [locative][7ac8] that identifies @@ -909,14 +909,14 @@ otherwise noted. See [`XREF-LOCATIVE-TYPE`][882a] and [`DREF-LOCATIVE-TYPE`][6801]. - + - [glossary-term] **reference** A reference is an [name][5fc4] plus a [locative][7ac8], and it identifies a possible definition. References are of class [`XREF`][1538]. When a reference is a [`DREF`][d930], it may also be called a definition. - + - [glossary-term] **presentation** [reference][43bd]s may have arguments (see @@ -927,18 +927,18 @@ otherwise noted. [`PAX:DOCUMENT`][432c]. Presentation arguments are available via [`DREF-EXT:DREF-ORIGIN`][c938]. - + ## 7 Extending DRef - + ### 7.1 References - + - [reader] **XREF-NAME** *XREF (:NAME)* The [name][5fc4] of the reference. - + - [reader] **XREF-LOCATIVE** *XREF (:LOCATIVE)* The [locative][7ac8] of the reference. @@ -957,19 +957,19 @@ otherwise noted. ``` - + - [reader] **DREF-NAME** *DREF* The same as [`XREF-NAME`][b88e], but only works on [`DREF`][d930]s. Use it as a statement of intent. - + - [reader] **DREF-LOCATIVE** *DREF* The same as [`XREF-LOCATIVE`][f486], but only works on [`DREF`][d930]s. Use it as a statement of intent. - + - [reader] **DREF-ORIGIN** *DREF* The object from which [`LOCATE`][8f19] constructed this @@ -1000,14 +1000,14 @@ otherwise noted. ``` - + - [function] **LOCATIVE-TYPE** *LOCATIVE* Return [locative type][a11d] of `LOCATIVE` (which may be from [`XREF-LOCATIVE`][f486]). This is the first element of `LOCATIVE` if it's a list. If it's a symbol, it's that symbol itself. - + - [function] **LOCATIVE-ARGS** *LOCATIVE* Return the [`REST`][fe9f] of `LOCATIVE` (which may be from [`XREF-LOCATIVE`][f486]) @@ -1021,19 +1021,19 @@ The following convenience functions are compositions of {[`LOCATIVE-TYPE`][97ba], [`LOCATIVE-ARGS`][2444]} and {[`XREF-LOCATIVE`][f486], [`DREF-LOCATIVE`][3d59]}. - + - [function] **XREF-LOCATIVE-TYPE** *XREF* - + - [function] **XREF-LOCATIVE-ARGS** *XREF* - + - [function] **DREF-LOCATIVE-TYPE** *DREF* - + - [function] **DREF-LOCATIVE-ARGS** *DREF* - + ### 7.2 Adding New Locatives Let's see how to tell DRef about new kinds of definitions through @@ -1114,7 +1114,7 @@ this can be done for non-`RESOLVE`able locative types. Classes have no arglist, so no [`ARGLIST*`][0a96] method is needed. In the following, we describe the pieces in detail. - + - [macro] **DEFINE-LOCATIVE-TYPE** *LOCATIVE-TYPE LAMBDA-LIST &BODY DOCSTRING* Declare `LOCATIVE-TYPE` as a [`LOCATIVE`][0b3a], which is the @@ -1138,7 +1138,7 @@ following, we describe the pieces in detail. Locative types defined with `DEFINE-LOCATIVE-TYPE` can be listed with [`LISP-LOCATIVE-TYPES`][30ad]. - + - [macro] **DEFINE-PSEUDO-LOCATIVE-TYPE** *LOCATIVE-TYPE LAMBDA-LIST &BODY DOCSTRING* Like [`DEFINE-LOCATIVE-TYPE`][b6c4], but declare that `LOCATIVE-TYPE` does @@ -1148,7 +1148,7 @@ following, we describe the pieces in detail. Locative types defined with `DEFINE-PSEUDO-LOCATIVE-TYPE` can be listed with [`PSEUDO-LOCATIVE-TYPES`][c340]. - + - [macro] **DEFINE-LOCATIVE-ALIAS** *ALIAS LOCATIVE-TYPE &BODY DOCSTRING* Define `ALIAS` as a locative equivalent to `LOCATIVE-TYPE` (both @@ -1177,14 +1177,14 @@ following, we describe the pieces in detail. Also, see [Locative Aliases][0fa3] in `PAX`. - + - [macro] **DEFINE-DEFINITION-CLASS** *LOCATIVE-TYPE CLASS-NAME &OPTIONAL (SUPERCLASSES '(DREF)) &BODY BODY* Define a subclass of `DREF`([`0`][d930] [`1`][7e92]). All definitions with `LOCATIVE-TYPE` must be of this type. If non-`NIL`, `BODY` is [`DEFCLASS`][ead6]' slot definitions and other options. - + - [generic-function] **LOCATE\*** *OBJECT* Return a definition of `OBJECT` as a [`DREF`][d930], @@ -1194,7 +1194,7 @@ following, we describe the pieces in detail. This function is for extending [`LOCATE`][8f19]. Do not call it directly. - + - [generic-function] **DREF\*** *NAME LOCATIVE-TYPE LOCATIVE-ARGS* [`LOCATE*`][76c4] calls this for [`XREF`][1538]s which are not @@ -1204,13 +1204,13 @@ following, we describe the pieces in detail. types. This function is for extending [`LOCATE`][8f19]. Do not call it directly. - + - [macro] **CHECK-LOCATIVE-ARGS** *LOCATIVE-TYPE LOCATIVE-ARGS* Signal a [`LOCATE-ERROR`][6334] condition if `LOCATIVE-ARGS` do not match the `LAMBDA-LIST` argument of `LOCATIVE-TYPE` (not evaluated). - + - [function] **LOCATE-ERROR** *&REST FORMAT-AND-ARGS* Call this function to signal a [`LOCATE-ERROR`][6334] condition from the @@ -1220,7 +1220,7 @@ following, we describe the pieces in detail. `FORMAT-AND-ARGS`, if non-`NIL`, is a format string and arguments suitable for [`FORMAT`][ad78]. - + - [function] **ADD-DREF-ACTUALIZER** *NAME* Add the global function denoted by the symbol `NAME` to the list @@ -1228,13 +1228,13 @@ following, we describe the pieces in detail. argument. They are called within [`LOCATE`][8f19] when [`LOCATE*`][76c4] returns a `DREF`. Their job is to make the `DREF` more specific. - + - [function] **REMOVE-DREF-ACTUALIZER** *NAME* Remove the global function denoted by the symbol `NAME` from the list of actualizers. - + - [generic-function] **RESOLVE\*** *DREF* Return the object defined by the definition `DREF` @@ -1249,7 +1249,7 @@ following, we describe the pieces in detail. It is an error for methods of this generic function to return an [`XREF`][1538]. - + - [function] **RESOLVE-ERROR** *&REST FORMAT-AND-ARGS* Call this function to signal a [`RESOLVE-ERROR`][0660] condition from the @@ -1259,7 +1259,7 @@ following, we describe the pieces in detail. `FORMAT-AND-ARGS`, if non-`NIL`, is a format string and arguments suitable for [`FORMAT`][ad78]. - + - [generic-function] **MAP-DEFINITIONS** *FN NAME LOCATIVE-TYPE* Call `FN` with [`DREF`][d930]s which have the given @@ -1270,7 +1270,7 @@ following, we describe the pieces in detail. This function is for extending [`DEFINITIONS`][e196]. Do not call it directly. - + - [generic-function] **MAP-NAMES** *FN LOCATIVE-TYPE* Call `FN` with [name][5fc4]s that form a [`DREF`][d930] with @@ -1281,7 +1281,7 @@ following, we describe the pieces in detail. This function is for extending [`DREF-APROPOS`][65b4]. Do not call it directly. - + - [generic-function] **ARGLIST\*** *OBJECT* To extend [`ARGLIST`][e6bd], specialize this on a subclass of @@ -1289,7 +1289,7 @@ following, we describe the pieces in detail. of object it resolves to. This function is for extension only. Do not call it directly. - + - [generic-function] **DOCSTRING\*** *DREF* To extend [`DOCSTRING`][affc], specialize this on a subclass @@ -1297,7 +1297,7 @@ following, we describe the pieces in detail. type of object it resolves to. This function is for extension only. Do not call it directly. - + - [generic-function] **SOURCE-LOCATION\*** *DREF* To extend [`SOURCE-LOCATION`][32da], specialize this on a @@ -1305,7 +1305,7 @@ following, we describe the pieces in detail. on the type of object it resolves to. This function is for extension only. Do not call it directly. - + ### 7.3 Symbol Locatives Let's see how the opaque [`DEFINE-SYMBOL-LOCATIVE-TYPE`][ee9b] and the @@ -1313,7 +1313,7 @@ obscure [`DEFINE-DEFINER-FOR-SYMBOL-LOCATIVE-TYPE`][3b96] macros work together to simplify the common task of associating definition with a symbol in a certain context. - + - [macro] **DEFINE-SYMBOL-LOCATIVE-TYPE** *LOCATIVE-TYPE LAMBDA-LIST &BODY DOCSTRING* Similar to [`DEFINE-LOCATIVE-TYPE`][b6c4], but it assumes that all things @@ -1338,7 +1338,7 @@ in a certain context. After all this, `(DREF 'UP 'DIRECTION)` refers to the `DEFINE-DIRECTION` form above. - + - [macro] **DEFINE-DEFINER-FOR-SYMBOL-LOCATIVE-TYPE** *NAME LOCATIVE-TYPE &BODY DOCSTRING* Define a macro with `NAME` that can be used to attach a lambda list, @@ -1347,7 +1347,7 @@ in a certain context. &OPTIONAL DOCSTRING)`. `LOCATIVE-TYPE` is assumed to have been defined with [`DEFINE-SYMBOL-LOCATIVE-TYPE`][ee9b]. - + ### 7.4 `DREF` Subclasses These are the [`DREF`][d930] subclasses corresponding to @@ -1357,104 +1357,104 @@ subclassing. **for Variables** - + - [class] **VARIABLE-DREF** *[DREF][d930]* - + - [class] **CONSTANT-DREF** *[VARIABLE-DREF][ad35]* **for Macros** - + - [class] **MACRO-DREF** *[DREF][d930]* - + - [class] **SYMBOL-MACRO-DREF** *[DREF][d930]* - + - [class] **COMPILER-MACRO-DREF** *[DREF][d930]* - + - [class] **SETF-DREF** *[DREF][d930]* **for Functions** - + - [class] **FUNCTION-DREF** *[DREF][d930]* - + - [class] **GENERIC-FUNCTION-DREF** *[FUNCTION-DREF][e576]* - + - [class] **METHOD-DREF** *[DREF][d930]* - + - [class] **METHOD-COMBINATION-DREF** *[DREF][d930]* - + - [class] **ACCESSOR-DREF** *[DREF][d930]* - + - [class] **READER-DREF** *[DREF][d930]* - + - [class] **WRITER-DREF** *[DREF][d930]* - + - [class] **STRUCTURE-ACCESSOR-DREF** *[DREF][d930]* **for Types and Declarations** - + - [class] **TYPE-DREF** *[DREF][d930]* - + - [class] **CLASS-DREF** *[DREF][d930]* - + - [class] **DECLARATION-DREF** *[DREF][d930]* **for the Condition System** - + - [class] **CONDITION-DREF** *[CLASS-DREF][b3a7]* - + - [class] **RESTART-DREF** *[SYMBOL-LOCATIVE-DREF][34b9]* **for Packages and Readtables** - + - [class] **ASDF-SYSTEM-DREF** *[DREF][d930]* - + - [class] **PACKAGE-DREF** *[DREF][d930]* - + - [class] **READTABLE-DREF** *[DREF][d930]* **for DRef Locatives** - + - [class] **LOCATIVE-DREF** *[DREF][d930]* - + - [class] **SYMBOL-LOCATIVE-DREF** *[DREF][d930]* - + - [class] **UNKNOWN-DREF** *[DREF][d930]* - + - [class] **LAMBDA-DREF** *[DREF][d930]* - + ### 7.5 Source Locations These represent the file or buffer position of a [defining form][23a8] and are returned by the [`SOURCE-LOCATION`][32da] function. For the details, see the Elisp function `slime-goto-source-location`. - + - [function] **MAKE-SOURCE-LOCATION** *&KEY FILE FILE-POSITION BUFFER BUFFER-POSITION SNIPPET* Make a Swank source location. The ultimate reference is `slime.el`. @@ -1462,12 +1462,12 @@ the details, see the Elisp function `slime-goto-source-location`. determined (see the Elisp `slime-isearch` and [`SOURCE-LOCATION-ADJUSTED-FILE-POSITION`][daac]). - + - [function] **SOURCE-LOCATION-P** *OBJECT* See if `OBJECT` is a source location object. - + - [function] **SOURCE-LOCATION-FILE** *LOCATION* Return the name of the file of the [defining form][23a8]. @@ -1475,32 +1475,32 @@ the details, see the Elisp function `slime-goto-source-location`. form][23a8] that was entered at the REPL, or compiled in the `*slime-scratch*` buffer. - + - [function] **SOURCE-LOCATION-FILE-POSITION** *LOCATION* Return the file position of the [defining form][23a8] or `NIL` if it's not available. The first position is 0. - + - [function] **SOURCE-LOCATION-BUFFER** *LOCATION* Return the name of the Emacs buffer of the [defining form][23a8] or `NIL` if there is no such Emacs buffer. - + - [function] **SOURCE-LOCATION-BUFFER-POSITION** *LOCATION* Return the position of the [defining form][23a8] in [`SOURCE-LOCATION-BUFFER`][39c2] or `NIL` if it's not available. The first position is 1. - + - [function] **SOURCE-LOCATION-SNIPPET** *LOCATION* Return the [defining form][23a8] or a prefix of it as a string or `NIL` if it's not available. - + - [function] **SOURCE-LOCATION-ADJUSTED-FILE-POSITION** *LOCATION* Return the actual file position `LOCATION` points to allowing for diff --git a/src/document/document.lisp b/src/document/document.lisp index 3b81959..5a17b45 100644 --- a/src/document/document.lisp +++ b/src/document/document.lisp @@ -2743,10 +2743,10 @@ (when (or v1 v2) (when v1 (format stream "~%" - (string-downcase (html4-safe-name (dref-to-anchor-v1 dref))))) + (html4-safe-name (dref-to-anchor-v1 dref)))) (when v2 (format stream "~%" - (string-downcase (urlencode (dref-to-anchor dref)))))))) + (urlencode (dref-to-anchor dref))))))) (defun anchor-id (dref) (string-downcase (if (= (first *document-url-versions*) 1)