文件列表:

COPYING (1073, 2023-10-30)
HACKING.md (2507, 2023-10-30)
TODO.org (5863, 2023-10-30)
dref/ (0, 2023-10-30)
dref/dref-test.asd (1437, 2023-10-30)
dref/dref.asd (2434, 2023-10-30)
dref/src/ (0, 2023-10-30)
dref/src/base/ (0, 2023-10-30)
dref/src/base/autoload.lisp (2201, 2023-10-30)
dref/src/base/dref.lisp (22876, 2023-10-30)
dref/src/base/early.lisp (1295, 2023-10-30)
dref/src/base/extension-api.lisp (18552, 2023-10-30)
dref/src/base/package.lisp (7952, 2023-10-30)
dref/src/base/util.lisp (1258, 2023-10-30)
dref/src/full/ (0, 2023-10-30)
dref/src/full/doc.lisp (437, 2023-10-30)
dref/src/full/late.lisp (10913, 2023-10-30)
dref/src/full/loaded.lisp (140, 2023-10-30)
dref/src/full/locatives.lisp (46809, 2023-10-30)
dref/src/full/source-location.lisp (4800, 2023-10-30)
dref/src/full/swank-util.lisp (19721, 2023-10-30)
dref/src/full/util.lisp (15384, 2023-10-30)
dref/test/ (0, 2023-10-30)
dref/test/package.lisp (232, 2023-10-30)
dref/test/test-autoload.lisp (1699, 2023-10-30)
dref/test/test-defs.lisp (4375, 2023-10-30)
dref/test/test-locate.lisp (20804, 2023-10-30)
dref/test/test.lisp (29573, 2023-10-30)
dref/test/test.sh (3846, 2023-10-30)
mgl-pax-bootstrap.asd (746, 2023-10-30)
mgl-pax-test.asd (1466, 2023-10-30)
mgl-pax.asd (5693, 2023-10-30)
** (81, 2023-10-30)
src/ (0, 2023-10-30)
** (1369, 2023-10-30)
... ...

# PAX Manual ## Table of Contents - [1 Introduction][685e] - [2 Emacs Setup][8541] - [3 Links and Systems][ba74] - [3.1 The mgl-pax ASDF System][6fdb] - [3.2 The mgl-pax/full ASDF System][d761] - [4 Background][f74b] - [5 Basics][94c7] - [5.1 Parsing][378f] - [6 PAX Locatives][292a] - [7 Navigating Sources in Emacs][3386] - [7.1 The mgl-pax/navigate ASDF System][f155] - [8 Generating Documentation][2c93] - [8.1 The `DOCUMENT` Function][dc0a] - [8.1.1 Documentables][2e45] - [8.1.2 Return Values][7dc7] - [8.1.3 Pages][9c7d] - [8.1.4 Package and Readtable][ab7e] - [8.2 The mgl-pax/document ASDF System][4bb8] - [8.3 Browsing Live Documentation][a595] - [8.3.1 PAX URLs][1e80] - [8.3.2 Apropos][b7fc] - [8.3.3 Emacs Setup for Browsing][9a7b] - [8.3.4 Browsing with w3m][83d5] - [8.3.5 Browsing with Other Browsers][c434] - [8.4 Markdown Support][c2d3] - [8.4.1 Markdown in Docstrings][7bf5] - [8.4.2 Syntax Highlighting][bc83] - [8.4.3 MathJax][a17d] - [8.5 Codification][f1ab] - [8.6 Linking to Code][1865] - [8.6.1 Specified Locative][8996] - [8.6.2 Unspecified Locative][524e] - [8.6.3 Explicit and Autolinking][b3cc] - [8.6.4 Preventing Autolinking][8c16] - [8.6.5 Unresolvable Links][b372] - [8.6.6 Suppressed Links][e2e8] - [8.6.7 Local References][4c96] - [8.7 Linking to the Hyperspec][7cc3] - [8.8 Linking to Sections][22c2] - [8.9 Miscellaneous Variables][7c82] - [8.10 Utilities for Generating Documentation][1b1b] - [8.10.1 HTML Output][36e1] - [8.10.2 Github Workflow][dff6] - [8.10.3 PAX World][1281] - [8.11 Overview of Escaping][2634] - [8.12 Output Details][af6f] - [8.13 Documentation Generation Implementation Notes][d1ca] - [9 Transcripts][6300] - [9.1 The mgl-pax/transcribe ASDF System][5825] - [9.2 Transcribing with Emacs][f5bd] - [9.3 Transcript API][9dbc] - [9.4 Transcript Consistency Checking][f47d] - [9.4.1 Finer-Grained Consistency Checks][6e18] - [9.4.2 Controlling the Dynamic Environment][6b59] - [9.4.3 Utilities for Consistency Checking][8423] - [10 Writing Extensions][c4ce] - [10.1 Adding New Locatives][54d8] - [10.2 Locative Aliases][0fa3] - [10.3 Extending `DOCUMENT`][574a] - [10.4 Sections][8a58] - [10.5 Glossary Terms][d1dc] ###### \[in package MGL-PAX with nicknames PAX\] ## 1 Introduction *What if documentation really lived in the code?* Docstrings are already there. If some narrative glued them together, we'd be able develop and explore the code along with the documentation due to their physical proximity. The main tool that PAX provides for this is [`DEFSECTION`][72b4]: ``` (defsection @foo-random-manual (:title "Foo Random manual") "Foo Random is a random number generator library." (foo-random-state class) (uniform-random function) (@foo-random-examples section)) ``` 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 - makes [SLIME][6be7]'s [`M-.`][cb15] work with references and - adds a documentation browser. See [Emacs Setup][8541]. Beyond interactive workflows, [Generating Documentation][2c93] from sections and all the referenced items in Markdown or HTML format is also implemented. With the simplistic tools provided, one may emphasize the narrative as with Literate Programming, but documentation is generated from code, not vice versa, and there is no support for chunking. *Code is first, code must look pretty, documentation is code*. ##### Docstrings PAX automatically recognizes and [marks up code][f1ab] with backticks and [links code][1865] to their definitions. Take, for instance, SBCL's [`ABORT`][479a] function, whose docstring is written in the usual style, uppercasing names of symbols: ``` (docstring #'abort) => "Transfer control to a restart named ABORT, signalling a CONTROL-ERROR if none exists." ``` 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" In the following [transcript][6300], 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 Here is an example of how it all works together: ``` (mgl-pax:define-package :foo-random (:documentation "This package provides various utilities for random. See FOO-RANDOM:@FOO-RANDOM-MANUAL.") (:use #:common-lisp #:mgl-pax)) (in-package :foo-random) (defsection @foo-random-manual (:title "Foo Random manual") "FOO-RANDOM is a random number generator library inspired by CL:RANDOM. Functions such as UNIFORM-RANDOM use *FOO-STATE* and have a :RANDOM-STATE keyword arg." (foo-random-state class) (state (reader foo-random-state)) "Hey we can also print states!" (print-object (method () (foo-random-state t))) (*foo-state* variable) (gaussian-random function) (uniform-random function) ;; This is a subsection. (@foo-random-examples section)) (defclass foo-random-state () ((state :reader state))) (defmethod print-object ((object foo-random-state) stream) (print-unreadable-object (object stream :type t))) (defvar *foo-state* (make-instance 'foo-random-state) "Much like *RANDOM-STATE* but uses the FOO algorithm.") (defun uniform-random (limit &key (random-state *foo-state*)) "Return a random number from the between 0 and LIMIT (exclusive) uniform distribution." nil) (defun gaussian-random (stddev &key (random-state *foo-state*)) "Return a random number from a zero mean normal distribution with STDDEV." nil) (defsection @foo-random-examples (:title "Examples") "Let's see the transcript of a real session of someone working with FOO: ```cl-transcript (values (princ :hello) (list 1 2)) .. HELLO => :HELLO => (1 2) (make-instance 'foo-random-state) ==> # ```") ``` Note how `(VARIABLE *FOO-STATE*)` in the [`DEFSECTION`][72b4] form both exports `*FOO-STATE*` and includes its documentation in `@FOO-RANDOM-MANUAL`. The symbols [`VARIABLE`][6c83] and [`FUNCTION`][ba62] are just two instances of [locative][7ac8]s, which are used in `DEFSECTION` to refer to definitions tied to symbols. `(DOCUMENT @FOO-RANDOM-MANUAL)` generates fancy markdown or HTML output with [automatic markup][f25f] and [autolinks][1865] uppercase [word][d7b0]s found in docstrings, numbers sections, and creates a table of contents. One can even generate documentation for different but related libraries at the same time with the output going to different files but with cross-page links being automatically added for symbols mentioned in docstrings. In fact, this is what [PAX World][1281] does. See [Generating Documentation][2c93] for some convenience functions to cover the most common cases. 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. If you installed PAX with Quicklisp, the location of `mgl-pax.el` may change with updates, and you may want to copy the current version of `mgl-pax.el` to a stable location: (mgl-pax:install-pax-elisp "~/quicklisp/") Then, assuming the Elisp file is in the quicklisp directory, add something like this to your `.emacs`: ```elisp (load "~/quicklisp/mgl-pax.el") (mgl-pax-hijack-slime-doc-keys) (global-set-key (kbd "C-.") 'mgl-pax-document) (global-set-key (kbd "s-x t") 'mgl-pax-transcribe-last-expression) (global-set-key (kbd "s-x r") 'mgl-pax-retranscribe-region) ``` For [Browsing Live Documentation][a595], `mgl-pax-browser-function` can be customized in Elisp. To browse within Emacs, choose `w3m-browse-url` (see [w3m](https://emacs-w3m.github.io/info/emacs-w3m.html)), and make sure both the w3m binary and the w3m Emacs package are installed. On Debian, simply install the `w3m-el` package. With other browser 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 repository](https://github.com/melisgl/mgl-pax) and the [HTML documentation](http://melisgl.github.io/mgl-pax-world/mgl-pax-manual.html) for the latest version. PAX is built on top of the [DRef 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.3.0 - Description: Documentation system, browser, generator. - Long Description: The set of dependencies of the MGL-PAX system is kept light, and its heavier dependencies are autoloaded via ASDF when the relevant functionality is accessed. See the `MGL-PAX/NAVIGATE`, `MGL-PAX/DOCUMENT`, `MGL-PAX/TRANSCRIBE` and `MGL-PAX/FULL` systems. To keep deployed code small, client systems should declare an ASDF dependency on this system, never on the others, which are intended for autoloading and interactive use. - Licence: MIT, see COPYING. - Author: Gábor Melis - Mailto: [mega@retes.hu](mailto:mega@retes.hu) - Homepage: [http://melisgl.github.io/mgl-pax](http://melisgl.github.io/mgl-pax) - 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. - Long Description: Do not declare a dependency on this system. It is autoloaded. - Licence: MIT, see COPYING. - Author: Gábor Melis - Mailto: [mega@retes.hu](mailto:mega@retes.hu) ## 4 Background As a user, I frequently run into documentation that's incomplete and out of date, so I tend to stay in the editor and explore the code by jumping around with [SLIME][6be7]'s [`M-.`][cb15] (`slime-edit-definition`). As a library author, I spend a great deal of time polishing code but precious little writing documentation. In fact, I rarely write anything more comprehensive than docstrings for exported stuff. Writing docstrings feels easier than writing a separate user manual, and they are always close at hand during development. The drawback of this style is that users of the library have to piece the big picture together themselves. That's easy to solve, I thought, let's just put all the narrative that holds docstrings together in the code and be a bit like a Literate Programmer turned inside out. The original prototype, which did almost everything I wanted, was this: ``` (defmacro defsection (name docstring) `(defun ,name () ,docstring)) ``` Armed with this `DEFSECTION`, I soon found myself organizing code following the flow of user-level documentation and relegated comments to implementation details entirely. However, some parts of `DEFSECTION` docstrings were just listings of all the functions, macros and variables related to the narrative, and this list was repeated in the [`DEFPACKAGE`][9b43] form complete with little comments that were like section names. A clear violation of [OAOO][7d18], one of them had to go, so `DEFSECTION` got a list of symbols to export. That was great, but soon I found that the listing of symbols is ambiguous if, for example, a function, a compiler macro and a class were named by the same symbol. This did not concern exporting, of course, but it didn't help readability. Distractingly, on such symbols, `M-.` was popping up selection dialogs. There were two birds to kill, and the symbol got accompanied by a type, which was later generalized into the concept of locatives: ``` (defsection @introduction () "A single line for one man ..." (foo class) (bar function)) ``` After a bit of elisp hacking, `M-.` was smart enough to disambiguate based on the locative found in the vicinity of the symbol, and everything was good for a while. Then, I realized that sections could refer to other sections if there were a [`SECTION`][672f] locative. Going down that path, I soon began to feel the urge to generate pretty documentation as all the necessary information was available in the `DEFSECTION` forms. The design constraint imposed on documentation generation was that following the typical style of upcasing symbols in docstrings, there should be no need to explicitly mark up links: if `M-.` works, then the documentation generator shall also be able figure out what's being referred to. I settled on [markdown][a317] as a reasonably non-intrusive format, and a 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. A bit behind the scenes, a global variable with `NAME` is defined and is bound to a [`SECTION`][5fac] object. By convention, section names start with the character `@`. See [Introduction][685e] for an example. **Entries** `ENTRIES` consists of docstrings and references in any order. Docstrings are arbitrary strings in markdown format. References are [`XREF`][1538]s given in the form `(NAME LOCATIVE)`. For example, `(FOO FUNCTION)` refers to the function `FOO`, `(@BAR SECTION)` says that `@BAR` is a subsection of this one. `(BAZ (METHOD () (T T T)))` refers to the default method of the three argument generic function `BAZ`. `(FOO FUNCTION)` is equivalent to `(FOO (FUNCTION))`. See the DRef [Introduction][ad80] for more. The same name may occur in multiple references, typically with different locatives, but this is not required. The references are not [`LOCATE`][8f19]d until documentation is generated, so they may refer to things yet to be defined. **Exporting** If `EXPORT` is true (the default), `NAME` and the [name][88cf]s of references among `ENTRIES` which are [`SYMBOL`][e5af]s are candidates for exporting. A candidate symbol is exported if - it is [accessible][3473] in `PACKAGE`, and - there is a reference to it in the section being defined which is approved by [`EXPORTABLE-REFERENCE-P`][e51f]. See [`DEFINE-PACKAGE`][63f3] if you use the export feature. The idea with confounding documentation and exporting is to force documentation of all exported symbols. **Misc** `TITLE` is a string containing markdown or `NIL`. If non-`NIL`, it determines the text of the heading in the generated output. `LINK-TITLE-TO` is a reference given as an `(NAME LOCATIVE)` pair or `NIL`, to which the heading will link when generating HTML. If not specified, the heading will link to its own anchor. 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 signalled when the redefined package is at variance with the current state of the package. Typically this situation occurs when symbols are exported by calling [`EXPORT`][0c4f] (as is the case with [`DEFSECTION`][72b4]) as opposed to adding `:EXPORT` forms to the `DEFPACKAGE` form and the package definition is subsequently reevaluated. See the section on [package variance](http://www.sbcl.org/manual/#Package-Variance) in the SBCL manual. 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 When [Navigating Sources in Emacs][3386] or [Generating Documentation][2c93], references 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] ... ...

近期下载者：

相关文件：

评论：[我要评论] [举报此文件]

收藏者：