STYLE.md (1426B)
1 # R7RS Texinfo style 2 3 These are a few style guidelines for the Texinfo version of R7RS. 4 5 ## Names 6 7 Use the usual Texinfo `@var`, `@code`, and `@samp` macros whenever 8 appropriate. Use our `@svar` macro for syntactic variables. Use 9 `@define{}` (custom macro) rather than `@dfn{}` for definitions; it 10 produces better HTML output. 11 12 Use semantic markup! No font (@r, @tt, etc.) nonsense. 13 14 Use `@rfivers{}`, etc. for report names. 15 16 ## Entries 17 18 Use `@deffn … @end deffn`, with `@deffnx` for run-on definitions. 19 Use the categories in the report ("procedure", "syntax", etc.). 20 21 For complex macros like `guard`, put only the keyword on the `@deffn` 22 line. Beneath that, put the actual syntax as an example. A simplified 23 example: 24 25 @deffn syntax guard 26 27 @lisp 28 (guard (<variable> 29 <cond clause1> <cond clause2> …) 30 <body>) 31 @end lisp 32 33 … 34 @end deffn 35 36 ## Code examples 37 38 Use `@lisp … @end lisp` for block examples. Within these, use 39 `@r{unspecified}` and `@r{error}` for unspecified or error results. 40 (This isn't very "semantic", but it's what the Texinfo manual 41 recommends. Is there a better way?) 42 43 Use our @rsvar macro for syntactic variables that occur in code 44 examples. This will emit an `@r{}` wrapper for the syntactic variable, 45 ensuring (where it's possible to ensure such things) that it appears 46 in Roman font. 47 48 ## Indexing 49 50 Use our `@sharpindex` macro to index names that begin with '#'.