document

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:

1. Create an appropriate directory under example/ if it doesn't exist
2. Write the example code in a .scm file
3. 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:

• Review the document for clarity and accuracy
• Check the document can be built by the commands above
• Check the generated HTML files are correctly sectioned