groff
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [groff] groff as the basis for comprehensive documentation?


From: Larry Kollar
Subject: Re: [groff] groff as the basis for comprehensive documentation?
Date: Wed, 18 Apr 2018 13:25:26 -0400

Nate Bargmann <address@hidden> wrote:

> I have long been involved with a project that has lacked good
> documentation for nearly all of its existence.  We've had documentation,
> but it isn't in a good format for generating man, HTML, or PDF versions.
> 
> Long ago I started with Docbook and then that got to a point no one else
> would touch it and I didn't want to either.  XML was the "wave of the
> future" but I didn't jump on that wagon.  …

At work, we’re in the first stages of moving our writers over to a DITA-based 
CMS.
It’s horribly complex (and I should know, I’m in the vanguard), but does have a
pretty good way of producing both good PDF and decent HTML. I love when
people go “ooh, topic-based, shiny!” and I point out manpages have been around
for decades. :-D

BUT… if you want manpages, write manpages. I have not found anything yet
that does a good job of automatically creating manpages from any other kind
of format. DITA’s reference topic might be a reasonable basis for a conversion,
but writing that descriptive title is still beyond any AI. It has to look 
natural to a
human reader, while containing all the keywords needed to find it in a search
(thus being both content and metadata).

Ingo’s mandoc solution is a good way to produce text/HTML output, and you
can use groff for PDF. The only thing I’d take issue with is his assertion that
-mdoc is easier to write than legacy -man. No doubt that -mdoc’s semantic
markup adds value, but I’ve always had trouble getting my head around the
syntax.

        Larry


reply via email to

[Prev in Thread] Current Thread [Next in Thread]