Re: Learning troff - where to start?

[Ingo Schwarze]

Hi Federico,

Federico Lucifredi via wrote on Tue, Oct 13, 2020 at 08:04:10PM -0400:

> For man page writing, I collected the available resources in this
> blog post a while ago - happy to hear about new resources.

If you are curious about new resources, you could mention the
concept of semantic markup and the mdoc(7) language, which was
new twenty years before you wrote your blog post.

Sure, some people might argue that semantic markup is useless or
evil and physical markup is simply better, though i rarely hear
that opinion.  Sure, some people might argue that some semantic
markup languages are too large and complicated for practical use,
and i definitely make that argument regarding DocBook with its 500
different elements and tens of thousands of nesting rules.  Some
people even make that argument for mdoc(7) with its about seventy
macros.

But advertising an article to "collect *the* available resources"
(emphasis is mine) in 2020 if that artcile does not mention the
possibility of writing manual pages with semantic markup feels
surprising to me.  In particular since the first sentence of the
post gives me the impression that this is not intended as Linux-only
but as community-independent.  For all BSD communities, the information
presented in the article is outdated by about three decades, and
for Illumos, it no longer applies, either.

Finally, there is an obvious, rather serious error.  I do not think
misattribution should be taken lightly:

  the man macro package, originally written by James Clark

The correct statement is:

  The man language first appeared as a macro package for the roff
  typesetting system in Version 7 AT&T UNIX.  It was later rewritten
  by James Clark as a macro package for groff.

I'm not sure which member(s) of the Bell Labs originally designed
and implemented the man(7) macros, but it clearly wasn't James Clark.

Yours,
  Ingo

> https://f2.svbtle.com/writing-man-pages