The mgl-pax Reference Manual

4.1.1 mgl-pax/mgl-pax.asd

Source

mgl-pax.asd.

Parent Component

mgl-pax (system).

ASDF Systems

mgl-pax.

---

4.1.2 mgl-pax.asdf/mgl-pax.asdf.asd

Source

mgl-pax.asdf.asd.

Parent Component

mgl-pax.asdf (system).

ASDF Systems

mgl-pax.asdf.

---

4.1.3 mgl-pax-bootstrap/mgl-pax-bootstrap.asd

Source

mgl-pax-bootstrap.asd.

Parent Component

mgl-pax-bootstrap (system).

ASDF Systems

mgl-pax-bootstrap.

---

4.1.4 dref/dref.asd

Source

dref.asd.

Parent Component

dref (system).

ASDF Systems

dref.

---

4.1.5 mgl-pax/src/base//autoload.lisp

Source

mgl-pax.asd.

Parent Component

src/base/ (module).

Internals

• autoload (macro).
• defun/autoloaded (macro).
• without-redefinition-warnings (macro).

---

4.1.6 mgl-pax/src/base//pax.lisp

Dependency

autoload.lisp (file).

Source

mgl-pax.asd.

Parent Component

src/base/ (module).

Public Interface

• install-pax-elisp (function).
• section-entries (function).
• section-link-title-to (function).

Internals

• @background (special variable).
• @basics (special variable).
• @emacs-setup (special variable).
• @introduction (special variable).
• @links (special variable).
• @m-. (special variable).
• @markdown (special variable).
• @oaoo (special variable).
• @pax-manual (special variable).
• @slime (special variable).
• check-pax-elisp-version (function).
• section-entry-to-xref (function).
• version<= (function).

---

4.1.7 mgl-pax/src/base//extension-api.lisp

Dependency

pax.lisp (file).

Source

mgl-pax.asd.

Parent Component

src/base/ (module).

Public Interface

• document-object* (generic function).
• ensure-navigate-loaded (function).

Internals

• @adding-new-locatives (special variable).
• @extension-api (special variable).
• @glossary-terms (special variable).
• @locative-aliases (special variable).
• @sections (special variable).

---

4.1.8 mgl-pax/src/base//navigate-early.lisp

Dependency

extension-api.lisp (file).

Source

mgl-pax.asd.

Parent Component

src/base/ (module).

Internals

• find-parent-section-for-emacs (function).
• locate-definitions-for-emacs (function).

---

4.1.9 mgl-pax/src/base//document-early.lisp

Dependency

navigate-early.lisp (file).

Source

mgl-pax.asd.

Parent Component

src/base/ (module).

Public Interface

• *browse-html-style* (special variable).
• *document-base-url* (special variable).
• *document-downcase-uppercase-code* (special variable).
• *document-fancy-html-navigation* (special variable).
• *document-html-bottom-blocks-of-links* (special variable).
• *document-html-default-style* (special variable).
• *document-html-head* (special variable).
• *document-html-max-navigation-table-of-contents-level* (special variable).
• *document-html-sidebar* (special variable).
• *document-html-top-blocks-of-links* (special variable).
• *document-hyperspec-root* (special variable).
• *document-link-code* (special variable).
• *document-link-sections* (special variable).
• *document-link-to-hyperspec* (special variable).
• *document-mark-up-signatures* (special variable).
• *document-max-numbering-level* (special variable).
• *document-max-table-of-contents-level* (special variable).
• *document-min-link-hash-length* (special variable).
• *document-normalize-packages* (special variable).
• *document-text-navigation* (special variable).
• *document-uppercase-is-code* (special variable).
• *document-url-versions* (special variable).
• *format* (special variable).
• document (function).
• document-docstring (function).
• documenting-reference (macro).
• escape-markdown (function).
• make-git-source-uri-fn (function).
• make-github-source-uri-fn (function).
• prin1-to-markdown (function).
• unresolvable-reflink (condition).
• update-asdf-system-html-docs (function).
• update-asdf-system-readmes (function).
• update-pax-world (function).
• with-dislocated-names (macro).
• with-heading (macro).

Internals

• *documenting-reference* (special variable).
• @extending-document (special variable).
• @github-workflow (special variable).
• asdf-system-git-root-and-version (function).
• call-with-heading (function).
• convert-source-location (function).
• current-definition-pax-url-for-emacs (function).
• document-for-emacs (function).
• downcasingp (function).
• end-of-register-doc-example (special variable).
• ensure-list (function).
• file-position-to-line-number (function).
• find-hyperspec-definition-url (function).
• find-hyperspec-glossary-entry-id (function).
• find-hyperspec-glossary-entry-url (function).
• find-hyperspec-issue-id (function).
• find-hyperspec-issue-url (function).
• find-hyperspec-section-id (function).
• find-hyperspec-section-url (function).
• git-root (function).
• git-version (function).
• in-git-p (function).
• line-file-positions (function).
• locate-pax-url-for-emacs (function).
• locatives-for-name-for-emacs (function).
• pathname-as-directory (function).
• pax-pages (function).
• pax-sections (function).
• print-reference-bullet (function).
• redocument-for-emacs (function).
• with-local-references (macro).

---

4.1.10 mgl-pax/src/base//web-early.lisp

Dependency

document-early.lisp (file).

Source

mgl-pax.asd.

Parent Component

src/base/ (module).

Internals

ensure-web-server (function).

---

4.1.11 mgl-pax/src/base//transcribe-early.lisp

Dependency

web-early.lisp (file).

Source

mgl-pax.asd.

Parent Component

src/base/ (module).

Public Interface

• *transcribe-check-consistency* (special variable).
• *transcribe-syntaxes* (special variable).
• delete-comments (function).
• delete-trailing-whitespace (function).
• squeeze-whitespace (function).
• transcribe (function).
• transcription-consistency-error (condition).
• transcription-error (condition).

Internals

• @transcripts (special variable).
• ensure-transcribe-loaded (function).
• transcribe-for-emacs (function).

---

4.1.12 mgl-pax/src/base//locatives-early.lisp

Dependency

transcribe-early.lisp (file).

Source

mgl-pax.asd.

Parent Component

src/base/ (module).

Internals

@pax-locatives (special variable).

---

4.1.13 mgl-pax.asdf/asdf.lisp

Source

mgl-pax.asdf.asd.

Parent Component

mgl-pax.asdf (system).

Packages

mgl-pax.asdf.

Public Interface

• call-with-wrappers (function).
• compile-pax (function).
• compile-per-file (function).
• compile-with-source-info (function).
• compose-wrappers (function).

Internals

compile-without-some-warnings (function).

---

4.1.14 mgl-pax-bootstrap/src/bootstrap//package.lisp

Source

mgl-pax-bootstrap.asd.

Parent Component

src/bootstrap/ (module).

Packages

mgl-pax.

---

4.1.15 mgl-pax-bootstrap/src/bootstrap//basics.lisp

Dependency

package.lisp (file).

Source

mgl-pax-bootstrap.asd.

Parent Component

src/bootstrap/ (module).

Public Interface

• *discard-documentation-p* (special variable).
• define-glossary-term (macro).
• define-package (macro).
• defsection (macro).
• exportable-locative-type-p (generic function).
• exportable-reference-p (generic function).
• glossary-term (class).
• glossary-term-name (reader method).
• glossary-term-title (reader method).
• glossary-term-url (reader method).
• print-object (method).
• section (class).
• section-name (reader method).
• section-package (reader method).
• section-readtable (reader method).
• section-title (reader method).

Internals

• check-link-title-to (function).
• check-section-entries (function).
• export-some-symbols (function).
• exportablep (function).
• glossary-term-docstring (reader method).
• malformed-ref-list-in-section-error (function).
• prin1-to-string/fully-qualified (function).
• ref-list-p (function).
• symbol-accessible-in-package-p (function).

---

4.1.16 mgl-pax-bootstrap/src/bootstrap//pax-world.lisp

Dependency

basics.lisp (file).

Source

mgl-pax-bootstrap.asd.

Parent Component

src/bootstrap/ (module).

Public Interface

register-doc-in-pax-world (function).

Internals

• *registered-pax-world-docs* (special variable).
• @pax-world (special variable).
• list-designator (function).

---

4.1.17 dref/src/base//package.lisp

Source

dref.asd.

Parent Component

src/base/ (module).

Packages

• dref.
• dref-ext.

Internals

• @condition-system-locatives (special variable).
• @dref-locatives (special variable).
• @dref-subclasses (special variable).
• @extending-dref (special variable).
• @functionlike-locatives (special variable).
• @locative-types (special variable).
• @macrolike-locatives (special variable).
• @packagelike-locatives (special variable).
• @references (special variable).
• @source-locations (special variable).
• @symbol-locatives (special variable).
• @typelike-locatives (special variable).
• @variablelike-locatives (special variable).
• dref-std-env (function).

---

4.1.18 dref/src/base//autoload.lisp

Dependency

package.lisp (file).

Source

dref.asd.

Parent Component

src/base/ (module).

Internals

• autoload (macro).
• defun/autoloaded (macro).
• without-redefinition-warnings (macro).

---

4.1.19 dref/src/base//util.lisp

Dependency

autoload.lisp (file).

Source

dref.asd.

Parent Component

src/base/ (module).

Internals

• hash-table-keys (function).
• macro-arg-names (function).

---

4.1.20 dref/src/base//dref.lisp

Dependency

util.lisp (file).

Source

dref.asd.

Parent Component

src/base/ (module).

Public Interface

• arglist (function).
• docstring (function).
• dref (function).
• dref (class).
• dref-locative (reader method).
• dref-locative-args (function).
• dref-locative-type (function).
• dref-name (reader method).
• dref-origin (reader method).
• initialize-instance (method).
• lisp-locative-types (function).
• locate (function).
• locate-error (condition).
• locative-aliases (function).
• locative-args (function).
• locative-type (function).
• locative-types (function).
• print-object (method).
• pseudo-locative-types (function).
• resolve (function).
• resolve-error (condition).
• source-location (function).
• xref (function).
• xref (class).
• xref-locative (reader method).
• xref-locative-args (function).
• xref-locative-type (function).
• xref-name (reader method).
• xref= (function).

Internals

• *lisp-locative-types* (special variable).
• *locative-aliases* (special variable).
• *locative-types* (special variable).
• *pseudo-locative-types* (special variable).
• @dref-manual (special variable).
• @glossary (special variable).
• @introduction (special variable).
• @listing-definitions (special variable).
• @locative (special variable).
• @locative-type (special variable).
• @locatives-and-references (special variable).
• @name (special variable).
• @operations (special variable).
• @presentation (special variable).
• @reference (special variable).
• declare-locative-alias (function).
• declare-locative-type (function).
• declare-pseudo-locative-type (function).
• ensure-dref-loaded (function).
• format-format-and-args (function).
• locate-error-message (reader method).
• locate-error-object (reader method).
• normalize-locative (function).
• resolve-error-dref (reader method).
• resolve-error-message (reader method).
• xref-name= (function).

---

4.1.21 dref/src/base//extension-api.lisp

Dependency

dref.lisp (file).

Source

dref.asd.

Parent Component

src/base/ (module).

Public Interface

• add-dref-actualizer (function).
• arglist* (generic function).
• check-locative-args (macro).
• define-definer-for-symbol-locative-type (macro).
• define-definition-class (macro).
• define-locative-alias (macro).
• define-locative-type (macro).
• define-pseudo-locative-type (macro).
• define-symbol-locative-type (macro).
• docstring* (generic function).
• dref* (generic function).
• locate* (generic function).
• locate-error (function).
• remove-dref-actualizer (function).
• resolve* (generic function).
• resolve-error (function).
• source-location* (generic function).
• symbol-locative-dref (class).

Internals

• %make-dref (macro).
• *dref-actualizers* (special variable).
• *locating-object* (special variable).
• *resolving-dref* (special variable).
• @adding-new-locatives (special variable).
• @symbol-locatives (special variable).
• actualize-dref (function).
• check-body-docstring (function).
• check-docstring-only-body (function).
• expand-define-definer-for-symbol-as-locative-definer-body (function).
• locative-type-lambda-list (generic function).
• map-definitions (generic function).
• map-names (generic function).
• symbol-lambda-list (generic function).
• symbol-lambda-list-method (macro).
• the-dref (macro).

---

4.1.22 dref/src/base//early.lisp

Dependency

extension-api.lisp (file).

Source

dref.asd.

Parent Component

src/base/ (module).

Public Interface

• define-restart (macro).
• definitions (function).
• dref* (method).
• dref-apropos (function).
• make-source-location (function).
• restart-dref (class).
• source-location-adjusted-file-position (function).
• source-location-buffer (function).
• source-location-buffer-position (function).
• source-location-file (function).
• source-location-file-position (function).
• source-location-p (function).
• source-location-snippet (function).

Internals

locative-type-lambda-list (method).

---

6.1.1 Special variables

Special Variable: *browse-html-style* ¶

Package

mgl-pax.

Source

document-early.lisp.

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

basics.lisp.

Special Variable: *document-base-url* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-downcase-uppercase-code* ¶

Package

mgl-pax.

Source

document-early.lisp.

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

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-html-bottom-blocks-of-links* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-html-default-style* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-html-head* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-html-max-navigation-table-of-contents-level* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-html-sidebar* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-html-top-blocks-of-links* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-hyperspec-root* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-link-code* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-link-sections* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-link-to-hyperspec* ¶

Package

mgl-pax.

Source

document-early.lisp.

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

Package

mgl-pax.

Source

document-early.lisp.

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

Package

mgl-pax.

Source

document-early.lisp.

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

Package

mgl-pax.

Source

document-early.lisp.

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

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-normalize-packages* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-text-navigation* ¶

Package

mgl-pax.

Source

document-early.lisp.

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

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *document-url-versions* ¶

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *format* ¶

Bound by DOCUMENT to its FORMAT argument, this allows markdown output to depend on the output format.

Package

mgl-pax.

Source

document-early.lisp.

Special Variable: *transcribe-check-consistency* ¶

Package

mgl-pax.

Source

transcribe-early.lisp.

Special Variable: *transcribe-syntaxes* ¶

Package

mgl-pax.

Source

transcribe-early.lisp.

---

6.1.2 Macros

Macro: check-locative-args (locative-type locative-args) ¶

Signal a LOCATE-ERROR condition if LOCATIVE-ARGS do not match the LAMBDA-LIST argument of LOCATIVE-TYPE (not evaluated).

Package

dref-ext.

Source

extension-api.lisp.

Macro: define-definer-for-symbol-locative-type (name locative-type &body docstring) ¶

Define a macro with NAME that can be used to attach a lambda list, documentation, 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

dref-ext.

Source

extension-api.lisp.

Macro: define-definition-class (locative-type class-name &optional superclasses &body body) ¶

Define a subclass of DREF. All definitions with LOCATIVE-TYPE
must be of this type. If non-NIL, BODY is DEFCLASS’ slot definitions and other options.

Package

dref-ext.

Source

extension-api.lisp.

Macro: define-glossary-term (name (&key title url discard-documentation-p) &optional docstring) ¶

Define a global variable with NAME, and set it to a [GLOSSARY-TERM] [class] object. TITLE, URL and DOCSTRING are markdown strings or NIL. Glossary terms are DOCUMENTed in the lightweight bullet + locative + name/title style. See the glossary entry @NAME for an example.

When a glossary term is linked to in documentation, its TITLE will be the link text instead of the name of the symbol (as with SECTIONs).

Glossary entries with a non-NIL URL are like external links: they are linked to their URL in the generated documentation. These offer a more reliable alternative to using markdown reference links and are usually not included in SECTIONs.

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

Package

mgl-pax.

Source

basics.lisp.

Macro: define-locative-alias (alias locative-type &body docstring) ¶

Define ALIAS as a locative equivalent to LOCATIVE-TYPE (both SYMBOLs). LOCATIVE-TYPE must exist (i.e. be among LOCATIVE-TYPES). For example, let’s define OBJECT as an alias of the CLASS locative:

“‘cl-transcript
(define-locative-alias object class)
“‘

Then, LOCATEing with OBJECT will find the CLASS:

“‘cl-transcript
(dref ’xref ’object)
==> #<DREF XREF CLASS>
“‘

The LOCATIVE-ARGS of OBJECT (none in the above) are passed on to CLASS.

“‘cl-transcript
(arglist (dref ’object ’locative))
=> (&REST ARGS)
=> :DESTRUCTURING
“‘

Also, see PAX::@LOCATIVE-ALIASES in PAX.

Package

dref-ext.

Source

extension-api.lisp.

Macro: define-locative-type (locative-type lambda-list &body docstring) ¶

Declare LOCATIVE-TYPE as a [LOCATIVE][locative], which is the first step in DREF-EXT::@EXTENDING-DREF.

LAMBDA-LIST is a [destructuring lambda list][clhs]. The LOCATIVE-ARGS of [DREF][class]s with @LOCATIVE-TYPE LOCATIVE-TYPE (the argument given to this macro) always conform to this lambda list. See CHECK-LOCATIVE-ARGS.

For example, if have:

“‘
(define-locative-type dummy (x &key y)
"Dummy docstring.")
“‘

then ‘(LOCATE ’DUMMY ’LOCATIVE)‘ refers to this definition. That is, ARGLIST, [DOCSTRING][function] and SOURCE-LOCATION all work on it.

Locative types defined with DEFINE-LOCATIVE-TYPE can be listed with LISP-LOCATIVE-TYPES.

Package

dref-ext.

Source

extension-api.lisp.

Macro: define-package (package &rest options) ¶

This is like CL:DEFPACKAGE but silences warnings and errors signalled when the redefined package is at variance with the current state of the package. Typically this situation occurs when symbols are exported by calling EXPORT (as is the case with DEFSECTION) as opposed to adding :EXPORT forms to the DEFPACKAGE form and the package definition is subsequently reevaluated. See the section on [package variance](http://www.sbcl.org/manual/#Package-Variance) in the SBCL manual.

The bottom line is that if you rely on DEFSECTION to do the exporting, then you’d better use DEFINE-PACKAGE.

Package

mgl-pax.

Source

basics.lisp.

Macro: define-pseudo-locative-type (locative-type lambda-list &body docstring) ¶

Like DEFINE-LOCATIVE-TYPE, but declare that LOCATIVE-TYPE does not correspond to definitions in the Lisp system. Definitions with pseduo locatives are not listed by default by DEFINITIONS.

Locative types defined with DEFINE-PSEUDO-LOCATIVE-TYPE can be listed with PSEUDO-LOCATIVE-TYPES.

Package

dref-ext.

Source

extension-api.lisp.

Macro: define-restart (symbol lambda-list &body docstring) ¶

Associate a definition with the name of a restart, which must be a symbol. LAMBDA-LIST should be what calls like ‘(INVOKE-RESTART ’<SYMBOL> ...)‘ must conform to, but this not enforced.

PAX "defines" standard CL restarts such as USE-VALUE with DEFINE-RESTART:

“‘cl-transcript (:dynenv dref-std-env)
(first-line (source-location-snippet
(source-location (dref ’use-value ’restart))))
=> "(define-restart use-value (value)"
“‘

Note that while there is a CL:RESTART class, its instances have no docstring or source location.

Package

dref.

Source

early.lisp.

Macro: define-symbol-locative-type (locative-type lambda-list &body docstring) ¶

Similar to DEFINE-LOCATIVE-TYPE, but it assumes that all things LOCATEable with LOCATIVE-TYPE are going to be symbols defined with a definer defined with DEFINE-DEFINER-FOR-SYMBOL-LOCATIVE-TYPE. Symbol locatives are for attaching a definition (along with arglist, documentation and source location) to a symbol in a particular context. An example will make everything clear:

“‘
(define-symbol-locative-type direction ()
"A direction is a symbol.")

(define-definer-for-symbol-locative-type define-direction direction "With DEFINE-DIRECTION, one can document 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, ‘(DREF ’UP ’DIRECTION)‘ refers to the ‘DEFINE-DIRECTION‘ form above.

Package

dref-ext.

Source

extension-api.lisp.

Macro: defsection (name (&key package readtable export title link-title-to 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 @INTRODUCTION for an example.

**Entries**

ENTRIES consists of docstrings and references in any order. Docstrings are arbitrary strings in markdown format.

References are [XREF][class]s given in the form ‘(NAME LOCATIVE)‘. For example, ‘(FOO FUNCTION)‘ refers to the function ‘FOO‘, ‘(@BAR SECTION)‘ says that ‘@BAR‘ is a subsection of this
one. ‘(BAZ (METHOD () (T T T)))‘ refers to the default method of the three argument generic function ‘BAZ‘. ‘(FOO FUNCTION)‘ is equivalent to ‘(FOO (FUNCTION))‘. See the DRef DREF::@INTRODUCTION for more.

The same name may occur in multiple references, typically with different locatives, but this is not required.

The references are not LOCATEd until documentation is generated, so they may refer to things yet to be defined.

**Exporting**

If EXPORT is true (the default), NAME and the @NAMEs of references among ENTRIES which are SYMBOLs are candidates for exporting. A candidate symbol is exported if

- it is [accessible][find-symbol] in PACKAGE, and

- there is a reference to it in the section being defined which is approved by EXPORTABLE-REFERENCE-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.

**Misc**

TITLE is a string containing markdown or NIL. If non-NIL, it determines the text of the heading in the generated output. LINK-TITLE-TO is a reference given as an ‘(NAME LOCATIVE)‘ pair or NIL, to which the heading will link when generating HTML. If not specified, the heading will link to its own anchor.

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

Package

mgl-pax.

Source

basics.lisp.

Macro: documenting-reference ((stream &key reference name package readtable arglist) &body body) ¶

Write REFERENCE to STREAM as described in *DOCUMENT-MARK-UP-SIGNATURES*, and establish REFERENCE as a [local reference][@LOCAL-REFERENCES] for the processing of BODY.

- REFERENCE defaults to the reference being DOCUMENTed.

- NAME defaults to ‘(XREF-NAME REFERENCE)‘ and is printed after the LOCATIVE-TYPE.

- *PACKAGE* and *READTABLE* are bound to PACKAGE and READTABLE for the duration of printing the ARGLIST and the processing of BODY. If either is NIL, then a default value is computed as described in @PACKAGE-AND-READTABLE.

- If ARGLIST is NIL, then it is not printed.

- If ARGLIST is a list, then it is must be a [lambda list][clhs] and is printed without the outermost parens and with the package names removed from the argument names.

- If ARGLIST is a string, then it must be valid markdown.

- It is not allowed to have WITH-HEADING within the [dynamic extent][clhs] of BODY.

Package

mgl-pax.

Source

document-early.lisp.

Macro: with-dislocated-names (names &body body) ¶

For each name in NAMES, establish a [local reference][@local-references] with the DISLOCATED locative, which [prevents autolinking][@preventing-autolinking].

Package

mgl-pax.

Source

document-early.lisp.

Macro: with-heading ((stream object title &key link-title-to) &body body) ¶

Write a markdown heading with TITLE to STREAM. Nested WITH-HEADINGs produce nested headings. If *DOCUMENT-LINK-SECTIONS*, generate anchors based on the [definition of][locate] OBJECT. LINK-TITLE-TO behaves like the LINK-TITLE-TO argument of DEFSECTION.

Package

mgl-pax.

Source

document-early.lisp.

---

6.1.3 Ordinary functions

Function: add-dref-actualizer (name) ¶

Add the global function denoted by the symbol NAME to the list
of actualizers. Actualizers are functions of a single [DREF][class] argument. They are called within LOCATE when LOCATE* returns a DREF. Their job is to make the DREF more specific.

Package

dref-ext.

Source

extension-api.lisp.

Function: arglist (object) ¶

Return the arglist of the definition of OBJECT or NIL if the arglist cannot be determined.

The second return value indicates whether the arglist has been found. Furthermore, :ORDINARY indicates an [ordinary lambda list][clhs], :MACRO a [macro lambda list][clhs], :DEFTYPE a [deftype lambda list][clhs], and :DESTRUCTURING a [destructuring lambda list][clhs]. Other non-NIL values are also allowed.

“‘cl-transcript (:dynenv dref-std-env)
(arglist #’arglist)
=> (OBJECT)
=> :ORDINARY
“‘
“‘cl-transcript (:dynenv dref-std-env)
(arglist (dref ’define-locative-type ’macro))
=> (LOCATIVE-TYPE LAMBDA-LIST &BODY DOCSTRING)
=> :MACRO
“‘
“‘cl-transcript (:dynenv dref-std-env)
(arglist (dref ’method ’locative))
=> (METHOD-QUALIFIERS METHOD-SPECIALIZERS)
=> :DESTRUCTURING
“‘

This function supports MACROs, COMPILER-MACROs, SETF functions, FUNCTIONs, GENERIC-FUNCTIONs, METHODs, TYPES, LOCATIVEs. Note that ARGLIST depends on the quality of SWANK-BACKEND:ARGLIST. With the exception of SBCL, which has perfect support, all Lisp implementations have minor omissions:

- DEFTYPE lambda lists on ABCL, AllegroCL, CLISP, CCL, CMUCL, ECL; - default values in MACRO lambda lists on AllegroCL; various edge - cases involving traced functions.

Can be extended via ARGLIST*

Package

dref.

Source

dref.lisp.

Function: call-with-wrappers (wrappers fn) ¶

Package

mgl-pax.asdf.

Source

asdf.lisp.

Function: compile-pax (continuation) ¶

Package

mgl-pax.asdf.

Source

asdf.lisp.

Function: compile-per-file (continuation) ¶

Package

mgl-pax.asdf.

Source

asdf.lisp.

Function: compile-with-source-info (continuation) ¶

Package

mgl-pax.asdf.

Source

asdf.lisp.

Function: compose-wrappers (wrappers) ¶

Package

mgl-pax.asdf.

Source

asdf.lisp.

Function: definitions (&rest args) ¶

Package

dref.

Source

early.lisp.

Function: delete-comments (&rest args) ¶

Package

mgl-pax.

Source

transcribe-early.lisp.

Function: delete-trailing-whitespace (&rest args) ¶

Package

mgl-pax.

Source

transcribe-early.lisp.

Function: docstring (object) ¶

Return the docstring from the definition of OBJECT.
As the second value, return the *PACKAGE* that was in effect when the docstring was installed or NIL if it cannot be determined (this is used by PAX:DOCUMENT when PAX::@PARSING the docstring). This function is similar in purpose to CL:DOCUMENTATION.

Note that some locative types such as ASDF:SYSTEMS and DECLARATIONs have no docstrings, and some Lisp implementations do not record all docstrings. The following are known to be missing:

- COMPILER-MACRO docstrings on ABCL, AllegroCL, CCL, ECL;
- METHOD-COMBINATION docstrings on ABCL, AllegroCL.

Can be extended via DOCSTRING*.

Package

mgl-pax.

Source

dref.lisp.

Function: document (&rest args) ¶

Package

mgl-pax.

Source

document-early.lisp.

Function: document-docstring (&rest args) ¶

Package

mgl-pax.

Source

document-early.lisp.

Function: dref (name locative &optional errorp) ¶

Shorthand for ‘(LOCATE (XREF NAME LOCATIVE) ERRORP)‘.

Package

dref.

Source

dref.lisp.

Function: dref-apropos (&rest args) ¶

Package

dref.

Source

early.lisp.

Function: dref-locative-args (dref) ¶

Package

dref-ext.

Source

dref.lisp.

Function: dref-locative-type (dref) ¶

Package

dref-ext.

Source

dref.lisp.

Function: ensure-navigate-loaded (&rest args) ¶

Package

mgl-pax.

Source

extension-api.lisp.

Function: escape-markdown (&rest args) ¶

Package

mgl-pax.

Source

document-early.lisp.

Function: install-pax-elisp (target-dir) ¶

Copy ‘mgl-pax.el‘ distributed with this package to TARGET-DIR.

Package

mgl-pax.

Source

pax.lisp.

Function: lisp-locative-types () ¶

Return the locative types that correspond to Lisp definitions except UNKNOWN. These are the ones defined with DEFINE-LOCATIVE-TYPE.

Package

dref.

Source

dref.lisp.

Function: locate (object &optional errorp) ¶

Return a [DREF][class] representing the definition given by the arguments. In the same [dynamic environment][clhs], two DREFs denote the same thing if and only if they are XREF=.

OBJECT must be a supported first-class object, a DREF, or an [XREF][class]:

“‘cl-transcript (:dynenv dref-std-env)
(locate #’print)
==> #<DREF PRINT FUNCTION>
“‘
“‘cl-transcript (:dynenv dref-std-env)
(locate (locate #’print))
==> #<DREF PRINT FUNCTION>
“‘
“‘cl-transcript (:dynenv dref-std-env)
(locate (xref ’print ’function))
==> #<DREF PRINT FUNCTION>
“‘

LOCATE-ERROR is signalled if OBJECT is an XREF with malformed LOCATIVE-ARGS, or if no corresponding definition is found. If ERRORP is NIL, then NIL and the LOCATE-ERROR condition are returned instead.

“‘cl-transcript (:dynenv dref-std-env)
(locate (xref ’no-such-function ’function))
.. debugger invoked on LOCATE-ERROR:
.. Could not locate NO-SUCH-FUNCTION FUNCTION.
.. NO-SUCH-FUNCTION is not a symbol naming a function.
“‘
“‘cl-transcript (:dynenv dref-std-env)
(locate (xref ’print ’(function xxx)))
.. debugger invoked on LOCATE-ERROR:
.. Could not locate PRINT #’XXX.
.. Bad arguments (XXX) for locative FUNCTION with lambda list NIL. “‘
“‘cl-transcript (:dynenv dref-std-env)
(locate "xxx")
.. debugger invoked on LOCATE-ERROR:
.. Could not locate "xxx".
“‘

Use the low-level XREF to construct an XREF without error checking.

Can be extended via LOCATE*.

Package

dref.

Source

dref.lisp.

Function: locate-error (&rest format-and-args) ¶

Call this function to signal a LOCATE-ERROR condition from the [dynamic extent][clhs] of a LOCATE* method (which includes DREF*). It is an error to call LOCATE-ERROR elsewhere.

FORMAT-AND-ARGS, if non-NIL, is a format string and arguments suitable for FORMAT.

Package

dref-ext.

Source

extension-api.lisp.

Function: locative-aliases () ¶

Return the list of locatives aliases, defined with DEFINE-LOCATIVE-ALIAS.

Package

dref.

Source

dref.lisp.

Function: locative-args (locative) ¶

Return the REST of LOCATIVE (which may be from XREF-LOCATIVE)
if it’s a list. If it’s a symbol, then return NIL. The locative args should match the LAMBDA-LIST of the LOCATIVE-TYPE’s [definition][define-locative-type], but this is guaranteed only for locatives of [DREF][class]s and is not checked for plain [XREF][class]s.

Package

dref-ext.

Source

dref.lisp.

Function: locative-type (locative) ¶

Return @LOCATIVE-TYPE of LOCATIVE (which may be from XREF-LOCATIVE). This is the first element of LOCATIVE if it’s a list. If it’s a symbol, it’s that symbol itself.

Package

dref-ext.

Source

dref.lisp.

Function: locative-types () ¶

Return a list of non-[alias][locative-aliases] locative types. This is the UNION of LISP-LOCATIVE-TYPES and PSEUDO-LOCATIVE-TYPES.

Package

dref.

Source

dref.lisp.

Function: make-git-source-uri-fn (asdf-system git-forge-uri &key git-version uri-format-string) ¶

Return a function suitable as :SOURCE-URI-FN of a page spec (see
the PAGES argument of DOCUMENT). The function looks at the source location of the object passed to it, and if the location is found, the path is made relative to the toplevel directory of the git checkout containing the file of the ASDF-SYSTEM and finally an \URI pointing to your git forge (such as github) is returned. A warning
is signalled whenever the source location lookup fails or if the source location points to a directory not below the directory of ASDF-SYSTEM.

If GIT-FORGE-URI is ‘"https://github.com/melisgl/mgl-pax/"‘ and GIT-VERSION is ‘"master"‘, then the returned \URI may look like this:

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

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
the git forge will be generated.

URI-FORMAT-STRING is a CL:FORMAT control string for four arguments:

- GIT-FORGE-URI,
- GIT-VERSION,
- the relative path to the file of the source location of the reference, - and the line number.

The default value of URI-FORMAT-STRING is for github. If using a non-standard git forge, such as Sourcehut or Gitlab, simply pass a suitable URI-FORMAT-STRING matching the \URI scheme of your forge.

Package

mgl-pax.

Source

document-early.lisp.

Function: make-github-source-uri-fn (asdf-system github-uri &key git-version) ¶

This function is a backward-compatibility wrapper around MAKE-GIT-SOURCE-URI-FN, which supersedes MAKE-GITHUB-SOURCE-URI-FN. All arguments are passed on to MAKE-GIT-SOURCE-URI-FN, leaving URI-FORMAT-STRING at its default, which is suitable for github.

Package

mgl-pax.

Source

document-early.lisp.

Function: make-source-location (&rest args) ¶

Package

dref-ext.

Source

early.lisp.

Function: prin1-to-markdown (&rest args) ¶

Package

mgl-pax.

Source

document-early.lisp.

Function: pseudo-locative-types () ¶

Return the locative types that correspond to non-Lisp definitions plus UNKNOWN. These are the ones defined with DEFINE-PSEUDO-LOCATIVE-TYPE.

Package

dref.

Source

dref.lisp.

Function: register-doc-in-pax-world (name sections page-specs) ¶

Register SECTIONS and PAGE-SPECS under NAME (a symbol) in PAX World. By default, UPDATE-PAX-WORLD generates documentation for all of these. SECTIONS and PAGE-SPECS must be lists of SECTIONs and PAGE-SPECs (SEE DOCUMENT) or designators of function of no arguments that return such lists.

Package

mgl-pax.

Source

pax-world.lisp.

Function: remove-dref-actualizer (name) ¶

Remove the global function denoted by the symbol NAME from the list of actualizers.

Package

dref-ext.

Source

extension-api.lisp.

Function: resolve (object &optional errorp) ¶

If OBJECT is an [XREF][class], then return the first-class object associated with its definition if any. Return OBJECT if it’s not an XREF. Thus, the value returned is never an XREF.

“‘cl-transcript (:dynenv dref-std-env)
(resolve (dref ’print ’function))
==> #<FUNCTION PRINT>
“‘
“‘cl-transcript (:dynenv dref-std-env)
(resolve #’print)
==> #<FUNCTION PRINT>
“‘

If OBJECT is an XREF, and the definition for it cannot be LOCATEd, then signal a LOCATE-ERROR condition.

“‘cl-transcript (:dynenv dref-std-env)
(resolve (xref ’undefined ’variable))
.. debugger invoked on LOCATE-ERROR:
.. Could not locate UNDEFINED VARIABLE.
“‘

If there is a definition, but there is no first-class object corresponding to it, then signal a RESOLVE-ERROR condition or return NIL depending on ERRORP:

“‘cl-transcript (:dynenv dref-std-env)
(resolve (dref ’*print-length* ’variable))
.. debugger invoked on RESOLVE-ERROR:
.. Could not resolve *PRINT-LENGTH* VARIABLE.
“‘
“‘cl-transcript (:dynenv dref-std-env)
(resolve (dref ’*print-length* ’variable) nil)
=> NIL
“‘

RESOLVE is a partial inverse of LOCATE: if a [DREF][class] is RESOLVEable, then LOCATEing the object it resolves to recovers the DREF equivalent to the original (XREF= and of the same type but not EQ).

Can be extended via RESOLVE*.

Package

dref.

Source

dref.lisp.

Function: resolve-error (&rest format-and-args) ¶

Call this function to signal a RESOLVE-ERROR condition from the [dynamic extent][clhs] of a RESOLVE* method. It is an error to call RESOLVE-ERROR elsewhere.

FORMAT-AND-ARGS, if non-NIL, is a format string and arguments suitable for FORMAT.

Package

dref.

Source

extension-api.lisp.

Function: section-entries (section) ¶

A list of markdown docstrings and [XREF][class]s in the order they occurred in DEFSECTION.

Package

mgl-pax.

Source

pax.lisp.

Function: section-link-title-to (section) ¶

Package

mgl-pax.

Source

pax.lisp.

Function: source-location (object &key errorp) ¶

Return the Swank source location for the [defining form][clhs] of OBJECT. If no source location was found, then either an ERROR condition is signalled if ERRORP else the [ERROR][condition] is returned as the second value (with the first being NIL). The returned Swank location object is to be accessed only through the DREF-EXT::@SOURCE-LOCATIONS API or to be passed to e.g Slime’s ‘slime-goto-source-location‘.

Note that the availability of source location information varies greatly across Lisp implementations.

Can be extended via SOURCE-LOCATION*.

Package

dref.

Source

dref.lisp.

Function: source-location-adjusted-file-position (&rest args) ¶

Package

dref-ext.

Source

early.lisp.

Function: source-location-buffer (&rest args) ¶

Package

dref-ext.

Source

early.lisp.

Function: source-location-buffer-position (&rest args) ¶

Package

dref-ext.

Source

early.lisp.

Function: source-location-file (&rest args) ¶

Package

dref-ext.

Source

early.lisp.

Function: source-location-file-position (&rest args) ¶

Package

dref-ext.

Source

early.lisp.

Function: source-location-p (&rest args) ¶

Package

dref-ext.

Source

early.lisp.

Function: source-location-snippet (&rest args) ¶

Package

dref-ext.

Source

early.lisp.

Function: squeeze-whitespace (&rest args) ¶

Package

mgl-pax.

Source

transcribe-early.lisp.

Function: transcribe (&rest args) ¶

Package

mgl-pax.

Source

transcribe-early.lisp.

Function: update-asdf-system-html-docs (&rest args) ¶

Package

mgl-pax.

Source

document-early.lisp.

Function: update-asdf-system-readmes (&rest args) ¶

Package

mgl-pax.

Source

document-early.lisp.

Function: update-pax-world (&rest args) ¶

Package

mgl-pax.

Source

document-early.lisp.

Function: xref (name locative) ¶

A shorthand for ‘(MAKE-INSTANCE ’XREF :NAME NAME :LOCATIVE LOCATIVE)‘. It does no error checking: the LOCATIVE-TYPE of LOCATIVE-TYPE need not be defined, and the LOCATIVE-ARGS need not be valid. Use LOCATE or the DREF function to create [DREF][class] objects.

Package

dref.

Source

dref.lisp.

Function: xref-locative-args (xref) ¶

Package

dref-ext.

Source

dref.lisp.

Function: xref-locative-type (xref) ¶

Package

dref-ext.

Source

dref.lisp.

Function: xref= (xref1 xref2) ¶

See if XREF1 and XREF2 have the same XREF-NAME and XREF-LOCATIVE under EQUAL. Comparing like this makes most sense for [DREF][class]s. However, two [XREF][class]s different under XREF= may denote the same [DREF][class]s.

Package

dref.

Source

dref.lisp.

---

6.1.4 Generic functions

Generic Function: arglist* (object) ¶

To extend ARGLIST, specialize this on a subclass of
[DREF][class] if that subclass is not RESOLVEable, else on the type of object it resolves to. This function is for extension only. Do not call it directly.

Package

dref-ext.

Source

extension-api.lisp.

Methods

Method: arglist* ((dref dref)) ¶

Method: arglist* (object) ¶

Generic Function: docstring* (dref) ¶

To extend DOCSTRING, specialize this on a subclass
of [DREF][class] if that subclass is not RESOLVEable, else on the type of object it resolves to. This function is for extension only. Do not call it directly.

Package

dref-ext.

Source

extension-api.lisp.

Methods

Method: docstring* ((dref dref)) ¶

Method: docstring* (object) ¶

Generic Function: document-object* (object stream) ¶

Write OBJECT in *FORMAT* to STREAM.
Specialize this on a subclass of [DREF][class] if that subclass is not RESOLVEable, else on the type of object it resolves to. This function is for extension only. Don’t call it directly.

Package

mgl-pax.

Source

extension-api.lisp.

Methods

Method: document-object* (object stream) ¶

Generic Function: dref* (name locative-type locative-args) ¶

LOCATE* calls this for [XREF][class]s which are not [DREF][class]s.

An EQL-specialized method must be defined for all new locative types. This function is for extending LOCATE. Do not call it directly.

Package

dref-ext.

Source

extension-api.lisp.

Methods

Method: dref* (symbol (locative-type (eql restart)) locative-args) ¶

Source

early.lisp.

Method: dref* :around (name locative-type locative-args) ¶

Method: dref* (name locative-type locative-args) ¶

Generic Reader: dref-locative (object) ¶

Package

dref-ext.

Methods

Reader Method: dref-locative ((dref dref)) ¶

The same as XREF-LOCATIVE, but only works on [DREF][class]s. Use it as a statement of intent.

Source

dref.lisp.

Target Slot

locative.

Generic Reader: dref-name (object) ¶

Package

dref-ext.

Methods

Reader Method: dref-name ((dref dref)) ¶

The same as XREF-NAME, but only works on [DREF][class]s. Use it as a statement of intent.

Source

dref.lisp.

Target Slot

name.

Generic Reader: dref-origin (object) ¶

Package

dref-ext.

Methods

Reader Method: dref-origin ((dref dref)) ¶

The object from which LOCATE constructed this
[DREF][class]. This is an [XREF][class] when the LOCATIVE argument to LOCATE was non-NIL and the value NAME-OR-OBJECT argument otherwise. DREF-ORIGIN may have @PRESENTATION arguments, which are not included in LOCATIVE-ARGS as is the case with INITFORM argument of the VARIABLE locative:

“‘cl-transcript (:dynenv dref-std-env)
(dref ’*standard-output* ’(variable "see-below"))
==> #<DREF *STANDARD-OUTPUT* VARIABLE>
“‘

“‘cl-transcript (:dynenv dref-std-env)
(dref-origin (dref ’*standard-output* ’(variable "see-below"))) ==> #<XREF *STANDARD-OUTPUT* (VARIABLE "see-below")>
“‘

The INITFORM argument overrides the global binding of *STANDARD-OUTPUT* when it’s PAX:DOCUMENTed:

“‘cl-transcript (:dynenv dref-std-env)
(first-line
(pax:document (dref ’*standard-output* ’(variable "see-below")) :stream nil))
=> "- [variable] *STANDARD-OUTPUT* \"see-below\""
“‘

Source

dref.lisp.

Target Slot

origin.

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 SECTION, GLOSSARY-TERM, PACKAGE, ASDF:SYSTEM, METHOD and INCLUDE return NIL.

This function is called by the default method of EXPORTABLE-REFERENCE-P to decide what symbols DEFSECTION shall export when its EXPORT argument is true.

Package

mgl-pax.

Source

basics.lisp.

Methods

Method: exportable-locative-type-p ((locative-type (eql mgl-pax:include))) ¶

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 asdf/system:system))) ¶

Method: exportable-locative-type-p (locative-type) ¶

Generic Function: exportable-reference-p (package symbol locative-type locative-args) ¶

Return true iff SYMBOL is to be exported from
PACKAGE when it occurs in a DEFSECTION in a reference with LOCATIVE-TYPE and LOCATIVE-ARGS. SYMBOL is [accessible][find-symbol] in PACKAGE.

The default method calls EXPORTABLE-LOCATIVE-TYPE-P with
LOCATIVE-TYPE and ignores the other arguments.

By default, SECTIONs and GLOSSARY-TERMs are not exported although
they are EXPORTABLE-LOCATIVE-TYPE-P. To export symbols naming
sections from MGL-PAX, the following method could be added:

“‘
(defmethod exportable-reference-p ((package (eql (find-package ’mgl-pax))) symbol (locative-type (eql ’section)) locative-args)
t)
“‘

Package

mgl-pax.

Source

basics.lisp.

Methods

Method: exportable-reference-p (package symbol (locative-type (eql mgl-pax:glossary-term)) locative-args) ¶

Method: exportable-reference-p (package symbol (locative-type (eql mgl-pax:section)) locative-args) ¶

Method: exportable-reference-p (package symbol locative-type locative-args) ¶

Generic Reader: glossary-term-name (object) ¶

Package

mgl-pax.

Methods

Reader Method: glossary-term-name ((glossary-term glossary-term)) ¶

The name of the global variable whose value is this GLOSSARY-TERM object.

Source

basics.lisp.

Target Slot

name.

Generic Reader: glossary-term-title (object) ¶

Package

mgl-pax.

Methods

Reader Method: glossary-term-title ((glossary-term glossary-term)) ¶

A markdown string or NIL. Used in generated documentation (see @OUTPUT-DETAILS).

Source

basics.lisp.

Target Slot

title.

Generic Reader: glossary-term-url (object) ¶

Package

mgl-pax.

Methods

Reader Method: glossary-term-url ((glossary-term glossary-term)) ¶

A string or NIL.

Source

basics.lisp.

Target Slot

url.

Generic Function: locate* (object) ¶

Return a definition of OBJECT as a [DREF][class],
without [actualizing it][ADD-DREF-ACTUALIZER]. If OBJECT is a DREF already, then this function simply returns it. If no definition is found for OBJECT, then LOCATE-ERROR is signalled.

This function is for extending LOCATE. Do not call it directly.

Package

dref-ext.

Source

extension-api.lisp.

Methods

Method: locate* :around (object) ¶

Method: locate* (object) ¶

Method: locate* ((xref xref)) ¶

Method: locate* ((dref dref)) ¶

Generic Function: resolve* (dref) ¶

Return the object defined by the definition DREF
refers to. Signal a RESOLVE-ERROR condition by calling the RESOLVE-ERROR function if the lookup fails.

To keep RESOLVE a partial inverse of LOCATE, a specialized LOCATE* method or an [actualizer][ add-dref-actualizer] must be defined for RESOLVEable definitions. This function is for extending RESOLVE. Do not call it directly.

It is an error for methods of this generic function to return an [XREF][class].

Package

dref-ext.

Source

extension-api.lisp.

Methods

Method: resolve* :around ((dref dref)) ¶

Method: resolve* ((dref dref)) ¶

Generic Reader: section-name (object) ¶

Package

mgl-pax.

Methods

Reader Method: section-name ((section section)) ¶

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

Source

basics.lisp.

Target Slot

name.

Generic Reader: section-package (object) ¶

Package

mgl-pax.

Methods

Reader Method: section-package ((section section)) ¶

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

Source

basics.lisp.

Target Slot

package.

Generic Reader: section-readtable (object) ¶

Package

mgl-pax.

Methods

Reader Method: section-readtable ((section section)) ¶

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

Source

basics.lisp.

Target Slot

readtable.

Generic Reader: section-title (object) ¶

Package

mgl-pax.

Methods

Reader Method: section-title ((section section)) ¶

A markdown string or NIL. Used in generated documentation.

Source

basics.lisp.

Target Slot

title.

Generic Function: source-location* (dref) ¶

To extend SOURCE-LOCATION, specialize this on a
subclass of [DREF][class] if that subclass is not RESOLVEable, else on the type of object it resolves to. This function is for extension only. Do not call it directly.

Package

dref-ext.

Source

extension-api.lisp.

Methods

Method: source-location* ((dref dref)) ¶

Method: source-location* (object) ¶

Generic Reader: xref-locative (object) ¶

Package

dref-ext.

Methods

Reader Method: xref-locative ((xref xref)) ¶

The @LOCATIVE of the reference.

The locative is normalized by replacing single-element lists with their only element:

“‘cl-transcript (:dynenv dref-std-env)
(xref ’print ’function)
==> #<XREF PRINT FUNCTION>
“‘
“‘cl-transcript (:dynenv dref-std-env)
(xref ’print ’(function))
==> #<XREF PRINT FUNCTION>
“‘

Source

dref.lisp.

Target Slot

locative.

Generic Reader: xref-name (object) ¶

Package

dref-ext.

Methods

Reader Method: xref-name ((xref xref)) ¶

The @NAME of the reference.

Source

dref.lisp.

Target Slot

name.

---

6.1.5 Standalone methods

Method: initialize-instance :after ((xref xref) &key &allow-other-keys) ¶

Source

dref.lisp.

Method: print-object ((section section) stream) ¶

Source

basics.lisp.

Method: print-object ((xref xref) stream) ¶

Source

dref.lisp.

---

6.1.6 Conditions

Condition: locate-error ¶

Signalled by LOCATE when the definition cannot be found, and ERRORP is true.

Package

dref-ext.

Source

dref.lisp.

Direct superclasses

error.

Direct methods

• locate-error-message.
• locate-error-object.

Direct slots

Slot: object ¶

Package

dref.

Initargs

:object

Readers

locate-error-object.

Writers

This slot is read-only.

Slot: message ¶

Package

dref.

Initargs

:message

Readers

locate-error-message.

Writers

This slot is read-only.

Condition: resolve-error ¶

Signalled by RESOLVE when the object defined cannot be returned, and ERRORP is true.

Package

dref.

Source

dref.lisp.

Direct superclasses

error.

Direct methods

• resolve-error-dref.
• resolve-error-message.

Direct slots

Slot: dref ¶

Initargs

:dref

Readers

resolve-error-dref.

Writers

This slot is read-only.

Slot: message ¶

Initargs

:message

Readers

resolve-error-message.

Writers

This slot is read-only.

Condition: transcription-consistency-error ¶

Package

mgl-pax.

Source

transcribe-early.lisp.

Direct superclasses

transcription-error.

Condition: transcription-error ¶

Package

mgl-pax.

Source

transcribe-early.lisp.

Direct superclasses

error.

Direct subclasses

transcription-consistency-error.

Condition: unresolvable-reflink ¶

Package

mgl-pax.

Source

document-early.lisp.

Direct superclasses

warning.

---

6.1.7 Classes

Class: dref ¶

[DREF][class]s can be thought of as referring to
definitions that actually exist, although changes in the system can invalidate them (for example, a DREF to a function definition can be invalidated by FMAKUNBOUND).

DREFs must be created with LOCATE, and their purpose is to allow easy specialization of other generic functions (see DREF-EXT::@EXTENDING-DREF) and to confine locative validation to LOCATE.

Package

dref.

Source

dref.lisp.

Direct superclasses

xref.

Direct subclasses

symbol-locative-dref.

Direct methods

• arglist*.
• docstring*.
• dref-locative.
• dref-name.
• dref-origin.
• locate*.
• resolve*.
• resolve*.
• source-location*.

Direct slots

Slot: name ¶

The same as XREF-NAME, but only works on [DREF][class]s. Use it as a statement of intent.

Readers

dref-name.

Writers

This slot is read-only.

Slot: locative ¶

The same as XREF-LOCATIVE, but only works on [DREF][class]s. Use it as a statement of intent.

Package

mgl-pax.

Readers

dref-locative.

Writers

This slot is read-only.

Slot: origin ¶

The object from which LOCATE constructed this
[DREF][class]. This is an [XREF][class] when the LOCATIVE argument to LOCATE was non-NIL and the value NAME-OR-OBJECT argument otherwise. DREF-ORIGIN may have @PRESENTATION arguments, which are not included in LOCATIVE-ARGS as is the case with INITFORM argument of the VARIABLE locative:

“‘cl-transcript (:dynenv dref-std-env)
(dref ’*standard-output* ’(variable "see-below"))
==> #<DREF *STANDARD-OUTPUT* VARIABLE>
“‘

“‘cl-transcript (:dynenv dref-std-env)
(dref-origin (dref ’*standard-output* ’(variable "see-below"))) ==> #<XREF *STANDARD-OUTPUT* (VARIABLE "see-below")>
“‘

The INITFORM argument overrides the global binding of *STANDARD-OUTPUT* when it’s PAX:DOCUMENTed:

“‘cl-transcript (:dynenv dref-std-env)
(first-line
(pax:document (dref ’*standard-output* ’(variable "see-below")) :stream nil))
=> "- [variable] *STANDARD-OUTPUT* \"see-below\""
“‘

Readers

dref-origin.

Writers

This slot is read-only.

Class: glossary-term ¶

See DEFINE-GLOSSARY-TERM.

Package

mgl-pax.

Source

basics.lisp.

Direct methods

• glossary-term-docstring.
• glossary-term-name.
• glossary-term-title.
• glossary-term-url.

Direct slots

Slot: name ¶

The name of the global variable whose value is this GLOSSARY-TERM object.

Initargs

:name

Readers

glossary-term-name.

Writers

This slot is read-only.

Slot: title ¶

A markdown string or NIL. Used in generated documentation (see @OUTPUT-DETAILS).

Initargs

:title

Readers

glossary-term-title.

Writers

This slot is read-only.

Slot: url ¶

A string or NIL.

Initargs

:url

Readers

glossary-term-url.

Writers

This slot is read-only.

Slot: docstring ¶

Initargs

:docstring

Readers

glossary-term-docstring.

Writers

This slot is read-only.

Class: restart-dref ¶

Package

dref-ext.

Source

early.lisp.

Direct superclasses

symbol-locative-dref.

Class: section ¶

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

Package

mgl-pax.

Source

basics.lisp.

Direct methods

• print-object.
• section-name.
• section-package.
• section-readtable.
• section-title.

Direct slots

Slot: name ¶

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

Initargs

:name

Readers

section-name.

Writers

This slot is read-only.

Slot: package ¶

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

Package

common-lisp.

Initargs

:package

Readers

section-package.

Writers

This slot is read-only.

Slot: readtable ¶

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

Package

common-lisp.

Initargs

:readtable

Readers

section-readtable.

Writers

This slot is read-only.

Slot: title ¶

A markdown string or NIL. Used in generated documentation.

Initargs

:title

Readers

section-title.

Writers

This slot is read-only.

Slot: %link-title-to ¶

Initargs

:link-title-to

Slot: %entries ¶

Initargs

:entries

Class: symbol-locative-dref ¶

Package

dref-ext.

Source

extension-api.lisp.

Direct superclasses

dref.

Direct subclasses

restart-dref.

Class: xref ¶

An XREF (cross-reference) may represent some
kind of definition of its @NAME in the context given by its @LOCATIVE. The definition may not exist and the locative may be [malformed] [define-locative-type]. The subclass [DREF][class] represents definitions that exist.

Package

dref.

Source

dref.lisp.

Direct subclasses

dref.

Direct methods

• initialize-instance.
• locate*.
• print-object.
• xref-locative.
• xref-name.

Direct slots

Slot: name ¶

The @NAME of the reference.

Initargs

:name

Readers

xref-name.

Writers

This slot is read-only.

Slot: locative ¶

The @LOCATIVE of the reference.

The locative is normalized by replacing single-element lists with their only element:

“‘cl-transcript (:dynenv dref-std-env)
(xref ’print ’function)
==> #<XREF PRINT FUNCTION>
“‘
“‘cl-transcript (:dynenv dref-std-env)
(xref ’print ’(function))
==> #<XREF PRINT FUNCTION>
“‘

Package

mgl-pax.

Initargs

:locative

Readers

xref-locative.

Writers

This slot is read-only.

---