r7rs-small-texinfo

R7RS-small Scheme converted to Texinfo.
git clone https://kaka.farm/~git/r7rs-small-texinfo
Log | Files | Refs | README | LICENSE

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 '#'.