help / color / mirror / Atom feed
From: Eldred HABERT <>
Subject: Re: Inconsistent HTML anchor names
Date: Tue, 20 Sep 2022 21:52:59 +0200	[thread overview]
Message-ID: <> (raw)
In-Reply-To: <>

[-- Attachment #1: Type: text/plain, Size: 3257 bytes --]

On 8/9/22 2:36 PM, Ingo Schwarze wrote:
> Salut Eldred,
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.
> It's also nice to see you using the mdoc(7) language for your manual
> pages.
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.
> 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:
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.
>    mandoc: rgbgfx.1:168:2: WARNING: skipping empty macro: Sy
I'm not really sure what this is pointing out.
>    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.

> The commit appended below (made both to OpenBSD and to the portable
> mandoc at fixes the bug.  Please check that it works for
> you, too, and tell me in case you notice any regressions.
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.
>> While we do some post-processing
>> [],
> 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.
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.
(I'm also noticing the '\-', and I /really/ hope we didn't mess up and 
use a breakable hyphen in places we shouldn't have...)
>   * 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".
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.

Late but yours nonetheless,
~ Eldred

[-- Attachment #2: Type: text/html, Size: 4933 bytes --]

      reply	other threads:[~2022-09-20 19:53 UTC|newest]

Thread overview: 3+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-08-08 14:24 Eldred Habert
2022-08-09 12:36 ` Ingo Schwarze
2022-09-20 19:52   ` Eldred HABERT [this message]

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \ \ \ \

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).