Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the helambdap Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Thu Sep 15 04:58:30 2022 GMT+0.
Next: Systems, Previous: The helambdap Reference Manual, Up: The helambdap Reference Manual [Contents][Index]
HEΛP
====
Copyright (c) 2012-2022 Marco Antoniotti and Stefano Gandelli
See file COPYING for licensing information
DESCRIPTION
-----------
HEΛP ("HELP") is yet another CL code documentation utility, which has
been inspired by JavaDoc and doxygen.
HEΛP produces, by default, a (mostly) XHTML set of documents. The
system strives to be simple to use by making a few choices, while
maintaining a number of hooks that can be used to customize the
system, e.g., by producing a different kind of output (e.g., Texinfo).
The simplest way to get HEΛP (pun intended) is to use the function
document, as in the example below, where a few assumptions are made.
We are in the directory where the code to be documented resides. The
actual documentation will end up in the directory (using POSIX syntax
and conventions) `./docs/html/`.
~~~~
cl-prompt> (document *the-current-directory* :documentation-title "My Library")
;;; Several messages, some warnings and error messages.
;;; More messages, more warnings and error messages (these last ones ignored.).
;;; Yadda, yadda, yadda....
NIL
~~~~
As stated, the previous command will create the documentation (with an
index.htm file in the `./docs/html/` folder. Alas, note that the
`*the-current-directory*` must be obtained in an
implementation-dependent way. Note also that the default format for
the documentation is (mostly) XHTML.
The documentation thus generated is incomplete. Some HTML files are
either skeletons or are not there (and your browser may complain
accordingly). It is up to you to fill these files with appropriate
content: a prominent example is the file named introduction.htm which
appears on the first page. It usually appears blank.
INSTALLATION
------------
HEΛP is available on quicklisp.
Otherwise, installation should be simple if you have quicklisp, ASDF,
or MK-DEFSYSTEM set up. You will need also XHTMΛ and a few other
libraries. Check out the system files for the current list.
A NOTE ON FORKING
-----------------
Of course you are free to fork the project subject to the current
licensing scheme. However, before you do so, I ask you to consider
plain old "cooperation" by asking me to become a developer.
It helps keeping the entropy level at an acceptable level.
Enjoy
Marco Antoniotti 2021-03-14
Next: Modules, Previous: Introduction, Up: The helambdap Reference Manual [Contents][Index]
The main system appears first, followed by any subsystem dependency.
The HELambdaP System.
Marco Antoniotti
BSD like
Next: Files, Previous: Systems, Up: The helambdap Reference Manual [Contents][Index]
Modules are listed depth-first from the system components tree.
Next: helambdap/impl-dependent, Previous: Modules, Up: Modules [Contents][Index]
helambdap-pkg.lisp (file).
helambdap (system).
Next: helambdap/tools, Previous: helambdap/utilities, Up: Modules [Contents][Index]
helambdap-pkg.lisp (file).
helambdap (system).
Previous: helambdap/impl-dependent, Up: Modules [Contents][Index]
helambdap-pkg.lisp (file).
helambdap (system).
asdf-hlp-doc.lisp (file).
Next: Packages, Previous: Modules, Up: The helambdap Reference Manual [Contents][Index]
Files are sorted by type and then listed depth-first from the systems components trees.
Next: helambdap/helambdap-pkg.lisp, Previous: Lisp, Up: Lisp [Contents][Index]
helambdap (system).
Next: helambdap/helambdap-globals.lisp, Previous: helambdap/helambdap.asd, Up: Lisp [Contents][Index]
helambdap (system).
Next: helambdap/utilities/text-utilities.lisp, Previous: helambdap/helambdap-pkg.lisp, Up: Lisp [Contents][Index]
helambdap-pkg.lisp (file).
helambdap (system).
Next: helambdap/utilities/package-utilities.lisp, Previous: helambdap/helambdap-globals.lisp, Up: Lisp [Contents][Index]
utilities (module).
Next: helambdap/utilities/filename-utilities.lisp, Previous: helambdap/utilities/text-utilities.lisp, Up: Lisp [Contents][Index]
utilities (module).
Next: helambdap/utilities/functions-utilities.lisp, Previous: helambdap/utilities/package-utilities.lisp, Up: Lisp [Contents][Index]
utilities (module).
Next: helambdap/utilities/collections-utilities.lisp, Previous: helambdap/utilities/filename-utilities.lisp, Up: Lisp [Contents][Index]
utilities (module).
Next: helambdap/utilities/time-utilities.lisp, Previous: helambdap/utilities/functions-utilities.lisp, Up: Lisp [Contents][Index]
utilities (module).
collect-duplicates (function).
Next: helambdap/utilities/streams-utilities.lisp, Previous: helambdap/utilities/collections-utilities.lisp, Up: Lisp [Contents][Index]
utilities (module).
Next: helambdap/utilities/symbols-utilities.lisp, Previous: helambdap/utilities/time-utilities.lisp, Up: Lisp [Contents][Index]
utilities (module).
Next: helambdap/utilities/lambda-list-parsing.lisp, Previous: helambdap/utilities/streams-utilities.lisp, Up: Lisp [Contents][Index]
utilities (module).
Next: helambdap/utilities/debugging-utilities.lisp, Previous: helambdap/utilities/symbols-utilities.lisp, Up: Lisp [Contents][Index]
utilities (module).
Next: helambdap/setup.lisp, Previous: helambdap/utilities/lambda-list-parsing.lisp, Up: Lisp [Contents][Index]
utilities (module).
Next: helambdap/naming.lisp, Previous: helambdap/utilities/debugging-utilities.lisp, Up: Lisp [Contents][Index]
helambdap (system).
Next: helambdap/doc-bit.lisp, Previous: helambdap/setup.lisp, Up: Lisp [Contents][Index]
setup.lisp (file).
helambdap (system).
Next: helambdap/extract-doc.lisp, Previous: helambdap/naming.lisp, Up: Lisp [Contents][Index]
helambdap (system).
print-object (method).
Next: helambdap/helambdap.lisp, Previous: helambdap/doc-bit.lisp, Up: Lisp [Contents][Index]
doc-bit.lisp (file).
helambdap (system).
Next: helambdap/collect-documentation.lisp, Previous: helambdap/extract-doc.lisp, Up: Lisp [Contents][Index]
doc-bit.lisp (file).
helambdap (system).
Next: helambdap/doc-formats.lisp, Previous: helambdap/helambdap.lisp, Up: Lisp [Contents][Index]
doc-bit.lisp (file).
helambdap (system).
Next: helambdap/known-doc-formats.lisp, Previous: helambdap/collect-documentation.lisp, Up: Lisp [Contents][Index]
helambdap (system).
Next: helambdap/doc-structure.lisp, Previous: helambdap/doc-formats.lisp, Up: Lisp [Contents][Index]
doc-formats.lisp (file).
helambdap (system).
Next: helambdap/documentation-production.lisp, Previous: helambdap/known-doc-formats.lisp, Up: Lisp [Contents][Index]
helambdap (system).
Next: helambdap/xhtml-common-definitions.lisp, Previous: helambdap/doc-structure.lisp, Up: Lisp [Contents][Index]
helambdap (system).
Next: helambdap/doc-string-handling.lisp, Previous: helambdap/documentation-production.lisp, Up: Lisp [Contents][Index]
setup.lisp (file).
helambdap (system).
Next: helambdap/html-source-handling.lisp, Previous: helambdap/xhtml-common-definitions.lisp, Up: Lisp [Contents][Index]
xhtml-common-definitions.lisp (file).
helambdap (system).
Next: helambdap/xhtml-lambda-producer-protocol.lisp, Previous: helambdap/doc-string-handling.lisp, Up: Lisp [Contents][Index]
xhtml-common-definitions.lisp (file).
helambdap (system).
Next: helambdap/xhtml-lambda-producer.lisp, Previous: helambdap/html-source-handling.lisp, Up: Lisp [Contents][Index]
xhtml-common-definitions.lisp (file).
helambdap (system).
Next: helambdap/impl-dependent/sbcl.lisp, Previous: helambdap/xhtml-lambda-producer-protocol.lisp, Up: Lisp [Contents][Index]
helambdap (system).
Next: helambdap/impl-dependent/asdf-deps.lisp, Previous: helambdap/xhtml-lambda-producer.lisp, Up: Lisp [Contents][Index]
impl-dependent (module).
Next: helambdap/tools/asdf-hlp-doc.lisp, Previous: helambdap/impl-dependent/sbcl.lisp, Up: Lisp [Contents][Index]
impl-dependent (module).
Previous: helambdap/impl-dependent/asdf-deps.lisp, Up: Lisp [Contents][Index]
tools (module).
Next: Definitions, Previous: Files, Up: The helambdap Reference Manual [Contents][Index]
Packages are listed by definition order.
The HELambdaP Package.
The package containing the implementation of the ’semi-offline’ documentation system for Common Lisp.
common-lisp.
Next: Indexes, Previous: Packages, Up: The helambdap Reference Manual [Contents][Index]
Definitions are sorted by export status, category, package, and then by lexicographic order.
Next: Internals, Previous: Definitions, Up: Definitions [Contents][Index]
Next: Macros, Previous: Public Interface, Up: Public Interface [Contents][Index]
The title that will appear on the main documentation page.
Controls whether the system must produce documentation for everything.
When *EVERYTHING* is true, HELAMBDAP produces documentation for every
bit in the ’search’ path requested regardless of the values of
*ONLY-DOCUMENTED* and *ONLY-EXPORTED*.
See Also:
*ONLY-DOCUMENTED* and *ONLY-EXPORTED*.
Controls whether the system must produce documentation only for
user-documented items.
When *ONLY-DOCUMENTED* is true, then the system produces documentation
only for those items the user has actually written a documentation
string.
See Also:
*EVERYTHING* and *ONLY-EXPORTED*.
Controls whether the system must produce documentation only for
’exported’ items (i.e., symbols).
When *ONLY-EXPORTED* is true, then the system produces documentation only for those items (symbols) that are exported from their package.
See Also:
*EVERYTHING* and *ONLY-DOCUMENTED*.
If T, the default, any documentation will be superseded.
The standard ’DOCTYPE’ w3c Frameset DTD (X)HTML string.
The standard HTML5 doctype declaration.
The standard ’DOCTYPE’ w3c DTD XHTML Strict DTD (X)HTML string.
Next: Ordinary functions, Previous: Special variables, Up: Public Interface [Contents][Index]
Defines a specialized procedure to extract a doc string from a definition.
Next: Generic functions, Previous: Macros, Up: Public Interface [Contents][Index]
Clears the doc-bits data base.
Produces the documentation for something.
The function is a wrapper for BUILD-DOCUMENTATION defaulting a few
parameters, in particular the output FORMAT. The current default for
FORMAT is :HTML, and experimental :HTML5 is available and it can be
used to produce the documentation in HTML5 format.
Arguments and Values:
FOR-WHAT — what to document; can be a pathname or a ’system’.
DOCUMENTATION-TITLE — a STRING which will appear as the documentation title.
FORMAT — a SYMBOL designating the desired kind of output.
DESTINATION — a (directory) PATHANME where the documentation will be produced.
ONLY-DOCUMENTED — a BOOLEAN: whether to produce documentation only for documented items.
ONLY-EXPORTED — a BOOLEAN: whether to produce documentation only for ’exported’ items.
EVERYTHING — a BOOLEAN: whether to produce documentation for everything, no matter what.
EXCLUDE-DIRECTORIES — a LIST of directory pathnames not to be considered.
EXCLUDE-FILES — a list of FILES not to be considered.
SPECIAL-METHODS-DEFS-FILES — a list of FILES to be LOADed before running the parsers.
CLEAR-DOCUMENTATION-DB — a KEYWORD stating if and when the documentation db should be cleared.
Notes:
At the time of this writing, ASDF and MK-DEFSYSTEM are supported.
The arguments SOURCE and SUPERSEDE are, at the time of this writing,
effectively ignored.
The argument SPECIAL-METHODS-DEFS-FILES is a list of Common Lisp files
that will be loaded before running the documentation parsers; it is
assumed that these files will contain mostly
DEFINE-DOCUMENTATION-EXTRACTOR and EXTRACT-NAMED-FORM-DOCUMENTATION
definitions. The loading of these files is wrapped in an
IGNORE-ERRORS form: failure to load one of them will not completely
hamper the documentation procedure.
Returns the location of the HELambdaP ’data’ folder.
A function that prints out the value of most configuration paramenters.
Arguments and Values:
WHERE : a destination stream to be used by FORMAT.
Initializes the doc-bits data base.
Inserts a doc-bit in the doc-bits data base.
Finds the DOCUMENTATION-FORMAT given a ’user’ tag.
The result is an istance (singleton) of a DOCUMENTATION-FORMAT structure, or NIL if none is found.
Next: Standalone methods, Previous: Ordinary functions, Up: Public Interface [Contents][Index]
Produces the documentation according to a number of parameters
Builds the documentation for a ASDF system in a given FORMAT.
Builds the documentation given a pathname P in a given FORMAT.
The pathname P can either denote a file or a folder. If it is a folder
then it is recursively traversed. The documentation is produced in
the DESTINATION directory/folder, which defaults to ’docs/html’
relative to the pathname P.
See Also:
COLLECT-DOCUMENTATION.
The DOCUMENTATION Generic Function.
The DOCUMENTATION generic function shadows CL:DOCUMENTATION in order to provide a few hooks for manipulating the underlying DOC-BITS DB.
If no documentation string is found in the doc bits db, then DOCUMENTATION falls back on CL:DOCUMENTATION.
Extracts the documentation from a source WHERE-FROM.
Extracts the documentation from a form tagged with a specific kind.
This :before method takes care of ensuring that the defpackage is actually evaluated while avoing problems with package synonyms. This method may signal a continuable error, that a user may decide s/he has to handle in a particular way; the continuable error is generated when there exist a package named by one of the defpackage form nicknames.
Extracts the documentation from a ’named’ form.
A ’named’ form has the following structure: (<name> . <forms>).
This generic function is useful to add functionality in the presence
of symbols for which the package may not be present at runtime.
This function is called by the more general EXTRACT-FORM-DOCUMENTATION
method on (FORM-KIND SYMBOL). The call has the form:
(extract-named-form-documentation s (intern s "HELAMBDAP") form)
In this way it is possible to write special methods to handle "unpackaged" symbols.
Translates from a ’user’ tag to the canonical internal one.
The internal tags are symbols in the HELambdaP implementation packages
(which may, or may not be exported).
Examples:
(output-format-tag :html) ==> HLP:HTML
Produces documentation for ELEMENT according to FORMAT.
This specialized method produces the (X)HTML documentation for an ELEMENT.
Saves the doc-bits data bases to a file.
The optional argument DOC-BITS-DB defaults to the ’current’ doc bits data base.
Next: Structures, Previous: Generic functions, Up: Public Interface [Contents][Index]
asdf/action.
asdf/action.
asdf/operate.
asdf/action.
asdf/action.
asdf/action.
Next: Classes, Previous: Standalone methods, Up: Public Interface [Contents][Index]
The Doc-bits Data Base structure.
An ’opaque’ wrapper around the actual doc-bits data base.
structure-object.
hash-table
(make-hash-table :test (function equal))
This slot is read-only.
Previous: Structures, Up: Public Interface [Contents][Index]
The HELambdaP Document Op ASDF Class.
non-propagating-operation.
Previous: Public Interface, Up: Definitions [Contents][Index]
Next: Symbol macros, Previous: Internals, Up: Internals [Contents][Index]
The variable holding the ’current’ package.
Processing an IN-PACKAGE form sets this variable (if the package is known) subsequent READs by the documentation extraction machinery are done with *PACKAGE* bound to *CURRENT-PACKAGE*.
The variable containing the default documentation structure.
The Data Base of doc bits.
The doc bits db is indexed on the NAME of a DOC-BIT.
A list of HELambdaP most important parameters.
The default name for the (x)html .css file.
The default pathname for the (X)HTML .css file.
The default directory is set to the location of the source file.
The user HELambdaP data folder.
Notes:
You are advised to handle this parameter with care. If you change
this parameter you should be prepared to change most other HELambdaP
pathnames.
See Also:
*HELAMBDAP-CSS-PATHNAME*, *HELAMBDAP5-CSS-PATHNAME*, *HELAMBDAP-JS-PATHNAME*
The site where HELambdaP currently resides.
The location where HELambdaP source resides.
This parameter is set during HELambdaP installation. If not it is NIL and it indicates that HELambdaP is not properly installed.
The default name for the HTML5 .css file.
The default pathname for the (X)HTML .css file.
The default directory is set to the location of the source file.
The HTML5 documentation structure.
A minimal documentation structure that contains only the main index (and introduction and the dictionary of the system/package/library).
List of possible ’source extensions’ of files where Lisp code may be found.
The Texinfo documentation structure.
Controls whether the system should try to create the packages it encouters.
DEFPACKAGE and IN-PACKAGE forms will be evaluated if non-NIL (default T). Only top-level occurrences of these forms are considered.
This parameter is bound to a condition class related to unknown packages.
The parameter is set by each implementation dependent code in order to properly generate the most appropriate condition.
The XHTML frame-based documentation structure.
The XHTML simple frame-based documentation structure.
A minimal documentation structure that contains only the main index (and introduction and the dictionary of of the system/package/library.
Next: Macros, Previous: Special variables, Up: Internals [Contents][Index]
Next: Ordinary functions, Previous: Symbol macros, Up: Internals [Contents][Index]
Defines a Documentation Format.
This macro generates the appropriate declarations and definitions that
introduce a documentation format in the HELambdaP system. In
particular it registers the new format in the internal tables and
makes the symbolic tags and keys used to retrieve the format known to
the system.
See Also:
OUTPUT-FORMAT, OUTPUT-FORMAT-TAG
Next: Generic functions, Previous: Macros, Up: Internals [Contents][Index]
Collects a list of declarations from a form list according to CL rules.
Notes:
Cfr. ANSI 3.4.11 Syntactic Interaction of Documentation Strings and Declarations.
name.
Prints/logs a message for debugging on *DEBUG-OUTPUT*.
TAG and PREFIX can be both T to simplify DEBUGMSG usage; in that case
defaults are used.
PREFIX, if not T, should be a STRING to be used as a prefix to the message.
Ensures that the resulting pathname does not contain ’problematic’ characters.
More specifically: #\/ #\Space #\* #% #( #)
Given a list of FORMS finds a doc-string according to CL rules.
Notes:
Cfr. ANSI 3.4.11 Syntactic Interaction of Documentation Strings and Declarations.
key.
tag.
key.
tag.
key.
tag.
Constructs a NAMING.
Constructs a NAMING.
NESTING-PATH is passed as a &rest parameter.
Prints the content of the curret Doc Bits DB.
Munging of RETURNS declaration.
Check whether two DOC-BTIs are ’similar’.
Two DOC-BITs are similar if they are of the same type (no subtyping), they have the same DOC-BIT-NAME and their DOC-BIT-DOC-STRINGs are equal.
key.
tag.
Produces a string of th form "Day Mon Dat HH:MM:SS TZ YEAR".
Issues a warning under certain conditions.
TAG and PREFIX can be both T to simplify WARNMSG usage; in that case
defaults are used.
PREFIX, if not T, should be a STRING to be used as a prefix to the message.
Next: Conditions, Previous: Ordinary functions, Up: Internals [Contents][Index]
Produces a skeleton for the documentation.
The skeleton consists of a number of ’judiciously’ editable files that can be used as building blocks for the final documentation.
automatically generated reader method
nav.
automatically generated writer method
nav.
automatically generated reader method
name.
automatically generated reader method
root.
automatically generated reader method
Quick and dirty ’section’ finding in (X)HTML(5) source.
The EXTRACT-SECTIONS function looks at an (X)HTML(5) source looking
for top level <H1>...</H1> ’sections’. More specifically, it looks for
sectioning markup of the form:
<H1><A name="Section Name">....</A></H1>
The "Section Name" is what is eventually saved in the result, which is then used to produce a file navigation bar.
automatically generated reader method
automatically generated reader method
automatically generated reader method
Loads a doc-bits data base from a source.
The SOURCE can be either a STREAM or a File Designator. The optional DOC-BITS-DB parameter defaults to the current doc-bits database.
Dispatches on argument UPC-CLASS to generate an UNKNOWN-PACKAGE instance.
This generic function relies on the presence of implementation
dependent subclasses of UNKNOWN-PACKAGE to ensure a compatible
treatment of this events.
See also:
The implementation dependent classes; e.g., UNKNOWN-PACKAGE-LW.
Merge two doc bits.
Information missing from DBIT1 that can be found in DBIT2 may be
copied to a copy of DBIT1 and viceversa.
The function will return two copies of DBIT1 and DBIT2 as two values.
Merge two FUNCTION-DOC-BITs.
This is useful for doc-bits that are the results of a (SETF (DOCUMENTATION ...) ...).
Generic function used in the PPRINT dispatch table.
Processes a ’doc string’.
The processing is done (or rather a best effort is made to parse) according to a give ’input-syntax’ and the result is built in a given ’output-format’.
Processes a documentation string.
This method tries to interpret a documentation string as a CLHS-style
entry. In particular it looks for ’sections’ titled ’Syntax’,
’Arguments and Values’, ’Description’, ’Examples’, ’Affected By’, ’See
Also’, ’Notes’, ’Exceptional Situations’ and ’Side Effects’.
These sections are then rendered as HTML.
Arguments and Values:
s – a string.
input-syntax – (eql ’text/hyperspec)
output-format – (eql ’html)
args-n-values-p – a boolean
lambda-list – a lambda-list
result-p – a boolean
return-decls – a list of the types of returned values
type-decls – a list of arguments declared types
skip-description-header-p – a boolean
Notes:
This documentation string is a (partial) example.
See Also:
parse-doc-hyperspec-style.
automatically generated reader method
Renders the ’Syntax’ section of a doc string.