From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=0.2 required=5.0 tests=DKIM_INVALID,DKIM_SIGNED, HTML_MESSAGE,T_SCC_BODY_TEXT_LINE,T_TVD_MIME_EPI autolearn=no autolearn_force=no version=3.4.4 Received: (qmail 29714 invoked from network); 8 Aug 2022 14:24:43 -0000 Received: from bsd.lv (HELO mandoc.bsd.lv) (66.111.2.12) by inbox.vuxu.org with ESMTPUTF8; 8 Aug 2022 14:24:43 -0000 Received: from fantadrom.bsd.lv (localhost [127.0.0.1]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 3954e537 for ; Mon, 8 Aug 2022 09:24:39 -0500 (EST) Received: from mail.celforyon.fr (ns352767.ip-91-121-87.eu [91.121.87.121]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 7618175b for ; Mon, 8 Aug 2022 09:24:38 -0500 (EST) Received: from [127.0.0.1] (localhost [127.0.0.1]) by localhost (Mailerdaemon) with ESMTPSA id 970C64D416FB for ; Mon, 8 Aug 2022 16:25:20 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=eldred.fr; s=dkim; t=1659968720; h=from:subject:date:message-id:to:mime-version:content-type; bh=k9aGwm5U9Wslv8sgdwZGvhYtNk+9XJ+kYPW/foj00B0=; b=Om1TD630ZBZo8sZvrqFbah/v32wr+EKk8XtIOmN7sOZSLnphBm5bUMuV/LbtAGxHllKqqg ZFE83nF8OyLlVdK2xI5L3GyAuEL/4ymIYo5CZ97PfUKQ9FpAIaCLqlzbuhubyJuS53FL6S pjyIIVCl9h9oP0Mo4IJlHVlG94C1qhuNI9jplU3ieOCTNu5nTn2ivJ/dhkS5hbicNz3SsG BB5ll5Lb3YT9TIdlbg7IvKMtNr73RJp/xmJqdChJm8V+FqTsoaci2khT5vPoaPN9ERnJ8j j2m70V1cJtkgQgvbVcTWC/Y248933kAajPIW2gpS/a09OWpHcXQPDZY8daR78Q== Date: Mon, 8 Aug 2022 14:24:35 +0000 (UTC) From: Eldred Habert To: tech@mandoc.bsd.lv Message-ID: Subject: Inconsistent HTML anchor names X-Mailinglist: mandoc-tech Reply-To: tech@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: multipart/alternative; boundary="----=_Part_13_62482821.1659968675522" X-Correlation-ID: X-Last-TLS-Session-Version: TLSv1.3 ------=_Part_13_62482821.1659968675522 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit Hello, We at RGBDS[https://rgbds.gbdev.io] use Mandoc for our manual pages, as well as the online documentation. I happened to notice that the "At-files" anchor under "REVERSE MODE"[https://rgbds.gbdev.io/docs/master/rgbgfx.1#REVERSE_MODE] does not work, as it points to #At_files instead of #At-files. While we do some post-processing[https://github.com/gbdev/rgbds-www/blob/master/maintainer/man_to_html.sh], none of it should affect this, as far as I'm aware, therefore I think it is a Mandoc bug. Sorry if I'm wrong on that. Thank you for your continued efforts! ~ Eldred ------=_Part_13_62482821.1659968675522 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable
Hello,

We at RGBDS use Mandoc for our manual pages, as = well as the online documentation. I happened to notice that the "At-files" = anchor under "REVERSE MODE" does not work, as it points to= #At_files= instead of #At-files.

While we do some post-processing= , none of it should affe= ct this, as far as I'm aware, therefore I think it is a Mandoc bug. Sorry i= f I'm wrong on that.

Thank = you for your continued efforts!
~ Eldred
------=_Part_13_62482821.1659968675522-- -- To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=-0.0 required=5.0 tests=T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 6888 invoked from network); 9 Aug 2022 12:36:25 -0000 Received: from bsd.lv (HELO mandoc.bsd.lv) (66.111.2.12) by inbox.vuxu.org with ESMTPUTF8; 9 Aug 2022 12:36:25 -0000 Received: from fantadrom.bsd.lv (localhost [127.0.0.1]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 49cf74a8 for ; Tue, 9 Aug 2022 07:36:23 -0500 (EST) Received: from scc-mailout-kit-01.scc.kit.edu (scc-mailout-kit-01.scc.kit.edu [129.13.231.81]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id e3db4718 for ; Tue, 9 Aug 2022 07:36:21 -0500 (EST) Received: from hekate.asta.kit.edu ([2a00:1398:5:f401::77]) by scc-mailout-kit-01.scc.kit.edu with esmtps (TLS1.3:ECDHE_SECP256R1__RSA_PSS_RSAE_SHA256__AES_256_GCM:256) (envelope-from ) id 1oLOT6-002OBt-Mo; Tue, 09 Aug 2022 14:36:21 +0200 Received: from login-1.asta.kit.edu ([2a00:1398:5:f400::72]) by hekate.asta.kit.edu with esmtp (Exim 4.94.2) (envelope-from ) id 1oLOT5-007Dva-Hf; Tue, 09 Aug 2022 14:36:19 +0200 Received: from schwarze by login-1.asta.kit.edu with local (Exim 4.92) (envelope-from ) id 1oLOT5-0007bU-GQ; Tue, 09 Aug 2022 14:36:19 +0200 Date: Tue, 9 Aug 2022 14:36:19 +0200 From: Ingo Schwarze To: Eldred Habert Cc: tech@mandoc.bsd.lv Subject: Re: Inconsistent HTML anchor names Message-ID: References: X-Mailinglist: mandoc-tech Reply-To: tech@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: Salut Eldred, Eldred Habert wrote on Mon, Aug 08, 2022 at 02:24:35PM +0000: > We at RGBDS[https://rgbds.gbdev.io] use Mandoc for our manual pages, > as well as the online documentation. Nice. :-) Thanks for telling me. I took this as a reason to finally create the sub-page https://mandoc.bsd.lv/css.html and list RGBDS there. I'm sure neither Debian nor Arch will run on the Game Boy, so RGBDS now has a unique position on that page. ;-) It's also nice to see you using the mdoc(7) language for your manual 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: $ mandoc -T lint -W warning rgbgfx.1 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 All four of these are legitimate warnings, and getting rid of them would improve the manual page. > I happened to notice that the "At-files" anchor under > "REVERSE MODE"[https://rgbds.gbdev.io/docs/master/rgbgfx.1#REVERSE_MODE] > does not work, as it points to #At_files instead of #At-files. Heh, what a subtle bug. The hyphen in the sentence .Do Sx At-files Dc may help with this . "At-files" may help with this. is breakable (i.e. if the word "At-files" begins shortly before the end of an output line, an output line break may be inserted between "At-" and "files"). To distinguish breakable from non-breakable hyphens, the roff(7) pre-parser (roff.c) replaces breakable hyphens with a dedicated C0 contol character, ASCII_HYPH = U+001E. Of course, RFC 3986 does not allow that in URI fragments, so it got wrongly turned into an underscore. 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. > 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: * The idea to link from flags in the SYNOPSIS to the descriptions of the flags is interesting. I might consider doing that in mandoc. :) Not today, though. * 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 * You may no longer need to shift headings; mandoc-current already translates .Sh to

and .Ss

. That change was motivated by accessibility considerations very similar to your comment "level 1 is reserved for the page's title". > none of it should affect this, as far as I'm aware, therefore I think > it is a Mandoc bug. Sorry if I'm wrong on that. You are correct. Thank you for reporting the bug! Yours, Ingo Log Message: ----------- prevent breakable hyphens in segment identifiers from being turned into underscores; bug reported by Habert Modified Files: -------------- mandoc: html.c Revision Data ------------- Index: html.c =================================================================== RCS file: /home/cvs/mandoc/mandoc/html.c,v retrieving revision 1.278 retrieving revision 1.279 diff -Lhtml.c -Lhtml.c -u -p -r1.278 -r1.279 --- html.c +++ html.c @@ -403,10 +403,13 @@ html_make_id(const struct roff_node *n, * In addition, reserve '~' for ordinal suffixes. */ - for (cp = buf; *cp != '\0'; cp++) - if (isalnum((unsigned char)*cp) == 0 && + for (cp = buf; *cp != '\0'; cp++) { + if (*cp == ASCII_HYPH) + *cp = '-'; + else if (isalnum((unsigned char)*cp) == 0 && strchr("!$&'()*+,-./:;=?@_", *cp) == NULL) *cp = '_'; + } if (unique == 0) return buf; -- To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=-3.3 required=5.0 tests=DKIM_INVALID,DKIM_SIGNED, HTML_MESSAGE,NICE_REPLY_A,T_TVD_MIME_EPI autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 16235 invoked from network); 20 Sep 2022 19:53:18 -0000 Received: from bsd.lv (HELO mandoc.bsd.lv) (66.111.2.12) by inbox.vuxu.org with ESMTPUTF8; 20 Sep 2022 19:53:18 -0000 Received: from fantadrom.bsd.lv (localhost [127.0.0.1]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 4cd40c03 for ; Tue, 20 Sep 2022 14:53:16 -0500 (EST) Received: from mail.celforyon.fr (ns3039568.ip-51-255-86.eu [51.255.86.93]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 528a70f8 for ; Tue, 20 Sep 2022 14:53:15 -0500 (EST) Received: from [127.0.0.1] (localhost [127.0.0.1]) by localhost (Mailerdaemon) with ESMTPSA id 07B611781A05 for ; Tue, 20 Sep 2022 21:53:13 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=eldred.fr; s=dkim; t=1663703594; h=from:subject:date:message-id:to:mime-version:content-type: content-language:in-reply-to:references; bh=RaAYmxuwMWjZUQgKNM/GBFTJdOTTqm4vKZop6ZEi1OY=; b=ny/01SwzDImh420lXPPkEDh5GKNsXxp2fEZe8iXPe0kbhadZEhsdvAUo8jUuEtPosJArpo F3qfjpIzasHJoYcRIQny3U58htyR64YemGN+8kLqskGTTnIPjtfw5Y2/L9/0cFhqh0nxdk 2QFovrVcc2lmJW8xsQ/mTj75eyElPkEK3BToJGiBCOWE9mHys9kD3fDjIRdqaLaTcYs/cd K2a5gbk+LRIxlxGxphjHaa1FJuvy8WBw8z3MFh1zr9rNOirUpIm938oQ0W6ch7gP0ho7Xh l3en9prDoIsEqVA/NqUZuH+ZxYSlkT0geeQ9zXtSy41UmtpGZeZ1fE6oj7opqA== Content-Type: multipart/alternative; boundary="------------Ypk0Ao7r0p6ah2iAraW1FzfS" Message-ID: <96de05f8-cfc6-02f2-7613-2215f901ad7c@eldred.fr> Date: Tue, 20 Sep 2022 21:52:59 +0200 X-Mailinglist: mandoc-tech Reply-To: tech@mandoc.bsd.lv MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.2.2 Subject: Re: Inconsistent HTML anchor names To: tech@mandoc.bsd.lv References: Content-Language: en-US, en-GB From: Eldred HABERT In-Reply-To: X-Last-TLS-Session-Version: TLSv1.3 This is a multi-part message in MIME format. --------------Ypk0Ao7r0p6ah2iAraW1FzfS Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit 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 bsd.lv) 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 >> [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 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

and .Ss

. 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 --------------Ypk0Ao7r0p6ah2iAraW1FzfS Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: 7bit
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 bsd.lv) 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
[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
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

--------------Ypk0Ao7r0p6ah2iAraW1FzfS-- -- To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv