[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
- Re: [groff] groff as the basis for comprehensive documentation?, (continued)
- Re: [groff] groff as the basis for comprehensive documentation?, Ralph Corderoy, 2018/04/16
- Re: [groff] groff as the basis for comprehensive documentation?, Ingo Schwarze, 2018/04/16
- Re: [groff] groff as the basis for comprehensive documentation?, John Gardner, 2018/04/16
- Re: [groff] groff as the basis for comprehensive documentation?, Ralph Corderoy, 2018/04/16
- Re: [groff] groff as the basis for comprehensive documentation?, John Gardner, 2018/04/16
- Re: [groff] groff as the basis for comprehensive documentation?, Ralph Corderoy, 2018/04/16
- Re: [groff] groff as the basis for comprehensive documentation?, G. Branden Robinson, 2018/04/21
- Re: [groff] groff as the basis for comprehensive documentation?, Ralph Corderoy, 2018/04/16
Re: [groff] groff as the basis for comprehensive documentation?,
Larry Kollar <=
Re: [groff] groff as the basis for comprehensive documentation?, Colin Watson, 2018/04/19
Re: [groff] groff as the basis for comprehensive documentation?, Ingo Schwarze, 2018/04/19