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

While that is true, roff is also famously confusing to many people. IMHO
the ideal language is a very simple one, no matter which one it is.

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

All true.

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

Exactly, but the problem also occurs in reverse :) Roff is not a good
source for generating Info pages.

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

Agreed.

> 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).

+1 for a Scribe/Scribble-style approach. I like the idea behind those
languages a lot, but found them surprisingly confusing to learn.

For another application (upcoming Lisp Union documents), I solved that
problem by trying to reduce Scribble to a minimal core. It ended up
looking like this:

----------------------------------------------------------------------
#section(Name)

#name(car)(cdr)(the car or cdr field of a pair (head and tail))

#section(Library)

#import(R6RS)(rnrs)
#import(R6RS)((rnrs base))
#import(R7RS)((scheme base))

#section(Synopsis)

#code((car pair))
#code((cdr pair))

#section(Description)

Returns the contents of the car or cdr field of a pair.

These procedures can also be used with lists, which in Scheme are
linked lists of pairs. The #proc(car) procedure returns the head of a
list. The #proc(cdr) procedure returns the tail of a list.

#section(Return values)

Returns the contents of the car or cdr field of #var(pair).
----------------------------------------------------------------------

So it interprets anything of the form #foo(...)(...) as a directive, and
everything else as plain text. It's possible to nest directives:
#foo(#bar(#baz(...))) The directives are completely arbitrary, and can
be tailored per application. I just wanted something flexible, trivial
to learn and trivial to parse.

> 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

If somebody volunteers to write a roff parser I have nothing against it :)
> BTW, press C-c C-c in Emacs to get the manpage rendered! There are
> benefits to working with existing formats and tools. :)

Another shameless plug: <http://melpa.org/#/live-preview>

Roff preview: <https://github.com/lassik/emacs-live-preview/issues/2>