The org-sampler Reference Manual

Table of Contents

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

The org-sampler Reference Manual

This is the org-sampler Reference Manual, version 0.2.0, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 12:21:19 2018 GMT+0.


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

1 Introduction

Use Org-mode in your Common Lisp docstrings

To more easily keep your documentation synchronized with the source code, write your Common Lisp documentation strings in Org-mode format and use this system to extract each symbol usage into its own separate Org file. Then your user manual and other documentation can just include these sampled extracts. Updates to the manual can be automated from updates to the docstrings - which we're more likely to actually remember to do.

Requires iterate.

Main routines

Function write-package-files

Documents a package by writing an Org file for each defined symbol.

(write-package-files PACKAGE
                     [ :all FLAG ]
                     [ :system ASDF-SYSTEM-NAME ]
                     [ :path DIR ]
                     [ :index FLAG ]
                     [ :index-acc HASH-OR-NIL ]
                     [ :show-package FLAG ]
                     [ :hoist-exported FLAG ]
                     [ :page-title STRNIG ]
                     [ :always-disambiguate FLAG ]
                     [ :section-level NUMBER-OR-NIL ]
                     [ :package-headers FLAG ]
                     [ :usage-headers FLAG ]
                     [ :show-title FLAG ] )

Function write-packages

Document several packages by making a call to write-package-files for each.

(write-packages PACKAGES
                [ :default-all FLAG ]
                [ :default-system ASDF-SYSTEM-NAME ]
                [ :default-path DIR ]
                [ :package-extension FLAG ]
                [ :extension-downcase FLAG ]
                [ :index FLAG ]
                [ :index-system ASDF-SYSTEM-NAME ]
                [ :index-acc HASH-TABLE ]
                [ :show-package FLAG ]
                [ :hoist-exported page-title FLAG ]
                [ :show-title FLAG ]
                [ :package-headers FLAG ]
                [ :usage-headers FLAG ] )

Function write-symbol-files

Writes Org-mode files (in the directory named by directory-path) documenting the uses of the given symbol.

(write-symbol-files SYMBOL DIRECTORY-PATH
  [ :index-acc HASH ] [ :always-disambiguate FLAG ] )

Nonstandard documentation targets

Function documentation*

Sometimes you may want to maintain documentation attached to non-standard targets in the source code, and pull those strings into the manual (for example, command options or available quoted forms). Some Lisp implementations make it easy to use non-standard targets to documentation; others essentially forbid it. The documentation* and (setf documentation*) functions manage the nonstandard documentation types on platforms which do not allow it.

(documentation* X DOC-TYPE)
(setf (documentation* X DOC-TYPE) DOC-STRING)

At this time, on Allegro Lisp these functions are inlined wrappers for the standard documentation functions, and on other platforms it filters out the non-standard types and stores them in the +nonstandard-doc-type+ hash.

Note that when using (setf documentation*) to install documentation strings of non-standard doc-type it is necessary to load the org-sampler ASDF system as a prerequisite of the documented system. This is in contrast to the use case of merely assembling documentation separately from loading the system, in which case there is no reason to :depends-on the Org-Sampler system.

Global switches

Variable *section-level*

If non-nil, then generated Org mode with begin with the indicated level of section header giving the name and use of the definition. If nil, no section header is generated.

Variable *show-package-header*

Whether a header line for the package should be written.

Variable *show-title*

Whether an initial comment with the title should be written.

Variable *show-usage-header*

Whether a header line for the usage should be written.

Variable *generate-html*

If non-nil, then an HTML file should be generated from each Org file.

Self-documentation

Function self-document

Applies Org-Sampler to itself in its own directory.


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

2 Systems

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


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

2.1 org-sampler

Author

John Maraist <lisper@maraist.org>

License

LLGPL 3.latest

Description

Extract docstrings as Emacs org-mode files

Version

0.2.0

Dependency

iterate

Source

org-sampler.asd (file)

Components

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 org-sampler.asd

Location

org-sampler.asd

Systems

org-sampler (system)

Packages

org-sampler-asd


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

3.1.2 org-sampler/package.lisp

Parent

org-sampler (system)

Location

package.lisp

Packages

org-sampler


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

3.1.3 org-sampler/sampler.lisp

Dependency

package.lisp (file)

Parent

org-sampler (system)

Location

sampler.lisp

Exported Definitions
Internal Definitions

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

4 Packages

Packages are listed by definition order.


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

4.1 org-sampler-asd

Source

org-sampler.asd

Use List

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

4.2 org-sampler

Source

package.lisp (file)

Use List
Exported Definitions
Internal Definitions

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 Special variables

Special Variable: *generate-html*

If non-nil, then an HTML file should be generated from each Org file.

Package

org-sampler

Source

sampler.lisp (file)

Special Variable: *section-level*

If non-nil, then generated Org mode with begin with the indicated level of section header giving the name and use of the definition. If =nil=, no section header is generated.

Package

org-sampler

Source

sampler.lisp (file)

Special Variable: *show-package-header*

Whether a header line for the package should be written.

Package

org-sampler

Source

sampler.lisp (file)

Special Variable: *show-title*

Whether an initial comment with the title should be written.

Package

org-sampler

Source

sampler.lisp (file)

Special Variable: *show-usage-header*

Whether a header line for the usage should be written.

Package

org-sampler

Source

sampler.lisp (file)


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

5.1.2 Functions

Function: documentation* X DOC-TYPE

Sometimes you may want to maintain documentation attached to
non-standard targets in the source code, and pull those strings into
the manual (for example, command options or available quoted forms).
Some Lisp implementations make it easy to use non-standard targets to =documentation=; others essentially forbid it. The =documentation*=
and =(setf documentation*)= functions manage the nonstandard documentation types on platforms which do not allow it.
#+begin_example
(documentation* X DOC-TYPE)
(setf (documentation* X DOC-TYPE) DOC-STRING)
#+end_example
At this time, on Allegro Lisp these functions are inlined wrappers for the standard =documentation= functions, and on other platforms it filters out the non-standard types and stores them in the =+nonstandard-doc-type+= hash.

Note that when using =(setf documentation*)= to install documentation strings of non-standard doc-type it is necessary to load the =org-sampler= ASDF system as a prerequisite of the documented system. This is in contrast to the use case of merely assembling documentation separately from loading the system, in which case there is no reason to =:depends-on= the Org-Sampler system.

Package

org-sampler

Source

sampler.lisp (file)

Writer

(setf documentation*) (function)

Function: (setf documentation*) DOCSTRING X DOC-TYPE
Package

org-sampler

Source

sampler.lisp (file)

Reader

documentation* (function)

Function: self-document ()

Applies =Org-Sampler= to itself in its own directory.

Package

org-sampler

Source

sampler.lisp (file)

Function: write-package-files PACKAGE &rest KEYARGS &key ALL SYSTEM PATH INDEX TYPES INDEX-ACC SHOW-PACKAGE HOIST-EXPORTED PAGE-TITLE ALWAYS-DISAMBIGUATE SECTION-LEVEL PACKAGE-HEADERS USAGE-HEADERS SHOW-TITLE LATEX-LABEL-SUFFIX

Documents a package by writing an Org file for each defined symbol. #+begin_example
(write-package-files PACKAGE
[ :all FLAG ]
[ :system ASDF-SYSTEM-NAME ]
[ :path DIR ]
[ :index FLAG ]
[ :index-acc HASH-OR-NIL ]
[ :show-package FLAG ]
[ :hoist-exported FLAG ]
[ :page-title STRNIG ]
[ :always-disambiguate FLAG ]
[ :section-level NUMBER-OR-NIL ]
[ :package-headers FLAG ]
[ :usage-headers FLAG ]
[ :show-title FLAG ] )
#+end_example
- The =package= argument should be a package specifier.
- If the =all= keyword argument is given and is non-nil, then all symbols in the package should be documented, instead of just exported symbols.
- The =path= argument gives the directory where the files should be written. This directory will be created if it does not exist.
- A relative =path= is resolved relative to the location of the ASDF file defining the given =system=.
- When this function is called by another function in this package, =index-acc= will be a hash-table used to accumulate symbol references for the index that page will create. When this function is called as an API from outside of this system, or if no index will be needed, then the argument should be left =nil=. - The =show-package=, =hoist-exported=, and =page-title= keyword arguments direct the formatting of the index page which this routine should create when it is the entry call to this package.
- If =show-package= is non-nil, then the symbol’s package name will be dsplayed on any index page.
- If =hoist-exported= in non-nil, then the list of symbols will be divided according to the package which exports each symbol, or by internal symbols of all packages.
- If non-nil, =page-title= should be a string to be used as the page name.

Package

org-sampler

Source

sampler.lisp (file)

Function: write-packages PACKAGES &rest KEYARGS &key DEFAULT-ALL DEFAULT-SYSTEM DEFAULT-PATH PACKAGE-EXTENSION EXTENSION-DOWNCASE INDEX INDEX-SYSTEM TYPES ALWAYS-DISAMBIGUATE INDEX-ACC SHOW-PACKAGE HOIST-EXPORTED PAGE-TITLE SECTION-LEVEL SHOW-TITLE PACKAGE-HEADERS USAGE-HEADERS LATEX-LABEL-SUFFIX

Document several packages by making a call to =write-package-files= for each. #+begin_example
(write-packages PACKAGES
[ :default-all FLAG ]
[ :default-system ASDF-SYSTEM-NAME ]
[ :default-path DIR ]
[ :package-extension FLAG ]
[ :extension-downcase FLAG ]
[ :index FLAG ]
[ :index-system ASDF-SYSTEM-NAME ]
[ :index-acc HASH-TABLE ]
[ :show-package FLAG ]
[ :hoist-exported page-title FLAG ]
[ :show-title FLAG ]
[ :package-headers FLAG ]
[ :usage-headers FLAG ] )
#+end_example
- The =packages= argument is a list giving a specification of the packages to be documented. Each element can be either a package designator or a list whose first element is a package designator and other elements are keyword arguments accepted by =write-package-files=. These keywords will be used for the call to =write-package-files= for that package.
- The =default-all=, =default-system=, and =default-path= arguments give the default arguments for the calls to =write-package-files=.
- If =package-extension= is non-nil (its default is =t=), then whenever a package spec does not give an explicit path, it should use a subdirectory of the default path whose name is taken from the package. If =extension-downcase= is non-nil (its default is =t=), then the package name is converted to lower-case for this extension.
- The =index-acc= is a hash-table used to accumulate symbol references for an index page, or =nil= if no index data should be saved.
- The =show-package=, =hoist-exported=, and =page-title= keyword arguments direct the formatting of the index page which this routine should create when it is the entry call to this package.
- If =show-package= is non-nil, then the symbol’s package name will be dsplayed on any index page.
- If =hoist-exported= in non-nil, then the list of symbols will be divided according to the package which exports each symbol, or by internal symbols of all packages.
- If non-nil, =page-title= should be a string to be used as the page name.

Package

org-sampler

Source

sampler.lisp (file)

Function: write-symbol-files SYMBOL DIRECTORY-PATH &key INDEX-ACC ALWAYS-DISAMBIGUATE TYPES

Writes Org-mode files (in the directory named by =directory-path=) documenting the uses of the given =symbol=.
#+begin_example
(write-symbol-files SYMBOL DIRECTORY-PATH
[ :index-acc HASH ] [ :always-disambiguate FLAG ] )
#+end_example
- The =index-acc= is a hash-table used to accumulate symbol references for an index page, or =nil= if no index data should be saved.
- This function will write a separate file for each /use/ of the symbol, disambiguating the file name where necessary with =__fn=, =__var= and so forth. If =always-disambiguate= is non-nil, then these suffixes will /always/ be added to the names of the generated files, even when a symbol has only one usage.

Package

org-sampler

Source

sampler.lisp (file)


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

5.2 Internal definitions


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

5.2.1 Special variables

Special Variable: *index-writer*

Should be left as =t=: used to indicate which outermost function API call should invoke =write-index-org=.

Package

org-sampler

Source

sampler.lisp (file)

Special Variable: *latex-label-suffix*

If non-nil, then a LaTeX label definition will be generated for each symbol with the given suffix.

Package

org-sampler

Source

sampler.lisp (file)

Special Variable: *no-edit-message*

Message printed at the top of

Package

org-sampler

Source

sampler.lisp (file)

Special Variable: *standard-doctype-alist*

Association list from symbols naming a =doc-type= to the string used to disambiguate the generated files when needed.

Package

org-sampler

Source

sampler.lisp (file)

Special Variable: +nonstandard-doc-type+

Hash table for non-standard documentation types.

Package

org-sampler

Source

sampler.lisp (file)


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

5.2.2 Functions

Function: set-index-usage INDEX-ACC SYMBOL USAGE PATH

The =index-acc= hash table builds up path information for an index.

Package

org-sampler

Source

sampler.lisp (file)

Function: write-index-org INDEX-ACC DIRECTORY-PATH INDEX-FILE-NAME &key SHOW-PACKAGE HOIST-EXPORTED TITLE

Write the accumulated indexing information to its own Org file.
- The =show-package=, =hoist-exported=, and =page-title= keyword arguments direct the formatting of the index page.
- If =show-package= is non-nil, then a symbol’s package name will be dsplayed in its list entry.
- If =hoist-exported= in non-nil, then the list of symbols will be divided according to the package which exports each symbol, or by internal symbols of all packages.
- If non-nil, =page-title= should be a string to be used as the page name.

Package

org-sampler

Source

sampler.lisp (file)

Function: write-names-list OUT NAMES SHOW-PACKAGE INDEX-ACC
Package

org-sampler

Source

sampler.lisp (file)

Function: write-org-file SYM PATH TYP
Package

org-sampler

Source

sampler.lisp (file)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   F   L   O  
Index Entry  Section

F
File, Lisp, org-sampler.asd: The org-sampler<dot>asd file
File, Lisp, org-sampler/package.lisp: The org-sampler/package<dot>lisp file
File, Lisp, org-sampler/sampler.lisp: The org-sampler/sampler<dot>lisp file

L
Lisp File, org-sampler.asd: The org-sampler<dot>asd file
Lisp File, org-sampler/package.lisp: The org-sampler/package<dot>lisp file
Lisp File, org-sampler/sampler.lisp: The org-sampler/sampler<dot>lisp file

O
org-sampler.asd: The org-sampler<dot>asd file
org-sampler/package.lisp: The org-sampler/package<dot>lisp file
org-sampler/sampler.lisp: The org-sampler/sampler<dot>lisp file

Jump to:   F   L   O  

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

A.2 Functions

Jump to:   (  
D   F   S   W  
Index Entry  Section

(
(setf documentation*): Exported functions

D
documentation*: Exported functions

F
Function, (setf documentation*): Exported functions
Function, documentation*: Exported functions
Function, self-document: Exported functions
Function, set-index-usage: Internal functions
Function, write-index-org: Internal functions
Function, write-names-list: Internal functions
Function, write-org-file: Internal functions
Function, write-package-files: Exported functions
Function, write-packages: Exported functions
Function, write-symbol-files: Exported functions

S
self-document: Exported functions
set-index-usage: Internal functions

W
write-index-org: Internal functions
write-names-list: Internal functions
write-org-file: Internal functions
write-package-files: Exported functions
write-packages: Exported functions
write-symbol-files: Exported functions

Jump to:   (  
D   F   S   W  

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

A.3 Variables

Jump to:   *   +  
S  
Index Entry  Section

*
*generate-html*: Exported special variables
*index-writer*: Internal special variables
*latex-label-suffix*: Internal special variables
*no-edit-message*: Internal special variables
*section-level*: Exported special variables
*show-package-header*: Exported special variables
*show-title*: Exported special variables
*show-usage-header*: Exported special variables
*standard-doctype-alist*: Internal special variables

+
+nonstandard-doc-type+: Internal special variables

S
Special Variable, *generate-html*: Exported special variables
Special Variable, *index-writer*: Internal special variables
Special Variable, *latex-label-suffix*: Internal special variables
Special Variable, *no-edit-message*: Internal special variables
Special Variable, *section-level*: Exported special variables
Special Variable, *show-package-header*: Exported special variables
Special Variable, *show-title*: Exported special variables
Special Variable, *show-usage-header*: Exported special variables
Special Variable, *standard-doctype-alist*: Internal special variables
Special Variable, +nonstandard-doc-type+: Internal special variables

Jump to:   *   +  
S  

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

A.4 Data types

Jump to:   O   P   S  
Index Entry  Section

O
org-sampler: The org-sampler system
org-sampler: The org-sampler package
org-sampler-asd: The org-sampler-asd package

P
Package, org-sampler: The org-sampler package
Package, org-sampler-asd: The org-sampler-asd package

S
System, org-sampler: The org-sampler system

Jump to:   O   P   S