This is the org-sampler Reference Manual, version 0.2.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 17:29:33 2024 GMT+0.
The main system appears first, followed by any subsystem dependency.
org-samplerExtract docstrings as Emacs org-mode files
John Maraist <lisper@maraist.org>
LLGPL 3.latest
0.2.0
iterate (system).
package.lisp (file).
sampler.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
org-sampler/org-sampler.asdorg-sampler (system).
org-sampler/sampler.lisppackage.lisp (file).
org-sampler (system).
*generate-html* (special variable).
*section-level* (special variable).
*show-package-header* (special variable).
*show-title* (special variable).
*show-usage-header* (special variable).
documentation* (function).
(setf documentation*) (function).
self-document (function).
write-package-files (function).
write-packages (function).
write-symbol-files (function).
*index-writer* (special variable).
*latex-label-suffix* (special variable).
*no-edit-message* (special variable).
*standard-doctype-alist* (special variable).
+nonstandard-doc-type+ (special variable).
set-index-usage (function).
write-index-org (function).
write-names-list (function).
write-org-file (function).
Packages are listed by definition order.
org-samplercommon-lisp.
iterate.
*generate-html* (special variable).
*section-level* (special variable).
*show-package-header* (special variable).
*show-title* (special variable).
*show-usage-header* (special variable).
documentation* (function).
(setf documentation*) (function).
self-document (function).
write-package-files (function).
write-packages (function).
write-symbol-files (function).
*index-writer* (special variable).
*latex-label-suffix* (special variable).
*no-edit-message* (special variable).
*standard-doctype-alist* (special variable).
+nonstandard-doc-type+ (special variable).
set-index-usage (function).
write-index-org (function).
write-names-list (function).
write-org-file (function).
Definitions are sorted by export status, category, package, and then by lexicographic order.
If non-nil, then an HTML file should be generated from each Org file.
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.
Whether a header line for the package should be written.
Whether an initial comment with the title should be written.
Whether a header line for the usage should be written.
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.
Applies =Org-Sampler= to itself in its own directory.
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.
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.
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.
Should be left as =t=: used to indicate which outermost function API call should invoke =write-index-org=.
If non-nil, then a LaTeX label definition will be generated for each symbol with the given suffix.
Message printed at the top of
Association list from symbols naming a =doc-type= to the string used to disambiguate the generated files when needed.
Hash table for non-standard documentation types.
The =index-acc= hash table builds up path information for an index.
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.
| Jump to: | (
D F S W |
|---|
| Jump to: | (
D F S W |
|---|
| Jump to: | *
+
S |
|---|
| Jump to: | *
+
S |
|---|
| Jump to: | F O P S |
|---|
| Jump to: | F O P S |
|---|