The mgl-pax Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The mgl-pax Reference Manual

This is the mgl-pax Reference Manual, version 0.0.2, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 04:19:05 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

# PAX Manual

###### \[in package MGL-PAX\]
## mgl-pax ASDF System Details

- Version: 0.0.2
- Description: Exploratory programming tool and documentation
  generator.
- Licence: MIT, see COPYING.
- Author: Gábor Melis
- Mailto: [mega@retes.hu](mailto:mega@retes.hu)
- Homepage: [http://quotenil.com](http://quotenil.com)

## Links

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.

## 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's [`M-.`][SLIME-M-.]. As a library
author, I spend a great deal of time polishing code, but precious
little writing documentation.

[SLIME-M-.]: http://common-lisp.net/project/slime/doc/html/Finding-definitions.html#Finding-definitions 

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 Programming weenie turned inside out. The original
prototype which did almost everything I wanted was this:

    (defmacro defsection (name docstring)
      `(defun ,name () ,docstring))

Armed with DEFSECTION, I soon found myself organizing code following
the flow of user level documentation and relegated comments to
implementational details entirely. However, some portions of
DEFSECTION docstrings were just listings of all the functions,
macros and variables related to the narrative, and this list was
effectively repeated in the DEFPACKAGE form complete with little
comments that were like section names. A clear violation of
[OAOO][oaoo], one of them had to go, so DEFSECTION got a list of
symbols to export.

[oaoo]: http://c2.com/cgi/wiki?OnceAndOnlyOnce 

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
are 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:

```commonlisp
(defsection @mgl-pax-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 locative. Going down that path, I soon began to feel
the urge to generate pretty documentation as all the necessary
information was manifest 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 find out what's being
referred to.

I settled on [Markdown][markdown] as a reasonably non-intrusive
format, and a few thousand lines later PAX was born.

[markdown]: https://daringfireball.net/projects/markdown/ 


## Tutorial

PAX provides an extremely poor man's Explorable Programming
environment. Narrative primarily lives in so called sections that
mix markdown docstrings with references to functions, variables,
etc, all of which should probably have their own docstrings.

The primary focus is on making code easily explorable by using
SLIME's `M-.` (`slime-edit-definition`). See how to enable some
fanciness in @MGL-PAX-EMACS-INTEGRATION. Generating documentation
from sections and all the referenced items in Markdown or HTML
format is also implemented.

With the simplistic tools provided, one may accomplish similar
effects as with Literate Programming, but documentation is generated
from code, not vice versa and there is no support for chunking yet.
Code is first, code must look pretty, documentation is code.

In typical use, PAX packages have no :EXPORT's defined. Instead the
DEFINE-PACKAGE form gets a docstring which may mention section
names (defined with DEFSECTION). When the code is loaded into the
lisp, pressing `M-.` in SLIME on the name of the section will take
you there. Sections can also refer to other sections, packages,
functions, etc and you can keep exploring.

Here is an example of how it all works together:

```commonlisp
(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")
  "Here you describe what's common to all the referenced (and
  exported) functions that follow. They work with *FOO-STATE*,
  and have a :RANDOM-STATE keyword arg. Also explain when to
  choose which."
  (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)
  ==> #
  ```")
```

Generating documentation in a very stripped down markdown format is
easy:

```commonlisp
(describe @foo-random-manual)
```

For this example, the generated markdown would look like this:

    # Foo Random manual
    
    ###### \[in package FOO-RANDOM\]
    Here you describe what's common to all the referenced (and
    exported) functions that follow. They work with *FOO-STATE*,
    and have a :RANDOM-STATE keyword arg. Also explain when to
    choose which.
    
    - [class] FOO-RANDOM-STATE
    
    - [reader] STATE FOO-RANDOM-STATE
    
    Hey we can also print states!
    
    - [method] PRINT-OBJECT (OBJECT FOO-RANDOM-STATE) STREAM
    
    - [variable] *FOO-STATE* #
    
        Much like *RANDOM-STATE* but uses the FOO algorithm.
    
    - [function] GAUSSIAN-RANDOM STDDEV &KEY (RANDOM-STATE *FOO-STATE*)
    
        Return a random number from a zero mean normal distribution with
        STDDEV.
    
    - [function] UNIFORM-RANDOM LIMIT &KEY (RANDOM-STATE *FOO-STATE*)
    
        Return a random number from the between 0 and LIMIT (exclusive)
        uniform distribution.
    
    ## 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)
    ==> #
    
    ```

More fancy markdown or HTML output with automatic markup and linking
of uppercase symbol names found in docstrings, section numbering,
table of contents, etc is possible by calling the DOCUMENT function.

*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.* For a complete example of how to generate
HTML with multiple pages, see `src/doc.lisp`.

Note how `(VARIABLE *FOO-STATE*)` in the DEFSECTION form both
exports `*FOO-STATE*` and includes its documentation in
`@FOO-RANDOM-MANUAL`. The symbols VARIABLE and FUNCTION are just two
instances of 'locatives' which are used in DEFSECTION to refer to
definitions tied to symbols. See @MGL-PAX-LOCATIVE-TYPES.

The transcript in the code block tagged with `cl-transcript` is
automatically checked for up-to-dateness. See
@MGL-PAX-TRANSCRIPT.

## Emacs Integration

Integration into SLIME's `M-.` (`slime-edit-definition`) allows one
to visit the source location of the thing that's identified by a
symbol and the locative before or after the symbol in a buffer. With
this extension, if a locative is the previous or the next expression
around the symbol of interest, then `M-.` will go straight to the
definition which corresponds to the locative. If that fails, `M-.`
will try to find the definitions in the normal way which may involve
popping up an xref buffer and letting the user interactively select
one of possible definitions.

*Note that the this feature is implemented in terms of
SWANK-BACKEND:FIND-SOURCE-LOCATION and
SWANK-BACKEND:FIND-DEFINITIONS whose support varies across the Lisp
implementations.*

In the following examples, pressing `M-.` when the cursor is on one
of the characters of `FOO` or just after `FOO`, will visit the
definition of function `FOO`:

    function foo
    foo function
    (function foo)
    (foo function)

In particular, references in a DEFSECTION form are in (SYMBOL
LOCATIVE) format so `M-.` will work just fine there.

Just like vanilla `M-.`, this works in comments and docstrings. In
this example pressing `M-.` on `FOO` will visit `FOO`'s default
method:

```commonlisp
;;;; See FOO `(method () (t t t))` for how this all works.
;;;; But if the locative has semicolons inside: FOO `(method
;;;; () (t t t))`, then it won't, so be wary of line breaks
;;;; in comments.
```

With a prefix argument (`C-u M-.`), one can enter a symbol plus a
locative separated by whitespace to preselect one of the
possibilities.

The `M-.` extensions can be enabled by adding this to your Emacs
initialization file (or loading `src/pax.el`):

```elisp
;;; MGL-PAX M-. integration

(defun slime-edit-locative-definition (name &optional where)
  (or (slime-locate-definition name (slime-locative-before))
      (slime-locate-definition name (slime-locative-after))
      (slime-locate-definition name (slime-locative-after-in-brackets))
      ;; support "foo function" and "function foo" syntax in
      ;; interactive use
      (let ((pos (cl-position ?\s name)))
        (when pos
          (or (slime-locate-definition (cl-subseq name 0 pos)
                                       (cl-subseq name (1+ pos)))
              (slime-locate-definition (cl-subseq name (1+ pos))
                                       (cl-subseq name 0 pos)))))))

(defun slime-locative-before ()
  (ignore-errors (save-excursion
                   (slime-beginning-of-symbol)
                   (slime-last-expression))))

(defun slime-locative-after ()
  (ignore-errors (save-excursion
                   (slime-end-of-symbol)
                   (slime-forward-sexp)
                   (slime-last-expression))))

(defun slime-locative-after-in-brackets ()
  (ignore-errors (save-excursion
                   (slime-end-of-symbol)
                   (skip-chars-forward "`" (+ (point) 1))
                   (when (and (= 1 (skip-chars-forward "\\]" (+ (point) 1)))
                              (= 1 (skip-chars-forward "\\[" (+ (point) 1))))
                     (buffer-substring-no-properties
                      (point)
                      (progn (search-forward "]" nil (+ (point) 1000))
                             (1- (point))))))))

(defun slime-locate-definition (name locative)
  (when locative
    (let ((location
           (slime-eval
            ;; Silently fail if mgl-pax is not loaded.
            `(cl:when (cl:find-package :mgl-pax)
                      (cl:funcall
                       (cl:find-symbol
                        (cl:symbol-name :locate-definition-for-emacs) :mgl-pax)
                       ,name ,locative)))))
      (when (and (consp location)
                 (not (eq (car location) :error)))
        (slime-edit-definition-cont
         (list (make-slime-xref :dspec `(,name)
                                :location location))
         "dummy name"
         where)))))

(add-hook 'slime-edit-definition-hooks 'slime-edit-locative-definition)
```

## Basics

Now let's examine the most important pieces in detail.

- [macro] DEFSECTION NAME (&KEY (PACKAGE '\*PACKAGE\*) (READTABLE '\*READTABLE\*) (EXPORT T) TITLE (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][class] object. By convention, section names
    start with the character `@`. See @MGL-PAX-TUTORIAL for an example.
    
    ENTRIES consists of docstrings and references. Docstrings are
    arbitrary strings in markdown format, references are defined in the
    form:
    
        (symbol 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))`.
    
    A locative in a reference can either be a symbol or it can be a list
    whose CAR is a symbol. In either case, the symbol is the called the
    type of the locative while the rest of the elements are the locative
    arguments. See @MGL-PAX-LOCATIVE-TYPES for the list of locative
    types available out of the box.
    
    The same symbol can occur multiple times in a reference, typically
    with different locatives, but this is not required.
    
    The references are not looked up (see RESOLVE in the
    @MGL-PAX-EXTENSION-API) until documentation is generated, so it is
    allowed to refer to things yet to be defined.
    
    If EXPORT is true (the default), the referenced symbols and NAME are
    candidates for exporting. A candidate symbol is exported if
    
    - it is accessible in PACKAGE (it's not `OTHER-PACKAGE:SOMETHING`)
      and
    
    - there is a reference to it in the section being defined with a
      locative whose type is approved by EXPORTABLE-LOCATIVE-TYPE-P.
    
    See DEFINE-PACKAGE if you use the export feature. The idea with
    confounding documentation and exporting is to force documentation of
    all exported symbols.
    
    When DISCARD-DOCUMENTATION-P (defaults to *DISCARD-DOCUMENTATION-P*)
    is true, ENTRIES will not be recorded to save memory.

- [variable] *DISCARD-DOCUMENTATION-P* NIL

    The default value of DEFSECTION'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 but silences warnings and errors
    signaled 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 (as is the case with DEFSECTION) as
    opposed to adding :EXPORT forms to the DEFPACKAGE form and the
    package definition is 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.

- [function] DOCUMENT OBJECT &KEY STREAM PAGES (FORMAT :MARKDOWN)

    Write OBJECT in FORMAT to STREAM diverting some output to PAGES.
    FORMAT can be anything [3BMD][3bmd] supports which is
    currently :MARKDOWN, :HTML and :PLAIN. STREAM may be a stream
    object, T or NIL as with CL:FORMAT.
    
    Most often, this function is called on section objects
    like `(DOCUMENT @MGL-PAX-MANUAL)`, but it supports all kinds of
    objects for which DOCUMENT-OBJECT is defined. To look up the
    documentation of function DOCUMENT:
    
        (document #'document)
    
    To generate the documentation for separate libraries with automatic
    cross-links:
    
        (document (list @cube-manual @mat-manual))
    
    Note that not only first class objects can have documentation. For
    instance, variables and deftypes are not represented by objects.
    That's why CL:DOCUMENTATION has a DOC-TYPE argument. DOCUMENT does
    not have anything like that, instead it relies on REFERENCE objects
    to carry the extra information. We are going to see later how
    references and locatives work. Until then, here is an example on how
    to look up the documentation of type `FOO`:
    
        (document (locate 'foo 'type))
    
    One can call DESCRIBE on [SECTION][class] objects to get
    documentation in markdown format with less markup than the default.
    See DESCRIBE-OBJECT `(METHOD () (SECTION T))`.
    
    There are quite a few special variables that affect how output is
    generated, see @MGL-PAX-DOCUMENTATION-PRINTER-VARIABLES.
    
    The rest of this description deals with how to generate multiple
    pages.
    
    The PAGES argument is to create multi-page documents by routing some
    of the generated output to files, strings or streams. PAGES is a
    list of page specification elements. A page spec is a plist with
    keys :OBJECTS, :OUTPUT, :URI-FRAGMENT, :SOURCE-URI-FN, :HEADER-FN
    and :FOOTER-FN. OBJECTS is a list of objects (references are allowed
    but not required) whose documentation is to be sent to `OUTPUT`.
    `OUTPUT` can be a number things:
    
    - If it's a list whose first element is a string or a pathname, then
      output will be sent to the file denoted by that and the rest of
      the elements of the list are passed on as arguments to CL:OPEN.
      One extra keyword argument is :ENSURE-DIRECTORIES-EXIST. If it's
      true, ENSURE-DIRECTORIES-EXIST will be called on the pathname
      before it's opened.
    
    - If it's NIL, then output will be collected in a string.
    
    - If it's T, then output will be sent to *STANDARD-OUTPUT*.
    
    - If it's a stream, then output will be sent to that stream.
    
    If some pages are specified, DOCUMENT returns a list of designators
    for generated output. If a page whose `OUTPUT` refers to a file that
    was created (which doesn't happen if nothing would be written to
    it), then the corresponding pathname is included in the list. For
    strings the string itself, while for streams the stream object is
    included in the list. This way it's possible to write some pages to
    files and some to strings and have the return value indicate what
    was created. The output designators in the returned list are ordered
    by creation time.
    
    If no PAGES are specified, DOCUMENT returns a single pathname,
    string or stream object according to the value of the STREAM
    argument.
    
    Note that even if PAGES is specified, STREAM acts as a catch all
    taking the generated documentation for references not claimed by any
    pages. Also, the filename, string or stream corresponding to STREAM
    is always the first element in list of generated things that is the
    return value.
    
    HEADER-FN, if not NIL, is a function of a single stream argument
    which is called just before the first write to the page.
    Since :FORMAT :HTML only generates HTML fragments, this makes it
    possible to print arbitrary headers, typically setting the title,
    css stylesheet, or charset.
    
    FOOTER-FN is similar to HEADER-FN, but it's called after the last
    write to the page. For HTML, it typically just closes the body.
    
    URI-FRAGMENT is a string such as `"doc/manual.html"` that specifies
    where the page will be deployed on a webserver. It defines how links
    between pages will look. If it's not specified and `OUTPUT` refers
    to a file, then it defaults to the name of the file. If URI-FRAGMENT
    is NIL, then no links will be made to or from that page.
    
    Finally, SOURCE-URI-FN is a function of a single, REFERENCE
    argument. If it returns a value other than NIL, then it must be a
    string representing an URI. If FORMAT is :HTML and
    *DOCUMENT-MARK-UP-SIGNATURES* is true, then the locative as
    displayed in the signature will be a link to this uri. See
    MAKE-GITHUB-SOURCE-URI-FN.
    
    PAGES may look something like this:
    
    ```commonlisp
    `((;; The section about SECTIONs and everything below it ...
       :objects (,@mgl-pax-sections)
       ;; ... is so boring that it's not worth the disk space, so
       ;; send it to a string.
       :output (nil)
       ;; Explicitly tell other pages not to link to these guys.
       :uri-fragment nil)
      ;; Send the @MGL-PAX-EXTENSIONS section and everything reachable
      ;; from it ...
      (:objects (,@mgl-pax-extension-api)
       ;; ... to build/tmp/pax-extension-api.html.
       :output ("build/tmp/pax-extension-api.html")
       ;; However, on the web server html files will be at this
       ;; location relative to some common root, so override the
       ;; default:
       :uri-fragment "doc/dev/pax-extension-api.html"
       ;; Set html page title, stylesheet, charset.
       :header-fn 'write-html-header
       ;; Just close the body.
       :footer-fn 'write-html-footer)
      (:objects (,@mgl-pax-manual)
       :output ("build/tmp/manual.html")
       ;; Links from the extension api page to the manual page will
       ;; be to ../user/pax-manual#, while links going to
       ;; the opposite direction will be to
       ;; ../dev/pax-extension-api.html#.
       :uri-fragment "doc/user/pax-manual.html"
       :header-fn 'write-html-header
       :footer-fn 'write-html-footer))
    ```


## Markdown Support

The [Markdown][markdown] in docstrings is processed with the
[3BMD][3bmd] library.

### Indentation

Docstrings can be indented in any of the usual styles. PAX
normalizes indentation by converting:

    (defun foo ()
      "This is
      indented
      differently")

to

    (defun foo ()
      "This is
    indented
    differently")

See [DOCUMENT-OBJECT][(method () (string t))] for the details.

### Syntax highlighting

For syntax highlighting, github's [fenced code
blocks][fenced-code-blocks] markdown extension to mark up code
blocks with triple backticks is enabled so all you need to do is
write:

    ```elisp
    (defun foo ())
    ```

to get syntactically marked up HTML output. Copy `doc/style.css`
from PAX and you are set. The language tag, `elisp` in this example,
is optional and defaults to `common-lisp`.

See the documentation of [3BMD][3bmd] and [colorize][colorize] for
the details.

[3bmd]: https://github.com/3b/3bmd 

[colorize]: https://github.com/redline6561/colorize/ 

[fenced-code-blocks]: https://help.github.com/articles/github-flavored-markdown#fenced-code-blocks 


### MathJax

Displaying pretty mathematics in TeX format is supported via
MathJax. It can be done inline with `$` like this:

    $\int_0^\infty e^{-x^2} dx=\frac{\sqrt{\pi}}{2}$

which is diplayed as $\int\_0^\infty e^{-x^2}
dx=\frac{\sqrt{\pi}}{2}$, or it can be delimited by `$$` like this:

    $$\int_0^\infty e^{-x^2} dx=\frac{\sqrt{\pi}}{2}$$

to get: $$\int\_0^\infty e^{-x^2} dx=\frac{\sqrt{\pi}}{2}$$

MathJax will leave code blocks (including those inline with
backticks) alone. Outside code blocks, escape `$` by prefixing it
with a backslash to scare MathJax off.

Escaping all those backslashes in TeX fragments embedded in Lisp
strings can be pain. [Pythonic String
Reader](https://github.com/smithzvk/pythonic-string-reader) can help
with that.

## Documentation Printer Variables

Docstrings are assumed to be in markdown format and they are pretty
much copied verbatim to the documentation subject to a few knobs
described below.

- [variable] *DOCUMENT-UPPERCASE-IS-CODE* T

    When true, words with at least three characters and no lowercase
    characters naming an interned symbol are assumed to be code as if
    they were marked up with backticks which is especially useful when
    combined with *DOCUMENT-LINK-CODE*. For example, this docstring:
    
        "`FOO` and FOO."
    
    is equivalent to this:
    
        "`FOO` and `FOO`."
    
    iff `FOO` is an interned symbol. To suppress this behavior, add a
    backslash to the beginning of the symbol or right after the leading
    \* if it would otherwise be parsed as markdown emphasis:
    
        "\\MGL-PAX *\\DOCUMENT-NORMALIZE-PACKAGES*"
    
    The number of backslashes is doubled above because that's how the
    example looks in a docstring. Note that the backslash is discarded
    even if *DOCUMENT-UPPERCASE-IS-CODE* is false.

- [variable] *DOCUMENT-LINK-CODE* T

    When true, during the process of generating documentation for a
    [SECTION][class], HTML anchors are added before the documentation of
    every reference that's not to a section. Also, markdown style
    reference links are added when a piece of inline code found in a
    docstring refers to a symbol that's referenced by one of the
    sections being documented. Assuming `BAR` is defined, the
    documentation for:
    
    ```commonlisp
    (defsection @foo
      (foo function)
      (bar function))
    
    (defun foo (x)
      "Calls `BAR` on `X`."
      (bar x))
    ```
    
    would look like this:
    
        - [function] FOO X
        
            Calls [`BAR`][1] on `X`.
    
    Instead of `BAR`, one can write `[bar][]` or ``[`bar`][]`` as well.
    Since symbol names are parsed according to READTABLE-CASE, character
    case rarely matters.
    
    Now, if `BAR` has references with different locatives:
    
    ```commonlisp
    (defsection @foo
      (foo function)
      (bar function)
      (bar type))
    
    (defun foo (x)
      "Calls `BAR` on `X`."
      (bar x))
    ```
    
    then documentation would link to all interpretations:
    
        - [function] FOO X
        
            Calls `BAR`([`1`][link-id-1] [`2`][link-id-2]) on `X`.
    
    This situation occurs in PAX with SECTION which is both a class (see
    [SECTION][class]) and a locative type denoted by a symbol (see
    [SECTION][locative]). Back in the example above, clearly,
    there is no reason to link to type `BAR`, so one may wish to select
    the function locative. There are two ways to do that. One is to
    specify the locative explicitly as the id of a reference link:
    
        "Calls [BAR][function] on X."
    
    However, if in the text there is a locative immediately before or
    after the symbol, then that locative is used to narrow down the
    range of possibilities. This is similar to what the `M-.` extension
    does. In a nutshell, if `M-.` works without questions then the
    documentation will contain a single link. So this also works without
    any markup:
    
        "Calls function `BAR` on X."
    
    This last option needs backticks around the locative if it's not a
    single symbol.
    
    Note that [*DOCUMENT-LINK-CODE*][variable] can be combined with
    [`*DOCUMENT-UPPERCASE-IS-CODE*`][] to have links generated for
    uppercase names with no quoting required.

- [variable] *DOCUMENT-LINK-SECTIONS* T

    When true, HTML anchors are generated before the heading of
    sections which allows the table of contents to contain links and
    also code-like references to sections (like `@FOO-MANUAL`) to be
    translated to links with the section title being the name of the
    link.

- [variable] *DOCUMENT-MIN-LINK-HASH-LENGTH* 4

    Recall that markdown reference style links (like `[label][id]`) are
    used for linking to sections and code. It is desirable to have ids
    that are short to maintain legibility of the generated markdown, but
    also stable to reduce the spurious diffs in the generated
    documentation which can be a pain in a version control system.
    
    Clearly, there is a tradeoff here. This variable controls how many
    characters of the md5 sum of the full link id (the reference as a
    string) are retained. If collisions are found due to the low number
    of characters, then the length of the hash of the colliding
    reference is increased.
    
    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
    rendered as bold and italic. In :HTML output, locative types become
    links to sources (if :SOURCE-URI-FN is provided, see DOCUMENT), and
    the symbol becomes a self-link for your permalinking pleasure.
    
    For example, a reference is rendered in markdown roughly as:
    
        - [function] foo x y
    
    With this option on, the above becomes:
    
        - [function] **foo** *x y*
    
    Also, in HTML `**foo**` will be a link to that very entry and
    `[function]` may turn into a link to sources.

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

    A non-negative integer. Top-level sections are given a table of
    contents which includes a nested tree of section titles whose depth
    is limited by this value. Setting it to 0 turns generation of the
    table of contents off. If *DOCUMENT-LINK-SECTIONS* is true, then the
    table of contents 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* to be on to work.

- [variable] *DOCUMENT-FANCY-HTML-NAVIGATION* T

    If true and the output format is HTML, then headings get a
    navigation component that consists of links to the previous, parent,
    next section and a permalink. This component is normally hidden, it
    is visible only when the mouse is over the heading. Needs
    *DOCUMENT-LINK-SECTIONS* to be on to work.

- [variable] *DOCUMENT-NORMALIZE-PACKAGES* T

    If true, symbols are printed relative to SECTION-PACKAGE of the
    innermost containing section or with full package names if there is
    no containing section. To eliminate ambiguity `[in package ...]`
    messages are printed right after the section heading if necessary.
    If false, symbols are always printed relative to the current
    package.

## Locative Types

These are the locatives type supported out of the box. As all
locative types, they are symbols and their names should make it
obvious what kind of things they refer to. Unless otherwise noted,
locatives take no arguments.

- [locative] ASDF/SYSTEM:SYSTEM

    Refers to an asdf system. The generated documentation will include
    meta information extracted from the system definition. This also
    serves as an example of a symbol that's not accessible in the
    current package and consequently is not exported.

- [locative] SECTION

    Refers to a section defined by DEFSECTION.

- [locative] VARIABLE &OPTIONAL INITFORM

    Refers to a global special variable. INITFORM, or if not specified,
    the global value of the variable is included in the documentation.

- [locative] CONSTANT &OPTIONAL INITFORM

    Refers to a DEFCONSTANT. INITFORM, or if not specified,
    the value of the constant is included in the documentation.

- [locative] MACRO

- [locative] COMPILER-MACRO

- [locative] FUNCTION

    Note that the arglist in the generated documentation depends on
    the quality of SWANK-BACKEND:ARGLIST. It may be that default
    values of optional and keyword arguments are missing.

- [locative] GENERIC-FUNCTION

- [locative] METHOD METHOD-QUALIFIERS METHOD-SPECIALIZERS

    See CL:FIND-METHOD for the description of the arguments.
    To refer to the default method of the three argument generic
    function FOO:
    
        (foo (method () (t t t)))


- [locative] ACCESSOR CLASS-NAME

    To refer to an accessor named `FOO-SLOT` of class
    `FOO`:
    
        (foo-slot (accessor foo))


- [locative] READER CLASS-NAME

    To refer to a reader named `FOO-SLOT` of class
    `FOO`:
    
        (foo-slot (reader foo))


- [locative] WRITER CLASS-NAME

    To refer to a writer named `FOO-SLOT` of class
    `FOO`:
    
        (foo-slot (writer foo))


- [locative] STRUCTURE-ACCESSOR

    This is a synonym of FUNCTION with the difference that the often
    ugly and certainly uninformative lambda list will not be printed.

- [locative] CLASS

- [locative] CONDITION

- [locative] TYPE

    TYPE can refer to classes as well, but it's better style to use the
    more specific CLASS locative type for that. Another difference to
    CLASS is that an attempt is made at printing the arguments of type
    specifiers.

- [locative] PACKAGE

- [locative] DISLOCATED

    Refers to a symbol in a non-specific context. Useful for preventing
    autolinking. For example, if there is a function called `FOO` then
    
        `FOO`
    
    will be linked to (if *DOCUMENT-LINK-CODE*) its definition. However,
    
        [`FOO`][dislocated]
    
    will not be. On a dislocated locative LOCATE always fails with a
    LOCATE-ERROR condition.

- [locative] LOCATIVE LAMBDA-LIST

    This is the locative for locatives. When `M-.` is pressed on
    `VARIABLE` in `(VARIABLE LOCATIVE)`, this is what makes it possible
    to land at the `(DEFINE-LOCATIVE-TYPE VARIABLE ...)` form.
    Similarly, `(LOCATIVE LOCATIVE)` leads to this very definition.

- [locative] INCLUDE SOURCE &KEY LINE-PREFIX HEADER FOOTER HEADER-NL FOOTER-NL

    Refers to a region of a file. SOURCE can be a string or a
    pathname in which case the whole file is being pointed to or it can
    explicitly supply START, END locatives. INCLUDE is typically used to
    include non-lisp files in the documentation (say markdown or elisp
    as in the next example) or regions of lisp source files. This can
    reduce clutter and duplication.
    
    ```commonlisp
    (defsection example-section ()
      (pax.el (include #.(asdf:system-relative-pathname :mgl-pax "src/pax.el")
                       :header-nl "```elisp" :footer-nl "```"))
      (foo-example (include (:start (foo function)
                             :end (end-of-foo-example variable))
                            :header-nl "```commonlisp"
                            :footer-nl "```"))
    
    (defun foo (x)
      (1+ x))
    
    ;;; Since file regions are copied verbatim, comments survive.
    (defmacro bar ())
    
    ;;; This comment is the last thing in FOO-EXAMPLE's
    ;;; documentation since we use the dummy END-OF-FOO-EXAMPLE
    ;;; variable to mark the end location.
    (defvar end-of-foo-example)
    
    ;;; More irrelevant code follows.
    ```
    
    In the above example, pressing `M-.` on PAX.EL will open the
    `src/pax.el` file and put the cursor on its first character. `M-.`
    on `FOO-EXAMPLE` will go to the source location of the `(asdf:system
    locative)` locative.
    
    When documentation is generated, the entire `pax.el` file is
    included in the markdown surrounded by the strings given as
    HEADER-NL and FOOTER-NL (if any). The trailing newline character is
    assumed implicitly. If that's undesirable, then use HEADER and
    FOOTER instead. The documentation of `FOO-EXAMPLE` will be the
    region of the file from the source location of the START
    locative (inclusive) to the source location of the END
    locative (exclusive). START and END default to the beginning and end
    of the file, respectively.
    
    Note that the file of the source location of :START and :END must be
    the same. If SOURCE is pathname designator, then it must be absolute
    so that the locative is context independent.
    
    Finally, if specified LINE-PREFIX is a string that's prepended to
    each line included in the documentation. For example, a string of
    four spaces makes markdown think it's a code block.

## Extension API

### Locatives and References

While Common Lisp has rather good introspective abilities, not
everything is first class. For example, there is no object
representing the variable defined with `(DEFVAR
FOO)`. `(MAKE-REFERENCE 'FOO 'VARIABLE)` constructs a REFERENCE that
captures the path to take from an object (the symbol FOO) to an
entity of interest (for example, the documentation of the variable).
The path is called the locative. A locative can be applied to an
object like this:

    (locate 'foo 'variable)

which will return the same reference as `(MAKE-REFERENCE 'FOO
'VARIABLE)`. Operations need to know how to deal with references
which we will see in LOCATE-AND-COLLECT-REACHABLE-OBJECTS,
LOCATE-AND-DOCUMENT and LOCATE-AND-FIND-SOURCE.

Naturally, `(LOCATE 'FOO 'FUNCTION)` will simply return `#'FOO`, no
need to muck with references when there is a perfectly good object.

- [function] LOCATE OBJECT LOCATIVE &KEY (ERRORP T)

    Follow LOCATIVE from OBJECT and return the object it leads to or a
    REFERENCE if there is no first class object corresponding to the
    location. If ERRORP, then a LOCATE-ERROR condition is signaled when
    lookup fails.

- [condition] LOCATE-ERROR ERROR

    Signaled by LOCATE when lookup fails and ERRORP is
    true.

- [reader] LOCATE-ERROR-MESSAGE LOCATE-ERROR (:MESSAGE)

- [reader] LOCATE-ERROR-OBJECT LOCATE-ERROR (:OBJECT)

- [reader] LOCATE-ERROR-LOCATIVE LOCATE-ERROR (:LOCATIVE)

- [function] RESOLVE REFERENCE &KEY (ERRORP T)

    A convenience function to LOCATE REFERENCE's object with its
    locative.

- [class] REFERENCE

    A REFERENCE represents a path (REFERENCE-LOCATIVE)
    to take from an object (REFERENCE-OBJECT).

- [reader] REFERENCE-OBJECT REFERENCE (:OBJECT)

- [reader] REFERENCE-LOCATIVE REFERENCE (:LOCATIVE)

- [function] MAKE-REFERENCE OBJECT LOCATIVE

- [function] LOCATIVE-TYPE LOCATIVE

    The first element of LOCATIVE if it's a list. If it's a symbol then
    it's that symbol itself. Typically, methods of generic functions
    working with locatives take locative type and locative args as
    separate arguments to allow methods have eql specializers on the
    type symbol.

- [function] LOCATIVE-ARGS LOCATIVE

    The REST of LOCATIVE if it's a list. If it's a symbol then
    it's ().

### Adding New Object Types

One may wish to make the DOCUMENT function and `M-.` navigation
work with new object types. Extending DOCUMENT can be done by
defining a DOCUMENT-OBJECT method. To allow these objects to be
referenced from DEFSECTION a LOCATE-OBJECT method is to be defined.
Finally, for `M-.` FIND-SOURCE can be specialized. Finally,
EXPORTABLE-LOCATIVE-TYPE-P may be overridden if exporting does not
makes sense. Here is a stripped down example of how all this is done
for ASDF:SYSTEM:

```commonlisp
(define-locative-type asdf:system ()
  "Refers to an asdf system. The generated documentation will include
  meta information extracted from the system definition. This also
  serves as an example of a symbol that's not accessible in the
  current package and consequently is not exported.")

(defmethod locate-object (symbol (locative-type (eql 'asdf:system))
                          locative-args)
  (assert (endp locative-args))
  ;; FIXME: This is slow as hell.
  (or (asdf:find-system symbol nil)
      (locate-error)))

(defmethod canonical-reference ((system asdf:system))
  (make-reference (asdf/find-system:primary-system-name system) 'asdf:system))

(defmethod document-object ((system asdf:system) stream)
  (with-heading (stream system
                        (format nil "~A ASDF System Details"
                                (asdf/find-system:primary-system-name system)))
    (flet ((foo (name fn &key type)
             (let ((value (funcall fn system)))
               (when value
                 (case type
                   ((:link)
                    (format stream "- ~A: [~A](~A)~%" name value value))
                   ((:mailto)
                    (format stream "- ~A: [~A](mailto:~A)~%"
                            name value value))
                   ((nil)
                    (format stream "- ~A: ~A~%" name value)))))))
      (foo "Version" 'asdf/component:component-version)
      (foo "Description" 'asdf/system:system-description)
      (foo "Licence" 'asdf/system:system-licence)
      (foo "Author" 'asdf/system:system-author)
      (foo "Maintainer" 'asdf/system:system-maintainer)
      (foo "Mailto" 'asdf/system:system-mailto :type :mailto)
      (foo "Homepage" 'asdf/system:system-homepage :type :link)
      (foo "Bug tracker" 'asdf/system:system-bug-tracker)
      (foo "Long description" 'asdf/system:system-long-description))))

(defmethod find-source ((system asdf:system))
  `(:location
    (:file ,(namestring (asdf/system:system-source-file system)))
    (:position 1)
    (:snippet "")))

```

- [macro] DEFINE-LOCATIVE-TYPE LOCATIVE-TYPE LAMBDA-LIST &BODY DOCSTRING

    Declare LOCATIVE-TYPE as a [LOCATIVE][locative]. One gets two
    things in return: first, a place to document the format and
    semantics of LOCATIVE-TYPE (in LAMBDA-LIST and DOCSTRING); second,
    being able to reference `(LOCATIVE-TYPE LOCATIVE)`. For example, if
    you have:
    
    ```common-lisp
    (define-locative-type variable (&optional initform)
      "Dummy docstring.")
    ```
    
    then `(VARIABLE LOCATIVE)` refers to this form.

- [generic-function] EXPORTABLE-LOCATIVE-TYPE-P LOCATIVE-TYPE

    Return true iff symbols in references with
    LOCATIVE-TYPE are to be exported by default when they occur in a
    DEFSECTION. The default method returns T, while the methods for
    PACKAGE, ASDF:SYSTEM and METHOD return NIL.
    
    DEFSECTION calls this function to decide what symbols to export when
    its EXPORT argument is true.

- [generic-function] LOCATE-OBJECT OBJECT LOCATIVE-TYPE LOCATIVE-ARGS

    Return the object OBJECT + locative refers to. For
    example, if LOCATIVE-TYPE is the symbol PACKAGE, this
    returns `(FIND-PACKAGE SYMBOL)`. Signal a LOCATE-ERROR condition by
    calling the LOCATE-ERROR function if lookup fails. Signal other
    errors if the types of the argument are bad, for instance
    LOCATIVE-ARGS is not the empty list in the package example. If a
    REFERENCE is returned then it must be canonical in the sense that
    calling CANONICAL-REFERENCE on it will return the same reference.
    For extension only, don't call this directly.

- [function] LOCATE-ERROR &REST FORMAT-AND-ARGS

    Call this function to signal a LOCATE-ERROR condition from a
    LOCATE-OBJECT method. FORMAT-AND-ARGS contains a format string and
    args suitable for FORMAT from which the LOCATE-ERROR-MESSAGE is
    constructed. If FORMAT-AND-ARGS is NIL, then the message will be NIL
    too.
    
    The object and the locative are not specified, they are added by
    LOCATE when it resignals the condition.

- [generic-function] CANONICAL-REFERENCE OBJECT

    Return a REFERENCE that resolves to OBJECT.

- [generic-function] COLLECT-REACHABLE-OBJECTS OBJECT

    Return a list of objects representing all things
    that would be documented in a (DOCUMENT OBJECT) call. For sections
    this is simply the union of references reachable from references in
    SECTION-ENTRIES. The returned objects can be anything provided that
    CANONICAL-REFERENCE works on them. The list need not include OBJECT
    itself.
    
    One only has to specialize this for new container-like objects.

- [method] COLLECT-REACHABLE-OBJECTS OBJECT

    This default implementation returns the empty list. This means that
    nothing is reachable from OBJECT.

- [generic-function] DOCUMENT-OBJECT OBJECT STREAM

    Write OBJECT (and its references recursively) in
    FORMAT to STREAM.
    
    The DOCUMENT function calls this generic function with LEVEL 0,
    passing FORMAT on. Add methods specializing on OBJECT to customize
    how objects of that type are presented in the documentation.

- [method] DOCUMENT-OBJECT (STRING STRING) STREAM

    Print STRING verbatim to STREAM after cleaning up indentation.
    
    Docstrings in sources are indented in various ways which can easily
    mess up markdown. To handle the most common cases leave the first
    line alone, but from the rest of the lines strip the longest run of
    leading spaces that is common to all non-blank lines.

- [generic-function] FIND-SOURCE OBJECT

    Like SWANK:FIND-DEFINITION-FOR-THING, but this
    one is a generic function to be extensible. In fact, the default
    implementation simply defers to SWANK:FIND-DEFINITION-FOR-THING.
    This function is called by LOCATE-DEFINITION-FOR-EMACS which lies
    behind the `M-.` extension (see @MGL-PAX-EMACS-INTEGRATION).
    
    If successful, the return value looks like this:
    
    ```commonlisp
    (:location (:file "/home/mega/own/mgl/pax/test/test.lisp")
               (:position 24) nil)
    ```
    
    The NIL is the source snippet which is optional. Note that position
    1 is the first character. If unsuccessful, the return values is
    like:
    
    ```commonlisp
    (:error "Unknown source location for SOMETHING")
    ```


### Reference Based Extensions

Let's see how to extend DOCUMENT and `M-.` navigation if there is
no first class object to represent the thing of interest. Recall
that LOCATE returns a REFERENCE object in this case. DOCUMENT-OBJECT
and FIND-SOURCE defer to LOCATE-AND-DOCUMENT and
LOCATE-AND-FIND-SOURCE which have LOCATIVE-TYPE in their argument
list for EQL specializing pleasure. Here is a stripped down example
of how the VARIABLE locative is defined:

```commonlisp
(define-locative-type variable (&optional initform)
  "Refers to a global special variable. INITFORM, or if not specified,
  the global value of the variable is included in the documentation.")

(defmethod locate-object (symbol (locative-type (eql 'variable)) locative-args)
  (assert (<= (length locative-args) 1))
  (make-reference symbol (cons locative-type locative-args)))

(defmethod locate-and-document (symbol (locative-type (eql 'variable))
                                locative-args stream)
  (destructuring-bind (&optional (initform nil initformp)) locative-args
    (locate-and-print-bullet locative-type locative-args symbol stream)
    (write-char #\Space stream)
    (multiple-value-bind (value unboundp) (symbol-global-value symbol)
      (print-arglist (prin1-to-string (cond (initformp initform)
                                            (unboundp "-unbound-")
                                            (t value)))
                     stream))
    (terpri stream)
    (with-dislocated-symbols ((list symbol))
      (maybe-print-docstring symbol locative-type stream))))

(defmethod locate-and-find-source (symbol (locative-type (eql 'variable))
                                   locative-args)
  (declare (ignore locative-args))
  (find-one-location (swank-backend:find-definitions symbol)
                     '("variable" "defvar" "defparameter"
                       "special-declaration")))

```

- [method] COLLECT-REACHABLE-OBJECTS (REFERENCE REFERENCE)

    If REFERENCE can be resolved to a non-reference, call
    COLLECT-REACHABLE-OBJECTS with it, else call
    LOCATE-AND-COLLECT-REACHABLE-OBJECTS on the object, locative-type,
    locative-args of REFERENCE

- [generic-function] LOCATE-AND-COLLECT-REACHABLE-OBJECTS OBJECT LOCATIVE-TYPE LOCATIVE-ARGS

    Called by COLLECT-REACHABLE-OBJECTS on REFERENCE
    objects, this function has essentially the same purpose as its
    caller but it has different arguments to allow specializing on
    LOCATIVE-TYPE.

- [method] LOCATE-AND-COLLECT-REACHABLE-OBJECTS OBJECT LOCATIVE-TYPE LOCATIVE-ARGS

    This default implementation returns the empty list. This means that
    nothing is reachable from the reference.

- [method] DOCUMENT-OBJECT (REFERENCE REFERENCE) STREAM

    If REFERENCE can be resolved to a non-reference, call
    DOCUMENT-OBJECT with it, else call LOCATE-AND-DOCUMENT-OBJECT on the
    object, locative-type, locative-args of REFERENCE

- [generic-function] LOCATE-AND-DOCUMENT OBJECT LOCATIVE-TYPE LOCATIVE-ARGS STREAM

    Called by DOCUMENT-OBJECT on REFERENCE objects,
    this function has essentially the same purpose as DOCUMENT-OBJECT
    but it has different arguments to allow specializing on
    LOCATIVE-TYPE.

- [method] FIND-SOURCE (REFERENCE REFERENCE)

    If REFERENCE can be resolved to a non-reference, call FIND-SOURCE
    with it, else call LOCATE-AND-FIND-SOURCE on the object,
    locative-type, locative-args of REFERENCE

- [generic-function] LOCATE-AND-FIND-SOURCE OBJECT LOCATIVE-TYPE LOCATIVE-ARGS

    Called by FIND-SOURCE on REFERENCE objects, this
    function has essentially the same purpose as FIND-SOURCE but it has
    different arguments to allow specializing on LOCATIVE-TYPE.

- [method] LOCATE-AND-FIND-SOURCE OBJECT LOCATIVE-TYPE LOCATIVE-ARGS

    This default implementation simply calls FIND-SOURCE with OBJECT
    which should cover the common case of a macro expanding to, for
    instance, a defun but having its own locative type.

We have covered the basic building blocks of reference based
extensions. Now let's see how the obscure
DEFINE-SYMBOL-LOCATIVE-TYPE and
DEFINE-DEFINER-FOR-SYMBOL-LOCATIVE-TYPE macros work together to
simplify the common task of associating definition and documentation
with symbols in a certain context.

- [macro] DEFINE-SYMBOL-LOCATIVE-TYPE LOCATIVE-TYPE LAMBDA-LIST &BODY DOCSTRING

    Similar to DEFINE-LOCATIVE-TYPE but it assumes that all things
    locatable with LOCATIVE-TYPE are going to be just symbols defined
    with a definer defined with DEFINE-DEFINER-FOR-SYMBOL-LOCATIVE-TYPE.
    It is useful to attach documentation and source location to symbols
    in a particular context. An example will make everything clear:
    
    ```commonlisp
    (define-symbol-locative-type direction ()
      "A direction is a symbol. (After this `M-.` on `DIRECTION LOCATIVE`
      works and it can also be included in DEFSECTION forms.)")
    
    (define-definer-for-symbol-locative-type define-direction direction ()
      "With DEFINE-DIRECTION one can document how what a symbol means
      when interpreted as a direction.")
    
    (define-direction up ()
      "UP is equivalent to a coordinate delta of (0, -1).")
    ```
    
    After all this, `(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 which can be used to attach documentation,
    a lambda-list and source location to a symbol in the context of
    LOCATIVE-TYPE. The defined macro's arglist is (SYMBOL LAMBDA-LIST
    &OPTIONAL DOCSTRING). LOCATIVE-TYPE is assumed to have been defined
    with DEFINE-SYMBOL-LOCATIVE-TYPE.

### Sections

[Section][class] objects rarely need to be dissected since
DEFSECTION and DOCUMENT cover most needs. However, it is plausible
that one wants to subclass them and maybe redefine how they are
presented.

- [class] SECTION

    DEFSECTION stores its NAME, TITLE and ENTRIES in
    [SECTION][class] objects.

- [reader] SECTION-NAME SECTION (:NAME)

    The name of the global variable whose value is
    this section object.

- [reader] SECTION-PACKAGE SECTION (:PACKAGE)

    *PACKAGE* will be bound to this package when
    generating documentation for this section.

- [reader] SECTION-READTABLE SECTION (:READTABLE)

    *READTABLE* will be bound to this when generating
    documentation for this section.

- [reader] SECTION-TITLE SECTION (:TITLE)

    Used in generated documentation.

- [reader] SECTION-ENTRIES SECTION (:ENTRIES)

    A list of strings and REFERENCE objects in the
    order they occurred in DEFSECTION.

- [method] DESCRIBE-OBJECT (SECTION SECTION) STREAM

    [SECTION][class] objects are printed by calling DOCUMENT on them
    with all @MGL-PAX-DOCUMENTATION-PRINTER-VARIABLES, except for
    *DOCUMENT-NORMALIZE-PACKAGES*, turned off to reduce clutter.

## Transcripts

What are transcripts for? When writing a tutorial, one often wants
to include a REPL session with maybe a few defuns and a couple of
forms whose output or return values are shown. Also, in a function's
docstring an example call with concrete arguments and return values
speaks volumes. A transcript is a text that looks like a repl
session, but which has a light markup for printed output and return
values, while no markup (i.e. prompt) for lisp forms. The PAX
transcripts may include output and return values of all forms, or
only selected ones. In either case the transcript itself can be
easily generated from the source code.

The main worry associated with including examples in the
documentation is that they tend to get out-of-sync with the code.
This is solved by being able to parse back and update transcripts.
In fact, this is exactly what happens during documentation
generation with PAX. Code sections tagged `cl-transcript` are
retranscribed and checked for inconsistency (that is, any difference
in output or return values). If the consistency check fails, an
error is signalled that includes a reference to the object being
documented.

Going beyond documentation, transcript consistency checks can be
used for writing simple tests in a very readable form. For example:

```cl-transcript
(+ 1 2)
=> 3

(values (princ :hello) (list 1 2))
.. HELLO
=> :HELLO
=> (1 2)

```

All in all, transcripts are a handy tool especially when combined
with the Emacs support to regenerate them and with
PYTHONIC-STRING-READER and its triple-quoted strings that allow one
to work with nested strings with less noise. The triple-quote syntax
can be enabled with:

    (in-readtable pythonic-string-syntax)


### Transcribing with Emacs

Typical transcript usage from within Emacs is simple: add a lisp
form to a docstring or comment at any indentation level. Move the
cursor right after the end of the form as if you were to evaluate it
with `C-x C-e`. The cursor is marked by `#\^`:

    This is part of a docstring.
    
    ```cl-transcript
    (values (princ :hello) (list 1 2))^
    ```

Note that the use of fenced code blocks with the language tag
`cl-transcript` is only to tell PAX to perform consistency checks at
documentation generation time.

Now invoke the elisp function `mgl-pax-transcribe` where the cursor
is and the fenced code block from the docstring becomes:

    (values (princ :hello) (list 1 2))
    .. HELLO
    => :HELLO
    => (1 2)
    ^

Then you change the printed message and add a comment to the second
return value:

    (values (princ :hello-world) (list 1 2))
    .. HELLO
    => :HELLO
    => (1
        ;; This value is arbitrary.
        2)

When generating the documentation you get a
TRANSCRIPTION-CONSISTENCY-ERROR because the printed output and the
first return value changed so you regenerate the documentation by
marking the region of bounded by `#\|` and the cursor at `#\^` in
the example:

    |(values (princ :hello-world) (list 1 2))
    .. HELLO
    => :HELLO
    => (1
        ;; This value is arbitrary.
        2)
    ^

then invoke the elisp function `mgl-pax-retranscribe-region` to get:

    (values (princ :hello-world) (list 1 2))
    .. HELLO-WORLD
    => :HELLO-WORLD
    => (1
        ;; This value is arbitrary.
        2)
    ^

Note how the indentation and the comment of `(1 2)` was left alone
but the output and the first return value got updated.

Alternatively, `C-u 1 mgl-pax-transcribe` will emit commented markup:

    (values (princ :hello) (list 1 2))
    ;.. HELLO
    ;=> :HELLO
    ;=> (1 2)

`C-u 0 mgl-pax-retranscribe-region` will turn commented into
non-commented markup. In general, the numeric prefix argument is the
index of the syntax to be used in MGL-PAX:*SYNTAXES*. Without a
prefix argument `mgl-pax-retranscribe-region` will not change the
markup style.

Finally, not only do both functions work at any indentation level,
but in comments too:

    ;;;; (values (princ :hello) (list 1 2))
    ;;;; .. HELLO
    ;;;; => :HELLO
    ;;;; => (1 2)

Transcription support in emacs can be enabled by adding this to your
Emacs initialization file (or loading `src/transcribe.el`):

```elisp
;;; MGL-PAX transcription

(defun mgl-pax-transcribe-last-expression ()
  "A bit like C-u C-x C-e (slime-eval-last-expression) that
inserts the output and values of the sexp before the point, this
does the same but with MGL-PAX:TRANSCRIBE. Use a numeric prefix
argument as in index to select one of the Common Lisp
MGL-PAX:*SYNTAXES* as the SYNTAX argument to MGL-PAX:TRANSCRIBE.
Without a prefix argument, the first syntax is used."
  (interactive)
  (insert
   (save-excursion
     (let* ((end (point))
            (start (progn (backward-sexp)
                          (move-beginning-of-line nil)
                          (point))))
       (mgl-pax-transcribe start end (mgl-pax-transcribe-syntax-arg)
                           nil nil nil)))))

(defun mgl-pax-retranscribe-region (start end)
  "Updates the transcription in the current region (as in calling
MGL-PAX:TRANSCRIBE with :UPDATE-ONLY T). Use a numeric prefix
argument as in index to select one of the Common Lisp
MGL-PAX:*SYNTAXES* as the SYNTAX argument to MGL-PAX:TRANSCRIBE.
Without a prefix argument, the syntax of the input will not be
changed."
  (interactive "r")
  (let* ((point-at-start-p (= (point) start))
         (point-at-end-p (= (point) end))
         (transcript (mgl-pax-transcribe start end
                                         (mgl-pax-transcribe-syntax-arg)
                                         t t nil)))
    (if point-at-start-p
        (save-excursion
          (goto-char start)
          (delete-region start end)
          (insert transcript))
      (save-excursion
          (goto-char start)
          (delete-region start end))
      (insert transcript))))

(defun mgl-pax-transcribe-syntax-arg ()
  (if current-prefix-arg
      (prefix-numeric-value current-prefix-arg)
    nil))

(defun mgl-pax-transcribe (start end syntax update-only echo
                                 first-line-special-p)
  (let ((transcription
         (slime-eval
          `(cl:if (cl:find-package :mgl-pax)
                  (cl:funcall
                   (cl:find-symbol
                    (cl:symbol-name :transcribe-for-emacs) :mgl-pax)
                   ,(buffer-substring-no-properties start end)
                   ',syntax ',update-only ',echo ',first-line-special-p)
                  t))))
    (if (eq transcription t)
        (error "MGL-PAX is not loaded.")
      transcription)))
```

### Transcript API

- [function] TRANSCRIBE INPUT OUTPUT &KEY UPDATE-ONLY (INCLUDE-NO-OUTPUT UPDATE-ONLY) (INCLUDE-NO-VALUE UPDATE-ONLY) (ECHO T) CHECK-CONSISTENCY DEFAULT-SYNTAX (INPUT-SYNTAXES \*SYNTAXES\*) (OUTPUT-SYNTAXES \*SYNTAXES\*)

    Read forms from INPUT and write them (iff ECHO) to OUTPUT
    followed by any output and return values produced by calling EVAL on
    the form. INPUT can be a stream or a string, while OUTPUT can be a
    stream or NIL in which case transcription goes into a string. The
    return value is the OUTPUT stream or the string that was
    constructed.
    
    A simple example is this:
    
    ```cl-transcript
    (transcribe "(princ 42) " nil)
    => "(princ 42)
    .. 42
    => 42
    "
    
    ```
    
    However, the above may be a bit confusing since this documentation
    uses TRANSCRIBE markup syntax in this very example, so let's do it
    differently. If we have a file with these contents:
    
    ```commonlisp
    (values (princ 42) (list 1 2))
    ```
    
    it is transcribed to:
    
    ```commonlisp
    (values (princ 42) (list 1 2))
    .. 42
    => 42
    => (1 2)
    ```
    
    Output to all standard streams is captured and printed with
    the :OUTPUT prefix (`".."`). The return values above are printed
    with the :READABLE prefix (`"=>"`). Note how these prefixes are
    always printed on a new line to facilitate parsing.
    
    **Updating**
    
    TRANSCRIBE is able to parse its own output. If we transcribe the
    previous output above, we get it back exactly. However, if we remove
    all output markers, leave only a placeholder value marker and
    pass :UPDATE-ONLY T with source:
    
    ```commonlisp
    (values (princ 42) (list 1 2))
    =>
    ```
    
    we get this:
    
    ```commonlisp
    (values (princ 42) (list 1 2))
    => 42
    => (1 2)
    ```
    
    With UPDATE-ONLY, printed output of a form is only transcribed if
    there were output markers in the source. Similarly, with
    UPDATE-ONLY, return values are only transcribed if there were value
    markers in the source.
    
    **No Output/Values**
    
    If the form produces no output or returns no values, then whether or
    not output and values are transcribed is controlled by
    INCLUDE-NO-OUTPUT and INCLUDE-NO-VALUE, respectively. By default,
    neither is on so:
    
    ```commonlisp
    (values)
    ..
    =>
    ```
    
    is transcribed to
    
    ```commonlisp
    (values)
    ```
    
    With UPDATE-ONLY true, we probably wouldn't like to lose those
    markers since they were put there for a reason. Hence, with
    UPDATE-ONLY, INCLUDE-NO-OUTPUT and INCLUDE-NO-VALUE default to true.
    So with UPDATE-ONLY the above example is transcribed to:
    
    ```commonlisp
    (values)
    ..
    => ; No value
    ```
    
    where the last line is the :NO-VALUE prefix.
    
    **Consistency Checks**
    
    If CHECK-CONSISTENCY is true, then TRANSCRIBE signals a continuable
    TRANSCRIPTION-OUTPUT-CONSISTENCY-ERROR whenever a form's output as a
    string is different from what was in INPUT, provided that INPUT
    contained the output. Similary, for values, a continuable
    TRANSCRIPTION-VALUES-CONSISTENCY-ERROR is signalled if a value read
    from the source does not print as the as the value returned by EVAL.
    This allows readable values to be hand-indented without failing
    consistency checks:
    
    ```commonlisp
    (list 1 2)
    => (1
          2)
    ```
    
    **Unreadable Values**
    
    The above scheme involves READ, so consistency of unreadable values
    cannot be treated the same. In fact, unreadable values must even be
    printed differently for transcribe to be able to read them back:
    
    ```commonlisp
    (defclass some-class () ())
    
    (defmethod print-object ((obj some-class) stream)
      (print-unreadable-object (obj stream :type t)
        (format stream \"~%~%end\")))
    
    (make-instance 'some-class)
    ==> #
    --> end>
    ```
    
    where `"==>"` is the :UNREADABLE prefix and `"-->"` is
    the :UNREADABLE-CONTINUATION prefix. As with outputs, a consistency
    check between an unreadable value from the source and the value from
    EVAL is performed with STRING=. That is, the value from 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. There is currently
    no remedy for that, except for customizing PRINT-OBJECT or not
    transcribing that kind of stuff.
    
    **Syntaxes**
    
    Finally, a transcript may employ different syntaxes for the output
    and values of different forms. When INPUT is read, the syntax for
    each form is determined by trying to match all prefixes from all
    syntaxes in INPUT-SYNTAXES against a line. If there are no output or
    values for a form in INPUT, then the syntax remains undetermined.
    
    When OUTPUT is written, the prefixes to be used are looked up in
    DEFAULT-SYNTAX of OUTPUT-SYNTAXES, if DEFAULT-SYNTAX is not NIL. If
    DEFAULT-SYNTAX is NIL, then the syntax used by the same form in the
    INPUT is used or (if that could not be determined) the syntax of the
    previous form. If there was no previous form, then the first syntax
    if OUTPUT-SYNTAXES is used.
    
    To produce a transcript that's executable Lisp code,
    use :DEFAULT-SYNTAX :COMMENTED-1:
    
    ```commonlisp
    (make-instance 'some-class)
    ;==> #
    ;--> end>
    
    (list 1 2)
    ;=> (1
    ;->    2)
    ```
    
    To translate the above to uncommented syntax,
    use :DEFAULT-SYNTAX :DEFAULT. If DEFAULT-SYNTAX is NIL (the
    default), the same syntax will be used in the output as in the input
    as much as possible.

- [variable] *SYNTAXES* ((:DEFAULT (:OUTPUT "..") (:NO-VALUE "=> ; No value") (:READABLE "=>")
  (:UNREADABLE "==>") (:UNREADABLE-CONTINUATION "-->"))
 (:COMMENTED-1 (:OUTPUT ";..") (:NO-VALUE ";=> ; No value")
  (:READABLE ";=>") (:READABLE-CONTINUATION ";->") (:UNREADABLE ";==>")
  (:UNREADABLE-CONTINUATION ";-->"))
 (:COMMENTED-2 (:OUTPUT ";;..") (:NO-VALUE ";;=> ; No value")
  (:READABLE ";;=>") (:READABLE-CONTINUATION ";;->")
  (:UNREADABLE ";;==>") (:UNREADABLE-CONTINUATION ";;-->")))

    The default syntaxes used by TRANSCRIBE for reading and writing
    lines containing output and values of an evaluated form.
    
    A syntax is a list of of the form `(SYNTAX-ID &REST PREFIXES)` where
    `PREFIXES` is a list of `(PREFIX-ID PREFIX-STRING)` elements. For
    example the syntax :COMMENTED-1 looks like this:
    
    ```commonlisp
    (:commented-1
     (:output ";..")
     (:no-value ";=>  No value")
     (:readable ";=>")
     (:readable-continuation ";->")
     (:unreadable ";==>")
     (:unreadable-continuation ";-->"))
    ```
    
    All of the above prefixes must be defined for every syntax except
    for :READABLE-CONTINUATION. If that's missing (as in the :DEFAULT
    syntax), then the following value is read with READ and printed with
    PRIN1 (hence no need to mark up the following lines).
    
    When writing, an extra space is added automatically if the line to
    be prefixed is not empty. Similarly, the first space following the
    prefix discarded when reading.
    
    See TRANSCRIBE for how the actual syntax to be used is selected.

- [condition] TRANSCRIPTION-ERROR ERROR

    Represents syntactic errors in the SOURCE argument
    of TRANSCRIBE and also serves as the superclass of
    TRANSCRIPTION-CONSISTENCY-ERROR.

- [condition] TRANSCRIPTION-CONSISTENCY-ERROR TRANSCRIPTION-ERROR

    A common superclass for
    TRANSCRIPTION-OUTPUT-CONSISTENCY-ERROR and
    TRANSCRIPTION-VALUES-CONSISTENCY-ERROR.

- [condition] TRANSCRIPTION-OUTPUT-CONSISTENCY-ERROR TRANSCRIPTION-CONSISTENCY-ERROR

    Signaled (with CERROR) by TRANSCRIBE 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

    Signaled (with CERROR) by TRANSCRIBE when invoked
    with :CHECK-CONSISTENCY and the values of a form are inconsistent
    with their parsed representation.

## Utilities

- [function] MAKE-GITHUB-SOURCE-URI-FN ASDF-SYSTEM GITHUB-URI &KEY GIT-VERSION

    Return a function suitable as :SOURCE-URI-FN of a page spec (see
    the PAGES argument of DOCUMENT). The function looks the source
    location of the reference passed to it, and if the location is
    found, the path is made relative to the root directory of
    ASDF-SYSTEM and finally an URI pointing to github is returned. The
    URI looks like this:
    
        https://github.com/melisgl/mgl-pax/blob/master/src/pax-early.lisp#L12
    
    "master" in the above link comes from GIT-VERSION.
    
    If GIT-VERSION is NIL, then an attempt is made to determine to
    current commit id from the `.git` in the directory holding
    ASDF-SYSTEM. If no `.git` directory is found, then no links to
    github will be generated.
    
    A separate warning is signalled whenever source location lookup
    fails or if the source location points to a directory not below the
    directory of ASDF-SYSTEM.

* * *
###### \[generated by [MGL-PAX](https://github.com/melisgl/mgl-pax)\]


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 mgl-pax

Author

Gábor Melis

Contact

mega@retes.hu

Home Page

http://quotenil.com

License

MIT, see COPYING.

Description

Exploratory programming tool and documentation generator.

Version

0.0.2

Dependencies
Source

mgl-pax.asd (file)

Component

src (module)


Next: , Previous: , Up: Top   [Contents][Index]

3 Modules

Modules are listed depth-first from the system components tree.


Previous: , Up: Modules   [Contents][Index]

3.1 mgl-pax/src

Parent

mgl-pax (system)

Location

src/

Components

Next: , Previous: , Up: Top   [Contents][Index]

4 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

4.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.1 mgl-pax.asd

Location

mgl-pax.asd

Systems

mgl-pax (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.2 mgl-pax/src/package.lisp

Parent

src (module)

Location

src/package.lisp

Packages

mgl-pax


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.3 mgl-pax/src/utility.lisp

Dependency

package.lisp (file)

Parent

src (module)

Location

src/utility.lisp

Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.4 mgl-pax/src/pax-early.lisp

Dependency

utility.lisp (file)

Parent

src (module)

Location

src/pax-early.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.5 mgl-pax/src/pax.lisp

Dependency

pax-early.lisp (file)

Parent

src (module)

Location

src/pax.lisp

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

4.1.6 mgl-pax/src/transcribe.lisp

Dependency

pax.lisp (file)

Parent

src (module)

Location

src/transcribe.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

5.1 mgl-pax

See MGL-PAX:@MGL-PAX-MANUAL.

Source

package.lisp (file)

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

6.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.1 Special variables

Special Variable: *discard-documentation-p*

The default value of DEFSECTION’s DISCARD-DOCUMENTATION-P argument. One may want to set *DISCARD-DOCUMENTATION-P* to true before building a binary application.

Package

mgl-pax

Source

pax-early.lisp (file)

Special Variable: *document-fancy-html-navigation*

If true and the output format is HTML, then headings get a navigation component that consists of links to the previous, parent, next section and a permalink. This component is normally hidden, it is visible only when the mouse is over the heading. Needs *DOCUMENT-LINK-SECTIONS* to be on to work.

Package

mgl-pax

Source

pax.lisp (file)

Special Variable: *document-link-code*

When true, during the process of generating documentation for a [SECTION][class], HTML anchors are added before the documentation of every reference that’s not to a section. Also, markdown style reference links are added when a piece of inline code found in a docstring refers to a symbol that’s referenced by one of the sections being documented. Assuming ‘BAR‘ is defined, the documentation for:

“‘commonlisp
(defsection @foo
(foo function)
(bar function))

(defun foo (x)
"Calls ‘BAR‘ on ‘X‘."
(bar x))
“‘

would look like this:

- [function] FOO X

Calls [‘BAR‘][1] on ‘X‘.

Instead of ‘BAR‘, one can write ‘[bar][]‘ or “[‘bar‘][]“ as well. Since symbol names are parsed according to READTABLE-CASE, character case rarely matters.

Now, if ‘BAR‘ has references with different locatives:

“‘commonlisp
(defsection @foo
(foo function)
(bar function)
(bar type))

(defun foo (x)
"Calls ‘BAR‘ on ‘X‘."
(bar x))
“‘

then documentation would link to all interpretations:

- [function] FOO X

Calls ‘BAR‘([‘1‘][link-id-1] [‘2‘][link-id-2]) on ‘X‘.

This situation occurs in PAX with SECTION which is both a class (see [SECTION][class]) and a locative type denoted by a symbol (see [SECTION][locative]). Back in the example above, clearly,
there is no reason to link to type ‘BAR‘, so one may wish to select the function locative. There are two ways to do that. One is to specify the locative explicitly as the id of a reference link:

"Calls [BAR][function] on X."

However, if in the text there is a locative immediately before or after the symbol, then that locative is used to narrow down the range of possibilities. This is similar to what the ‘M-.‘ extension does. In a nutshell, if ‘M-.‘ works without questions then the documentation will contain a single link. So this also works without any markup:

"Calls function ‘BAR‘ on X."

This last option needs backticks around the locative if it’s not a single symbol.

Note that [*DOCUMENT-LINK-CODE*][variable] can be combined with [‘*DOCUMENT-UPPERCASE-IS-CODE*‘][] to have links generated for uppercase names with no quoting required.

Package

mgl-pax

Source

pax.lisp (file)

Special Variable: *document-link-sections*

When true, HTML anchors are generated before the heading of sections which allows the table of contents to contain links and also code-like references to sections (like ‘@FOO-MANUAL‘) to be translated to links with the section title being the name of the link.

Package

mgl-pax

Source

pax.lisp (file)

Special Variable: *document-mark-up-signatures*

When true, some things such as function names and arglists are rendered as bold and italic. In :HTML output, locative types become links to sources (if :SOURCE-URI-FN is provided, see DOCUMENT), and the symbol becomes a self-link for your permalinking pleasure.

For example, a reference is rendered in markdown roughly as:

- [function] foo x y

With this option on, the above becomes:

- [function] **foo** *x y*

Also, in HTML ‘**foo**‘ will be a link to that very entry and ‘[function]‘ may turn into a link to sources.

Package

mgl-pax

Source

pax.lisp (file)

Special Variable: *document-max-numbering-level*

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.

Package

mgl-pax

Source

pax.lisp (file)

Special Variable: *document-max-table-of-contents-level*

A non-negative integer. Top-level sections are given a table of contents which includes a nested tree of section titles whose depth is limited by this value. Setting it to 0 turns generation of the table of contents off. If *DOCUMENT-LINK-SECTIONS* is true, then the table of contents will link to the sections.

Package

mgl-pax

Source

pax.lisp (file)

Special Variable: *document-min-link-hash-length*

Recall that markdown reference style links (like ‘[label][id]‘) are used for linking to sections and code. It is desirable to have ids that are short to maintain legibility of the generated markdown, but also stable to reduce the spurious diffs in the generated documentation which can be a pain in a version control system.

Clearly, there is a tradeoff here. This variable controls how many characters of the md5 sum of the full link id (the reference as a string) are retained. If collisions are found due to the low number of characters, then the length of the hash of the colliding reference is increased.

This variable has no effect on the HTML generated from markdown, but it can make markdown output more readable.

Package

mgl-pax

Source

pax.lisp (file)

Special Variable: *document-normalize-packages*

If true, symbols are printed relative to SECTION-PACKAGE of the innermost containing section or with full package names if there is no containing section. To eliminate ambiguity ‘[in package ...]‘ messages are printed right after the section heading if necessary. If false, symbols are always printed relative to the current package.

Package

mgl-pax

Source

pax.lisp (file)

Special Variable: *document-text-navigation*

If true, then before each heading a line is printed with links to the previous, parent and next section. Needs *DOCUMENT-LINK-SECTIONS* to be on to work.

Package

mgl-pax

Source

pax.lisp (file)

Special Variable: *document-uppercase-is-code*

When true, words with at least three characters and no lowercase characters naming an interned symbol are assumed to be code as if they were marked up with backticks which is especially useful when combined with *DOCUMENT-LINK-CODE*. For example, this docstring:

"‘FOO‘ and FOO."

is equivalent to this:

"‘FOO‘ and ‘FOO‘."

iff ‘FOO‘ is an interned symbol. To suppress this behavior, add a backslash to the beginning of the symbol or right after the leading * if it would otherwise be parsed as markdown emphasis:

"\\MGL-PAX *\\DOCUMENT-NORMALIZE-PACKAGES*"

The number of backslashes is doubled above because that’s how the example looks in a docstring. Note that the backslash is discarded even if *DOCUMENT-UPPERCASE-IS-CODE* is false.

Package

mgl-pax

Source

pax.lisp (file)

Special Variable: *syntaxes*

The default syntaxes used by TRANSCRIBE for reading and writing lines containing output and values of an evaluated form.

A syntax is a list of of the form ‘(SYNTAX-ID &REST PREFIXES)‘ where ‘PREFIXES‘ is a list of ‘(PREFIX-ID PREFIX-STRING)‘ elements. For example the syntax :COMMENTED-1 looks like this:

“‘commonlisp
(:commented-1
(:output ";..")
(:no-value ";=> No value")
(:readable ";=>")
(:readable-continuation ";->")
(:unreadable ";==>")
(:unreadable-continuation ";–>"))
“‘

All of the above prefixes must be defined for every syntax except for :READABLE-CONTINUATION. If that’s missing (as in the :DEFAULT syntax), then the following value is read with READ and printed with PRIN1 (hence no need to mark up the following lines).

When writing, an extra space is added automatically if the line to be prefixed is not empty. Similarly, the first space following the prefix discarded when reading.

See TRANSCRIBE for how the actual syntax to be used is selected.

Package

mgl-pax

Source

transcribe.lisp (file)

Special Variable: @mgl-pax-background
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: @mgl-pax-basics
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: @mgl-pax-documentation-printer-variables
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: @mgl-pax-emacs-integration
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: @mgl-pax-extension-api
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: @mgl-pax-links
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: @mgl-pax-locative-types
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: @mgl-pax-locatives-and-references
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: @mgl-pax-manual
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: @mgl-pax-markdown-indentation
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: @mgl-pax-markdown-support
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: @mgl-pax-markdown-syntax-highlighting
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: @mgl-pax-mathjax
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: @mgl-pax-new-object-types
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: @mgl-pax-reference-based-extensions
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: @mgl-pax-sections
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: @mgl-pax-transcript
Package

mgl-pax

Source

transcribe.lisp (file)

Special Variable: @mgl-pax-transcript-api
Package

mgl-pax

Source

transcribe.lisp (file)

Special Variable: @mgl-pax-transcript-emacs-integration
Package

mgl-pax

Source

transcribe.lisp (file)

Special Variable: @mgl-pax-tutorial
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: @mgl-pax-utilities
Package

mgl-pax

Source

pax.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.2 Macros

Macro: define-definer-for-symbol-locative-type NAME LOCATIVE-TYPE &body DOCSTRING

Define a macro with NAME which can be used to attach documentation, a lambda-list and source location to a symbol in the context of LOCATIVE-TYPE. The defined macro’s arglist is (SYMBOL LAMBDA-LIST &OPTIONAL DOCSTRING). LOCATIVE-TYPE is assumed to have been defined with DEFINE-SYMBOL-LOCATIVE-TYPE.

Package

mgl-pax

Source

pax.lisp (file)

Macro: define-locative-type LOCATIVE-TYPE LAMBDA-LIST &body DOCSTRING

Declare LOCATIVE-TYPE as a [LOCATIVE][locative]. One gets two things in return: first, a place to document the format and semantics of LOCATIVE-TYPE (in LAMBDA-LIST and DOCSTRING); second, being able to reference ‘(LOCATIVE-TYPE LOCATIVE)‘. For example, if you have:

“‘common-lisp
(define-locative-type variable (&optional initform)
"Dummy docstring.")
“‘

then ‘(VARIABLE LOCATIVE)‘ refers to this form.

Package

mgl-pax

Source

pax.lisp (file)

Macro: define-package PACKAGE &rest OPTIONS

This is like CL:DEFPACKAGE but silences warnings and errors signaled 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 (as is the case with DEFSECTION) as opposed to adding :EXPORT forms to the DEFPACKAGE form and the package definition is 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.

Package

mgl-pax

Source

pax.lisp (file)

Macro: define-symbol-locative-type LOCATIVE-TYPE LAMBDA-LIST &body DOCSTRING

Similar to DEFINE-LOCATIVE-TYPE but it assumes that all things locatable with LOCATIVE-TYPE are going to be just symbols defined with a definer defined with DEFINE-DEFINER-FOR-SYMBOL-LOCATIVE-TYPE. It is useful to attach documentation and source location to symbols in a particular context. An example will make everything clear:

“‘commonlisp
(define-symbol-locative-type direction ()
"A direction is a symbol. (After this ‘M-.‘ on ‘DIRECTION LOCATIVE‘ works and it can also be included in DEFSECTION forms.)")

(define-definer-for-symbol-locative-type define-direction direction () "With DEFINE-DIRECTION one can document how what a symbol means when interpreted as a direction.")

(define-direction up ()
"UP is equivalent to a coordinate delta of (0, -1).")
“‘

After all this, ‘(UP DIRECTION)‘ refers to the ‘DEFINE-DIRECTION‘ form above.

Package

mgl-pax

Source

pax.lisp (file)

Macro: defsection NAME (&key PACKAGE READTABLE EXPORT TITLE 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][class] object. By convention, section names start with the character ‘@‘. See @MGL-PAX-TUTORIAL for an example.

ENTRIES consists of docstrings and references. Docstrings are arbitrary strings in markdown format, references are defined in the form:

(symbol 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))‘.

A locative in a reference can either be a symbol or it can be a list whose CAR is a symbol. In either case, the symbol is the called the type of the locative while the rest of the elements are the locative arguments. See @MGL-PAX-LOCATIVE-TYPES for the list of locative types available out of the box.

The same symbol can occur multiple times in a reference, typically with different locatives, but this is not required.

The references are not looked up (see RESOLVE in the @MGL-PAX-EXTENSION-API) until documentation is generated, so it is allowed to refer to things yet to be defined.

If EXPORT is true (the default), the referenced symbols and NAME are candidates for exporting. A candidate symbol is exported if

- it is accessible in PACKAGE (it’s not ‘OTHER-PACKAGE:SOMETHING‘) and

- there is a reference to it in the section being defined with a locative whose type is approved by EXPORTABLE-LOCATIVE-TYPE-P.

See DEFINE-PACKAGE if you use the export feature. The idea with confounding documentation and exporting is to force documentation of all exported symbols.

When DISCARD-DOCUMENTATION-P (defaults to *DISCARD-DOCUMENTATION-P*) is true, ENTRIES will not be recorded to save memory.

Package

mgl-pax

Source

pax-early.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.3 Functions

Function: document OBJECT &key STREAM PAGES FORMAT

Write OBJECT in FORMAT to STREAM diverting some output to PAGES. FORMAT can be anything [3BMD][3bmd] supports which is
currently :MARKDOWN, :HTML and :PLAIN. STREAM may be a stream object, T or NIL as with CL:FORMAT.

Most often, this function is called on section objects
like ‘(DOCUMENT @MGL-PAX-MANUAL)‘, but it supports all kinds of objects for which DOCUMENT-OBJECT is defined. To look up the documentation of function DOCUMENT:

(document #’document)

To generate the documentation for separate libraries with automatic cross-links:

(document (list @cube-manual @mat-manual))

Note that not only first class objects can have documentation. For instance, variables and deftypes are not represented by objects. That’s why CL:DOCUMENTATION has a DOC-TYPE argument. DOCUMENT does not have anything like that, instead it relies on REFERENCE objects to carry the extra information. We are going to see later how references and locatives work. Until then, here is an example on how to look up the documentation of type ‘FOO‘:

(document (locate ’foo ’type))

One can call DESCRIBE on [SECTION][class] objects to get documentation in markdown format with less markup than the default. See DESCRIBE-OBJECT ‘(METHOD () (SECTION T))‘.

There are quite a few special variables that affect how output is generated, see @MGL-PAX-DOCUMENTATION-PRINTER-VARIABLES.

The rest of this description deals with how to generate multiple pages.

The PAGES argument is to create multi-page documents by routing some of the generated output to files, strings or streams. PAGES is a list of page specification elements. A page spec is a plist with keys :OBJECTS, :OUTPUT, :URI-FRAGMENT, :SOURCE-URI-FN, :HEADER-FN and :FOOTER-FN. OBJECTS is a list of objects (references are allowed but not required) whose documentation is to be sent to ‘OUTPUT‘. ‘OUTPUT‘ can be a number things:

- If it’s a list whose first element is a string or a pathname, then output will be sent to the file denoted by that and the rest of the elements of the list are passed on as arguments to CL:OPEN. One extra keyword argument is :ENSURE-DIRECTORIES-EXIST. If it’s true, ENSURE-DIRECTORIES-EXIST will be called on the pathname before it’s opened.

- If it’s NIL, then output will be collected in a string.

- If it’s T, then output will be sent to *STANDARD-OUTPUT*.

- If it’s a stream, then output will be sent to that stream.

If some pages are specified, DOCUMENT returns a list of designators for generated output. If a page whose ‘OUTPUT‘ refers to a file that was created (which doesn’t happen if nothing would be written to it), then the corresponding pathname is included in the list. For strings the string itself, while for streams the stream object is included in the list. This way it’s possible to write some pages to files and some to strings and have the return value indicate what was created. The output designators in the returned list are ordered by creation time.

If no PAGES are specified, DOCUMENT returns a single pathname, string or stream object according to the value of the STREAM argument.

Note that even if PAGES is specified, STREAM acts as a catch all taking the generated documentation for references not claimed by any pages. Also, the filename, string or stream corresponding to STREAM is always the first element in list of generated things that is the return value.

HEADER-FN, if not NIL, is a function of a single stream argument which is called just before the first write to the page.
Since :FORMAT :HTML only generates HTML fragments, this makes it possible to print arbitrary headers, typically setting the title, css stylesheet, or charset.

FOOTER-FN is similar to HEADER-FN, but it’s called after the last write to the page. For HTML, it typically just closes the body.

URI-FRAGMENT is a string such as ‘"doc/manual.html"‘ that specifies where the page will be deployed on a webserver. It defines how links between pages will look. If it’s not specified and ‘OUTPUT‘ refers to a file, then it defaults to the name of the file. If URI-FRAGMENT is NIL, then no links will be made to or from that page.

Finally, SOURCE-URI-FN is a function of a single, REFERENCE argument. If it returns a value other than NIL, then it must be a string representing an URI. If FORMAT is :HTML and *DOCUMENT-MARK-UP-SIGNATURES* is true, then the locative as displayed in the signature will be a link to this uri. See MAKE-GITHUB-SOURCE-URI-FN.

PAGES may look something like this:

“‘commonlisp
‘((;; The section about SECTIONs and everything below it ... :objects (,@mgl-pax-sections)
;; ... is so boring that it’s not worth the disk space, so
;; send it to a string.
:output (nil)
;; Explicitly tell other pages not to link to these guys. :uri-fragment nil)
;; Send the @MGL-PAX-EXTENSIONS section and everything reachable ;; from it ...
(:objects (,@mgl-pax-extension-api)
;; ... to build/tmp/pax-extension-api.html.
:output ("build/tmp/pax-extension-api.html")
;; However, on the web server html files will be at this
;; location relative to some common root, so override the
;; default:
:uri-fragment "doc/dev/pax-extension-api.html"
;; Set html page title, stylesheet, charset.
:header-fn ’write-html-header
;; Just close the body.
:footer-fn ’write-html-footer)
(:objects (,@mgl-pax-manual)
:output ("build/tmp/manual.html")
;; Links from the extension api page to the manual page will ;; be to ../user/pax-manual#<anchor>, while links going to
;; the opposite direction will be to
;; ../dev/pax-extension-api.html#<anchor>.
:uri-fragment "doc/user/pax-manual.html"
:header-fn ’write-html-header
:footer-fn ’write-html-footer))
“‘

Package

mgl-pax

Source

pax.lisp (file)

Function: locate OBJECT LOCATIVE &key ERRORP

Follow LOCATIVE from OBJECT and return the object it leads to or a REFERENCE if there is no first class object corresponding to the location. If ERRORP, then a LOCATE-ERROR condition is signaled when lookup fails.

Package

mgl-pax

Source

pax.lisp (file)

Function: locate-error &rest FORMAT-AND-ARGS

Call this function to signal a LOCATE-ERROR condition from a LOCATE-OBJECT method. FORMAT-AND-ARGS contains a format string and args suitable for FORMAT from which the LOCATE-ERROR-MESSAGE is constructed. If FORMAT-AND-ARGS is NIL, then the message will be NIL too.

The object and the locative are not specified, they are added by LOCATE when it resignals the condition.

Package

mgl-pax

Source

pax.lisp (file)

Function: locative-args LOCATIVE

The REST of LOCATIVE if it’s a list. If it’s a symbol then it’s ().

Package

mgl-pax

Source

pax-early.lisp (file)

Function: locative-type LOCATIVE

The first element of LOCATIVE if it’s a list. If it’s a symbol then it’s that symbol itself. Typically, methods of generic functions working with locatives take locative type and locative args as separate arguments to allow methods have eql specializers on the type symbol.

Package

mgl-pax

Source

pax-early.lisp (file)

Function: make-github-source-uri-fn ASDF-SYSTEM GITHUB-URI &key GIT-VERSION

Return a function suitable as :SOURCE-URI-FN of a page spec (see
the PAGES argument of DOCUMENT). The function looks the source location of the reference passed to it, and if the location is
found, the path is made relative to the root directory of
ASDF-SYSTEM and finally an URI pointing to github is returned. The URI looks like this:

https://github.com/melisgl/mgl-pax/blob/master/src/pax-early.lisp#L12

"master" in the above link comes from GIT-VERSION.

If GIT-VERSION is NIL, then an attempt is made to determine to current commit id from the ‘.git‘ in the directory holding ASDF-SYSTEM. If no ‘.git‘ directory is found, then no links to
github will be generated.

A separate warning is signalled whenever source location lookup
fails or if the source location points to a directory not below the directory of ASDF-SYSTEM.

Package

mgl-pax

Source

pax.lisp (file)

Function: make-reference OBJECT LOCATIVE
Package

mgl-pax

Source

pax-early.lisp (file)

Function: resolve REFERENCE &key ERRORP

A convenience function to LOCATE REFERENCE’s object with its locative.

Package

mgl-pax

Source

pax.lisp (file)

Function: transcribe INPUT OUTPUT &key UPDATE-ONLY INCLUDE-NO-OUTPUT INCLUDE-NO-VALUE ECHO CHECK-CONSISTENCY DEFAULT-SYNTAX INPUT-SYNTAXES OUTPUT-SYNTAXES

Read forms from INPUT and write them (iff ECHO) to OUTPUT
followed by any output and return values produced by calling EVAL on the form. INPUT can be a stream or a string, while OUTPUT can be a stream or NIL in which case transcription goes into a string. The return value is the OUTPUT stream or the string that was constructed.

A simple example is this:

“‘cl-transcript
(transcribe "(princ 42) " nil)
=> "(princ 42)
.. 42
=> 42
"
“‘

However, the above may be a bit confusing since this documentation uses TRANSCRIBE markup syntax in this very example, so let’s do it differently. If we have a file with these contents:

“‘commonlisp
(values (princ 42) (list 1 2))
“‘

it is transcribed to:

“‘commonlisp
(values (princ 42) (list 1 2))
.. 42
=> 42
=> (1 2)
“‘

Output to all standard streams is captured and printed with
the :OUTPUT prefix (‘".."‘). The return values above are printed with the :READABLE prefix (‘"=>"‘). Note how these prefixes are always printed on a new line to facilitate parsing.

**Updating**

TRANSCRIBE is able to parse its own output. If we transcribe the previous output above, we get it back exactly. However, if we remove all output markers, leave only a placeholder value marker and pass :UPDATE-ONLY T with source:

“‘commonlisp
(values (princ 42) (list 1 2))
=>
“‘

we get this:

“‘commonlisp
(values (princ 42) (list 1 2))
=> 42
=> (1 2)
“‘

With UPDATE-ONLY, printed output of a form is only transcribed if there were output markers in the source. Similarly, with UPDATE-ONLY, return values are only transcribed if there were value markers in the source.

**No Output/Values**

If the form produces no output or returns no values, then whether or not output and values are transcribed is controlled by INCLUDE-NO-OUTPUT and INCLUDE-NO-VALUE, respectively. By default, neither is on so:

“‘commonlisp
(values)
..
=>
“‘

is transcribed to

“‘commonlisp
(values)
“‘

With UPDATE-ONLY true, we probably wouldn’t like to lose those markers since they were put there for a reason. Hence, with UPDATE-ONLY, INCLUDE-NO-OUTPUT and INCLUDE-NO-VALUE default to true. So with UPDATE-ONLY the above example is transcribed to:

“‘commonlisp
(values)
..
=> ; No value
“‘

where the last line is the :NO-VALUE prefix.

**Consistency Checks**

If CHECK-CONSISTENCY is true, then TRANSCRIBE signals a continuable TRANSCRIPTION-OUTPUT-CONSISTENCY-ERROR whenever a form’s output as a string is different from what was in INPUT, provided that INPUT contained the output. Similary, for values, a continuable TRANSCRIPTION-VALUES-CONSISTENCY-ERROR is signalled if a value read from the source does not print as the as the value returned by EVAL. This allows readable values to be hand-indented without failing consistency checks:

“‘commonlisp
(list 1 2)
=> (1
2)
“‘

**Unreadable Values**

The above scheme involves READ, so consistency of unreadable values cannot be treated the same. In fact, unreadable values must even be printed differently for transcribe to be able to read them back:

“‘commonlisp
(defclass some-class () ())

(defmethod print-object ((obj some-class) stream) (print-unreadable-object (obj stream :type t)
(format stream \"~%~%end\")))

(make-instance ’some-class)
==> #<SOME-CLASS
–>
–> end>
“‘

where ‘"==>"‘ is the :UNREADABLE prefix and ‘"–>"‘ is
the :UNREADABLE-CONTINUATION prefix. As with outputs, a consistency check between an unreadable value from the source and the value from EVAL is performed with STRING=. That is, the value from 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. There is currently no remedy for that, except for customizing PRINT-OBJECT or not transcribing that kind of stuff.

**Syntaxes**

Finally, a transcript may employ different syntaxes for the output and values of different forms. When INPUT is read, the syntax for each form is determined by trying to match all prefixes from all syntaxes in INPUT-SYNTAXES against a line. If there are no output or values for a form in INPUT, then the syntax remains undetermined.

When OUTPUT is written, the prefixes to be used are looked up in DEFAULT-SYNTAX of OUTPUT-SYNTAXES, if DEFAULT-SYNTAX is not NIL. If DEFAULT-SYNTAX is NIL, then the syntax used by the same form in the INPUT is used or (if that could not be determined) the syntax of the previous form. If there was no previous form, then the first syntax if OUTPUT-SYNTAXES is used.

To produce a transcript that’s executable Lisp code,
use :DEFAULT-SYNTAX :COMMENTED-1:

“‘commonlisp
(make-instance ’some-class)
;==> #<SOME-CLASS
;–>
;–> end>

(list 1 2)
;=> (1
;-> 2)
“‘

To translate the above to uncommented syntax,
use :DEFAULT-SYNTAX :DEFAULT. If DEFAULT-SYNTAX is NIL (the default), the same syntax will be used in the output as in the input as much as possible.

Package

mgl-pax

Source

transcribe.lisp (file)

Function: transcription-error STREAM FILE-POSITION FORM-AS-STRING MESSAGE &rest MESSAGE-ARGS
Package

mgl-pax

Source

transcribe.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.4 Generic functions

Generic Function: canonical-reference OBJECT

Return a REFERENCE that resolves to OBJECT.

Package

mgl-pax

Source

pax.lisp (file)

Methods
Method: canonical-reference (PACKAGE package)
Method: canonical-reference (CLASS class)
Method: canonical-reference (METHOD method)
Method: canonical-reference (FUNCTION generic-function)
Method: canonical-reference (FUNCTION function)
Method: canonical-reference (SYSTEM system)
Method: canonical-reference (SECTION section)
Method: canonical-reference (REFERENCE reference)
Generic Function: collect-reachable-objects OBJECT

Return a list of objects representing all things
that would be documented in a (DOCUMENT OBJECT) call. For sections this is simply the union of references reachable from references in SECTION-ENTRIES. The returned objects can be anything provided that CANONICAL-REFERENCE works on them. The list need not include OBJECT itself.

One only has to specialize this for new container-like objects.

Package

mgl-pax

Source

pax.lisp (file)

Methods
Method: collect-reachable-objects (SECTION section)
Method: collect-reachable-objects (REFERENCE reference)

If REFERENCE can be resolved to a non-reference, call COLLECT-REACHABLE-OBJECTS with it, else call LOCATE-AND-COLLECT-REACHABLE-OBJECTS on the object, locative-type, locative-args of REFERENCE

Method: collect-reachable-objects OBJECT

This default implementation returns the empty list. This means that nothing is reachable from OBJECT.

Generic Function: document-object OBJECT STREAM

Write OBJECT (and its references recursively) in
FORMAT to STREAM.

The DOCUMENT function calls this generic function with LEVEL 0, passing FORMAT on. Add methods specializing on OBJECT to customize how objects of that type are presented in the documentation.

Package

mgl-pax

Source

pax.lisp (file)

Methods
Method: document-object (PACKAGE package) STREAM
Method: document-object (CLASS class) STREAM
Method: document-object (METHOD method) STREAM
Method: document-object (FUNCTION function) STREAM
Method: document-object (SYSTEM system) STREAM
Method: document-object (SECTION section) STREAM
Method: document-object (REFERENCE reference) STREAM

If REFERENCE can be resolved to a non-reference, call DOCUMENT-OBJECT with it, else call LOCATE-AND-DOCUMENT-OBJECT on the object, locative-type, locative-args of REFERENCE

Method: document-object OBJECT STREAM around
Method: document-object (STRING string) STREAM

Print STRING verbatim to STREAM after cleaning up indentation.

Docstrings in sources are indented in various ways which can easily mess up markdown. To handle the most common cases leave the first line alone, but from the rest of the lines strip the longest run of leading spaces that is common to all non-blank lines.

Generic Function: exportable-locative-type-p LOCATIVE-TYPE

Return true iff symbols in references with
LOCATIVE-TYPE are to be exported by default when they occur in a DEFSECTION. The default method returns T, while the methods for PACKAGE, ASDF:SYSTEM and METHOD return NIL.

DEFSECTION calls this function to decide what symbols to export when its EXPORT argument is true.

Package

mgl-pax

Source

pax-early.lisp (file)

Methods
Method: exportable-locative-type-p (LOCATIVE-TYPE (eql include))
Source

pax.lisp (file)

Method: exportable-locative-type-p (LOCATIVE-TYPE (eql method))
Method: exportable-locative-type-p (LOCATIVE-TYPE (eql package))
Method: exportable-locative-type-p (LOCATIVE-TYPE (eql system))
Method: exportable-locative-type-p LOCATIVE-TYPE
Generic Function: find-source OBJECT

Like SWANK:FIND-DEFINITION-FOR-THING, but this
one is a generic function to be extensible. In fact, the default implementation simply defers to SWANK:FIND-DEFINITION-FOR-THING. This function is called by LOCATE-DEFINITION-FOR-EMACS which lies behind the ‘M-.‘ extension (see @MGL-PAX-EMACS-INTEGRATION).

If successful, the return value looks like this:

“‘commonlisp
(:location (:file "/home/mega/own/mgl/pax/test/test.lisp") (:position 24) nil)
“‘

The NIL is the source snippet which is optional. Note that position 1 is the first character. If unsuccessful, the return values is like:

“‘commonlisp
(:error "Unknown source location for SOMETHING")
“‘

Package

mgl-pax

Source

pax.lisp (file)

Methods
Method: find-source (SYSTEM system)
Method: find-source (SECTION section)
Method: find-source (REFERENCE reference)

If REFERENCE can be resolved to a non-reference, call FIND-SOURCE with it, else call LOCATE-AND-FIND-SOURCE on the object, locative-type, locative-args of REFERENCE

Method: find-source OBJECT
Generic Function: locate-and-collect-reachable-objects OBJECT LOCATIVE-TYPE LOCATIVE-ARGS

Called by COLLECT-REACHABLE-OBJECTS on REFERENCE
objects, this function has essentially the same purpose as its caller but it has different arguments to allow specializing on LOCATIVE-TYPE.

Package

mgl-pax

Source

pax.lisp (file)

Methods
Method: locate-and-collect-reachable-objects OBJECT LOCATIVE-TYPE LOCATIVE-ARGS

This default implementation returns the empty list. This means that nothing is reachable from the reference.

Generic Function: locate-and-document OBJECT LOCATIVE-TYPE LOCATIVE-ARGS STREAM

Called by DOCUMENT-OBJECT on REFERENCE objects,
this function has essentially the same purpose as DOCUMENT-OBJECT but it has different arguments to allow specializing on LOCATIVE-TYPE.

Package

mgl-pax

Source

pax.lisp (file)

Methods
Method: locate-and-document SYMBOL (LOCATIVE-TYPE (eql include)) LOCATIVE-ARGS STREAM
Method: locate-and-document SYMBOL (LOCATIVE-TYPE (eql type)) LOCATIVE-ARGS STREAM
Method: locate-and-document SYMBOL (LOCATIVE-TYPE (eql writer)) LOCATIVE-ARGS STREAM
Method: locate-and-document SYMBOL (LOCATIVE-TYPE (eql reader)) LOCATIVE-ARGS STREAM
Method: locate-and-document SYMBOL (LOCATIVE-TYPE (eql accessor)) LOCATIVE-ARGS STREAM
Method: locate-and-document SYMBOL (LOCATIVE-TYPE (eql compiler-macro)) LOCATIVE-ARGS STREAM
Method: locate-and-document SYMBOL (LOCATIVE-TYPE (eql macro)) LOCATIVE-ARGS STREAM
Method: locate-and-document (SYMBOL symbol) (LOCATIVE-TYPE (eql structure-accessor)) LOCATIVE-ARGS STREAM
Method: locate-and-document SYMBOL (LOCATIVE-TYPE (eql constant)) LOCATIVE-ARGS STREAM
Method: locate-and-document SYMBOL (LOCATIVE-TYPE (eql variable)) LOCATIVE-ARGS STREAM
Method: locate-and-document SYMBOL (LOCATIVE-TYPE (eql locative)) LOCATIVE-ARGS STREAM
Generic Function: locate-and-find-source OBJECT LOCATIVE-TYPE LOCATIVE-ARGS

Called by FIND-SOURCE on REFERENCE objects, this
function has essentially the same purpose as FIND-SOURCE but it has different arguments to allow specializing on LOCATIVE-TYPE.

Package

mgl-pax

Source

pax.lisp (file)

Methods
Method: locate-and-find-source SYMBOL (LOCATIVE-TYPE (eql include)) LOCATIVE-ARGS
Method: locate-and-find-source SYMBOL (LOCATIVE-TYPE (eql type)) LOCATIVE-ARGS
Method: locate-and-find-source SYMBOL (LOCATIVE-TYPE (eql writer)) LOCATIVE-ARGS
Method: locate-and-find-source SYMBOL (LOCATIVE-TYPE (eql reader)) LOCATIVE-ARGS
Method: locate-and-find-source SYMBOL (LOCATIVE-TYPE (eql accessor)) LOCATIVE-ARGS
Method: locate-and-find-source SYMBOL (LOCATIVE-TYPE (eql compiler-macro)) LOCATIVE-ARGS
Method: locate-and-find-source SYMBOL (LOCATIVE-TYPE (eql macro)) LOCATIVE-ARGS
Method: locate-and-find-source SYMBOL (LOCATIVE-TYPE (eql structure-accessor)) LOCATIVE-ARGS
Method: locate-and-find-source SYMBOL (LOCATIVE-TYPE (eql constant)) LOCATIVE-ARGS
Method: locate-and-find-source SYMBOL (LOCATIVE-TYPE (eql variable)) LOCATIVE-ARGS
Method: locate-and-find-source SYMBOL (LOCATIVE-TYPE (eql locative)) LOCATIVE-ARGS
Method: locate-and-find-source OBJECT LOCATIVE-TYPE LOCATIVE-ARGS

This default implementation simply calls FIND-SOURCE with OBJECT which should cover the common case of a macro expanding to, for instance, a defun but having its own locative type.

Generic Function: locate-error-locative CONDITION
Package

mgl-pax

Methods
Method: locate-error-locative (CONDITION locate-error)
Source

pax.lisp (file)

Generic Function: locate-error-message CONDITION
Package

mgl-pax

Methods
Method: locate-error-message (CONDITION locate-error)
Source

pax.lisp (file)

Generic Function: locate-error-object CONDITION
Package

mgl-pax

Methods
Method: locate-error-object (CONDITION locate-error)
Source

pax.lisp (file)

Generic Function: locate-object OBJECT LOCATIVE-TYPE LOCATIVE-ARGS

Return the object OBJECT + locative refers to. For
example, if LOCATIVE-TYPE is the symbol PACKAGE, this
returns ‘(FIND-PACKAGE SYMBOL)‘. Signal a LOCATE-ERROR condition by calling the LOCATE-ERROR function if lookup fails. Signal other errors if the types of the argument are bad, for instance LOCATIVE-ARGS is not the empty list in the package example. If a REFERENCE is returned then it must be canonical in the sense that calling CANONICAL-REFERENCE on it will return the same reference. For extension only, don’t call this directly.

Package

mgl-pax

Source

pax.lisp (file)

Methods
Method: locate-object SYMBOL (LOCATIVE-TYPE (eql include)) LOCATIVE-ARGS
Method: locate-object SYMBOL (LOCATIVE-TYPE (eql dislocated)) LOCATIVE-ARGS
Method: locate-object SYMBOL (LOCATIVE-TYPE (eql package)) LOCATIVE-ARGS
Method: locate-object SYMBOL (LOCATIVE-TYPE (eql condition)) LOCATIVE-ARGS
Method: locate-object SYMBOL (LOCATIVE-TYPE (eql class)) LOCATIVE-ARGS
Method: locate-object SYMBOL (LOCATIVE-TYPE (eql type)) LOCATIVE-ARGS
Method: locate-object SYMBOL (LOCATIVE-TYPE (eql writer)) LOCATIVE-ARGS
Method: locate-object SYMBOL (LOCATIVE-TYPE (eql reader)) LOCATIVE-ARGS
Method: locate-object SYMBOL (LOCATIVE-TYPE (eql accessor)) LOCATIVE-ARGS
Method: locate-object SYMBOL (LOCATIVE-TYPE (eql method)) LOCATIVE-ARGS
Method: locate-object SYMBOL (LOCATIVE-TYPE (eql generic-function)) LOCATIVE-ARGS
Method: locate-object SYMBOL (LOCATIVE-TYPE (eql function)) LOCATIVE-ARGS
Method: locate-object SYMBOL (LOCATIVE-TYPE (eql compiler-macro)) LOCATIVE-ARGS
Method: locate-object SYMBOL (LOCATIVE-TYPE (eql macro)) LOCATIVE-ARGS
Method: locate-object (SYMBOL symbol) (LOCATIVE-TYPE (eql structure-accessor)) LOCATIVE-ARGS
Method: locate-object SYMBOL (LOCATIVE-TYPE (eql system)) LOCATIVE-ARGS
Method: locate-object SYMBOL (LOCATIVE-TYPE (eql constant)) LOCATIVE-ARGS
Method: locate-object SYMBOL (LOCATIVE-TYPE (eql variable)) LOCATIVE-ARGS
Method: locate-object SYMBOL (LOCATIVE-TYPE (eql section)) LOCATIVE-ARGS
Method: locate-object SYMBOL (LOCATIVE-TYPE (eql locative)) LOCATIVE-ARGS
Generic Function: reference-locative OBJECT
Package

mgl-pax

Methods
Method: reference-locative (REFERENCE reference)

automatically generated reader method

Source

pax-early.lisp (file)

Generic Function: reference-object OBJECT
Package

mgl-pax

Methods
Method: reference-object (REFERENCE reference)

automatically generated reader method

Source

pax-early.lisp (file)

Generic Function: section-entries OBJECT
Package

mgl-pax

Methods
Method: section-entries (SECTION section)

A list of strings and REFERENCE objects in the order they occurred in DEFSECTION.

Source

pax-early.lisp (file)

Generic Function: section-name OBJECT
Package

mgl-pax

Methods
Method: section-name (SECTION section)

The name of the global variable whose value is this section object.

Source

pax-early.lisp (file)

Generic Function: section-package OBJECT
Package

mgl-pax

Methods
Method: section-package (SECTION section)

*PACKAGE* will be bound to this package when generating documentation for this section.

Source

pax-early.lisp (file)

Generic Function: section-readtable OBJECT
Package

mgl-pax

Methods
Method: section-readtable (SECTION section)

*READTABLE* will be bound to this when generating documentation for this section.

Source

pax-early.lisp (file)

Generic Function: section-title OBJECT
Package

mgl-pax

Methods
Method: section-title (SECTION section)

Used in generated documentation.

Source

pax-early.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.5 Conditions

Condition: locate-error ()

Signaled by LOCATE when lookup fails and ERRORP is true.

Package

mgl-pax

Source

pax.lisp (file)

Direct superclasses

error (condition)

Direct methods
Direct slots
Slot: message
Initargs

:message

Readers

locate-error-message (generic function)

Slot: object
Initargs

:object

Readers

locate-error-object (generic function)

Slot: locative
Initargs

:locative

Readers

locate-error-locative (generic function)

Condition: transcription-consistency-error ()

A common superclass for TRANSCRIPTION-OUTPUT-CONSISTENCY-ERROR and TRANSCRIPTION-VALUES-CONSISTENCY-ERROR.

Package

mgl-pax

Source

transcribe.lisp (file)

Direct superclasses

transcription-error (condition)

Direct subclasses
Condition: transcription-error ()

Represents syntactic errors in the SOURCE argument of TRANSCRIBE and also serves as the superclass of TRANSCRIPTION-CONSISTENCY-ERROR.

Package

mgl-pax

Source

transcribe.lisp (file)

Direct superclasses

error (condition)

Direct subclasses

transcription-consistency-error (condition)

Direct methods
Direct slots
Slot: on
Initargs

:on

Readers

transcription-error-on (generic function)

Slot: file-position
Initargs

:file-position

Readers

transcription-error-file-position (generic function)

Slot: form-as-string
Initargs

:form-as-string

Readers

transcription-error-form-as-string (generic function)

Slot: message
Initargs

:message

Readers

transcription-error-message (generic function)

Slot: message-args
Initargs

:message-args

Readers

transcription-error-message-args (generic function)

Condition: transcription-output-consistency-error ()

Signaled (with CERROR) by TRANSCRIBE when invoked
with :CHECK-CONSISTENCY and the output of a form is not the same as what was parsed.

Package

mgl-pax

Source

transcribe.lisp (file)

Direct superclasses

transcription-consistency-error (condition)

Condition: transcription-values-consistency-error ()

Signaled (with CERROR) by TRANSCRIBE when invoked
with :CHECK-CONSISTENCY and the values of a form are inconsistent with their parsed representation.

Package

mgl-pax

Source

transcribe.lisp (file)

Direct superclasses

transcription-consistency-error (condition)


Previous: , Up: Exported definitions   [Contents][Index]

6.1.6 Classes

Class: reference ()

A REFERENCE represents a path (REFERENCE-LOCATIVE) to take from an object (REFERENCE-OBJECT).

Package

mgl-pax

Source

pax-early.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: object
Initargs

:object

Readers

reference-object (generic function)

Slot: locative
Initargs

:locative

Readers

reference-locative (generic function)

Class: section ()

DEFSECTION stores its NAME, TITLE, PACKAGE, READTABLE and ENTRIES in [SECTION][class] objects.

Package

mgl-pax

Source

pax-early.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: name

The name of the global variable whose value is this section object.

Initargs

:name

Readers

section-name (generic function)

Slot: package

*PACKAGE* will be bound to this package when generating documentation for this section.

Initargs

:package

Readers

section-package (generic function)

Slot: readtable

*READTABLE* will be bound to this when generating documentation for this section.

Initargs

:readtable

Readers

section-readtable (generic function)

Slot: title

Used in generated documentation.

Initargs

:title

Readers

section-title (generic function)

Slot: entries

A list of strings and REFERENCE objects in the order they occurred in DEFSECTION.

Initargs

:entries

Readers

section-entries (generic function)


Previous: , Up: Definitions   [Contents][Index]

6.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.1 Special variables

Special Variable: *collecting-headings-p*
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: *find-definitions-right-trim*
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: *format*
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: *heading-level*
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: *heading-number*
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: *headings*
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: *links*
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: *page*
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: *pages-created*
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: *reference-being-documented*
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: *references*
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: *section*
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: *table-of-contents-page*
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: *table-of-contents-stream*
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: *whitespace-chars*
Package

mgl-pax

Source

utility.lisp (file)

Special Variable: +first-name-characters+
Package

mgl-pax

Source

utility.lisp (file)

Special Variable: +name-characters+
Package

mgl-pax

Source

utility.lisp (file)

Special Variable: end-of-asdf-example
Package

mgl-pax

Source

pax.lisp (file)

Special Variable: end-of-variable-example
Package

mgl-pax

Source

pax.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.2 Macros

Macro: do-pages-created (PAGE) &body BODY
Package

mgl-pax

Source

pax.lisp (file)

Macro: with-dislocated-symbols (SYMBOLS) &body BODY
Package

mgl-pax

Source

pax.lisp (file)

Macro: with-final-output-to-page (STREAM PAGE) &body BODY
Package

mgl-pax

Source

pax.lisp (file)

Macro: with-heading (STREAM OBJECT TITLE) &body BODY
Package

mgl-pax

Source

pax.lisp (file)

Macro: with-headings (OBJECT) &body BODY
Package

mgl-pax

Source

pax.lisp (file)

Macro: with-input-stream (STREAM INPUT) &body BODY
Package

mgl-pax

Source

transcribe.lisp (file)

Macro: with-load-environment (STREAM) &body BODY
Package

mgl-pax

Source

transcribe.lisp (file)

Macro: with-nested-headings () &body BODY
Package

mgl-pax

Source

pax.lisp (file)

Macro: with-open-stream-spec (STREAM STREAM-SPEC &key DIRECTION) &body BODY
Package

mgl-pax

Source

utility.lisp (file)

Macro: with-output-stream (STREAM OUTPUT) &body BODY
Package

mgl-pax

Source

transcribe.lisp (file)

Macro: with-pages (PAGES) &body BODY
Package

mgl-pax

Source

pax.lisp (file)

Macro: with-swank () &body BODY
Package

mgl-pax

Source

pax.lisp (file)

Macro: with-temp-input-from-page (STREAM PAGE) &body BODY
Package

mgl-pax

Source

pax.lisp (file)

Macro: with-temp-output-to-page (STREAM PAGE) &body BODY
Package

mgl-pax

Source

pax.lisp (file)

Macro: with-tracking-pages-created () &body BODY
Package

mgl-pax

Source

pax.lisp (file)

Macro: with-transcription-syntax () &body BODY
Package

mgl-pax

Source

transcribe.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.3 Functions

Function: _mark-one ARRAY CH
Package

mgl-pax

Source

utility.lisp (file)

Function: _mark-range ARRAY START END
Package

mgl-pax

Source

utility.lisp (file)

Function: anchor ANCHOR STREAM
Package

mgl-pax

Source

utility.lisp (file)

Function: arglist-to-string ARGLIST
Package

mgl-pax

Source

pax.lisp (file)

Function: asdf-system-git-version SYSTEM
Package

mgl-pax

Source

pax.lisp (file)

Function: blankp STRING
Package

mgl-pax

Source

utility.lisp (file)

Function: bold STRING STREAM
Package

mgl-pax

Source

utility.lisp (file)

Function: call-with-heading STREAM OBJECT TITLE FN
Package

mgl-pax

Source

pax.lisp (file)

Function: call-with-input-stream FN INPUT
Package

mgl-pax

Source

transcribe.lisp (file)

Function: call-with-output-stream FN OUTPUT
Package

mgl-pax

Source

transcribe.lisp (file)

Function: capture-id CAPTURE
Package

mgl-pax

Source

transcribe.lisp (file)

Function: capture-value CAPTURE
Package

mgl-pax

Source

transcribe.lisp (file)

Function: check-body-docstring DOCSTRING
Package

mgl-pax

Source

pax.lisp (file)

Function: check-command-values COMMAND
Package

mgl-pax

Source

transcribe.lisp (file)

Function: check-location LOCATION
Package

mgl-pax

Source

pax.lisp (file)

Function: check-output-consistency STREAM FORM-AS-STRING OUTPUT CAPTURED-OUTPUT
Package

mgl-pax

Source

transcribe.lisp (file)

Function: check-value-consistency STREAM FORM-AS-STRING VALUE VALUE-CAPTURE
Package

mgl-pax

Source

transcribe.lisp (file)

Function: check-values-consistency STREAM FORM-AS-STRING VALUES VALUE-CAPTURES
Package

mgl-pax

Source

transcribe.lisp (file)

Function: code STRING
Package

mgl-pax

Source

utility.lisp (file)

Function: code-fragment NAME
Package

mgl-pax

Source

utility.lisp (file)

Function: collect-heading OBJECT TITLE
Package

mgl-pax

Source

pax.lisp (file)

Function: collect-headings OBJECT
Package

mgl-pax

Source

pax.lisp (file)

Function: command-captures COMMAND
Package

mgl-pax

Source

transcribe.lisp (file)

Function: command-form COMMAND
Package

mgl-pax

Source

transcribe.lisp (file)

Function: command-output-capture COMMAND
Package

mgl-pax

Source

transcribe.lisp (file)

Function: command-string COMMAND
Package

mgl-pax

Source

transcribe.lisp (file)

Function: command-syntax-id COMMAND
Package

mgl-pax

Source

transcribe.lisp (file)

Setf Expander

(setf command-syntax-id) (setf expander)

Setf Expander: (setf command-syntax-id) COMMAND
Package

mgl-pax

Source

transcribe.lisp (file)

Reader

command-syntax-id (function)

Function: command-value-captures COMMAND
Package

mgl-pax

Source

transcribe.lisp (file)

Function: consistency-error CLASS STREAM FORM-AS-STRING MESSAGE &rest MESSAGE-ARGS
Package

mgl-pax

Source

transcribe.lisp (file)

Function: convert-source-location SOURCE-LOCATION SYSTEM-DIR REFERENCE
Package

mgl-pax

Source

pax.lisp (file)

Function: copy-heading INSTANCE
Package

mgl-pax

Source

pax.lisp (file)

Function: copy-link INSTANCE
Package

mgl-pax

Source

pax.lisp (file)

Function: copy-page INSTANCE
Package

mgl-pax

Source

pax.lisp (file)

Function: defer-tag-handling TAGS STOP-TAGS HANDLE-STRINGS FN PARENT TREE
Package

mgl-pax

Source

utility.lisp (file)

Function: delimiterp CHAR
Package

mgl-pax

Source

pax.lisp (file)

Function: docstring-indentation DOCSTRING &key FIRST-LINE-SPECIAL-P
Package

mgl-pax

Source

pax.lisp (file)

Function: emit-footer STREAM
Package

mgl-pax

Source

pax.lisp (file)

Function: entry-to-reference ENTRY
Package

mgl-pax

Source

pax-early.lisp (file)

Function: escape-markdown STRING
Package

mgl-pax

Source

utility.lisp (file)

Function: eval-and-capture FORM
Package

mgl-pax

Source

transcribe.lisp (file)

Function: expand-define-definer-for-symbol-as-locative-definer-body SYMBOL LOCATIVE-TYPE LAMBDA-LIST DOCSTRING
Package

mgl-pax

Source

pax.lisp (file)

Function: export-some-symbols NAME ENTRIES PACKAGE
Package

mgl-pax

Source

pax-early.lisp (file)

Function: extract-name-from-label LABEL
Package

mgl-pax

Source

pax.lisp (file)

Function: fancy-navigation OBJECT
Package

mgl-pax

Source

pax.lisp (file)

Function: file-position-to-line-number FILENAME FILE-POSITION
Package

mgl-pax

Source

pax.lisp (file)

Function: file-subseq PATHNAME &optional START END
Package

mgl-pax

Source

pax.lisp (file)

Function: filter-captures CAPTURES &rest IDS
Package

mgl-pax

Source

transcribe.lisp (file)

Function: filter-documentation SYMBOL DOC-TYPE
Package

mgl-pax

Source

pax.lisp (file)

Function: filter-locations LOCATIONS FILTER-STRING
Package

mgl-pax

Source

pax.lisp (file)

Function: filter-references REFS
Package

mgl-pax

Source

pax.lisp (file)

Function: filter-references-by-format REFS
Package

mgl-pax

Source

pax.lisp (file)

Function: find-accessor-slot-definition ACCESSOR-SYMBOL CLASS-SYMBOL
Package

mgl-pax

Source

pax.lisp (file)

Function: find-definitions-find-symbol-or-package NAME
Package

mgl-pax

Source

pax.lisp (file)

Function: find-known-reference REFERENCE
Package

mgl-pax

Source

pax.lisp (file)

Function: find-link REFERENCE
Package

mgl-pax

Source

pax.lisp (file)

Function: find-link-by-id ID
Package

mgl-pax

Source

pax.lisp (file)

Function: find-locative-around TREE NAME-ELEMENT KNOWN-REFERENCES
Package

mgl-pax

Source

pax.lisp (file)

Function: find-one-location LOCATIONS FILTER-STRINGS
Package

mgl-pax

Source

pax.lisp (file)

Function: find-prefix ID SYNTAX &key ERRORP
Package

mgl-pax

Source

transcribe.lisp (file)

Function: find-reader-slot-definition ACCESSOR-SYMBOL CLASS-SYMBOL
Package

mgl-pax

Source

pax.lisp (file)

Function: find-reference-by-locative-string LOCATIVE-STRING KNOWN-REFERENCES &key IF-DISLOCATED
Package

mgl-pax

Source

pax.lisp (file)

Function: find-syntax SYNTAX
Package

mgl-pax

Source

transcribe.lisp (file)

Function: find-writer-slot-definition ACCESSOR-SYMBOL CLASS-SYMBOL
Package

mgl-pax

Source

pax.lisp (file)

Function: format-references NAME REFS
Package

mgl-pax

Source

pax.lisp (file)

Function: function-arg-names ARGLIST
Package

mgl-pax

Source

pax.lisp (file)

Function: generate-documentation-for-slot-definition SYMBOL SLOT-DEF LOCATIVE-TYPE LOCATIVE-ARGS STREAM
Package

mgl-pax

Source

pax.lisp (file)

Function: git-version GIT-DIR
Package

mgl-pax

Source

pax.lisp (file)

Function: hash-link STRING DETECT-COLLISION-FN &key MIN-N-CHARS
Package

mgl-pax

Source

pax.lisp (file)

Function: heading LEVEL STREAM
Package

mgl-pax

Source

utility.lisp (file)

Function: heading-level INSTANCE
Function: (setf heading-level) VALUE INSTANCE
Package

mgl-pax

Source

pax.lisp (file)

Function: heading-number ()
Package

mgl-pax

Source

pax.lisp (file)

Function: heading-object INSTANCE
Function: (setf heading-object) VALUE INSTANCE
Package

mgl-pax

Source

pax.lisp (file)

Function: heading-p OBJECT
Package

mgl-pax

Source

pax.lisp (file)

Function: heading-title INSTANCE
Function: (setf heading-title) VALUE INSTANCE
Package

mgl-pax

Source

pax.lisp (file)

Function: html-safe-name NAME
Package

mgl-pax

Source

utility.lisp (file)

Function: include-region SOURCE
Package

mgl-pax

Source

pax.lisp (file)

Function: italic STRING STREAM
Package

mgl-pax

Source

utility.lisp (file)

Function: join-consecutive-non-blank-strings-in-list LIST
Package

mgl-pax

Source

utility.lisp (file)

Function: join-consecutive-non-blank-strings-in-parse-tree PARSE-TREE
Package

mgl-pax

Source

utility.lisp (file)

Function: link-id INSTANCE
Function: (setf link-id) VALUE INSTANCE
Package

mgl-pax

Source

pax.lisp (file)

Function: link-p OBJECT
Package

mgl-pax

Source

pax.lisp (file)

Function: link-page INSTANCE
Function: (setf link-page) VALUE INSTANCE
Package

mgl-pax

Source

pax.lisp (file)

Function: link-page-to-n-uses INSTANCE
Function: (setf link-page-to-n-uses) VALUE INSTANCE
Package

mgl-pax

Source

pax.lisp (file)

Function: link-reference INSTANCE
Function: (setf link-reference) VALUE INSTANCE
Package

mgl-pax

Source

pax.lisp (file)

Function: link-to-reference REFERENCE
Package

mgl-pax

Source

pax.lisp (file)

Function: link-used-on-current-page-p LINK
Package

mgl-pax

Source

pax.lisp (file)

Function: locate-and-print-bullet LOCATIVE-TYPE LOCATIVE-ARGS SYMBOL STREAM
Package

mgl-pax

Source

pax.lisp (file)

Function: locate-definition-for-emacs NAME LOCATIVE-STRING
Package

mgl-pax

Source

pax.lisp (file)

Function: locate-definition-for-emacs-1 NAME LOCATIVE-STRING
Package

mgl-pax

Source

pax.lisp (file)

Function: locate-reference-link-definition-for-emacs STRING
Package

mgl-pax

Source

pax.lisp (file)

Function: location-file LOCATION
Package

mgl-pax

Source

pax.lisp (file)

Function: location-position LOCATION
Package

mgl-pax

Source

pax.lisp (file)

Function: locative-equal LOCATIVE-1 LOCATIVE-2
Package

mgl-pax

Source

pax-early.lisp (file)

Function: locative-lambda-list-method-for-symbol SYMBOL
Package

mgl-pax

Source

pax.lisp (file)

Function: longest-common-prefix STRING CHARS &key FIRST-LINE-SPECIAL-P
Package

mgl-pax

Source

utility.lisp (file)

Function: macro-arg-names ARGLIST
Package

mgl-pax

Source

pax.lisp (file)

Function: make-heading &key (OBJECT OBJECT) (TITLE TITLE) (LEVEL LEVEL)
Package

mgl-pax

Source

pax.lisp (file)

Function: make-link &key (REFERENCE REFERENCE) (PAGE PAGE) (ID ID) (PAGE-TO-N-USES PAGE-TO-N-USES)
Package

mgl-pax

Source

pax.lisp (file)

Function: make-page &key (REFERENCES REFERENCES) (TEMP-STREAM-SPEC TEMP-STREAM-SPEC) (FINAL-STREAM-SPEC FINAL-STREAM-SPEC) (URI-FRAGMENT URI-FRAGMENT) (HEADER-FN HEADER-FN) (FOOTER-FN FOOTER-FN) (SOURCE-URI-FN SOURCE-URI-FN)
Package

mgl-pax

Source

pax.lisp (file)

Function: map-markdown-parse-tree TAGS STOP-TAGS HANDLE-STRINGS FN STRING
Package

mgl-pax

Source

utility.lisp (file)

Function: map-names STRING FN
Package

mgl-pax

Source

pax.lisp (file)

Function: mark-page-created PAGE
Package

mgl-pax

Source

pax.lisp (file)

Function: mark-up-superclasses SUPERCLASSES
Package

mgl-pax

Source

pax.lisp (file)

Function: markdown-special-char-p CHAR
Package

mgl-pax

Source

utility.lisp (file)

Function: massage-docstring DOCSTRING &key INDENTATION
Package

mgl-pax

Source

pax.lisp (file)

Function: match-prefixes LINE SYNTAX-ID
Package

mgl-pax

Source

transcribe.lisp (file)

Function: matching-prefix STRING CHARS
Package

mgl-pax

Source

utility.lisp (file)

Function: maybe-print-docstring OBJECT DOC-TYPE STREAM
Package

mgl-pax

Source

pax.lisp (file)

Function: method-for-inspect-value METHOD

Returns a "pretty" list describing METHOD. The first element of the list is the name of generic-function method is specialized on, the second element is the method qualifiers, the rest of the list is the method’s specialiazers (as per METHOD-SPECIALIZERS-FOR-INSPECT).

Package

mgl-pax

Source

pax.lisp (file)

Function: method-specializers-for-inspect METHOD

Return a "pretty" list of the method’s specializers. Normal specializers are replaced by the name of the class, eql specializers are replaced by ‘(eql ,object).

Package

mgl-pax

Source

pax.lisp (file)

Function: method-specializers-list METHOD
Package

mgl-pax

Source

pax.lisp (file)

Function: n-leading-spaces LINE
Package

mgl-pax

Source

pax.lisp (file)

Function: navigation-link OBJECT STREAM
Package

mgl-pax

Source

pax.lisp (file)

Function: no-lowercase-chars-p STRING
Package

mgl-pax

Source

pax.lisp (file)

Function: no-value-capture-p CAPTURE
Package

mgl-pax

Source

transcribe.lisp (file)

Function: normalize-pathname PATHNAME
Package

mgl-pax

Source

utility.lisp (file)

Function: output-capture-p CAPTURE
Package

mgl-pax

Source

transcribe.lisp (file)

Function: output-string OUTPUT-CAPTURE
Package

mgl-pax

Source

transcribe.lisp (file)

Function: page-final-stream-spec INSTANCE
Function: (setf page-final-stream-spec) VALUE INSTANCE
Package

mgl-pax

Source

pax.lisp (file)

Function: page-footer-fn INSTANCE
Function: (setf page-footer-fn) VALUE INSTANCE
Package

mgl-pax

Source

pax.lisp (file)

Function: page-header-fn INSTANCE
Function: (setf page-header-fn) VALUE INSTANCE
Package

mgl-pax

Source

pax.lisp (file)

Function: page-p OBJECT
Package

mgl-pax

Source

pax.lisp (file)

Function: page-references INSTANCE
Function: (setf page-references) VALUE INSTANCE
Package

mgl-pax

Source

pax.lisp (file)

Function: page-source-uri-fn INSTANCE
Function: (setf page-source-uri-fn) VALUE INSTANCE
Package

mgl-pax

Source

pax.lisp (file)

Function: page-temp-stream-spec INSTANCE
Function: (setf page-temp-stream-spec) VALUE INSTANCE
Package

mgl-pax

Source

pax.lisp (file)

Function: page-uri-fragment INSTANCE
Function: (setf page-uri-fragment) VALUE INSTANCE
Package

mgl-pax

Source

pax.lisp (file)

Function: parse-form STREAM
Package

mgl-pax

Source

transcribe.lisp (file)

Function: parse-prefixed STREAM PREFIX-ID SYNTAX-ID
Package

mgl-pax

Source

transcribe.lisp (file)

Function: parse-readable STREAM SYNTAX-ID
Package

mgl-pax

Source

transcribe.lisp (file)

Function: parse-readable* STREAM
Package

mgl-pax

Source

transcribe.lisp (file)

Function: parse-readable-with-continuation STREAM CONTINUATION-PREFIX
Package

mgl-pax

Source

transcribe.lisp (file)

Function: parse-transcript-element STREAM PREFIX-ID SYNTAX-ID FIRST-LINE MATCH-LENGTH
Package

mgl-pax

Source

transcribe.lisp (file)

Function: prefix-lines PREFIX STRING &key EXCLUDE-FIRST-LINE-P
Package

mgl-pax

Source

pax.lisp (file)

Function: prin1-and-escape-markdown OBJECT
Package

mgl-pax

Source

utility.lisp (file)

Function: print-arglist ARGLIST STREAM
Package

mgl-pax

Source

pax.lisp (file)

Function: print-bullet OBJECT STREAM
Package

mgl-pax

Source

pax.lisp (file)

Function: print-reference-bullet REFERENCE STREAM
Package

mgl-pax

Source

pax.lisp (file)

Function: print-reference-with-package REFERENCE
Package

mgl-pax

Source

transcribe.lisp (file)

Function: print-table-of-contents-entry OBJECT STRING STREAM
Package

mgl-pax

Source

pax.lisp (file)

Function: reachable-canonical-references OBJECTS
Package

mgl-pax

Source

pax.lisp (file)

Function: read-first-line FILENAME
Package

mgl-pax

Source

pax.lisp (file)

Function: read-form-and-string STREAM EOF &key PRESERVE-WHITESPACE-P
Package

mgl-pax

Source

transcribe.lisp (file)

Function: read-line* STREAM &optional EOF-ERROR-P EOF-VALUE
Package

mgl-pax

Source

utility.lisp (file)

Function: read-locative-from-string STRING
Package

mgl-pax

Source

pax.lisp (file)

Function: read-marked-up-locative-from-string STRING
Package

mgl-pax

Source

pax.lisp (file)

Function: read-prefixed-lines STREAM PREFIX &key FIRST-LINE-PREFIX EAT-ONE-SPACE-P
Package

mgl-pax

Source

utility.lisp (file)

Function: read-stream-into-string STREAM &key BUFFER-SIZE
Package

mgl-pax

Source

utility.lisp (file)

Function: read-transcript INPUT &key SYNTAXES
Package

mgl-pax

Source

transcribe.lisp (file)

Function: readable-capture-p CAPTURE
Package

mgl-pax

Source

transcribe.lisp (file)

Function: readable-object READABLE-CAPTURE
Package

mgl-pax

Source

transcribe.lisp (file)

Function: readable-object-p OBJECT
Package

mgl-pax

Source

transcribe.lisp (file)

Function: readable-string READABLE-CAPTURE
Package

mgl-pax

Source

transcribe.lisp (file)

Function: readably-consistent-p OBJECT CAPTURE
Package

mgl-pax

Source

transcribe.lisp (file)

Function: reference-locative-type REFERENCE
Package

mgl-pax

Source

pax-early.lisp (file)

Function: reference-page REFERENCE
Package

mgl-pax

Source

pax.lisp (file)

Function: reference-to-anchor REFERENCE
Package

mgl-pax

Source

pax.lisp (file)

Function: reference= REFERENCE-1 REFERENCE-2
Package

mgl-pax

Source

pax-early.lisp (file)

Function: references-for-similar-names NAME REFS
Package

mgl-pax

Source

pax.lisp (file)

Function: references-for-symbol SYMBOL REFS N-CHARS-READ
Package

mgl-pax

Source

pax.lisp (file)

Function: references-for-the-same-symbol-p REFS
Package

mgl-pax

Source

pax.lisp (file)

Function: relative-page-uri-fragment PAGE REFERENCE-PAGE
Package

mgl-pax

Source

pax.lisp (file)

Function: relativize-pathname PATHNAME REFERENCE-PATHNAME

Return a pathname that’s equivalent to PATHNAME but relative to REFERENCE-PATHNAME if possible. Like ENOUGH-NAMESTRING, but inserts :UP components if necessary.

Package

mgl-pax

Source

utility.lisp (file)

Function: replace-known-references STRING &key KNOWN-REFERENCES
Package

mgl-pax

Source

pax.lisp (file)

Function: resolve-dislocated REFS
Package

mgl-pax

Source

pax.lisp (file)

Function: resolve-generic-function-and-methods REFS
Package

mgl-pax

Source

pax.lisp (file)

Function: section-title-or-name SECTION
Package

mgl-pax

Source

pax-early.lisp (file)

Function: skip-white-space-till-end-of-line STREAM
Package

mgl-pax

Source

transcribe.lisp (file)

Function: source-uri REFERENCE
Package

mgl-pax

Source

pax.lisp (file)

Function: strip-docstring-indentation DOCSTRING &key FIRST-LINE-SPECIAL-P
Package

mgl-pax

Source

pax.lisp (file)

Function: strip-longest-common-prefix STRING CHARS &key FIRST-LINE-SPECIAL-P
Package

mgl-pax

Source

utility.lisp (file)

Function: subseq* SEQ START
Package

mgl-pax

Source

utility.lisp (file)

Function: symbol-accessible-in-package-p SYMBOL PACKAGE
Package

mgl-pax

Source

pax-early.lisp (file)

Function: symbol-global-value SYMBOL
Package

mgl-pax

Source

utility.lisp (file)

Function: symbol-lambda-list-method SYMBOL LOCATIVE-TYPE
Package

mgl-pax

Source

pax.lisp (file)

Function: transcribe-for-emacs STRING DEFAULT-SYNTAX* UPDATE-ONLY ECHO FIRST-LINE-SPECIAL-P
Package

mgl-pax

Source

transcribe.lisp (file)

Function: transcribe-output STREAM OUTPUT CAPTURE SYNTAX-ID UPDATE-ONLY INCLUDE-NO-OUTPUT
Package

mgl-pax

Source

transcribe.lisp (file)

Function: transcribe-readable-value STREAM VALUE CAPTURE SYNTAX-ID
Package

mgl-pax

Source

transcribe.lisp (file)

Function: transcribe-unreadable-value STREAM OBJECT SYNTAX-ID
Package

mgl-pax

Source

transcribe.lisp (file)

Function: transcribe-values STREAM VALUES CAPTURES SYNTAX-ID UPDATE-ONLY INCLUDE-NO-VALUE
Package

mgl-pax

Source

transcribe.lisp (file)

Function: transcription-error* MESSAGE &rest MESSAGE-ARGS
Package

mgl-pax

Source

transcribe.lisp (file)

Function: transform-entries ENTRIES
Package

mgl-pax

Source

pax-early.lisp (file)

Function: transform-tree FN TREE
Package

mgl-pax

Source

utility.lisp (file)

Function: translate-code-block PARENT CODE-BLOCK
Package

mgl-pax

Source

pax.lisp (file)

Function: translate-emph PARENT TREE KNOWN-REFERENCES
Package

mgl-pax

Source

pax.lisp (file)

Function: translate-name PARENT TREE NAME KNOWN-REFERENCES
Package

mgl-pax

Source

pax.lisp (file)

Function: translate-page-spec PAGE FORMAT
Package

mgl-pax

Source

pax.lisp (file)

Function: translate-page-specs PAGES FORMAT
Package

mgl-pax

Source

pax.lisp (file)

Function: translate-to-code PARENT TREE KNOWN-REFERENCES
Package

mgl-pax

Source

pax.lisp (file)

Function: translate-to-links PARENT TREE KNOWN-REFERENCES
Package

mgl-pax

Source

pax.lisp (file)

Function: translate-uppercase-name PARENT TREE NAME KNOWN-REFERENCES
Package

mgl-pax

Source

pax.lisp (file)

Function: trim-whitespace STRING
Package

mgl-pax

Source

utility.lisp (file)

Function: unreadable-capture-p CAPTURE
Package

mgl-pax

Source

transcribe.lisp (file)

Function: unreadable-string UNREADABLE-CAPTURE
Package

mgl-pax

Source

transcribe.lisp (file)

Function: value-capture-p CAPTURE
Package

mgl-pax

Source

transcribe.lisp (file)

Function: whitespacep CHAR
Package

mgl-pax

Source

utility.lisp (file)

Function: write-navigation-link HEADING STREAM
Package

mgl-pax

Source

pax.lisp (file)

Function: write-prefixed-lines STRING PREFIX STREAM &key ADD-ONE-SPACE-P FIRST-LINE-PREFIX
Package

mgl-pax

Source

utility.lisp (file)

Function: write-transcript TRANSCRIPT OUTPUT &key UPDATE-ONLY INCLUDE-NO-OUTPUT INCLUDE-NO-VALUE ECHO CHECK-CONSISTENCY DEFAULT-SYNTAX SYNTAXES
Package

mgl-pax

Source

transcribe.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.4 Generic functions

Generic Function: call-with-open-stream-spec STREAM-SPEC DIRECTION FN
Package

mgl-pax

Source

utility.lisp (file)

Methods
Method: call-with-open-stream-spec (STREAM stream) DIRECTION FN
Method: call-with-open-stream-spec (SPEC file-stream-spec) DIRECTION FN
Method: call-with-open-stream-spec (SPEC string-stream-spec) (DIRECTION (eql output)) FN
Method: call-with-open-stream-spec (SPEC string-stream-spec) (DIRECTION (eql input)) FN
Generic Function: delete-stream-spec STREAM-SPEC
Package

mgl-pax

Source

utility.lisp (file)

Methods
Method: delete-stream-spec (SPEC file-stream-spec)
Method: delete-stream-spec (SPEC string-stream-spec)
Generic Function: file-stream-spec-open-args OBJECT
Package

mgl-pax

Methods
Method: file-stream-spec-open-args (FILE-STREAM-SPEC file-stream-spec)

automatically generated reader method

Source

utility.lisp (file)

Generic Function: file-stream-spec-pathname OBJECT
Package

mgl-pax

Methods
Method: file-stream-spec-pathname (FILE-STREAM-SPEC file-stream-spec)

automatically generated reader method

Source

utility.lisp (file)

Generic Function: locative-lambda-list SYMBOL
Package

mgl-pax

Source

pax.lisp (file)

Methods
Method: locative-lambda-list (SYMBOL (eql include))

Refers to a region of a file. SOURCE can be a string or a
pathname in which case the whole file is being pointed to or it can explicitly supply START, END locatives. INCLUDE is typically used to include non-lisp files in the documentation (say markdown or elisp
as in the next example) or regions of lisp source files. This can reduce clutter and duplication.

“‘commonlisp
(defsection example-section ()
(pax.el (include #.(asdf:system-relative-pathname :mgl-pax "src/pax.el") :header-nl "“‘elisp" :footer-nl "“‘")) (foo-example (include (:start (foo function)
:end (end-of-foo-example variable)) :header-nl "“‘commonlisp"
:footer-nl "“‘"))

(defun foo (x)
(1+ x))

;;; Since file regions are copied verbatim, comments survive. (defmacro bar ())

;;; This comment is the last thing in FOO-EXAMPLE’s
;;; documentation since we use the dummy END-OF-FOO-EXAMPLE
;;; variable to mark the end location.
(defvar end-of-foo-example)

;;; More irrelevant code follows.
“‘

In the above example, pressing ‘M-.‘ on PAX.EL will open the ‘src/pax.el‘ file and put the cursor on its first character. ‘M-.‘
on ‘FOO-EXAMPLE‘ will go to the source location of the ‘(asdf:system locative)‘ locative.

When documentation is generated, the entire ‘pax.el‘ file is
included in the markdown surrounded by the strings given as
HEADER-NL and FOOTER-NL (if any). The trailing newline character is assumed implicitly. If that’s undesirable, then use HEADER and
FOOTER instead. The documentation of ‘FOO-EXAMPLE‘ will be the
region of the file from the source location of the START
locative (inclusive) to the source location of the END
locative (exclusive). START and END default to the beginning and end of the file, respectively.

Note that the file of the source location of :START and :END must be the same. If SOURCE is pathname designator, then it must be absolute so that the locative is context independent.

Finally, if specified LINE-PREFIX is a string that’s prepended to
each line included in the documentation. For example, a string of
four spaces makes markdown think it’s a code block.

Method: locative-lambda-list (SYMBOL (eql dislocated))

Refers to a symbol in a non-specific context. Useful for preventing autolinking. For example, if there is a function called ‘FOO‘ then

‘FOO‘

will be linked to (if *DOCUMENT-LINK-CODE*) its definition. However,

[‘FOO‘][dislocated]

will not be. On a dislocated locative LOCATE always fails with a LOCATE-ERROR condition.

Method: locative-lambda-list (SYMBOL (eql package))
Method: locative-lambda-list (SYMBOL (eql condition))
Method: locative-lambda-list (SYMBOL (eql class))
Method: locative-lambda-list (SYMBOL (eql type))

TYPE can refer to classes as well, but it’s better style to use the more specific CLASS locative type for that. Another difference to CLASS is that an attempt is made at printing the arguments of type specifiers.

Method: locative-lambda-list (SYMBOL (eql writer))

To refer to a writer named ‘FOO-SLOT‘ of class ‘FOO‘:

(foo-slot (writer foo))

Method: locative-lambda-list (SYMBOL (eql reader))

To refer to a reader named ‘FOO-SLOT‘ of class ‘FOO‘:

(foo-slot (reader foo))

Method: locative-lambda-list (SYMBOL (eql accessor))

To refer to an accessor named ‘FOO-SLOT‘ of class ‘FOO‘:

(foo-slot (accessor foo))

Method: locative-lambda-list (SYMBOL (eql method))

See CL:FIND-METHOD for the description of the arguments. To refer to the default method of the three argument generic function FOO:

(foo (method () (t t t)))

Method: locative-lambda-list (SYMBOL (eql generic-function))
Method: locative-lambda-list (SYMBOL (eql function))

Note that the arglist in the generated documentation depends on the quality of SWANK-BACKEND:ARGLIST. It may be that default values of optional and keyword arguments are missing.

Method: locative-lambda-list (SYMBOL (eql compiler-macro))
Method: locative-lambda-list (SYMBOL (eql macro))
Method: locative-lambda-list (SYMBOL (eql structure-accessor))

This is a synonym of FUNCTION with the difference that the often ugly and certainly uninformative lambda list will not be printed.

Method: locative-lambda-list (SYMBOL (eql system))

Refers to an asdf system. The generated documentation will include meta information extracted from the system definition. This also serves as an example of a symbol that’s not accessible in the current package and consequently is not exported.

Method: locative-lambda-list (SYMBOL (eql constant))

Refers to a DEFCONSTANT. INITFORM, or if not specified, the value of the constant is included in the documentation.

Method: locative-lambda-list (SYMBOL (eql variable))

Refers to a global special variable. INITFORM, or if not specified, the global value of the variable is included in the documentation.

Method: locative-lambda-list (SYMBOL (eql section))

Refers to a section defined by DEFSECTION.

Method: locative-lambda-list (SYMBOL (eql locative))

This is the locative for locatives. When ‘M-.‘ is pressed on ‘VARIABLE‘ in ‘(VARIABLE LOCATIVE)‘, this is what makes it possible to land at the ‘(DEFINE-LOCATIVE-TYPE VARIABLE ...)‘ form. Similarly, ‘(LOCATIVE LOCATIVE)‘ leads to this very definition.

Generic Function: make-stream-spec OBJECT &rest ARGS
Package

mgl-pax

Source

utility.lisp (file)

Methods
Method: make-stream-spec (SPEC (eql t)) &rest ARGS
Method: make-stream-spec (STREAM stream) &rest ARGS
Method: make-stream-spec (OBJECT pathname) &rest ARGS
Method: make-stream-spec (OBJECT string) &rest ARGS
Method: make-stream-spec (OBJECT null) &rest ARGS
Generic Function: string-stream-spec-string OBJECT
Generic Function: (setf string-stream-spec-string) NEW-VALUE OBJECT
Package

mgl-pax

Methods
Method: string-stream-spec-string (STRING-STREAM-SPEC string-stream-spec)

automatically generated reader method

Source

utility.lisp (file)

Method: (setf string-stream-spec-string) NEW-VALUE (STRING-STREAM-SPEC string-stream-spec)

automatically generated writer method

Source

utility.lisp (file)

Generic Function: symbol-lambda-list SYMBOL LOCATIVE-TYPE
Package

mgl-pax

Source

pax.lisp (file)

Generic Function: transcription-error-file-position CONDITION
Package

mgl-pax

Methods
Method: transcription-error-file-position (CONDITION transcription-error)
Source

transcribe.lisp (file)

Generic Function: transcription-error-form-as-string CONDITION
Package

mgl-pax

Methods
Method: transcription-error-form-as-string (CONDITION transcription-error)
Source

transcribe.lisp (file)

Generic Function: transcription-error-message CONDITION
Package

mgl-pax

Methods
Method: transcription-error-message (CONDITION transcription-error)
Source

transcribe.lisp (file)

Generic Function: transcription-error-message-args CONDITION
Package

mgl-pax

Methods
Method: transcription-error-message-args (CONDITION transcription-error)
Source

transcribe.lisp (file)

Generic Function: transcription-error-on CONDITION
Package

mgl-pax

Methods
Method: transcription-error-on (CONDITION transcription-error)
Source

transcribe.lisp (file)

Generic Function: unmake-stream-spec STREAM-SPEC
Package

mgl-pax

Source

utility.lisp (file)

Methods
Method: unmake-stream-spec (STREAM stream)
Method: unmake-stream-spec (SPEC file-stream-spec)
Method: unmake-stream-spec (SPEC string-stream-spec)

Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.5 Structures

Structure: heading ()
Package

mgl-pax

Source

pax.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots
Slot: object
Readers

heading-object (function)

Writers

(setf heading-object) (function)

Slot: title
Readers

heading-title (function)

Writers

(setf heading-title) (function)

Slot: level
Readers

heading-level (function)

Writers

(setf heading-level) (function)

Structure: link ()
Package

mgl-pax

Source

pax.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots
Slot: reference
Readers

link-reference (function)

Writers

(setf link-reference) (function)

Slot: page
Readers

link-page (function)

Writers

(setf link-page) (function)

Slot: id
Readers

link-id (function)

Writers

(setf link-id) (function)

Slot: page-to-n-uses
Readers

link-page-to-n-uses (function)

Writers

(setf link-page-to-n-uses) (function)

Structure: page ()
Package

mgl-pax

Source

pax.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots
Slot: references
Readers

page-references (function)

Writers

(setf page-references) (function)

Slot: temp-stream-spec
Readers

page-temp-stream-spec (function)

Writers

(setf page-temp-stream-spec) (function)

Slot: final-stream-spec
Readers

page-final-stream-spec (function)

Writers

(setf page-final-stream-spec) (function)

Slot: uri-fragment
Readers

page-uri-fragment (function)

Writers

(setf page-uri-fragment) (function)

Slot: header-fn
Readers

page-header-fn (function)

Writers

(setf page-header-fn) (function)

Slot: footer-fn
Readers

page-footer-fn (function)

Writers

(setf page-footer-fn) (function)

Slot: source-uri-fn
Readers

page-source-uri-fn (function)

Writers

(setf page-source-uri-fn) (function)


Previous: , Up: Internal definitions   [Contents][Index]

6.2.6 Classes

Class: file-stream-spec ()
Package

mgl-pax

Source

utility.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: pathname
Initargs

:pathname

Readers

file-stream-spec-pathname (generic function)

Slot: open-args
Initargs

:open-args

Readers

file-stream-spec-open-args (generic function)

Class: string-stream-spec ()
Package

mgl-pax

Source

utility.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: string
Initargs

:string

Initform

""

Readers

string-stream-spec-string (generic function)

Writers

(setf string-stream-spec-string) (generic function)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   M  
Index Entry  Section

F
File, Lisp, mgl-pax.asd: The mgl-pax<dot>asd file
File, Lisp, mgl-pax/src/package.lisp: The mgl-pax/src/package<dot>lisp file
File, Lisp, mgl-pax/src/pax-early.lisp: The mgl-pax/src/pax-early<dot>lisp file
File, Lisp, mgl-pax/src/pax.lisp: The mgl-pax/src/pax<dot>lisp file
File, Lisp, mgl-pax/src/transcribe.lisp: The mgl-pax/src/transcribe<dot>lisp file
File, Lisp, mgl-pax/src/utility.lisp: The mgl-pax/src/utility<dot>lisp file

L
Lisp File, mgl-pax.asd: The mgl-pax<dot>asd file
Lisp File, mgl-pax/src/package.lisp: The mgl-pax/src/package<dot>lisp file
Lisp File, mgl-pax/src/pax-early.lisp: The mgl-pax/src/pax-early<dot>lisp file
Lisp File, mgl-pax/src/pax.lisp: The mgl-pax/src/pax<dot>lisp file
Lisp File, mgl-pax/src/transcribe.lisp: The mgl-pax/src/transcribe<dot>lisp file
Lisp File, mgl-pax/src/utility.lisp: The mgl-pax/src/utility<dot>lisp file

M
mgl-pax.asd: The mgl-pax<dot>asd file
mgl-pax/src: The mgl-pax/src module
mgl-pax/src/package.lisp: The mgl-pax/src/package<dot>lisp file
mgl-pax/src/pax-early.lisp: The mgl-pax/src/pax-early<dot>lisp file
mgl-pax/src/pax.lisp: The mgl-pax/src/pax<dot>lisp file
mgl-pax/src/transcribe.lisp: The mgl-pax/src/transcribe<dot>lisp file
mgl-pax/src/utility.lisp: The mgl-pax/src/utility<dot>lisp file
Module, mgl-pax/src: The mgl-pax/src module

Jump to:   F   L   M  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   (   _  
A   B   C   D   E   F   G   H   I   J   L   M   N   O   P   R   S   T   U   V   W  
Index Entry  Section

(
(setf command-syntax-id): Internal functions
(setf heading-level): Internal functions
(setf heading-object): Internal functions
(setf heading-title): Internal functions
(setf link-id): Internal functions
(setf link-page): Internal functions
(setf link-page-to-n-uses): Internal functions
(setf link-reference): Internal functions
(setf page-final-stream-spec): Internal functions
(setf page-footer-fn): Internal functions
(setf page-header-fn): Internal functions
(setf page-references): Internal functions
(setf page-source-uri-fn): Internal functions
(setf page-temp-stream-spec): Internal functions
(setf page-uri-fragment): Internal functions
(setf string-stream-spec-string): Internal generic functions
(setf string-stream-spec-string): Internal generic functions

_
_mark-one: Internal functions
_mark-range: Internal functions

A
anchor: Internal functions
arglist-to-string: Internal functions
asdf-system-git-version: Internal functions

B
blankp: Internal functions
bold: Internal functions

C
call-with-heading: Internal functions
call-with-input-stream: Internal functions
call-with-open-stream-spec: Internal generic functions
call-with-open-stream-spec: Internal generic functions
call-with-open-stream-spec: Internal generic functions
call-with-open-stream-spec: Internal generic functions
call-with-open-stream-spec: Internal generic functions
call-with-output-stream: Internal functions
canonical-reference: Exported generic functions
canonical-reference: Exported generic functions
canonical-reference: Exported generic functions
canonical-reference: Exported generic functions
canonical-reference: Exported generic functions
canonical-reference: Exported generic functions
canonical-reference: Exported generic functions
canonical-reference: Exported generic functions
canonical-reference: Exported generic functions
capture-id: Internal functions
capture-value: Internal functions
check-body-docstring: Internal functions
check-command-values: Internal functions
check-location: Internal functions
check-output-consistency: Internal functions
check-value-consistency: Internal functions
check-values-consistency: Internal functions
code: Internal functions
code-fragment: Internal functions
collect-heading: Internal functions
collect-headings: Internal functions
collect-reachable-objects: Exported generic functions
collect-reachable-objects: Exported generic functions
collect-reachable-objects: Exported generic functions
collect-reachable-objects: Exported generic functions
command-captures: Internal functions
command-form: Internal functions
command-output-capture: Internal functions
command-string: Internal functions
command-syntax-id: Internal functions
command-value-captures: Internal functions
consistency-error: Internal functions
convert-source-location: Internal functions
copy-heading: Internal functions
copy-link: Internal functions
copy-page: Internal functions

D
defer-tag-handling: Internal functions
define-definer-for-symbol-locative-type: Exported macros
define-locative-type: Exported macros
define-package: Exported macros
define-symbol-locative-type: Exported macros
defsection: Exported macros
delete-stream-spec: Internal generic functions
delete-stream-spec: Internal generic functions
delete-stream-spec: Internal generic functions
delimiterp: Internal functions
do-pages-created: Internal macros
docstring-indentation: Internal functions
document: Exported functions
document-object: Exported generic functions
document-object: Exported generic functions
document-object: Exported generic functions
document-object: Exported generic functions
document-object: Exported generic functions
document-object: Exported generic functions
document-object: Exported generic functions
document-object: Exported generic functions
document-object: Exported generic functions
document-object: Exported generic functions

E
emit-footer: Internal functions
entry-to-reference: Internal functions
escape-markdown: Internal functions
eval-and-capture: Internal functions
expand-define-definer-for-symbol-as-locative-definer-body: Internal functions
export-some-symbols: Internal functions
exportable-locative-type-p: Exported generic functions
exportable-locative-type-p: Exported generic functions
exportable-locative-type-p: Exported generic functions
exportable-locative-type-p: Exported generic functions
exportable-locative-type-p: Exported generic functions
exportable-locative-type-p: Exported generic functions
extract-name-from-label: Internal functions

F
fancy-navigation: Internal functions
file-position-to-line-number: Internal functions
file-stream-spec-open-args: Internal generic functions
file-stream-spec-open-args: Internal generic functions
file-stream-spec-pathname: Internal generic functions
file-stream-spec-pathname: Internal generic functions
file-subseq: Internal functions
filter-captures: Internal functions
filter-documentation: Internal functions
filter-locations: Internal functions
filter-references: Internal functions
filter-references-by-format: Internal functions
find-accessor-slot-definition: Internal functions
find-definitions-find-symbol-or-package: Internal functions
find-known-reference: Internal functions
find-link: Internal functions
find-link-by-id: Internal functions
find-locative-around: Internal functions
find-one-location: Internal functions
find-prefix: Internal functions
find-reader-slot-definition: Internal functions
find-reference-by-locative-string: Internal functions
find-source: Exported generic functions
find-source: Exported generic functions
find-source: Exported generic functions
find-source: Exported generic functions
find-source: Exported generic functions
find-syntax: Internal functions
find-writer-slot-definition: Internal functions
format-references: Internal functions
Function, (setf heading-level): Internal functions
Function, (setf heading-object): Internal functions
Function, (setf heading-title): Internal functions
Function, (setf link-id): Internal functions
Function, (setf link-page): Internal functions
Function, (setf link-page-to-n-uses): Internal functions
Function, (setf link-reference): Internal functions
Function, (setf page-final-stream-spec): Internal functions
Function, (setf page-footer-fn): Internal functions
Function, (setf page-header-fn): Internal functions
Function, (setf page-references): Internal functions
Function, (setf page-source-uri-fn): Internal functions
Function, (setf page-temp-stream-spec): Internal functions
Function, (setf page-uri-fragment): Internal functions
Function, anchor: Internal functions
Function, arglist-to-string: Internal functions
Function, asdf-system-git-version: Internal functions
Function, blankp: Internal functions
Function, bold: Internal functions
Function, call-with-heading: Internal functions
Function, call-with-input-stream: Internal functions
Function, call-with-output-stream: Internal functions
Function, capture-id: Internal functions
Function, capture-value: Internal functions
Function, check-body-docstring: Internal functions
Function, check-command-values: Internal functions
Function, check-location: Internal functions
Function, check-output-consistency: Internal functions
Function, check-value-consistency: Internal functions
Function, check-values-consistency: Internal functions
Function, code: Internal functions
Function, code-fragment: Internal functions
Function, collect-heading: Internal functions
Function, collect-headings: Internal functions
Function, command-captures: Internal functions
Function, command-form: Internal functions
Function, command-output-capture: Internal functions
Function, command-string: Internal functions
Function, command-syntax-id: Internal functions
Function, command-value-captures: Internal functions
Function, consistency-error: Internal functions
Function, convert-source-location: Internal functions
Function, copy-heading: Internal functions
Function, copy-link: Internal functions
Function, copy-page: Internal functions
Function, defer-tag-handling: Internal functions
Function, delimiterp: Internal functions
Function, docstring-indentation: Internal functions
Function, document: Exported functions
Function, emit-footer: Internal functions
Function, entry-to-reference: Internal functions
Function, escape-markdown: Internal functions
Function, eval-and-capture: Internal functions
Function, expand-define-definer-for-symbol-as-locative-definer-body: Internal functions
Function, export-some-symbols: Internal functions
Function, extract-name-from-label: Internal functions
Function, fancy-navigation: Internal functions
Function, file-position-to-line-number: Internal functions
Function, file-subseq: Internal functions
Function, filter-captures: Internal functions
Function, filter-documentation: Internal functions
Function, filter-locations: Internal functions
Function, filter-references: Internal functions
Function, filter-references-by-format: Internal functions
Function, find-accessor-slot-definition: Internal functions
Function, find-definitions-find-symbol-or-package: Internal functions
Function, find-known-reference: Internal functions
Function, find-link: Internal functions
Function, find-link-by-id: Internal functions
Function, find-locative-around: Internal functions
Function, find-one-location: Internal functions
Function, find-prefix: Internal functions
Function, find-reader-slot-definition: Internal functions
Function, find-reference-by-locative-string: Internal functions
Function, find-syntax: Internal functions
Function, find-writer-slot-definition: Internal functions
Function, format-references: Internal functions
Function, function-arg-names: Internal functions
Function, generate-documentation-for-slot-definition: Internal functions
Function, git-version: Internal functions
Function, hash-link: Internal functions
Function, heading: Internal functions
Function, heading-level: Internal functions
Function, heading-number: Internal functions
Function, heading-object: Internal functions
Function, heading-p: Internal functions
Function, heading-title: Internal functions
Function, html-safe-name: Internal functions
Function, include-region: Internal functions
Function, italic: Internal functions
Function, join-consecutive-non-blank-strings-in-list: Internal functions
Function, join-consecutive-non-blank-strings-in-parse-tree: Internal functions
Function, link-id: Internal functions
Function, link-p: Internal functions
Function, link-page: Internal functions
Function, link-page-to-n-uses: Internal functions
Function, link-reference: Internal functions
Function, link-to-reference: Internal functions
Function, link-used-on-current-page-p: Internal functions
Function, locate: Exported functions
Function, locate-and-print-bullet: Internal functions
Function, locate-definition-for-emacs: Internal functions
Function, locate-definition-for-emacs-1: Internal functions
Function, locate-error: Exported functions
Function, locate-reference-link-definition-for-emacs: Internal functions
Function, location-file: Internal functions
Function, location-position: Internal functions
Function, locative-args: Exported functions
Function, locative-equal: Internal functions
Function, locative-lambda-list-method-for-symbol: Internal functions
Function, locative-type: Exported functions
Function, longest-common-prefix: Internal functions
Function, macro-arg-names: Internal functions
Function, make-github-source-uri-fn: Exported functions
Function, make-heading: Internal functions
Function, make-link: Internal functions
Function, make-page: Internal functions
Function, make-reference: Exported functions
Function, map-markdown-parse-tree: Internal functions
Function, map-names: Internal functions
Function, mark-page-created: Internal functions
Function, mark-up-superclasses: Internal functions
Function, markdown-special-char-p: Internal functions
Function, massage-docstring: Internal functions
Function, match-prefixes: Internal functions
Function, matching-prefix: Internal functions
Function, maybe-print-docstring: Internal functions
Function, method-for-inspect-value: Internal functions
Function, method-specializers-for-inspect: Internal functions
Function, method-specializers-list: Internal functions
Function, n-leading-spaces: Internal functions
Function, navigation-link: Internal functions
Function, no-lowercase-chars-p: Internal functions
Function, no-value-capture-p: Internal functions
Function, normalize-pathname: Internal functions
Function, output-capture-p: Internal functions
Function, output-string: Internal functions
Function, page-final-stream-spec: Internal functions
Function, page-footer-fn: Internal functions
Function, page-header-fn: Internal functions
Function, page-p: Internal functions
Function, page-references: Internal functions
Function, page-source-uri-fn: Internal functions
Function, page-temp-stream-spec: Internal functions
Function, page-uri-fragment: Internal functions
Function, parse-form: Internal functions
Function, parse-prefixed: Internal functions
Function, parse-readable: Internal functions
Function, parse-readable*: Internal functions
Function, parse-readable-with-continuation: Internal functions
Function, parse-transcript-element: Internal functions
Function, prefix-lines: Internal functions
Function, prin1-and-escape-markdown: Internal functions
Function, print-arglist: Internal functions
Function, print-bullet: Internal functions
Function, print-reference-bullet: Internal functions
Function, print-reference-with-package: Internal functions
Function, print-table-of-contents-entry: Internal functions
Function, reachable-canonical-references: Internal functions
Function, read-first-line: Internal functions
Function, read-form-and-string: Internal functions
Function, read-line*: Internal functions
Function, read-locative-from-string: Internal functions
Function, read-marked-up-locative-from-string: Internal functions
Function, read-prefixed-lines: Internal functions
Function, read-stream-into-string: Internal functions
Function, read-transcript: Internal functions
Function, readable-capture-p: Internal functions
Function, readable-object: Internal functions
Function, readable-object-p: Internal functions
Function, readable-string: Internal functions
Function, readably-consistent-p: Internal functions
Function, reference-locative-type: Internal functions
Function, reference-page: Internal functions
Function, reference-to-anchor: Internal functions
Function, reference=: Internal functions
Function, references-for-similar-names: Internal functions
Function, references-for-symbol: Internal functions
Function, references-for-the-same-symbol-p: Internal functions
Function, relative-page-uri-fragment: Internal functions
Function, relativize-pathname: Internal functions
Function, replace-known-references: Internal functions
Function, resolve: Exported functions
Function, resolve-dislocated: Internal functions
Function, resolve-generic-function-and-methods: Internal functions
Function, section-title-or-name: Internal functions
Function, skip-white-space-till-end-of-line: Internal functions
Function, source-uri: Internal functions
Function, strip-docstring-indentation: Internal functions
Function, strip-longest-common-prefix: Internal functions
Function, subseq*: Internal functions
Function, symbol-accessible-in-package-p: Internal functions
Function, symbol-global-value: Internal functions
Function, symbol-lambda-list-method: Internal functions
Function, transcribe: Exported functions
Function, transcribe-for-emacs: Internal functions
Function, transcribe-output: Internal functions
Function, transcribe-readable-value: Internal functions
Function, transcribe-unreadable-value: Internal functions
Function, transcribe-values: Internal functions
Function, transcription-error: Exported functions
Function, transcription-error*: Internal functions
Function, transform-entries: Internal functions
Function, transform-tree: Internal functions
Function, translate-code-block: Internal functions
Function, translate-emph: Internal functions
Function, translate-name: Internal functions
Function, translate-page-spec: Internal functions
Function, translate-page-specs: Internal functions
Function, translate-to-code: Internal functions
Function, translate-to-links: Internal functions
Function, translate-uppercase-name: Internal functions
Function, trim-whitespace: Internal functions
Function, unreadable-capture-p: Internal functions
Function, unreadable-string: Internal functions
Function, value-capture-p: Internal functions
Function, whitespacep: Internal functions
Function, write-navigation-link: Internal functions
Function, write-prefixed-lines: Internal functions
Function, write-transcript: Internal functions
Function, _mark-one: Internal functions
Function, _mark-range: Internal functions
function-arg-names: Internal functions

G
generate-documentation-for-slot-definition: Internal functions
Generic Function, (setf string-stream-spec-string): Internal generic functions
Generic Function, call-with-open-stream-spec: Internal generic functions
Generic Function, canonical-reference: Exported generic functions
Generic Function, collect-reachable-objects: Exported generic functions
Generic Function, delete-stream-spec: Internal generic functions
Generic Function, document-object: Exported generic functions
Generic Function, exportable-locative-type-p: Exported generic functions
Generic Function, file-stream-spec-open-args: Internal generic functions
Generic Function, file-stream-spec-pathname: Internal generic functions
Generic Function, find-source: Exported generic functions
Generic Function, locate-and-collect-reachable-objects: Exported generic functions
Generic Function, locate-and-document: Exported generic functions
Generic Function, locate-and-find-source: Exported generic functions
Generic Function, locate-error-locative: Exported generic functions
Generic Function, locate-error-message: Exported generic functions
Generic Function, locate-error-object: Exported generic functions
Generic Function, locate-object: Exported generic functions
Generic Function, locative-lambda-list: Internal generic functions
Generic Function, make-stream-spec: Internal generic functions
Generic Function, reference-locative: Exported generic functions
Generic Function, reference-object: Exported generic functions
Generic Function, section-entries: Exported generic functions
Generic Function, section-name: Exported generic functions
Generic Function, section-package: Exported generic functions
Generic Function, section-readtable: Exported generic functions
Generic Function, section-title: Exported generic functions
Generic Function, string-stream-spec-string: Internal generic functions
Generic Function, symbol-lambda-list: Internal generic functions
Generic Function, transcription-error-file-position: Internal generic functions
Generic Function, transcription-error-form-as-string: Internal generic functions
Generic Function, transcription-error-message: Internal generic functions
Generic Function, transcription-error-message-args: Internal generic functions
Generic Function, transcription-error-on: Internal generic functions
Generic Function, unmake-stream-spec: Internal generic functions
git-version: Internal functions

H
hash-link: Internal functions
heading: Internal functions
heading-level: Internal functions
heading-number: Internal functions
heading-object: Internal functions
heading-p: Internal functions
heading-title: Internal functions
html-safe-name: Internal functions

I
include-region: Internal functions
italic: Internal functions

J
join-consecutive-non-blank-strings-in-list: Internal functions
join-consecutive-non-blank-strings-in-parse-tree: Internal functions

L
link-id: Internal functions
link-p: Internal functions
link-page: Internal functions
link-page-to-n-uses: Internal functions
link-reference: Internal functions
link-to-reference: Internal functions
link-used-on-current-page-p: Internal functions
locate: Exported functions
locate-and-collect-reachable-objects: Exported generic functions
locate-and-collect-reachable-objects: Exported generic functions
locate-and-document: Exported generic functions
locate-and-document: Exported generic functions
locate-and-document: Exported generic functions
locate-and-document: Exported generic functions
locate-and-document: Exported generic functions
locate-and-document: Exported generic functions
locate-and-document: Exported generic functions
locate-and-document: Exported generic functions
locate-and-document: Exported generic functions
locate-and-document: Exported generic functions
locate-and-document: Exported generic functions
locate-and-document: Exported generic functions
locate-and-find-source: Exported generic functions
locate-and-find-source: Exported generic functions
locate-and-find-source: Exported generic functions
locate-and-find-source: Exported generic functions
locate-and-find-source: Exported generic functions
locate-and-find-source: Exported generic functions
locate-and-find-source: Exported generic functions
locate-and-find-source: Exported generic functions
locate-and-find-source: Exported generic functions
locate-and-find-source: Exported generic functions
locate-and-find-source: Exported generic functions
locate-and-find-source: Exported generic functions
locate-and-find-source: Exported generic functions
locate-and-print-bullet: Internal functions
locate-definition-for-emacs: Internal functions
locate-definition-for-emacs-1: Internal functions
locate-error: Exported functions
locate-error-locative: Exported generic functions
locate-error-locative: Exported generic functions
locate-error-message: Exported generic functions
locate-error-message: Exported generic functions
locate-error-object: Exported generic functions
locate-error-object: Exported generic functions
locate-object: Exported generic functions
locate-object: Exported generic functions
locate-object: Exported generic functions
locate-object: Exported generic functions
locate-object: Exported generic functions
locate-object: Exported generic functions
locate-object: Exported generic functions
locate-object: Exported generic functions
locate-object: Exported generic functions
locate-object: Exported generic functions
locate-object: Exported generic functions
locate-object: Exported generic functions
locate-object: Exported generic functions
locate-object: Exported generic functions
locate-object: Exported generic functions
locate-object: Exported generic functions
locate-object: Exported generic functions
locate-object: Exported generic functions
locate-object: Exported generic functions
locate-object: Exported generic functions
locate-object: Exported generic functions
locate-reference-link-definition-for-emacs: Internal functions
location-file: Internal functions
location-position: Internal functions
locative-args: Exported functions
locative-equal: Internal functions
locative-lambda-list: Internal generic functions
locative-lambda-list: Internal generic functions
locative-lambda-list: Internal generic functions
locative-lambda-list: Internal generic functions
locative-lambda-list: Internal generic functions
locative-lambda-list: Internal generic functions
locative-lambda-list: Internal generic functions
locative-lambda-list: Internal generic functions
locative-lambda-list: Internal generic functions
locative-lambda-list: Internal generic functions
locative-lambda-list: Internal generic functions
locative-lambda-list: Internal generic functions
locative-lambda-list: Internal generic functions
locative-lambda-list: Internal generic functions
locative-lambda-list: Internal generic functions
locative-lambda-list: Internal generic functions
locative-lambda-list: Internal generic functions
locative-lambda-list: Internal generic functions
locative-lambda-list: Internal generic functions
locative-lambda-list: Internal generic functions
locative-lambda-list: Internal generic functions
locative-lambda-list-method-for-symbol: Internal functions
locative-type: Exported functions
longest-common-prefix: Internal functions

M
Macro, define-definer-for-symbol-locative-type: Exported macros
Macro, define-locative-type: Exported macros
Macro, define-package: Exported macros
Macro, define-symbol-locative-type: Exported macros
Macro, defsection: Exported macros
Macro, do-pages-created: Internal macros
Macro, with-dislocated-symbols: Internal macros
Macro, with-final-output-to-page: Internal macros
Macro, with-heading: Internal macros
Macro, with-headings: Internal macros
Macro, with-input-stream: Internal macros
Macro, with-load-environment: Internal macros
Macro, with-nested-headings: Internal macros
Macro, with-open-stream-spec: Internal macros
Macro, with-output-stream: Internal macros
Macro, with-pages: Internal macros
Macro, with-swank: Internal macros
Macro, with-temp-input-from-page: Internal macros
Macro, with-temp-output-to-page: Internal macros
Macro, with-tracking-pages-created: Internal macros
Macro, with-transcription-syntax: Internal macros
macro-arg-names: Internal functions
make-github-source-uri-fn: Exported functions
make-heading: Internal functions
make-link: Internal functions
make-page: Internal functions
make-reference: Exported functions
make-stream-spec: Internal generic functions
make-stream-spec: Internal generic functions
make-stream-spec: Internal generic functions
make-stream-spec: Internal generic functions
make-stream-spec: Internal generic functions
make-stream-spec: Internal generic functions
map-markdown-parse-tree: Internal functions
map-names: Internal functions
mark-page-created: Internal functions
mark-up-superclasses: Internal functions
markdown-special-char-p: Internal functions
massage-docstring: Internal functions
match-prefixes: Internal functions
matching-prefix: Internal functions
maybe-print-docstring: Internal functions
Method, (setf string-stream-spec-string): Internal generic functions
Method, call-with-open-stream-spec: Internal generic functions
Method, call-with-open-stream-spec: Internal generic functions
Method, call-with-open-stream-spec: Internal generic functions
Method, call-with-open-stream-spec: Internal generic functions
Method, canonical-reference: Exported generic functions
Method, canonical-reference: Exported generic functions
Method, canonical-reference: Exported generic functions
Method, canonical-reference: Exported generic functions
Method, canonical-reference: Exported generic functions
Method, canonical-reference: Exported generic functions
Method, canonical-reference: Exported generic functions
Method, canonical-reference: Exported generic functions
Method, collect-reachable-objects: Exported generic functions
Method, collect-reachable-objects: Exported generic functions
Method, collect-reachable-objects: Exported generic functions
Method, delete-stream-spec: Internal generic functions
Method, delete-stream-spec: Internal generic functions
Method, document-object: Exported generic functions
Method, document-object: Exported generic functions
Method, document-object: Exported generic functions
Method, document-object: Exported generic functions
Method, document-object: Exported generic functions
Method, document-object: Exported generic functions
Method, document-object: Exported generic functions
Method, document-object: Exported generic functions
Method, document-object: Exported generic functions
Method, exportable-locative-type-p: Exported generic functions
Method, exportable-locative-type-p: Exported generic functions
Method, exportable-locative-type-p: Exported generic functions
Method, exportable-locative-type-p: Exported generic functions
Method, exportable-locative-type-p: Exported generic functions
Method, file-stream-spec-open-args: Internal generic functions
Method, file-stream-spec-pathname: Internal generic functions
Method, find-source: Exported generic functions
Method, find-source: Exported generic functions
Method, find-source: Exported generic functions
Method, find-source: Exported generic functions
Method, locate-and-collect-reachable-objects: Exported generic functions
Method, locate-and-document: Exported generic functions
Method, locate-and-document: Exported generic functions
Method, locate-and-document: Exported generic functions
Method, locate-and-document: Exported generic functions
Method, locate-and-document: Exported generic functions
Method, locate-and-document: Exported generic functions
Method, locate-and-document: Exported generic functions
Method, locate-and-document: Exported generic functions
Method, locate-and-document: Exported generic functions
Method, locate-and-document: Exported generic functions
Method, locate-and-document: Exported generic functions
Method, locate-and-find-source: Exported generic functions
Method, locate-and-find-source: Exported generic functions
Method, locate-and-find-source: Exported generic functions
Method, locate-and-find-source: Exported generic functions
Method, locate-and-find-source: Exported generic functions
Method, locate-and-find-source: Exported generic functions
Method, locate-and-find-source: Exported generic functions
Method, locate-and-find-source: Exported generic functions
Method, locate-and-find-source: Exported generic functions
Method, locate-and-find-source: Exported generic functions
Method, locate-and-find-source: Exported generic functions
Method, locate-and-find-source: Exported generic functions
Method, locate-error-locative: Exported generic functions
Method, locate-error-message: Exported generic functions
Method, locate-error-object: Exported generic functions
Method, locate-object: Exported generic functions
Method, locate-object: Exported generic functions
Method, locate-object: Exported generic functions
Method, locate-object: Exported generic functions
Method, locate-object: Exported generic functions
Method, locate-object: Exported generic functions
Method, locate-object: Exported generic functions
Method, locate-object: Exported generic functions
Method, locate-object: Exported generic functions
Method, locate-object: Exported generic functions
Method, locate-object: Exported generic functions
Method, locate-object: Exported generic functions
Method, locate-object: Exported generic functions
Method, locate-object: Exported generic functions
Method, locate-object: Exported generic functions
Method, locate-object: Exported generic functions
Method, locate-object: Exported generic functions
Method, locate-object: Exported generic functions
Method, locate-object: Exported generic functions
Method, locate-object: Exported generic functions
Method, locative-lambda-list: Internal generic functions
Method, locative-lambda-list: Internal generic functions
Method, locative-lambda-list: Internal generic functions
Method, locative-lambda-list: Internal generic functions
Method, locative-lambda-list: Internal generic functions
Method, locative-lambda-list: Internal generic functions
Method, locative-lambda-list: Internal generic functions
Method, locative-lambda-list: Internal generic functions
Method, locative-lambda-list: Internal generic functions
Method, locative-lambda-list: Internal generic functions
Method, locative-lambda-list: Internal generic functions
Method, locative-lambda-list: Internal generic functions
Method, locative-lambda-list: Internal generic functions
Method, locative-lambda-list: Internal generic functions
Method, locative-lambda-list: Internal generic functions
Method, locative-lambda-list: Internal generic functions
Method, locative-lambda-list: Internal generic functions
Method, locative-lambda-list: Internal generic functions
Method, locative-lambda-list: Internal generic functions
Method, locative-lambda-list: Internal generic functions
Method, make-stream-spec: Internal generic functions
Method, make-stream-spec: Internal generic functions
Method, make-stream-spec: Internal generic functions
Method, make-stream-spec: Internal generic functions
Method, make-stream-spec: Internal generic functions
Method, reference-locative: Exported generic functions
Method, reference-object: Exported generic functions
Method, section-entries: Exported generic functions
Method, section-name: Exported generic functions
Method, section-package: Exported generic functions
Method, section-readtable: Exported generic functions
Method, section-title: Exported generic functions
Method, string-stream-spec-string: Internal generic functions
Method, transcription-error-file-position: Internal generic functions
Method, transcription-error-form-as-string: Internal generic functions
Method, transcription-error-message: Internal generic functions
Method, transcription-error-message-args: Internal generic functions
Method, transcription-error-on: Internal generic functions
Method, unmake-stream-spec: Internal generic functions
Method, unmake-stream-spec: Internal generic functions
Method, unmake-stream-spec: Internal generic functions
method-for-inspect-value: Internal functions
method-specializers-for-inspect: Internal functions
method-specializers-list: Internal functions

N
n-leading-spaces: Internal functions
navigation-link: Internal functions
no-lowercase-chars-p: Internal functions
no-value-capture-p: Internal functions
normalize-pathname: Internal functions

O
output-capture-p: Internal functions
output-string: Internal functions

P
page-final-stream-spec: Internal functions
page-footer-fn: Internal functions
page-header-fn: Internal functions
page-p: Internal functions
page-references: Internal functions
page-source-uri-fn: Internal functions
page-temp-stream-spec: Internal functions
page-uri-fragment: Internal functions
parse-form: Internal functions
parse-prefixed: Internal functions
parse-readable: Internal functions
parse-readable*: Internal functions
parse-readable-with-continuation: Internal functions
parse-transcript-element: Internal functions
prefix-lines: Internal functions
prin1-and-escape-markdown: Internal functions
print-arglist: Internal functions
print-bullet: Internal functions
print-reference-bullet: Internal functions
print-reference-with-package: Internal functions
print-table-of-contents-entry: Internal functions

R
reachable-canonical-references: Internal functions
read-first-line: Internal functions
read-form-and-string: Internal functions
read-line*: Internal functions
read-locative-from-string: Internal functions
read-marked-up-locative-from-string: Internal functions
read-prefixed-lines: Internal functions
read-stream-into-string: Internal functions
read-transcript: Internal functions
readable-capture-p: Internal functions
readable-object: Internal functions
readable-object-p: Internal functions
readable-string: Internal functions
readably-consistent-p: Internal functions
reference-locative: Exported generic functions
reference-locative: Exported generic functions
reference-locative-type: Internal functions
reference-object: Exported generic functions
reference-object: Exported generic functions
reference-page: Internal functions
reference-to-anchor: Internal functions
reference=: Internal functions
references-for-similar-names: Internal functions
references-for-symbol: Internal functions
references-for-the-same-symbol-p: Internal functions
relative-page-uri-fragment: Internal functions
relativize-pathname: Internal functions
replace-known-references: Internal functions
resolve: Exported functions
resolve-dislocated: Internal functions
resolve-generic-function-and-methods: Internal functions

S
section-entries: Exported generic functions
section-entries: Exported generic functions
section-name: Exported generic functions
section-name: Exported generic functions
section-package: Exported generic functions
section-package: Exported generic functions
section-readtable: Exported generic functions
section-readtable: Exported generic functions
section-title: Exported generic functions
section-title: Exported generic functions
section-title-or-name: Internal functions
Setf Expander, (setf command-syntax-id): Internal functions
skip-white-space-till-end-of-line: Internal functions
source-uri: Internal functions
string-stream-spec-string: Internal generic functions
string-stream-spec-string: Internal generic functions
strip-docstring-indentation: Internal functions
strip-longest-common-prefix: Internal functions
subseq*: Internal functions
symbol-accessible-in-package-p: Internal functions
symbol-global-value: Internal functions
symbol-lambda-list: Internal generic functions
symbol-lambda-list-method: Internal functions

T
transcribe: Exported functions
transcribe-for-emacs: Internal functions
transcribe-output: Internal functions
transcribe-readable-value: Internal functions
transcribe-unreadable-value: Internal functions
transcribe-values: Internal functions
transcription-error: Exported functions
transcription-error*: Internal functions
transcription-error-file-position: Internal generic functions
transcription-error-file-position: Internal generic functions
transcription-error-form-as-string: Internal generic functions
transcription-error-form-as-string: Internal generic functions
transcription-error-message: Internal generic functions
transcription-error-message: Internal generic functions
transcription-error-message-args: Internal generic functions
transcription-error-message-args: Internal generic functions
transcription-error-on: Internal generic functions
transcription-error-on: Internal generic functions
transform-entries: Internal functions
transform-tree: Internal functions
translate-code-block: Internal functions
translate-emph: Internal functions
translate-name: Internal functions
translate-page-spec: Internal functions
translate-page-specs: Internal functions
translate-to-code: Internal functions
translate-to-links: Internal functions
translate-uppercase-name: Internal functions
trim-whitespace: Internal functions

U
unmake-stream-spec: Internal generic functions
unmake-stream-spec: Internal generic functions
unmake-stream-spec: Internal generic functions
unmake-stream-spec: Internal generic functions
unreadable-capture-p: Internal functions
unreadable-string: Internal functions

V
value-capture-p: Internal functions

W
whitespacep: Internal functions
with-dislocated-symbols: Internal macros
with-final-output-to-page: Internal macros
with-heading: Internal macros
with-headings: Internal macros
with-input-stream: Internal macros
with-load-environment: Internal macros
with-nested-headings: Internal macros
with-open-stream-spec: Internal macros
with-output-stream: Internal macros
with-pages: Internal macros
with-swank: Internal macros
with-temp-input-from-page: Internal macros
with-temp-output-to-page: Internal macros
with-tracking-pages-created: Internal macros
with-transcription-syntax: Internal macros
write-navigation-link: Internal functions
write-prefixed-lines: Internal functions
write-transcript: Internal functions

Jump to:   (   _  
A   B   C   D   E   F   G   H   I   J   L   M   N   O   P   R   S   T   U   V   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *   +   @  
E   F   H   I   L   M   N   O   P   R   S   T   U  
Index Entry  Section

*
*collecting-headings-p*: Internal special variables
*discard-documentation-p*: Exported special variables
*document-fancy-html-navigation*: Exported special variables
*document-link-code*: Exported special variables
*document-link-sections*: Exported special variables
*document-mark-up-signatures*: Exported special variables
*document-max-numbering-level*: Exported special variables
*document-max-table-of-contents-level*: Exported special variables
*document-min-link-hash-length*: Exported special variables
*document-normalize-packages*: Exported special variables
*document-text-navigation*: Exported special variables
*document-uppercase-is-code*: Exported special variables
*find-definitions-right-trim*: Internal special variables
*format*: Internal special variables
*heading-level*: Internal special variables
*heading-number*: Internal special variables
*headings*: Internal special variables
*links*: Internal special variables
*page*: Internal special variables
*pages-created*: Internal special variables
*reference-being-documented*: Internal special variables
*references*: Internal special variables
*section*: Internal special variables
*syntaxes*: Exported special variables
*table-of-contents-page*: Internal special variables
*table-of-contents-stream*: Internal special variables
*whitespace-chars*: Internal special variables

+
+first-name-characters+: Internal special variables
+name-characters+: Internal special variables

@
@mgl-pax-background: Exported special variables
@mgl-pax-basics: Exported special variables
@mgl-pax-documentation-printer-variables: Exported special variables
@mgl-pax-emacs-integration: Exported special variables
@mgl-pax-extension-api: Exported special variables
@mgl-pax-links: Exported special variables
@mgl-pax-locative-types: Exported special variables
@mgl-pax-locatives-and-references: Exported special variables
@mgl-pax-manual: Exported special variables
@mgl-pax-markdown-indentation: Exported special variables
@mgl-pax-markdown-support: Exported special variables
@mgl-pax-markdown-syntax-highlighting: Exported special variables
@mgl-pax-mathjax: Exported special variables
@mgl-pax-new-object-types: Exported special variables
@mgl-pax-reference-based-extensions: Exported special variables
@mgl-pax-sections: Exported special variables
@mgl-pax-transcript: Exported special variables
@mgl-pax-transcript-api: Exported special variables
@mgl-pax-transcript-emacs-integration: Exported special variables
@mgl-pax-tutorial: Exported special variables
@mgl-pax-utilities: Exported special variables

E
end-of-asdf-example: Internal special variables
end-of-variable-example: Internal special variables
entries: Exported classes

F
file-position: Exported conditions
final-stream-spec: Internal structures
footer-fn: Internal structures
form-as-string: Exported conditions

H
header-fn: Internal structures

I
id: Internal structures

L
level: Internal structures
locative: Exported conditions
locative: Exported classes

M
message: Exported conditions
message: Exported conditions
message-args: Exported conditions

N
name: Exported classes

O
object: Exported conditions
object: Exported classes
object: Internal structures
on: Exported conditions
open-args: Internal classes

P
package: Exported classes
page: Internal structures
page-to-n-uses: Internal structures
pathname: Internal classes

R
readtable: Exported classes
reference: Internal structures
references: Internal structures

S
Slot, entries: Exported classes
Slot, file-position: Exported conditions
Slot, final-stream-spec: Internal structures
Slot, footer-fn: Internal structures
Slot, form-as-string: Exported conditions
Slot, header-fn: Internal structures
Slot, id: Internal structures
Slot, level: Internal structures
Slot, locative: Exported conditions
Slot, locative: Exported classes
Slot, message: Exported conditions
Slot, message: Exported conditions
Slot, message-args: Exported conditions
Slot, name: Exported classes
Slot, object: Exported conditions
Slot, object: Exported classes
Slot, object: Internal structures
Slot, on: Exported conditions
Slot, open-args: Internal classes
Slot, package: Exported classes
Slot, page: Internal structures
Slot, page-to-n-uses: Internal structures
Slot, pathname: Internal classes
Slot, readtable: Exported classes
Slot, reference: Internal structures
Slot, references: Internal structures
Slot, source-uri-fn: Internal structures
Slot, string: Internal classes
Slot, temp-stream-spec: Internal structures
Slot, title: Exported classes
Slot, title: Internal structures
Slot, uri-fragment: Internal structures
source-uri-fn: Internal structures
Special Variable, *collecting-headings-p*: Internal special variables
Special Variable, *discard-documentation-p*: Exported special variables
Special Variable, *document-fancy-html-navigation*: Exported special variables
Special Variable, *document-link-code*: Exported special variables
Special Variable, *document-link-sections*: Exported special variables
Special Variable, *document-mark-up-signatures*: Exported special variables
Special Variable, *document-max-numbering-level*: Exported special variables
Special Variable, *document-max-table-of-contents-level*: Exported special variables
Special Variable, *document-min-link-hash-length*: Exported special variables
Special Variable, *document-normalize-packages*: Exported special variables
Special Variable, *document-text-navigation*: Exported special variables
Special Variable, *document-uppercase-is-code*: Exported special variables
Special Variable, *find-definitions-right-trim*: Internal special variables
Special Variable, *format*: Internal special variables
Special Variable, *heading-level*: Internal special variables
Special Variable, *heading-number*: Internal special variables
Special Variable, *headings*: Internal special variables
Special Variable, *links*: Internal special variables
Special Variable, *page*: Internal special variables
Special Variable, *pages-created*: Internal special variables
Special Variable, *reference-being-documented*: Internal special variables
Special Variable, *references*: Internal special variables
Special Variable, *section*: Internal special variables
Special Variable, *syntaxes*: Exported special variables
Special Variable, *table-of-contents-page*: Internal special variables
Special Variable, *table-of-contents-stream*: Internal special variables
Special Variable, *whitespace-chars*: Internal special variables
Special Variable, +first-name-characters+: Internal special variables
Special Variable, +name-characters+: Internal special variables
Special Variable, @mgl-pax-background: Exported special variables
Special Variable, @mgl-pax-basics: Exported special variables
Special Variable, @mgl-pax-documentation-printer-variables: Exported special variables
Special Variable, @mgl-pax-emacs-integration: Exported special variables
Special Variable, @mgl-pax-extension-api: Exported special variables
Special Variable, @mgl-pax-links: Exported special variables
Special Variable, @mgl-pax-locative-types: Exported special variables
Special Variable, @mgl-pax-locatives-and-references: Exported special variables
Special Variable, @mgl-pax-manual: Exported special variables
Special Variable, @mgl-pax-markdown-indentation: Exported special variables
Special Variable, @mgl-pax-markdown-support: Exported special variables
Special Variable, @mgl-pax-markdown-syntax-highlighting: Exported special variables
Special Variable, @mgl-pax-mathjax: Exported special variables
Special Variable, @mgl-pax-new-object-types: Exported special variables
Special Variable, @mgl-pax-reference-based-extensions: Exported special variables
Special Variable, @mgl-pax-sections: Exported special variables
Special Variable, @mgl-pax-transcript: Exported special variables
Special Variable, @mgl-pax-transcript-api: Exported special variables
Special Variable, @mgl-pax-transcript-emacs-integration: Exported special variables
Special Variable, @mgl-pax-tutorial: Exported special variables
Special Variable, @mgl-pax-utilities: Exported special variables
Special Variable, end-of-asdf-example: Internal special variables
Special Variable, end-of-variable-example: Internal special variables
string: Internal classes

T
temp-stream-spec: Internal structures
title: Exported classes
title: Internal structures

U
uri-fragment: Internal structures

Jump to:   *   +   @  
E   F   H   I   L   M   N   O   P   R   S   T   U  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   F   H   L   M   P   R   S   T  
Index Entry  Section

C
Class, file-stream-spec: Internal classes
Class, reference: Exported classes
Class, section: Exported classes
Class, string-stream-spec: Internal classes
Condition, locate-error: Exported conditions
Condition, transcription-consistency-error: Exported conditions
Condition, transcription-error: Exported conditions
Condition, transcription-output-consistency-error: Exported conditions
Condition, transcription-values-consistency-error: Exported conditions

F
file-stream-spec: Internal classes

H
heading: Internal structures

L
link: Internal structures
locate-error: Exported conditions

M
mgl-pax: The mgl-pax system
mgl-pax: The mgl-pax package

P
Package, mgl-pax: The mgl-pax package
page: Internal structures

R
reference: Exported classes

S
section: Exported classes
string-stream-spec: Internal classes
Structure, heading: Internal structures
Structure, link: Internal structures
Structure, page: Internal structures
System, mgl-pax: The mgl-pax system

T
transcription-consistency-error: Exported conditions
transcription-error: Exported conditions
transcription-output-consistency-error: Exported conditions
transcription-values-consistency-error: Exported conditions

Jump to:   C   F   H   L   M   P   R   S   T