commit 6e9b20776a1c23ca0003e03db32268bfad60b8a8
parent 3d085714141f5cf40e25c68a4ca9ef2a0e7e0063
Author: Wolfgang Corcoran-Mathe <wcm@sigwinch.xyz>
Date: Sun, 4 Feb 2024 16:10:58 -0500
Add STYLE document, mainly to help me remember.
Diffstat:
| A | STYLE.md | | | 37 | +++++++++++++++++++++++++++++++++++++ |
1 file changed, 37 insertions(+), 0 deletions(-)
diff --git a/STYLE.md b/STYLE.md
@@ -0,0 +1,37 @@
+# R7RS Texinfo style
+
+These are a few style guidelines for the Texinfo version of R7RS.
+
+## Names
+
+Use the usual Texinfo `@var`, `@code`, and `@samp` macros whenever
+appropriate. Use our `@svar` macro for syntactic variables.
+
+Use semantic markup! No font (@r, @tt, etc.) nonsense.
+
+## Entries
+
+Use `@deffn … @end deffn`, with `@deffnx` for run-on definitions.
+Use the categories in the report ("procedure", "syntax", etc.).
+
+For complex macros like `guard`, put only the keyword on the `@deffn`
+line. Beneath that, put the actual syntax as an example. A simplified
+example:
+
+ @deffn syntax guard
+
+ @lisp
+ (guard (<variable>
+ <cond clause1> <cond clause2> …)
+ <body>)
+ @end lisp
+
+ …
+ @end deffn
+
+## Code examples
+
+Use `@lisp … @end lisp` for block examples. Within these, use
+`@r{unspecified}` and `@r{error}` for unspecified or error results.
+(This isn't very "semantic", but it's what the Texinfo manual
+recommends. Is there a better way?)
