groff
[Top][All Lists]
Advanced

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

Re: [groff] [PATCH] man7/mdoc_samples.7: srcfix: Avoid a warning about a


From: Michael Kerrisk (man-pages)
Subject: Re: [groff] [PATCH] man7/mdoc_samples.7: srcfix: Avoid a warning about a wrong section
Date: Fri, 1 Mar 2019 10:49:41 +0100

> The mandoc package is also slowly becoming more popular on Linux.
> For example, optional packages exist for Debian, Ubuntu, Gentoo,
> Arch, Alpine, Void, Slackware, Crux, ...  So quite a few Linux users
> may already have Kristaps' modern mdoc(7) manual page in addition
> to the classical groff_mdoc(7).

[...]

> I would no doubt like to see mdoc(7) used more in Linux contexts,
> too, because Cynthia managed to reach an excellent balance between
> simplicity, conciseness, mnemonic value, and semantic markup power -
> the semantic search facilities mdoc(7) supports nowadays are very
> valuable in practice, and i think the difficulty of learning it is
> often vastly exaggerated even for casual users.  Just look at the
> MACRO OVERVIEW in mdoc(7), there aren't really that many macros:
>   https://man.openbsd.org/mdoc.7#MACRO_OVERVIEW
> If you want to see something that is *really* excessively complicated,
> try DocBook for a change...  :-/
>
> Anyway, that doesn't mean the Linux man-pages project has to document
> mdoc(7) given that it is not currently using it in any significant way.

Just to be clear, I'm not against mdoc in any way. (I consider it
unfortunate that man markup isn't at all semantic.)

It's just that the project that I inherited had > 95% pages in man
format, and the existence of a handful of pages in mdoc format was
painful when (in the early days) I was trying to do various automated
global automated edits to get greater consistency of formatting across
pages. I wouldn't have been unhappy if all of the pages had instead
been in mdoc format, but that was not the history.

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/



reply via email to

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