Well, I hope you will forgive my lack of response for a month and a half. I've been busy elsewhere, and this email got buried under many others. Apologies.Salut Eldred,
Blame bentley for that. I think he originally wrote the man pages, and I think they provide good defaults that are more convenient than directly messing with groff formatting, so I use it for all my (admittedly few) man pages.It's also nice to see you using the mdoc(7) language for your manual pages.
It does make sense, and I do run this from time to time. The warnings haven't been fixed mainly because they seemed harmless/false positives, but this seems like a good occasion to discuss them, if you want.You might also consider using "mandoc -T lint" on your manual pages, it produces a lot of output. Even if you don't care about STYLE messages, at least running "mandoc -T lint -W warning" would make sense, for example:
I'm not really sure what this is pointing out.mandoc: rgbgfx.1:168:2: WARNING: skipping empty macro: Sy
mandoc: rgbgfx.1:573:2: WARNING: sections out of conventional order: Sh SEE ALSO mandoc: rgbgfx.1:575:2: WARNING: unusual Xr order: rgbasm(1) after rgbds(7) mandoc: rgbgfx.1:577:2: WARNING: unusual Xr order: rgbfix after rgblink
My understanding is that the Xr order is supposed to be by
section, then alphabetical, right?
The rationale for our ordering is that it is the order in which we
expect the users to read the manual pages; this made more sense
back when we served the renders online directly; now that we have
a separate navbar, it might be okay to reorder the footers.
I haven't found any thus far, but my testing isn't thorough. We haven't really set up any kind of anchor checker, sadly.The commit appended below (made both to OpenBSD and to the portable mandoc at bsd.lv) fixes the bug. Please check that it works for you, too, and tell me in case you notice any regressions.
Again, blame bentley. I didn't realise this page existed until I went through two fairly small links lost in the middle of others. Good resources, despite not being very easy to find. I'll fix this.While we do some post-processing [https://github.com/gbdev/rgbds-www/blob/master/maintainer/man_to_html.sh],I'm not convinced i understood all of that, but here are some remarks anyway: * Using ".Fl Fl foo" for GNU-style long options is discouraged because it is semantically wrong. Using ".Fl \-foo" is better. https://mandoc.bsd.lv/mdoc/style/options.html
Great! That said, I'm reluctant to use a non-release version of Mandoc in our documentation generator, as I don't have much time to dedicate to maintaining it; so I think I'll patiently wait for the next release.* You may no longer need to shift headings; mandoc-current already translates .Sh to <h2> and .Ss <h3>. That change was motivated by accessibility considerations very similar to your comment "level 1 is reserved for the page's title".
Late but yours nonetheless,
~ Eldred