Not all section headers have id in HTML output

Not all section headers have id in HTML output

[Aman Verma]

Hi Ingo,

Thanks for the fix for the `pre` bug. I have another (possible)
bug to report:

In the HTML output for mdoc(7)[1] the first two section headers don't
have an id attribute. In fact, it seems that two other elements down the
page have taken the ids ("NAME" and "DESCRIPTION") that the first two
headers were supposed to have. This makes it impossible to link to those
headers and also breaks the table of contents generated with the `-O toc`
option to mandoc.

[1]: https://mandoc.bsd.lv/man/mdoc.7.html

Best regards,
Aman
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: Not all section headers have id in HTML output

[Ingo Schwarze]

Hello Aman,

Aman Verma wrote on Wed, Oct 28, 2020 at 06:40:45PM -0400:

> Thanks for the fix for the `pre` bug. I have another (possible)
> bug to report:
> 
> In the HTML output for mdoc(7)[1] the first two section headers don't
> have an id attribute. In fact, it seems that two other elements down the
> page have taken the ids ("NAME" and "DESCRIPTION") that the first two
> headers were supposed to have.

That is true.  Automatic tagging of the .It macro tagged with
TAG_STRONG whereas .Sh only tagged with TAG_WEAK.

> This makes it impossible to link to those headers and also breaks the
> table of contents generated with the `-O toc` option to mandoc.

You are right; arguably, that is not ideal.

So i changed the priority from TAG_WEAK to TAG_STRONG for all
headers where the header text can be used as the fragment identifier
without any modification; that includes single-word titles, in
particular NAME and DESCRIPTION, see the patch below.

I do see value in having ...#DESCRIPTION always linking to the
description, just as you say.

I have also installed the changed code on https://man.openbsd.org/
such that the new behaviour can be easily inspected.

Thanks for the suggestion,
  Ingo


Log Message:
-----------
Promote section headers that can can be used unmodified as fragment 
identifiers from TAG_WEAK to TAG_STRONG, 
such that for example ...#DESCRIPTION always works.
Suggested by Aman Verma on the discuss@ list.

Modified Files:
--------------
    mandoc:
        man_validate.c
        mdoc_validate.c

Revision Data
-------------
Index: mdoc_validate.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mdoc_validate.c,v
retrieving revision 1.387
retrieving revision 1.388
diff -Lmdoc_validate.c -Lmdoc_validate.c -u -p -r1.387 -r1.388
--- mdoc_validate.c
+++ mdoc_validate.c
@@ -2617,7 +2617,7 @@ post_section(POST_ARGS)
 			if ((nch = n->child) != NULL &&
 			    nch->type == ROFFT_TEXT &&
 			    strcmp(nch->string, tag) == 0)
-				tag_put(NULL, TAG_WEAK, n);
+				tag_put(NULL, TAG_STRONG, n);
 			else
 				tag_put(tag, TAG_FALLBACK, n);
 			free(tag);
Index: man_validate.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/man_validate.c,v
retrieving revision 1.154
retrieving revision 1.155
diff -Lman_validate.c -Lman_validate.c -u -p -r1.154 -r1.155
--- man_validate.c
+++ man_validate.c
@@ -324,7 +324,7 @@ post_SH(CHKARGS)
 					*cp = '_';
 			if (nc != NULL && nc->type == ROFFT_TEXT &&
 			    strcmp(nc->string, tag) == 0)
-				tag_put(NULL, TAG_WEAK, n);
+				tag_put(NULL, TAG_STRONG, n);
 			else
 				tag_put(tag, TAG_FALLBACK, n);
 			free(tag);
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv