This is my fork of Nikodemus Siivola's SB-TEXINFO library, which is used to translate docstrings in the SBCL code into Texinfo format which can be incorporated in a larger document.
I have forked this so that I can use it in the SHOP3 planner system, and also to add some documentation. I hope to make this the foundation of something like the Numpy documentation format in Python: a docstring format that is clearly readable as-is (either in an editor, or using the documentation function in the REPL), but that supports at least some forms of markup when incorporated into a manual or perhaps an on-line reader that's a little smarter than documentation).
SB-TEXINFO uses a number of heuristics to process the contents of docstrings.
If SB-TEXINFO finds a line of docstring that begins with whitespace, and then an open parent character, it will assume this is a lisp code block.
Remark: We could support Markdown-style use of three backticks, as well. This would let us do things like have embedded quotes that could confuse SB-TEXINFO at present.
Itemized lists are indented lists whose items begin with either the * or - character.
Remark: We could add the + character for greater compatibility, but it's not hugely important.
I will have to document this later; it's complicated and not hugely important to me right now.
- Heuristically try to identify symbols.
- Copy text into texinfo without modification between symbols.
- For symbols attempt to identify whether they should be typeset using
@codeor@var, depending on whether they are in*texinfo-variables*.
I believe that the system treats capital letters as indicating symbols, and presumably lower-case letters as not being symbols.
The letters A and I are treated specially for some reason.
It seems that *texinfo-variables* are just pulled from the lambda list, so maybe these are better referred to as texinfo parameters.
Introducing backticks for marking up code seems reasonable.
It would be great to find a syntax for cross-referencing that does not obscure reading the docstring too much. Perhaps just the string see followed by a double-quoted string?