| name | document |
| description | Guide for writing Sagittarius documents. Use this when asked to write a user reference manual or other Sagittarius documents. |
Structure of the doc directory
doc/
- CMakeLists.txt - the build file
- gendoc - script to generate document
- lib/ - static library for after conversion, such as Javascript or CSS
- sagittarius-ref.md - The main document
- clos.md - CLOS library documents
- srfi.md - table of supporting SRFI
- r6rs.md - top document for R6RS libraries
- rnrs/ - R6RS standard library document
- r7rs.md - R7RS support document
- sagittarius.md - top document of Sagittarius extensions. This file includes documents located in
sagittarius/ directory.
- sagittarius/ - Sagittarius extensions document
- utils.md - surface of utils/ directory. To expose, add inclusion in this file.
- utils/ - Utility library document, mainly located in
sitelib/ directory
- ported/ - Ported library document.
Structure of the document
Sagittarius document can be written GFM with extra extensions.
Section extension
Section starts with [§{n}] together with Markdown header notation
where {n} specifies the section level.
Header 1 section example:
[§1] Header 1 section
=====================
The header 1 section must be used for the top level section such as
Sagittarius extensions or R6RS Libraries.
Header 2 section example:
[§2] Header 2 section
---------------------
The header 2 section must be used for library level description.
Such as (sagittarius).
Header 3 section example:
### [§3] Header 3 section
The header 3 section must be used to split the library document
logically. Such as High level API or Low level API.
Header 4 section example:
#### [§4] Header 4 section
The header 4 section must be used to split the header 3 section into
the finer section.
Inclusion extension
Document can include document or example code.
Document inclusion
* @[[path/to/markdown.md](path/to/markdown.md)]
The document inclusion must use the path as its title.
Example code inclusion
* @[-[Title of the example](path/to/the/example/code.scm)]
The code inclusion must specify the title and path.
Writing Style Guidelines
When writing documentation for Sagittarius libraries, follow these guidelines:
Content Guidelines
-
Keep descriptions short and concise: Focus on essential information.
Avoid lengthy explanations unless necessary for understanding.
-
Omit obvious examples: Do not provide examples for self-explanatory
procedures, such as predicates (foo?) or simple getters/setters.
-
Externalize long examples: If an example exceeds 15 lines, create
a file in the appropriate example/ subdirectory and use the example
code inclusion syntax instead of embedding it inline.
-
All examples must run: Every code example in the documentation must
be executable and produce the expected output. Test each example using
the Sagittarius interpreter before finalizing the documentation:
./build/sagittarius -Llib -Lsitelib -L'ext/*' -Dbuild test-example.scm
If an example requires extensions that may not be available (e.g., threads),
simplify the example to demonstrate the concept without those dependencies.
Example placement
For long examples:
- Create an appropriate directory under
example/ if it doesn't exist
- Write the example code in a
.scm file
- Use the example code inclusion syntax in the documentation:
* @[-[Title describing the example](example/category/example-name.scm)]
Build the document
Building document uses doc or online-doc target.
For POSIX like environment
make doc
make online-doc
For Windows
ninja doc
ninja online-doc
The result document will be doc directory of the building directory.
One file document is sagittarius-ref.html, multiple file document, aka
online document, is sagittarius-online-ref.html and its sections are
located in sections/ directory.
Checklist
Before submitting:
