Last-Modified: 2023-03-25T11:29:23+00:00
SCM-Info: (git) 2023-03-25T11:29:53+00:00 - 74226a7b0ab9f1b3ea32b0f522727c4794c719a1


# Enhanced guix.texi conventions
Co-authored-by: Felix Lechner


Here are some ideas to enhance the Guix manual:


## Anchor introduction

* Let's mandate anchors for all record-types and their fields

  This helps with cross-referencing records and their fields across
  the manual. Fortunately, the define-configuration macro can easily
  be adjusted to add those anchors automatically.


## Name allocation for anchors

Let's institute a little bit of a name allocation policy. It reduces
the chance of naming clashes and resulting confusion as the manual
grows.

The names should follow a pattern that is consistent and practical.

* Record types

Anchor names for record fields should be constructed by concatenating
the record name and the field name like this:

<anchor-name> ::= <record-type-name> "-" <field name> "-field"

The ending "-field" is intended to avoid a potential clash with
accessor for the same field.


## Procedure anchoring

\\\\TODO: namespace using module as prefix?


## Annotation of procedures and variables

All Scheme procedures should use @defun. All Scheme variables should use
@defvar. Those make the most sense, since Guix is written in Scheme.

Environment variables should use @env.
Note: Do not include the dollar sign, that's shell specific syntax.

Note 2: When using @defun, the character & is special.
See <https://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html#Special-Charactersf>.


## Mandatory preservation of @c start fragment, end fragment for generated docs

Generated documentation should be clearly demarcated to discourage editing
it directly.

### FIXME: configuration->documentation

* Collapse unnecessary newlines from output


## Representation of list

* Lists of strings, numbers and other static data & empty lists

Represent as a quoted list.

### FIXME: configuration->documentation

configuration->documentation inconsistently formats lists as:

""""""""""""""""""""""""""""""""""""
@code{("foo" "bar")}
@code{()}
@code{'()}  ; if predicate is alist?
""""""""""""""""""""""""""""""""""""


## Miscellaneous @-command convention

* Use @url instead of @uref




===========================================================================================

                     Special considerations for documentation writers

* Avoid describing 00:00 or 13:00/01:00PM as midnight/noon.
  This needn't hold with high latitude locations. A simple test is to consider
  what would be the situation in Antarctica.




===========================================================================================




>>>>>>>>>>>>>>>> RFC / TODO

* record-type convention, with or without angle brackets?

* cindex, pindex, findex, tindex