The 40ants-doc Reference Manual

Table of Contents

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

The 40ants-doc Reference Manual

This is the 40ants-doc Reference Manual, version 0.1.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Oct 13 10:44:28 2021 GMT+0.


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

1 Introduction

40Ants Doc Manual

Table of Contents

[in package 40ANTS-DOC/DOC]

1 About this fork

This system is a fork of MGL-PAX.

There are a few reasons, why I've created the fork.

The main goal is to extract a core features into the system 40ANTS-DOC with as little dependencies as possible. This is important, because with MGL-PAX's style, you define documentation sections in your library's code, which makes it dependent on the documentation system. However, heavy weight dependencies like IRONCLAD, 3BMD or SWANK should not be required.

The seconds goal was to refactor a 3.5k lines of pax.lisp file into a smaller modules to make navigation easier. This will help any person who will decide to learn how the documentation builder works. Also, granular design will make it possible loading subsystems like SLIME or SLY integration.

1.1 Why this fork is different

Here is features already implemented in this fork:

WARNING: Unable to find symbol "API" mentioned in (CL-INFO:@INDEX SECTION)

I'm planning to extend this fork even more. Read TODO section to learn about proposed features or start a new discussion on the GitHub to suggest a new feature.

2 40ANTS-DOC ASDF System Details

3 Links

Here is the official repository and the HTML documentation for the latest version.

This system is a fork of the MGL-PAX. Because of massive refactoring, it is incompatible with original repository.

4 Background

As a user, I frequently run into documentation that's incomplete and out of date, so I tend to stay in the editor and explore the code by jumping around with SLIME's M-.. As a library author, I spend a great deal of time polishing code, but precious little writing documentation.

In fact, I rarely write anything more comprehensive than docstrings for exported stuff. Writing docstrings feels easier than writing a separate user manual and they are always close at hand during development. The drawback of this style is that users of the library have to piece the big picture together themselves.

That's easy to solve, I thought, let's just put all the narrative that holds docstrings together in the code and be a bit like a Literate 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, one of them had to go, so DEFSECTION got a list of symbols to export.

That was great, but soon I found that the listing of symbols is ambiguous if, for example, a function, a compiler macro and a class 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:

(defsection @introduction ()
  "A single line for one man ..."
  (foo class)
  (bar function))

After a bit of elisp hacking, M-. was smart enough to disambiguate based on the locative found in the vicinity of the symbol and everything was good for a while.

Then I realized that sections could refer to other sections if there were a SECTION 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 as a reasonably non-intrusive format, and a few thousand lines later MGL-PAX was born.

5 Tutorial

40ANTS-DOC 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 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, using 40ANTS-DOC, packages have no :EXPORT's defined. Instead the UIOP: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:

(uiop:define-package #:foo-random
  (:documentation "This package provides various utilities for
random. See @FOO-RANDOM-MANUAL.")
  (:use #:common-lisp #:40ants-doc))

(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)
==> #<FOO-RANDOM-STATE >
```")

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

(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* #<FOO-RANDOM-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)
==> #<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 40ANTS-DOC/DOCUMENT::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. See Generating Documentation for some convenience functions to cover the most common cases.

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 Locative Types.

The transcript in the code block tagged with cl-transcript is automatically checked for up-to-dateness. See Transcripts.

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

;;;; 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):

;;; 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)

7 Basics

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

8 Generating Documentation

[in package 40ANTS-DOC/BUILDER]

Two convenience functions are provided to serve the common case of having an ASDF system with some readmes and a directory for the HTML documentation and the default css stylesheet.

8.1 Github Workflow

[in package 40ANTS-DOC/GITHUB]

It is generally recommended to commit generated readmes (see 40ANTS-DOC/BUILDER::UPDATE-ASDF-SYSTEM-README) so that users have something to read without reading the code and sites like github can display them.

HTML documentation can also be committed, but there is an issue with that: when linking to the sources (see MAKE-GITHUB-SOURCE-URI-FN), the commit id is in the link. This means that code changes need to be committed first, then HTML documentation regenerated and committed in a followup commit.

The second issue is that github is not very good at serving HTMLs files from the repository itself (and http://htmlpreview.github.io chokes on links to the sources).

The recommended workflow is to use gh-pages, which can be made relatively painless with the git workflow command. The gist of it is to make the doc/ directory a checkout of the branch named gh-pages. A good description of this process is http://sangsoonam.github.io/2019/02/08/using-git-worktree-to-deploy-github-pages.html. Two commits needed still, but it is somewhat less painful.

This way the HTML documentation will be available at http://<username>.github.io/<repo-name>. It is probably a good idea to add section like the Links section to allow jumping between the repository and the gh-pages site.

8.2 PAX World

[in package 40ANTS-DOC/WORLD]

MGL-PAX supported a "World" which was a registry of documents, which can generate cross-linked HTML documentation pages for all the registered documents.

But I decided to drop this feature for now, because usually build libraries documentation separately as part of their CI pipline.

If somebody want's cross referencing between different libraries, then instead of building their docs simultaneously, I'd suggest to create an index of entities, provided by libraries and to store them as a JSON file along with a library documentation.

This way it will be possible to enumerate such sources of cross references as usual URLs.

Such feature is not implemented in the 40ANTS-DOC system yet, but probably it will be useful for libraries built around the Weblocks. If you want to help and implement the feature, please, let me know.

9 Markdown Support

[in package 40ANTS-DOC/MARKDOWN]

The Markdown in docstrings is processed with the 3BMD library.

9.1 Indentation

Docstrings can be indented in any of the usual styles. 40ANTS-DOC normalizes indentation by converting:

(defun foo ()
  "This is

indented differently")

to

(defun foo ()
  "This is

indented differently")

See 40ANTS-DOC/DOCUMENT::DOCUMENT-OBJECT for the details.

9.2 Syntax highlighting

For syntax highlighting, github's 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 src/style.css from 40ANTS-DOC and you are set. The language tag, elisp in this example, is optional and defaults to common-lisp.

See the documentation of 3BMD and colorize for the details.

9.3 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 a pain. Pythonic String Reader can help with that.

10 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.

11 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.

12 Extension API

12.1 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 40ANTS-DOC/REFERENCE::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 40ANTS-DOC/LOCATIVES/BASE::LOCATE-AND-COLLECT-REACHABLE-OBJECTS, 40ANTS-DOC/LOCATIVES/BASE::LOCATE-AND-DOCUMENT and 40ANTS-DOC/LOCATIVES/BASE::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.

12.2 Adding New Object Types

One may wish to make the 40ANTS-DOC/DOCUMENT::DOCUMENT function and M-. navigation work with new object types. Extending 40ANTS-DOC/DOCUMENT::DOCUMENT can be done by defining a 40ANTS-DOC/DOCUMENT::DOCUMENT-OBJECT method. To allow these objects to be referenced from DEFSECTION, a 40ANTS-DOC/LOCATIVES/BASE::LOCATE-OBJECT method is to be defined. Finally, for M-. 40ANTS-DOC/SOURCE-API::FIND-SOURCE can be specialized. Finally, 40ANTS-DOC::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:

(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))
  (40ants-doc/reference::make-reference (asdf::primary-system-name system) 'asdf:system))

(defmethod document-object ((system asdf:system) stream)
  (40ants-doc/builder/heading::with-heading (stream system
                                             (format nil "~A ASDF System Details"
                                                     (string-upcase
                                                      (asdf::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))
                   ((:source-control)
                    (format stream "- ~A: [~A](~A)"
                            name (first value) (second 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 :type :link)
      (foo "Source control" 'asdf/system:system-source-control
           :type :source-control)
      (terpri stream))))

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

12.3 Reference Based Extensions

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

(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))
  (40ants-doc/reference::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
    (40ants-doc/builder/bullet::locate-and-print-bullet locative-type locative-args symbol stream)
    (write-char #\Space stream)
    (multiple-value-bind (value unboundp) (40ants-doc/utils::symbol-global-value symbol)
      (40ants-doc/render/args::print-arglist (prin1-to-string (cond (initformp initform)
                                                                    (unboundp "-unbound-")
                                                                    (t value)))
                     stream))
    (40ants-doc/builder/bullet::print-end-bullet stream)
    (with-dislocated-symbols ((list symbol))
      (40ants-doc/render/print::maybe-print-docstring symbol locative-type stream))))

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

We have covered the basic building blocks of reference based extensions. Now let's see how the obscure 40ANTS-DOC/LOCATIVES/DEFINERS::DEFINE-SYMBOL-LOCATIVE-TYPE and 40ANTS-DOC/LOCATIVES/DEFINE-DEFINER::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.

12.4 Sections

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

13 Transcripts

[in package 40ANTS-DOC/TRANSCRIBE]

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:

(+ 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)

13.1 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 40ants-doc-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 40ANTS-DOC-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 40ants-doc-transcribe will emit commented markup:

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

C-u 0 40ants-doc-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 40ants-doc:*SYNTAXES*. Without a prefix argument 40ants-doc-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 elisp/transcribe.el):

;;; 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)))

13.2 Transcript API

14 TODO


[generated by 40ANTS-DOC]

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

2 Systems

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


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

2.1 40ants-doc

Author

Alexander Artemenko

Contact

svetlyak.40wt@gmail.com

Home Page

http://40ants.com/doc

Source Control

(:git "https://github.com/40ants/doc")

Bug Tracker

https://github.com/40ants/doc/issues

License

MIT

Description

Documentation generator, based on MGL-PAX. Allows to put documentation inside lisp files and cross-reference between different entities.

Version

0.1.0

Dependencies
Source

40ants-doc.asd (file)


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

2.2 40ants-doc/restart

Author

Alexander Artemenko

Contact

svetlyak.40wt@gmail.com

Home Page

http://40ants.com/doc

Source Control

(:git "https://github.com/40ants/doc")

Bug Tracker

https://github.com/40ants/doc/issues

License

MIT

Dependencies
Source

40ants-doc.asd (file)

Component

file-type.lisp (file)


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

2.3 40ants-doc/locatives/define-definer

Author

Alexander Artemenko

Contact

svetlyak.40wt@gmail.com

Home Page

http://40ants.com/doc

Source Control

(:git "https://github.com/40ants/doc")

Bug Tracker

https://github.com/40ants/doc/issues

License

MIT

Dependency

40ants-doc/locatives/base (system)

Source

40ants-doc.asd (file)

Component

file-type.lisp (file)


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

2.4 40ants-doc/glossary

Author

Alexander Artemenko

Contact

svetlyak.40wt@gmail.com

Home Page

http://40ants.com/doc

Source Control

(:git "https://github.com/40ants/doc")

Bug Tracker

https://github.com/40ants/doc/issues

License

MIT

Dependency

40ants-doc/core (system)

Source

40ants-doc.asd (file)

Component

file-type.lisp (file)


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

2.5 40ants-doc/core

Author

Alexander Artemenko

Contact

svetlyak.40wt@gmail.com

Home Page

http://40ants.com/doc

Source Control

(:git "https://github.com/40ants/doc")

Bug Tracker

https://github.com/40ants/doc/issues

License

MIT

Dependencies
Source

40ants-doc.asd (file)

Component

file-type.lisp (file)


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

2.6 40ants-doc/reference

Author

Alexander Artemenko

Contact

svetlyak.40wt@gmail.com

Home Page

http://40ants.com/doc

Source Control

(:git "https://github.com/40ants/doc")

Bug Tracker

https://github.com/40ants/doc/issues

License

MIT

Dependencies
Source

40ants-doc.asd (file)

Component

file-type.lisp (file)


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

2.7 40ants-doc/reference-api

Author

Alexander Artemenko

Contact

svetlyak.40wt@gmail.com

Home Page

http://40ants.com/doc

Source Control

(:git "https://github.com/40ants/doc")

Bug Tracker

https://github.com/40ants/doc/issues

License

MIT

Source

40ants-doc.asd (file)

Component

file-type.lisp (file)


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

2.8 40ants-doc/document

Author

Alexander Artemenko

Contact

svetlyak.40wt@gmail.com

Home Page

http://40ants.com/doc

Source Control

(:git "https://github.com/40ants/doc")

Bug Tracker

https://github.com/40ants/doc/issues

License

MIT

Dependencies
Source

40ants-doc.asd (file)

Component

file-type.lisp (file)


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

2.9 40ants-doc/locatives/dislocated

Author

Alexander Artemenko

Contact

svetlyak.40wt@gmail.com

Home Page

http://40ants.com/doc

Source Control

(:git "https://github.com/40ants/doc")

Bug Tracker

https://github.com/40ants/doc/issues

License

MIT

Dependencies
Source

40ants-doc.asd (file)

Component

file-type.lisp (file)


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

2.10 40ants-doc/locatives/base

Author

Alexander Artemenko

Contact

svetlyak.40wt@gmail.com

Home Page

http://40ants.com/doc

Source Control

(:git "https://github.com/40ants/doc")

Bug Tracker

https://github.com/40ants/doc/issues

License

MIT

Dependencies
Source

40ants-doc.asd (file)

Component

file-type.lisp (file)


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

2.11 40ants-doc/source-api

Author

Alexander Artemenko

Contact

svetlyak.40wt@gmail.com

Home Page

http://40ants.com/doc

Source Control

(:git "https://github.com/40ants/doc")

Bug Tracker

https://github.com/40ants/doc/issues

License

MIT

Dependencies
Source

40ants-doc.asd (file)

Component

file-type.lisp (file)


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

2.12 40ants-doc/locatives

Author

Alexander Artemenko

Contact

svetlyak.40wt@gmail.com

Home Page

http://40ants.com/doc

Source Control

(:git "https://github.com/40ants/doc")

Bug Tracker

https://github.com/40ants/doc/issues

License

MIT

Dependency

asdf

Source

40ants-doc.asd (file)

Component

file-type.lisp (file)


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

3 Files

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


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

3.1 Lisp


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

3.1.1 40ants-doc.asd

Location

/home/quickref/quicklisp/dists/quicklisp/software/doc-20210630-git/40ants-doc.asd

Systems

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

3.1.2 40ants-doc/restart/file-type.lisp

Parent

40ants-doc/restart (system)

Location

restart.lisp

Packages

40ants-doc/restart

Internal Definitions

define-restart (macro)


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

3.1.3 40ants-doc/locatives/define-definer/file-type.lisp

Parent

40ants-doc/locatives/define-definer (system)

Location

locatives/define-definer.lisp

Packages

40ants-doc/locatives/define-definer

Internal Definitions

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

3.1.4 40ants-doc/glossary/file-type.lisp

Parent

40ants-doc/glossary (system)

Location

glossary.lisp

Packages

40ants-doc/glossary

Internal Definitions

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

3.1.5 40ants-doc/core/file-type.lisp

Parent

40ants-doc/core (system)

Location

core.lisp

Packages

40ants-doc

Exported Definitions
Internal Definitions

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

3.1.6 40ants-doc/reference/file-type.lisp

Parent

40ants-doc/reference (system)

Location

reference.lisp

Packages

40ants-doc/reference

Internal Definitions

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

3.1.7 40ants-doc/reference-api/file-type.lisp

Parent

40ants-doc/reference-api (system)

Location

reference-api.lisp

Packages

40ants-doc/reference-api

Internal Definitions

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

3.1.8 40ants-doc/document/file-type.lisp

Parent

40ants-doc/document (system)

Location

document.lisp

Packages

40ants-doc/document

Internal Definitions

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

3.1.9 40ants-doc/locatives/dislocated/file-type.lisp

Parent

40ants-doc/locatives/dislocated (system)

Location

locatives/dislocated.lisp

Packages

40ants-doc/locatives/dislocated

Internal Definitions

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

3.1.10 40ants-doc/locatives/base/file-type.lisp

Parent

40ants-doc/locatives/base (system)

Location

locatives/base.lisp

Packages

40ants-doc/locatives/base

Internal Definitions

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

3.1.11 40ants-doc/source-api/file-type.lisp

Parent

40ants-doc/source-api (system)

Location

source-api.lisp

Packages

40ants-doc/source-api

Internal Definitions

find-source (generic function)


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

3.1.12 40ants-doc/locatives/file-type.lisp

Parent

40ants-doc/locatives (system)

Location

locatives.lisp

Packages

40ants-doc/locatives


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

4 Packages

Packages are listed by definition order.


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

4.1 40ants-doc/restart

Source

file-type.lisp (file)

Use List

common-lisp

Internal Definitions

define-restart (macro)


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

4.2 40ants-doc/locatives/define-definer

Source

file-type.lisp (file)

Use List

common-lisp

Internal Definitions

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

4.3 40ants-doc/glossary

Source

file-type.lisp (file)

Use List

common-lisp

Internal Definitions

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

4.4 40ants-doc

See 40ants-doc:@index.

Source

file-type.lisp (file)

Nickname

40ants-doc/core

Use List

common-lisp

Exported Definitions
Internal Definitions

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

4.5 40ants-doc/reference

Source

file-type.lisp (file)

Use List

common-lisp

Internal Definitions

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

4.6 40ants-doc/reference-api

Source

file-type.lisp (file)

Use List

common-lisp

Internal Definitions

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

4.7 40ants-doc/document

Source

file-type.lisp (file)

Use List

common-lisp

Internal Definitions

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

4.8 40ants-doc/locatives/dislocated

Source

file-type.lisp (file)

Use List

common-lisp


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

4.9 40ants-doc/locatives/base

Source

file-type.lisp (file)

Use List

common-lisp

Internal Definitions

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

4.10 40ants-doc/source-api

Source

file-type.lisp (file)

Use List

common-lisp

Internal Definitions

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

4.11 40ants-doc/locatives

This package holds all symbols denoting 40ANTS-DOC locatives.

It serves for a forward declaration of supported locatives.
To build documentation you’ll need to load the 40ANTS-DOC-FULL system which includes methods supporting these locatives.

Source

file-type.lisp (file)

Use List

common-lisp


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

5 Definitions

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


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

5.1 Exported definitions


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

5.1.1 Macros

Macro: defsection NAME (&key PACKAGE-SYMBOL READTABLE-SYMBOL EXPORT TITLE LINK-TITLE-TO DISCARD-DOCUMENTATION-P IGNORE-WORDS) &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 ‘40ANTS-DOC/DOC::@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 40ANTS-DOC/DOC:@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 40ANTS-DOC/REFERENCE::RESOLVE in the 40ANTS-DOC/DOC:@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.

The idea with confounding documentation and exporting is to force documentation of all exported symbols. :EXPORT argument will cause [package variance](http://www.sbcl.org/manual/#Package-Variance)
error on SBCL. To prevent it, use UIOP:DEFINE-PACKAGE instead
of CL:DEFPACKAGE.

:TITLE is a non-marked-up string 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
‘(OBJECT 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.

:IGNORE-WORDS allows to pass a list of string which will not cause warnings. Usually these as uppercased words which are not symbols
in the current package, like SLIME, LISP, etc.

Package

40ants-doc

Source

file-type.lisp (file)


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

5.1.2 Generic functions

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

40ants-doc

Source

file-type.lisp (file)

Methods
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: section-entries OBJECT
Package

40ants-doc

Methods
Method: section-entries (SECTION section)

A list of strings and 40ANTS-DOC/REFERENCE::REFERENCE objects in the order they occurred in DEFSECTION.

Source

file-type.lisp (file)

Package

40ants-doc

Methods

A 40ANTS-DOC/REFERENCE::REFERENCE or NIL. Used in generated documentation.

Source

file-type.lisp (file)

Generic Function: section-name OBJECT
Package

40ants-doc

Methods
Method: section-name (SECTION section)

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

Source

file-type.lisp (file)

Generic Function: section-package OBJECT
Package

40ants-doc

Methods
Method: section-package (SECTION section)

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

Source

file-type.lisp (file)

Generic Function: section-readtable OBJECT
Package

40ants-doc

Methods
Method: section-readtable (SECTION section)

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

Source

file-type.lisp (file)

Generic Function: section-title OBJECT
Package

40ants-doc

Methods
Method: section-title (SECTION section)

STRING or NIL. Used in generated documentation.

Source

file-type.lisp (file)


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

5.1.3 Classes

Class: section ()

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

Package

40ants-doc

Source

file-type.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

STRING or NIL. Used in generated documentation.

Initargs

:title

Readers

section-title (generic function)

A 40ANTS-DOC/REFERENCE::REFERENCE or NIL. Used in generated documentation.

Initargs

:link-title-to

Readers

section-link-title-to (generic function)

Slot: entries

A list of strings and 40ANTS-DOC/REFERENCE::REFERENCE objects in the order they occurred in DEFSECTION.

Initargs

:entries

Readers

section-entries (generic function)

Slot: ignore-words

A list of strings to not warn about.

Initargs

:ignore-words

Readers

section-ignore-words (generic function)


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

5.2 Internal definitions


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

5.2.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

40ants-doc

Source

file-type.lisp (file)

Special Variable: *reference-being-documented*
Package

40ants-doc/reference

Source

file-type.lisp (file)

Special Variable: *references*
Package

40ants-doc/reference

Source

file-type.lisp (file)


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

5.2.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 40ANTS-DOC/LOCATIVES/DEFINERS::DEFINE-SYMBOL-LOCATIVE-TYPE.

Package

40ants-doc/locatives/define-definer

Source

file-type.lisp (file)

Macro: define-glossary-term NAME (&key TITLE DISCARD-DOCUMENTATION-P) DOCSTRING

Define a global variable with NAME and set it to a glossary term
object. A glossary term is just a symbol to hang a docstring on. It
is a bit like a 40ANTS-DOC::SECTION in that, when linked to, its TITLE will be the link text instead of the name of the symbol. Unlike sections
though, glossary terms are not rendered with headings, but in the
more lightweight bullet + locative + name/title style.

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

Package

40ants-doc/glossary

Source

file-type.lisp (file)

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

Declare LOCATIVE-TYPE as a 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

40ants-doc/locatives/base

Source

file-type.lisp (file)

Macro: define-restart SYMBOL LAMBDA-LIST &body DOCSTRING

A definer macro to hang the documentation of a restart on a
symbol.

“‘
(define-restart my-ignore-error ()
"Available when MY-ERROR is signalled, MY-IGNORE-ERROR unsafely continues.") “‘

Note that while there is a CL:RESTART class, there is no
corresponding source location or docstring like for CONDITIONs.

Package

40ants-doc/restart

Source

file-type.lisp (file)


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

5.2.3 Functions

Function: ensure-list LIST

If LIST is a list, it is returned. Otherwise returns the list designated by LIST.

Package

40ants-doc

Source

file-type.lisp (file)

Function: entry-to-reference ENTRY
Package

40ants-doc

Source

file-type.lisp (file)

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

40ants-doc/locatives/define-definer

Source

file-type.lisp (file)

Function: export-some-symbols NAME ENTRIES PACKAGE
Package

40ants-doc

Source

file-type.lisp (file)

Function: filter-asdf-system-references REFS
Package

40ants-doc/reference

Source

file-type.lisp (file)

Function: locate OBJECT LOCATIVE &key ERRORP

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

Package

40ants-doc/locatives/base

Source

file-type.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

40ants-doc/locatives/base

Source

file-type.lisp (file)

Function: locative-args LOCATIVE

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

Package

40ants-doc/locatives/base

Source

file-type.lisp (file)

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

40ants-doc

Source

file-type.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

40ants-doc/locatives/base

Source

file-type.lisp (file)

Function: make-reference OBJECT LOCATIVE
Package

40ants-doc/reference

Source

file-type.lisp (file)

Function: reachable-canonical-references OBJECTS
Package

40ants-doc/reference

Source

file-type.lisp (file)

Function: reference-locative-type REFERENCE
Package

40ants-doc/reference

Source

file-type.lisp (file)

Function: reference-to-anchor REFERENCE
Package

40ants-doc/reference

Source

file-type.lisp (file)

Function: reference= REFERENCE-1 REFERENCE-2
Package

40ants-doc/reference

Source

file-type.lisp (file)

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

40ants-doc/reference

Source

file-type.lisp (file)

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

40ants-doc/reference

Source

file-type.lisp (file)

Function: resolve REFERENCE &key ERRORP

A convenience function to 40ANTS-DOC/LOCATIVES/BASE::LOCATE REFERENCE’s object with its locative.

Package

40ants-doc/reference

Source

file-type.lisp (file)

Function: resolve-dislocated REFS
Package

40ants-doc/reference

Source

file-type.lisp (file)

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

40ants-doc/reference

Source

file-type.lisp (file)

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

40ants-doc

Source

file-type.lisp (file)

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

40ants-doc/locatives/base

Source

file-type.lisp (file)

Function: transform-entries ENTRIES
Package

40ants-doc

Source

file-type.lisp (file)

Package

40ants-doc

Source

file-type.lisp (file)

Function: transform-locative-symbols ENTRIES &aux LOCATIVES-PACKAGE
Package

40ants-doc

Source

file-type.lisp (file)


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

5.2.4 Generic functions

Generic Function: canonical-reference OBJECT

Return a 40ANTS-DOC/REFERENCE::REFERENCE that resolves to OBJECT.

Package

40ants-doc/reference-api

Source

file-type.lisp (file)

Methods
Method: canonical-reference (REFERENCE reference)
Source

file-type.lisp (file)

Generic Function: collect-reachable-objects OBJECT

Return a list of objects representing all things
that would be documented in a (40ANTS-DOC/DOCUMENT::DOCUMENT OBJECT) call. For sections this is simply the union of references reachable from references in 40ANTS-DOC::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

40ants-doc/reference-api

Source

file-type.lisp (file)

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

If REFERENCE can be resolved to a non-reference, call
COLLECT-REACHABLE-OBJECTS with it, else call 40ANTS-DOC/LOCATIVES/BASE::LOCATE-AND-COLLECT-REACHABLE-OBJECTS on the object, locative-type, locative-args of REFERENCE

Source

file-type.lisp (file)

Method: collect-reachable-objects OBJECT

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

Source

file-type.lisp (file)

Generic 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 @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 40ANTS-DOC/REFERENCE::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 [40ANTS-DOC: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 40ANTS-DOC/DOC:@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.

When documentation for an object is generated, the first matching
page spec is used, where the object matches the page spec if it is
contained in one of its :OBJECTS in the sense of 40ANTS-DOC/REFERENCE-API::COLLECT-REACHABLE-OBJECTS.

: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, 40ANTS-DOC/REFERENCE::REFERENCE argument. If it returns a value other than NIL, then it must be a
string representing an URI. If FORMAT is :HTML and 40ANTS-DOC/BUILDER/VARS::*DOCUMENT-MARK-UP-SIGNATURES* is true, then the locative as displayed in the signature will be a link to this uri. See 40ANTS-DOC/GITHUB::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-EXTENSION-API 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)
;; Catch the reference that were not reachable from the above. It
;; is important for this page spec to be last.
(: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

40ants-doc/document

Source

file-type.lisp (file)

Generic Function: document-object OBJECT STREAM
Package

40ants-doc/document

Source

file-type.lisp (file)

Methods
Method: document-object OBJECT STREAM
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 40ANTS-DOC/SWANK::LOCATE-DEFINITION-FOR-EMACS which lies behind the ‘M-.‘ extension (see 40ANTS-DOC/DOC:@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

40ants-doc/source-api

Source

file-type.lisp (file)

Methods
Method: find-source (REFERENCE reference)

If REFERENCE can be resolved to a non-reference, call 40ANTS-DOC/SOURCE-API::FIND-SOURCE with it, else call 40ANTS-DOC/LOCATIVES/BASE::LOCATE-AND-FIND-SOURCE on the object, locative-type, locative-args of REFERENCE.

Source

file-type.lisp (file)

Generic Function: format-reference OBJ NAME REF LINK
Package

40ants-doc/reference-api

Source

file-type.lisp (file)

Generic Function: glossary-term-docstring OBJECT
Package

40ants-doc/glossary

Methods
Method: glossary-term-docstring (GLOSSARY-TERM glossary-term)

automatically generated reader method

Source

file-type.lisp (file)

Generic Function: glossary-term-name OBJECT
Package

40ants-doc/glossary

Methods
Method: glossary-term-name (GLOSSARY-TERM glossary-term)

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

Source

file-type.lisp (file)

Generic Function: glossary-term-title OBJECT
Package

40ants-doc/glossary

Methods
Method: glossary-term-title (GLOSSARY-TERM glossary-term)

Used in generated documentation.

Source

file-type.lisp (file)

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

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

Package

40ants-doc/locatives/base

Source

file-type.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 40ANTS-DOC/DOCUMENT::DOCUMENT-OBJECT on 40ANTS-DOC/REFERENCE::REFERENCE objects, this function has essentially the same purpose as 40ANTS-DOC/DOCUMENT::DOCUMENT-OBJECT but it has different arguments to allow specializing on
LOCATIVE-TYPE.

Package

40ants-doc/locatives/base

Source

file-type.lisp (file)

Methods
Method: locate-and-document OBJECT LOCATIVE-TYPE LOCATIVE-ARGS STREAM around
Source

file-type.lisp (file)

Generic Function: locate-and-find-source OBJECT LOCATIVE-TYPE LOCATIVE-ARGS

Called by 40ANTS-DOC/SOURCE-API::FIND-SOURCE on 40ANTS-DOC/REFERENCE::REFERENCE objects, this
function has essentially the same purpose as 40ANTS-DOC/SOURCE-API::FIND-SOURCE generic-function but it has different arguments to allow specializing on LOCATIVE-TYPE.

Package

40ants-doc/locatives/base

Source

file-type.lisp (file)

Methods
Method: locate-and-find-source OBJECT LOCATIVE-TYPE LOCATIVE-ARGS

This default implementation simply calls 40ANTS-DOC/SOURCE-API::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

40ants-doc/locatives/base

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

file-type.lisp (file)

Generic Function: locate-error-message CONDITION
Package

40ants-doc/locatives/base

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

file-type.lisp (file)

Generic Function: locate-error-object CONDITION
Package

40ants-doc/locatives/base

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

file-type.lisp (file)

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

Return the object, to which OBJECT and the locative
refer. 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 the 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 40ANTS-DOC/REFERENCE::REFERENCE is returned then it must be canonical in the sense that calling 40ANTS-DOC/REFERENCE-API::CANONICAL-REFERENCE on it will return the same reference. For extension only, don’t call this directly.

Package

40ants-doc/locatives/base

Source

file-type.lisp (file)

Methods
Method: locate-object SYMBOL (LOCATIVE-TYPE (eql dislocated)) LOCATIVE-ARGS
Source

file-type.lisp (file)

Generic Function: locative-lambda-list SYMBOL
Package

40ants-doc/locatives/base

Source

file-type.lisp (file)

Methods
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 40ANTS-DOC/LINK::*DOCUMENT-LINK-CODE*) its definition. However,

[‘FOO‘][dislocated]

will not be. On a dislocated locative 40ANTS-DOC/LOCATIVES/BASE::LOCATE always fails with a LOCATE-ERROR condition.

Source

file-type.lisp (file)

Generic Function: reference-locative OBJECT
Package

40ants-doc/reference

Methods
Method: reference-locative (REFERENCE reference)

automatically generated reader method

Source

file-type.lisp (file)

Generic Function: reference-object OBJECT
Package

40ants-doc/reference

Methods
Method: reference-object (REFERENCE reference)

automatically generated reader method

Source

file-type.lisp (file)

Generic Function: section-ignore-words OBJECT
Package

40ants-doc

Methods
Method: section-ignore-words (SECTION section)

A list of strings to not warn about.

Source

file-type.lisp (file)

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

40ants-doc/locatives/base

Source

file-type.lisp (file)


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

5.2.5 Conditions

Condition: locate-error ()

Signaled by LOCATE when the lookup fails and ERRORP is true.

Package

40ants-doc/locatives/base

Source

file-type.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)


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

5.2.6 Classes

Class: glossary-term ()
Package

40ants-doc/glossary

Source

file-type.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: name

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

Initargs

:name

Readers

glossary-term-name (generic function)

Slot: title

Used in generated documentation.

Initargs

:title

Readers

glossary-term-title (generic function)

Slot: docstring
Initargs

:docstring

Readers

glossary-term-docstring (generic function)

Class: reference ()

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

Package

40ants-doc/reference

Source

file-type.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)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   4  
F   L  
Index Entry  Section

4
40ants-doc.asd: The 40ants-doc․asd file
40ants-doc/core/file-type.lisp: The 40ants-doc/core/file-type․lisp file
40ants-doc/document/file-type.lisp: The 40ants-doc/document/file-type․lisp file
40ants-doc/glossary/file-type.lisp: The 40ants-doc/glossary/file-type․lisp file
40ants-doc/locatives/base/file-type.lisp: The 40ants-doc/locatives/base/file-type․lisp file
40ants-doc/locatives/define-definer/file-type.lisp: The 40ants-doc/locatives/define-definer/file-type․lisp file
40ants-doc/locatives/dislocated/file-type.lisp: The 40ants-doc/locatives/dislocated/file-type․lisp file
40ants-doc/locatives/file-type.lisp: The 40ants-doc/locatives/file-type․lisp file
40ants-doc/reference-api/file-type.lisp: The 40ants-doc/reference-api/file-type․lisp file
40ants-doc/reference/file-type.lisp: The 40ants-doc/reference/file-type․lisp file
40ants-doc/restart/file-type.lisp: The 40ants-doc/restart/file-type․lisp file
40ants-doc/source-api/file-type.lisp: The 40ants-doc/source-api/file-type․lisp file

F
File, Lisp, 40ants-doc.asd: The 40ants-doc․asd file
File, Lisp, 40ants-doc/core/file-type.lisp: The 40ants-doc/core/file-type․lisp file
File, Lisp, 40ants-doc/document/file-type.lisp: The 40ants-doc/document/file-type․lisp file
File, Lisp, 40ants-doc/glossary/file-type.lisp: The 40ants-doc/glossary/file-type․lisp file
File, Lisp, 40ants-doc/locatives/base/file-type.lisp: The 40ants-doc/locatives/base/file-type․lisp file
File, Lisp, 40ants-doc/locatives/define-definer/file-type.lisp: The 40ants-doc/locatives/define-definer/file-type․lisp file
File, Lisp, 40ants-doc/locatives/dislocated/file-type.lisp: The 40ants-doc/locatives/dislocated/file-type․lisp file
File, Lisp, 40ants-doc/locatives/file-type.lisp: The 40ants-doc/locatives/file-type․lisp file
File, Lisp, 40ants-doc/reference-api/file-type.lisp: The 40ants-doc/reference-api/file-type․lisp file
File, Lisp, 40ants-doc/reference/file-type.lisp: The 40ants-doc/reference/file-type․lisp file
File, Lisp, 40ants-doc/restart/file-type.lisp: The 40ants-doc/restart/file-type․lisp file
File, Lisp, 40ants-doc/source-api/file-type.lisp: The 40ants-doc/source-api/file-type․lisp file

L
Lisp File, 40ants-doc.asd: The 40ants-doc․asd file
Lisp File, 40ants-doc/core/file-type.lisp: The 40ants-doc/core/file-type․lisp file
Lisp File, 40ants-doc/document/file-type.lisp: The 40ants-doc/document/file-type․lisp file
Lisp File, 40ants-doc/glossary/file-type.lisp: The 40ants-doc/glossary/file-type․lisp file
Lisp File, 40ants-doc/locatives/base/file-type.lisp: The 40ants-doc/locatives/base/file-type․lisp file
Lisp File, 40ants-doc/locatives/define-definer/file-type.lisp: The 40ants-doc/locatives/define-definer/file-type․lisp file
Lisp File, 40ants-doc/locatives/dislocated/file-type.lisp: The 40ants-doc/locatives/dislocated/file-type․lisp file
Lisp File, 40ants-doc/locatives/file-type.lisp: The 40ants-doc/locatives/file-type․lisp file
Lisp File, 40ants-doc/reference-api/file-type.lisp: The 40ants-doc/reference-api/file-type․lisp file
Lisp File, 40ants-doc/reference/file-type.lisp: The 40ants-doc/reference/file-type․lisp file
Lisp File, 40ants-doc/restart/file-type.lisp: The 40ants-doc/restart/file-type․lisp file
Lisp File, 40ants-doc/source-api/file-type.lisp: The 40ants-doc/source-api/file-type․lisp file

Jump to:   4  
F   L  

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

A.2 Functions

Jump to:   C   D   E   F   G   L   M   R   S   T  
Index Entry  Section

C
canonical-reference: Internal generic functions
canonical-reference: Internal generic functions
collect-reachable-objects: Internal generic functions
collect-reachable-objects: Internal generic functions
collect-reachable-objects: Internal generic functions

D
define-definer-for-symbol-locative-type: Internal macros
define-glossary-term: Internal macros
define-locative-type: Internal macros
define-restart: Internal macros
defsection: Exported macros
document: Internal generic functions
document-object: Internal generic functions
document-object: Internal generic functions

E
ensure-list: Internal functions
entry-to-reference: 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

F
filter-asdf-system-references: Internal functions
find-source: Internal generic functions
find-source: Internal generic functions
format-reference: Internal generic functions
Function, ensure-list: Internal functions
Function, entry-to-reference: Internal functions
Function, expand-define-definer-for-symbol-as-locative-definer-body: Internal functions
Function, export-some-symbols: Internal functions
Function, filter-asdf-system-references: Internal functions
Function, locate: Internal functions
Function, locate-error: Internal functions
Function, locative-args: Internal functions
Function, locative-equal: Internal functions
Function, locative-type: Internal functions
Function, make-reference: Internal functions
Function, reachable-canonical-references: Internal functions
Function, reference-locative-type: Internal functions
Function, reference-to-anchor: Internal functions
Function, reference=: Internal functions
Function, references-for-symbol: Internal functions
Function, references-for-the-same-symbol-p: Internal functions
Function, resolve: Internal functions
Function, resolve-dislocated: Internal functions
Function, resolve-generic-function-and-methods: Internal functions
Function, symbol-accessible-in-package-p: Internal functions
Function, symbol-lambda-list-method: Internal functions
Function, transform-entries: Internal functions
Function, transform-link-title-to: Internal functions
Function, transform-locative-symbols: Internal functions

G
Generic Function, canonical-reference: Internal generic functions
Generic Function, collect-reachable-objects: Internal generic functions
Generic Function, document: Internal generic functions
Generic Function, document-object: Internal generic functions
Generic Function, exportable-locative-type-p: Exported generic functions
Generic Function, find-source: Internal generic functions
Generic Function, format-reference: Internal generic functions
Generic Function, glossary-term-docstring: Internal generic functions
Generic Function, glossary-term-name: Internal generic functions
Generic Function, glossary-term-title: Internal generic functions
Generic Function, locate-and-collect-reachable-objects: Internal generic functions
Generic Function, locate-and-document: Internal generic functions
Generic Function, locate-and-find-source: Internal generic functions
Generic Function, locate-error-locative: Internal generic functions
Generic Function, locate-error-message: Internal generic functions
Generic Function, locate-error-object: Internal generic functions
Generic Function, locate-object: Internal generic functions
Generic Function, locative-lambda-list: Internal generic functions
Generic Function, reference-locative: Internal generic functions
Generic Function, reference-object: Internal generic functions
Generic Function, section-entries: Exported generic functions
Generic Function, section-ignore-words: Internal generic functions
Generic Function, section-link-title-to: 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, symbol-lambda-list: Internal generic functions
glossary-term-docstring: Internal generic functions
glossary-term-docstring: Internal generic functions
glossary-term-name: Internal generic functions
glossary-term-name: Internal generic functions
glossary-term-title: Internal generic functions
glossary-term-title: Internal generic functions

L
locate: Internal functions
locate-and-collect-reachable-objects: Internal generic functions
locate-and-collect-reachable-objects: Internal generic functions
locate-and-document: Internal generic functions
locate-and-document: Internal generic functions
locate-and-find-source: Internal generic functions
locate-and-find-source: Internal generic functions
locate-error: Internal functions
locate-error-locative: Internal generic functions
locate-error-locative: Internal generic functions
locate-error-message: Internal generic functions
locate-error-message: Internal generic functions
locate-error-object: Internal generic functions
locate-error-object: Internal generic functions
locate-object: Internal generic functions
locate-object: Internal generic functions
locative-args: Internal functions
locative-equal: Internal functions
locative-lambda-list: Internal generic functions
locative-lambda-list: Internal generic functions
locative-type: Internal functions

M
Macro, define-definer-for-symbol-locative-type: Internal macros
Macro, define-glossary-term: Internal macros
Macro, define-locative-type: Internal macros
Macro, define-restart: Internal macros
Macro, defsection: Exported macros
make-reference: Internal functions
Method, canonical-reference: Internal generic functions
Method, collect-reachable-objects: Internal generic functions
Method, collect-reachable-objects: Internal generic functions
Method, document-object: Internal 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, find-source: Internal generic functions
Method, glossary-term-docstring: Internal generic functions
Method, glossary-term-name: Internal generic functions
Method, glossary-term-title: Internal generic functions
Method, locate-and-collect-reachable-objects: Internal generic functions
Method, locate-and-document: Internal generic functions
Method, locate-and-find-source: Internal generic functions
Method, locate-error-locative: Internal generic functions
Method, locate-error-message: Internal generic functions
Method, locate-error-object: Internal generic functions
Method, locate-object: Internal generic functions
Method, locative-lambda-list: Internal generic functions
Method, reference-locative: Internal generic functions
Method, reference-object: Internal generic functions
Method, section-entries: Exported generic functions
Method, section-ignore-words: Internal generic functions
Method, section-link-title-to: 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

R
reachable-canonical-references: Internal functions
reference-locative: Internal generic functions
reference-locative: Internal generic functions
reference-locative-type: Internal functions
reference-object: Internal generic functions
reference-object: Internal generic functions
reference-to-anchor: Internal functions
reference=: Internal functions
references-for-symbol: Internal functions
references-for-the-same-symbol-p: Internal functions
resolve: Internal functions
resolve-dislocated: Internal functions
resolve-generic-function-and-methods: Internal functions

S
section-entries: Exported generic functions
section-entries: Exported generic functions
section-ignore-words: Internal generic functions
section-ignore-words: Internal generic functions
section-link-title-to: Exported generic functions
section-link-title-to: 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
symbol-accessible-in-package-p: Internal functions
symbol-lambda-list: Internal generic functions
symbol-lambda-list-method: Internal functions

T
transform-entries: Internal functions
transform-link-title-to: Internal functions
transform-locative-symbols: Internal functions

Jump to:   C   D   E   F   G   L   M   R   S   T  

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

A.3 Variables

Jump to:   *  
D   E   I   L   M   N   O   P   R   S   T  
Index Entry  Section

*
*discard-documentation-p*: Internal special variables
*reference-being-documented*: Internal special variables
*references*: Internal special variables

D
docstring: Internal classes

E
entries: Exported classes

I
ignore-words: Exported classes

L
link-title-to: Exported classes
locative: Internal conditions
locative: Internal classes

M
message: Internal conditions

N
name: Exported classes
name: Internal classes

O
object: Internal conditions
object: Internal classes

P
package: Exported classes

R
readtable: Exported classes

S
Slot, docstring: Internal classes
Slot, entries: Exported classes
Slot, ignore-words: Exported classes
Slot, link-title-to: Exported classes
Slot, locative: Internal conditions
Slot, locative: Internal classes
Slot, message: Internal conditions
Slot, name: Exported classes
Slot, name: Internal classes
Slot, object: Internal conditions
Slot, object: Internal classes
Slot, package: Exported classes
Slot, readtable: Exported classes
Slot, title: Exported classes
Slot, title: Internal classes
Special Variable, *discard-documentation-p*: Internal special variables
Special Variable, *reference-being-documented*: Internal special variables
Special Variable, *references*: Internal special variables

T
title: Exported classes
title: Internal classes

Jump to:   *  
D   E   I   L   M   N   O   P   R   S   T  

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

A.4 Data types

Jump to:   4  
C   G   L   P   R   S  
Index Entry  Section

4
40ants-doc: The 40ants-doc system
40ants-doc: The 40ants-doc package
40ants-doc/core: The 40ants-doc/core system
40ants-doc/document: The 40ants-doc/document system
40ants-doc/document: The 40ants-doc/document package
40ants-doc/glossary: The 40ants-doc/glossary system
40ants-doc/glossary: The 40ants-doc/glossary package
40ants-doc/locatives: The 40ants-doc/locatives system
40ants-doc/locatives: The 40ants-doc/locatives package
40ants-doc/locatives/base: The 40ants-doc/locatives/base system
40ants-doc/locatives/base: The 40ants-doc/locatives/base package
40ants-doc/locatives/define-definer: The 40ants-doc/locatives/define-definer system
40ants-doc/locatives/define-definer: The 40ants-doc/locatives/define-definer package
40ants-doc/locatives/dislocated: The 40ants-doc/locatives/dislocated system
40ants-doc/locatives/dislocated: The 40ants-doc/locatives/dislocated package
40ants-doc/reference: The 40ants-doc/reference system
40ants-doc/reference: The 40ants-doc/reference package
40ants-doc/reference-api: The 40ants-doc/reference-api system
40ants-doc/reference-api: The 40ants-doc/reference-api package
40ants-doc/restart: The 40ants-doc/restart system
40ants-doc/restart: The 40ants-doc/restart package
40ants-doc/source-api: The 40ants-doc/source-api system
40ants-doc/source-api: The 40ants-doc/source-api package

C
Class, glossary-term: Internal classes
Class, reference: Internal classes
Class, section: Exported classes
Condition, locate-error: Internal conditions

G
glossary-term: Internal classes

L
locate-error: Internal conditions

P
Package, 40ants-doc: The 40ants-doc package
Package, 40ants-doc/document: The 40ants-doc/document package
Package, 40ants-doc/glossary: The 40ants-doc/glossary package
Package, 40ants-doc/locatives: The 40ants-doc/locatives package
Package, 40ants-doc/locatives/base: The 40ants-doc/locatives/base package
Package, 40ants-doc/locatives/define-definer: The 40ants-doc/locatives/define-definer package
Package, 40ants-doc/locatives/dislocated: The 40ants-doc/locatives/dislocated package
Package, 40ants-doc/reference: The 40ants-doc/reference package
Package, 40ants-doc/reference-api: The 40ants-doc/reference-api package
Package, 40ants-doc/restart: The 40ants-doc/restart package
Package, 40ants-doc/source-api: The 40ants-doc/source-api package

R
reference: Internal classes

S
section: Exported classes
System, 40ants-doc: The 40ants-doc system
System, 40ants-doc/core: The 40ants-doc/core system
System, 40ants-doc/document: The 40ants-doc/document system
System, 40ants-doc/glossary: The 40ants-doc/glossary system
System, 40ants-doc/locatives: The 40ants-doc/locatives system
System, 40ants-doc/locatives/base: The 40ants-doc/locatives/base system
System, 40ants-doc/locatives/define-definer: The 40ants-doc/locatives/define-definer system
System, 40ants-doc/locatives/dislocated: The 40ants-doc/locatives/dislocated system
System, 40ants-doc/reference: The 40ants-doc/reference system
System, 40ants-doc/reference-api: The 40ants-doc/reference-api system
System, 40ants-doc/restart: The 40ants-doc/restart system
System, 40ants-doc/source-api: The 40ants-doc/source-api system

Jump to:   4  
C   G   L   P   R   S