Lassi Kortela <xxxxxx@lassi.io> writes:

[...]
> Would it be possible to write the source documentation as
> S-expressions (which src/make-templates.scm already has some of)?
> Those could easily use conditional expressions for any
> output-format-specific stuff. It would also be easy to extract
> information programmatically from S-exprs.

Doing this well is not as easy as it seems.

Knowing that it would come up, I tried it already (that's partly why
there is a roff printer in the project). I found it awkward to need to
invent a new document format when my primary target is manpages anyway
(Not Invented Here, anyone?). Someone coming in to help isn't going to
have any clue what is going on if everything's in a documentation format
nobody has ever seen.

There are of course benefits to what you're proposing, namely that there
is a big difference between writing (proc car) to refer to a procedure
or writing .I car to make the word italic. The mdoc package actually
lets you express semantic information, but it's more complicated than
the man package and geared towards C and Unix (see groff_mdoc(7) vs
groff_man(7)). The arguments in favor of this are essentially the same
as those in favor of CSS for HTML.

Popular newer formats like Markdown also don't let you express
semantics. The formats I'm aware of that express semantic information
are reStructuredText, Texinfo and Racket's Scribble. Texinfo does not
seem suitable:

|    From time to time, proposals are made to generate traditional Unix
| man pages from Texinfo source. However, because man pages have a
| strict conventional format, creating a good man page requires a
| completely different source from that needed for the typical Texinfo
| applications of writing a good user tutorial and/or a good reference
| manual. This makes generating man pages incompatible with the Texinfo
| design goal of not having to document the same information in
| different ways for different output formats. You might as well write
| the man page directly.

reStructuredText on the other hand is... complicated:
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html

Since you're in favor of using an S-expression format, might I suggest
that Scribble is a better option for the surface syntax:
<https://docs.racket-lang.org/scribble/getting-started.html#%28part._how-to~3areader%29>
Writing documentation purely with S-expressions gets tedious very fast
because editing the text involves a lot of unnatural operations like
moving words from one string to another.

I'm very open to writing the manpages in Scribble format if we have a
manpage renderer for it (there isn't one today). But right now I'm more
about getting on with the writing. I think if we do come up with
something better then it's not a huge task to convert. The manpage
format is really easy to parse (if you don't use mdoc) and any tool we
write for it would only need to work with the pages we've written
ourselves, which makes it easy to extract semantics after the fact.

BTW, press C-c C-c in Emacs to get the manpage rendered! There are
benefits to working with existing formats and tools. :)

Regards,

--
Göran Weinholt   | https://weinholt.se/
Debian developer | 73 de SA6CJK