help / color / mirror / Atom feed
From: Ingo Schwarze <>
To: Eldred Habert <>
Subject: Re: Inconsistent HTML anchor names
Date: Tue, 9 Aug 2022 14:36:19 +0200	[thread overview]
Message-ID: <> (raw)
In-Reply-To: <>

Salut Eldred,

Eldred Habert wrote on Mon, Aug 08, 2022 at 02:24:35PM +0000:

> We at RGBDS[] 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

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
> 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

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.

> While we do some post-processing
> [],

I'm not convinced i understood all of that, but here are some remarks

 * 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.

 * 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".

> 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!


Log Message:
prevent breakable hyphens in segment identifiers 
from being turned into underscores;
bug reported by <Eldred dot fr> Habert

Modified Files:

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

  reply	other threads:[~2022-08-09 12:36 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 [this message]
2022-09-20 19:52   ` Eldred HABERT

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).