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

[Nate Bargmann]

* On 2018 18 Apr 12:26 -0500, Larry Kollar wrote:
> At work, we’re in the first stages of moving our writers over to a
> DITA-based CMS.

Well, you forced me to look up DITA.  ;-)

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

After reading a bit about mdoc, I was disappointed that unlike "man"
that I find on Slackware or Debian, I had to add an uninstalled man page
into the db in order for "mandoc" to open it.  Perhaps I missed an
option, but the "man" I'm familiar with is capable of opening a file
simply by giving it a path name.  Fortunately, the "man" currently in
Slackware does read an mdoc formatted page just fine, so mdoc formatted
pages are not on island.

Another thing I have to consider is the ability of others to submit
patches based on familiarity.  As arcane as it is, most contributors
seem to have bumped against classic man macros but I think jumping to
mdoc would leave me as the sole maintainer.  Consequently, the project
will use the man macros until more distributions make mdoc the default.
Note that I'm not arguing against it, just saying that right now it
doesn't appear to be the right tool for us.

Deri's effort is quite in line with what I think I am looking for.
Using the .texi files for an introduction and even starting each
reference chapter and then including the man pages to make up the
references without duplicating the work, would seem to be an ideal way
to meld the strengths of each document system.

With that in mind, I'll continue to work on the man pages.  Thanks for
the good discussion thus far.

- Nate

-- 

"The optimist proclaims that we live in the best of all
possible worlds.  The pessimist fears this is true."

Web: http://www.n0nb.us  GPG key: D55A8819  GitHub: N0NB

signature.asc
Description: PGP signature