linting mdoc(7) pages (was: [PATCH v2] man*/: ffix (migrate to `MR`))

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1.1: Type: text/plain, Size: 2795 bytes --]

Hi Ingo!

On 2023-08-16 20:25, Alejandro Colomar wrote:
> Hi Ingo!
> 
> On 2023-08-16 18:33, Ingo Schwarze wrote:
>> That perspective is not really helpful for general purpose Linux
>> distributions: for these, the Linux man-pages project matters a lot,
>> and that project is not considering the man(7) language as obsolete at
>> all.  That i keep recommending changing that stance does not appear to
>> have much effect so far
> 
> It does have an effect, or I like to think it has.  Branden and I are
> pushing to improve man(7) to be on par with mdoc(7) where it's lacking.
> 
> I also recently added support for mdoc(7) in the build system, so new
> mdoc(7) pages will enjoy the same linting level to which I subject our
> existing man(7) pages.  If anyone wants to write new pages using
> mdoc(7), they're welcome.  I'm not going to require man(7) (but I
> prefer it for my own pages).
> 
> <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/share/mk?id=c76a587148d9b69667852311ece53403b1458844>
> <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/share/mk?id=5a34548ecbf4200b4a7bcc3ce9f26bedd84450cb>
> <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/share/mk?id=3c8198d1786501eb4a9e9a46c61c17ff233f3d54>
> 
> So, if anyone wants to add a page that's not present, and decides to
> write it using mdoc(7), it'll be welcome.  That includes the suggestion
> of a new intro.1, which IIRC was written in mdoc(7).  I should revise
> that page.  I lack experience using it, but I guess I'll learn more
> with enough time.
> 
> Also, if anyone wants to fork this project and rewrite it using mdoc(7),
> or maybe use it for having a documentation repo of whatever project,
> I made it easy to do so.  (In fact, I added mdoc(7) support for linting
> an mdoc(7) page at my job.)
> 
> I even plan to add support for mm(7) pages, if POSIX deigns to talk to
> me to provide their sources.

BTW, I remember you showed interest in the ability to lint all pages.
You may be interested in trying this:

$ make lint-mdoc MANDIR=/home/alx/src/bsd/openbsd/src -k

You may really use anything as MANDIR, and you may also use different
targets, but lint-mdoc will run mandoc(1) as the linter, which I guess is
the most interesting one to you.  Check `make help` for that.

You may need to adjust a few command variables to use the gnu variants,
as I doubt I write portable stuff.  Ye be warned.  Check
`make help-variables` for that.

If you try this, you'll need the very latest commit, as I just fixed
a bug in a script that misinterpreted some pathname in the OpenBSD tree.

Cheers,
Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]