mandoc & perl documentation

mandoc & perl documentation

[Pali Rohár]

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

Hello!

In perl world is documentation for perl modules or perl scripts writing
in the POD format. Build process for perl scripts/modules then convert
POD documentation into manpages and install it into standard system
location.

I looked at Debian manpages which uses mandoc for converting man pages
to HTML and basically documentation for perl modules is not good.

For example this is HTMLized manpage for Email::Address::XS perl module:
https://manpages.debian.org/Email::Address::XS

There is also converting tool which formats POD documentation directly
into HTML output. And for Email::Address::XS module is looks like:
https://metacpan.org/pod/Email::Address::XS

So, I would like to ask, how can be HTML output generated from perl
manpages improved (process: POD --> mandoc --> HTML), so documentation
would be more close to the native HTML output (process: POD --> HTML)?

I understand that something like syntax highlighting is not possible,
but if you look at differences, in HTML output from mandoc are broken
vertical spaces (some are totally missing) or missing all different font
families.

If problem is in POD --> manpage converter (Pod::Man module), I can look
at it. But at the first I would need to know what mandoc is able to
process and what not.

-- 
Pali Rohár
pali.rohar@gmail.com

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

Re: mandoc & perl documentation

[Anthony J. Bentley]

Hi Pali,

Pali Rohár writes:
> In perl world is documentation for perl modules or perl scripts writing
> in the POD format. Build process for perl scripts/modules then convert
> POD documentation into manpages and install it into standard system
> location.
>
> I looked at Debian manpages which uses mandoc for converting man pages
> to HTML and basically documentation for perl modules is not good.
>
> For example this is HTMLized manpage for Email::Address::XS perl module:
> https://manpages.debian.org/Email::Address::XS
>
> There is also converting tool which formats POD documentation directly
> into HTML output. And for Email::Address::XS module is looks like:
> https://metacpan.org/pod/Email::Address::XS
>
> So, I would like to ask, how can be HTML output generated from perl
> manpages improved (process: POD --> mandoc --> HTML), so documentation
> would be more close to the native HTML output (process: POD --> HTML)?

LibreSSL's documentation was originally in pod, and was converted to
mdoc by Ingo and myself. We used Kristaps's pod2mdoc(1) as a base, and
fixed up the resulting mdoc source to be more semantic.

https://mandoc.bsd.lv/pod2mdoc/

If you want to keep the source formatting in pod, you could use pod2mdoc
during the build. The result is not incredibly good due to an inherent
lack of semantics in pod, but it is better than pod2man output.

I imagine a nicer result would come from keeping the source in mdoc
format and converting to pod during the build, but I'm not aware of
any such converter yet...

-- 
Anthony J. Bentley
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: mandoc & perl documentation

[Pali Rohár]

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

On Thursday 13 September 2018 09:32:48 Anthony J. Bentley wrote:
> Hi Pali,
> 
> Pali Rohár writes:
> > In perl world is documentation for perl modules or perl scripts writing
> > in the POD format. Build process for perl scripts/modules then convert
> > POD documentation into manpages and install it into standard system
> > location.
> >
> > I looked at Debian manpages which uses mandoc for converting man pages
> > to HTML and basically documentation for perl modules is not good.
> >
> > For example this is HTMLized manpage for Email::Address::XS perl module:
> > https://manpages.debian.org/Email::Address::XS
> >
> > There is also converting tool which formats POD documentation directly
> > into HTML output. And for Email::Address::XS module is looks like:
> > https://metacpan.org/pod/Email::Address::XS
> >
> > So, I would like to ask, how can be HTML output generated from perl
> > manpages improved (process: POD --> mandoc --> HTML), so documentation
> > would be more close to the native HTML output (process: POD --> HTML)?
> 
> LibreSSL's documentation was originally in pod, and was converted to
> mdoc by Ingo and myself. We used Kristaps's pod2mdoc(1) as a base, and
> fixed up the resulting mdoc source to be more semantic.
> 
> https://mandoc.bsd.lv/pod2mdoc/
> 
> If you want to keep the source formatting in pod, you could use pod2mdoc
> during the build. The result is not incredibly good due to an inherent
> lack of semantics in pod, but it is better than pod2man output.
> 
> I imagine a nicer result would come from keeping the source in mdoc
> format and converting to pod during the build, but I'm not aware of
> any such converter yet...

That is not possible for general usage. Documentation for perl modules
are written in POD and would be written also in the future...

-- 
Pali Rohár
pali.rohar@gmail.com

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

Re: mandoc & perl documentation

[Pali Rohár]

On Thursday 13 September 2018 17:12:26 Pali Rohár wrote:
> Hello!
> 
> In perl world is documentation for perl modules or perl scripts writing
> in the POD format. Build process for perl scripts/modules then convert
> POD documentation into manpages and install it into standard system
> location.
> 
> I looked at Debian manpages which uses mandoc for converting man pages
> to HTML and basically documentation for perl modules is not good.
> 
> For example this is HTMLized manpage for Email::Address::XS perl module:
> https://manpages.debian.org/Email::Address::XS
> 
> There is also converting tool which formats POD documentation directly
> into HTML output. And for Email::Address::XS module is looks like:
> https://metacpan.org/pod/Email::Address::XS
> 
> So, I would like to ask, how can be HTML output generated from perl
> manpages improved (process: POD --> mandoc --> HTML), so documentation
> would be more close to the native HTML output (process: POD --> HTML)?
> 
> I understand that something like syntax highlighting is not possible,
> but if you look at differences, in HTML output from mandoc are broken
> vertical spaces (some are totally missing) or missing all different font
> families.
> 
> If problem is in POD --> manpage converter (Pod::Man module), I can look
> at it. But at the first I would need to know what mandoc is able to
> process and what not.
> 

Just to note, raw manpage (generated by Pod::Man) is available there:
https://manpages.debian.org/Email::Address::XS.3pm.en.gz

And viewing it on terminal does not case problems with vertical spaces
like in HTML output.

So it is problem in mandoc HTML generator?

-- 
Pali Rohár
pali.rohar@gmail.com
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: mandoc & perl documentation

[Jan Stary]

On Oct 11 09:52:47, pali.rohar@gmail.com wrote:
> On Thursday 13 September 2018 17:12:26 Pali Rohár wrote:
> > In perl world is documentation for perl modules or perl scripts writing
> > in the POD format. Build process for perl scripts/modules then convert
> > POD documentation into manpages and install it into standard system
> > location.
> > 
> > I looked at Debian manpages which uses mandoc for converting man pages
> > to HTML and basically documentation for perl modules is not good.
> > 
> > For example this is HTMLized manpage for Email::Address::XS perl module:
> > https://manpages.debian.org/Email::Address::XS
> > 
> > There is also converting tool which formats POD documentation directly
> > into HTML output. And for Email::Address::XS module is looks like:
> > https://metacpan.org/pod/Email::Address::XS

You might want to try http://mandoc.bsd.lv/pod2mdoc/

	Jan

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

Re: mandoc & perl documentation

[Ingo Schwarze]

Hi Pali,

Pali Rohar wrote on Thu, Oct 11, 2018 at 09:52:47AM +0200:
> On Thursday 13 September 2018 17:12:26 Pali Rohar wrote:

>> In perl world is documentation for perl modules or perl scripts writing
>> in the POD format. Build process for perl scripts/modules then convert
>> POD documentation into manpages and install it into standard system
>> location.
>> 
>> I looked at Debian manpages which uses mandoc for converting man pages
>> to HTML and basically documentation for perl modules is not good.
>> 
>> For example this is HTMLized manpage for Email::Address::XS perl module:
>> https://manpages.debian.org/Email::Address::XS
>> 
>> There is also converting tool which formats POD documentation directly
>> into HTML output. And for Email::Address::XS module is looks like:
>> https://metacpan.org/pod/Email::Address::XS
>> 
>> So, I would like to ask, how can be HTML output generated from perl
>> manpages improved (process: POD --> mandoc --> HTML), so documentation
>> would be more close to the native HTML output (process: POD --> HTML)?
>> 
>> I understand that something like syntax highlighting is not possible,
>> but if you look at differences, in HTML output from mandoc are broken
>> vertical spaces (some are totally missing)

At first, i got confused because your report isn't really related
to the POD format at all (but your mail misled me to think so),
because your English is slightly hard to understand, because the
actual bug you were trying to report was well hidden near the end
of the text, because you only vaguely alluded to what was wrong with
the output without being specific, and because i couldn't readily
access the actual source document you were trying to format - and
then i forgot about the report.  Sorry for the delay!

>> or missing all different font families.

I'm still not sure what you are alluding to here - can you be more
specific?

>> If problem is in POD --> manpage converter (Pod::Man module), I can
>> look at it.

In general, that is not very likely.  Pod2man is very stable software
that rarely changes nowadays, and i hardly ever found a bug in it -
well, maybe one in a decade or so.

Besides, even if pod2man(1) would contain a bug, mandoc(1) should
possibly try to cope because pod2man(1) is so stable and widespread
that whatever it does can almost be considered a feature.

>> But at the first I would need to know what mandoc is able to
>> process and what not.

Most of that is documented in the man(7) and roff(7) manual pages
included in the mandoc distribution.  To explain more details, i
would need a more specific question - which feature is it that
you feel unsure whether mandoc implements it or not?

Besides, (new) manual pages should really only use a tiny fraction
of the features implemented in mandoc.  Most of the functionality
is provided purely fo backward compatibility.

> Just to note, raw manpage (generated by Pod::Man) is available there:
> https://manpages.debian.org/Email::Address::XS.3pm.en.gz

Oh yes, that link is helpful, and thanks for the reminder.

> And viewing it on terminal does not case problems with vertical spaces
> like in HTML output.
> 
> So it is problem in mandoc HTML generator?

Yes, in the mandoc -man -Thtml formatter; i fixed it with the
commit appended below.

In general, finding problems in -man -Thtml output is still more
likely than in -mdoc -Thtml because the man(7) language is much
more complicated than mdoc(7), much less suited to translation to
HTML because it is purely presentational, and much less used in
practice, so mostly untested.

Thanks for the report and sorry again for the delay,
  Ingo


Log Message:
-----------
Input lines that are not blank but generate no output,
for example lines containing nothing but "\&", are significant
in no-fill mode and can be represented by blank lines inside <pre>.
Fixing a bug that Pali dot Rohar at gmail dot com found
in pod2man(1) output, for example Email::Address::XS(3p).

While here, inside no-fill mode, there is no need to encode
totally blank input lines by emulating .PP - just let them
through as we are inside <pre> anyway.

Modified Files:
--------------
    mandoc:
        man_html.c

Revision Data
-------------
Index: man_html.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/man_html.c,v
retrieving revision 1.156
retrieving revision 1.157
diff -Lman_html.c -Lman_html.c -u -p -r1.156 -r1.157
--- man_html.c
+++ man_html.c
@@ -264,7 +264,7 @@ print_man_node(MAN_ARGS)
 		    n->flags & NODE_LINE && *n->string == ' ' &&
 		    (h->flags & HTML_NONEWLINE) == 0)
 			print_otag(h, TAG_BR, "");
-		if (*n->string != '\0')
+		if (want_fillmode == MAN_nf || *n->string != '\0')
 			break;
 		print_paragraph(h);
 		return;
@@ -338,8 +338,11 @@ print_man_node(MAN_ARGS)
 	print_stagq(h, t);
 
 	if (fillmode(h, 0) == MAN_nf &&
-	    n->next != NULL && n->next->flags & NODE_LINE)
+	    n->next != NULL && n->next->flags & NODE_LINE) {
+		/* In .nf = <pre>, print even empty lines. */
+		h->col++;
 		print_endline(h);
+	}
 }
 
 /*
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: mandoc & perl documentation

[Pali Rohár]

On Tuesday 23 October 2018 19:45:45 Ingo Schwarze wrote:
> Hi Pali,
> 
> Pali Rohar wrote on Thu, Oct 11, 2018 at 09:52:47AM +0200:
> > On Thursday 13 September 2018 17:12:26 Pali Rohar wrote:
> 
> >> In perl world is documentation for perl modules or perl scripts writing
> >> in the POD format. Build process for perl scripts/modules then convert
> >> POD documentation into manpages and install it into standard system
> >> location.
> >> 
> >> I looked at Debian manpages which uses mandoc for converting man pages
> >> to HTML and basically documentation for perl modules is not good.
> >> 
> >> For example this is HTMLized manpage for Email::Address::XS perl module:
> >> https://manpages.debian.org/Email::Address::XS
> >> 
> >> There is also converting tool which formats POD documentation directly
> >> into HTML output. And for Email::Address::XS module is looks like:
> >> https://metacpan.org/pod/Email::Address::XS
> >> 
> >> So, I would like to ask, how can be HTML output generated from perl
> >> manpages improved (process: POD --> mandoc --> HTML), so documentation
> >> would be more close to the native HTML output (process: POD --> HTML)?
> >> 
> >> I understand that something like syntax highlighting is not possible,
> >> but if you look at differences, in HTML output from mandoc are broken
> >> vertical spaces (some are totally missing)
> 
> At first, i got confused because your report isn't really related
> to the POD format at all (but your mail misled me to think so),
> because your English is slightly hard to understand, because the
> actual bug you were trying to report was well hidden near the end
> of the text, because you only vaguely alluded to what was wrong with
> the output without being specific, and because i couldn't readily
> access the actual source document you were trying to format - and
> then i forgot about the report.  Sorry for the delay!

Hi Ingo!

Sorry for that. English is not my native language and I guessed that
problem could be in Pod::Man...

> >> or missing all different font families.
> 
> I'm still not sure what you are alluding to here - can you be more
> specific?

Different font families. E.g. directive C<...> in POD switches font
family to typewriter/monospaced, I<...> to italic, B<...> to bold...

Looks like that bold and italic families are working.

But typewriter/monospaced font is somehow ignored or unsupported in html
output from mandoc.

If you look at the output for Email::Address::XS, then whole SYNOPSIS
should be written in typewriter/monospaced font. Or e.g. section
"Deprecated Functions and Variables" has also some keywords in
monospaced font and remaining parts are in normal/roman font. Compare it
with html output on metacpan to see how it should look like.

> >> If problem is in POD --> manpage converter (Pod::Man module), I can
> >> look at it.
> 
> In general, that is not very likely.  Pod2man is very stable software
> that rarely changes nowadays, and i hardly ever found a bug in it -
> well, maybe one in a decade or so.
> 
> Besides, even if pod2man(1) would contain a bug, mandoc(1) should
> possibly try to cope because pod2man(1) is so stable and widespread
> that whatever it does can almost be considered a feature.

Ok. But seems that Pod::Man is still under development and fixes bugs...
https://metacpan.org/changes/distribution/podlators

> >> But at the first I would need to know what mandoc is able to
> >> process and what not.
> 
> Most of that is documented in the man(7) and roff(7) manual pages
> included in the mandoc distribution.  To explain more details, i
> would need a more specific question - which feature is it that
> you feel unsure whether mandoc implements it or not?
> 
> Besides, (new) manual pages should really only use a tiny fraction
> of the features implemented in mandoc.  Most of the functionality
> is provided purely fo backward compatibility.
> 
> > Just to note, raw manpage (generated by Pod::Man) is available there:
> > https://manpages.debian.org/Email::Address::XS.3pm.en.gz
> 
> Oh yes, that link is helpful, and thanks for the reminder.

Btw, link to raw manpage is also in the upper right corner of HTMLized
Debian page.

> > And viewing it on terminal does not case problems with vertical spaces
> > like in HTML output.
> > 
> > So it is problem in mandoc HTML generator?
> 
> Yes, in the mandoc -man -Thtml formatter; i fixed it with the
> commit appended below.

Great, thank you!

> In general, finding problems in -man -Thtml output is still more
> likely than in -mdoc -Thtml because the man(7) language is much
> more complicated than mdoc(7), much less suited to translation to
> HTML because it is purely presentational, and much less used in
> practice, so mostly untested.
> 
> Thanks for the report and sorry again for the delay,
>   Ingo
> 
> 
> Log Message:
> -----------
> Input lines that are not blank but generate no output,
> for example lines containing nothing but "\&", are significant
> in no-fill mode and can be represented by blank lines inside <pre>.
> Fixing a bug that Pali dot Rohar at gmail dot com found
> in pod2man(1) output, for example Email::Address::XS(3p).
> 
> While here, inside no-fill mode, there is no need to encode
> totally blank input lines by emulating .PP - just let them
> through as we are inside <pre> anyway.
> 
> Modified Files:
> --------------
>     mandoc:
>         man_html.c
> 
> Revision Data
> -------------
> Index: man_html.c
> ===================================================================
> RCS file: /home/cvs/mandoc/mandoc/man_html.c,v
> retrieving revision 1.156
> retrieving revision 1.157
> diff -Lman_html.c -Lman_html.c -u -p -r1.156 -r1.157
> --- man_html.c
> +++ man_html.c
> @@ -264,7 +264,7 @@ print_man_node(MAN_ARGS)
>  		    n->flags & NODE_LINE && *n->string == ' ' &&
>  		    (h->flags & HTML_NONEWLINE) == 0)
>  			print_otag(h, TAG_BR, "");
> -		if (*n->string != '\0')
> +		if (want_fillmode == MAN_nf || *n->string != '\0')
>  			break;
>  		print_paragraph(h);
>  		return;
> @@ -338,8 +338,11 @@ print_man_node(MAN_ARGS)
>  	print_stagq(h, t);
>  
>  	if (fillmode(h, 0) == MAN_nf &&
> -	    n->next != NULL && n->next->flags & NODE_LINE)
> +	    n->next != NULL && n->next->flags & NODE_LINE) {
> +		/* In .nf = <pre>, print even empty lines. */
> +		h->col++;
>  		print_endline(h);
> +	}
>  }
>  
>  /*

-- 
Pali Rohár
pali.rohar@gmail.com
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: mandoc & perl documentation

[Ingo Schwarze]

Hi Pali,

Pali Rohar wrote on Wed, Oct 24, 2018 at 10:03:22AM +0200:

> Different font families. E.g. directive C<...> in POD switches font
> family to typewriter/monospaced, I<...> to italic, B<...> to bold...

Oh.  Italic and bold are not font *families*, but font *styles*.
Font families are things like Times, Garamond, and Helvetica.
Groff does support switching these, but fortunately nobody uses
that in manual pages, so mandoc(1) doesn't provide font family
support at all, except that it parses and ignores the \fam request.

> Looks like that bold and italic families are working.
>
> But typewriter/monospaced font is somehow ignored or unsupported
> in html output from mandoc.

Not in general.  Look at

  https://man.openbsd.org/strlcpy
  https://man.openbsd.org/environ

For example, code samples and environment variables *are* set in
typewriter/monospaced font.

> If you look at the output for Email::Address::XS, then whole
> SYNOPSIS should be written in typewriter/monospaced font.

On the one hand, no, a SYNOPSIS should absolutely not be written
in typewriter/monospaced font, consider stuff like

  https://man.openbsd.org/rpc

which would look even more horrible than it already does.

On the other hand, manpages.debian.org renders absolutely *everything*
in typewriter/monospaced font.  That is a conscious choice by Michael
Stapelberg (the Debian developer who built and maintains the server,
including being the author of critical parts of the software running
on it).  I mildly disagree with that specific choice.  His rationale
is that manual pages have traditionally been presented in monospaced
font and people have become used to it.  But i don't think anybody
would have problems reading running text in proportional font, and
people will quickly get used to it - in particular since almost
nothing else they read on the web uses a monospaced font as the
main text font.  I don't think it is wise to artificially make
manual pages look archaic.

Anyway, that choice of course kills the distinction between
proportional and monospaced font, even where that distinction could
be derived from the markup that is present in the manual page source
code.

> Or e.g. section
> "Deprecated Functions and Variables" has also some keywords in
> monospaced font and remaining parts are in normal/roman font.
> Compare it with html output on metacpan to see how it should look like.

Indeed, you found another bug.
Thank you very much, in particular for the more specific explanation!

I fixed it with the commit below and also installed the improved
code on man.openbsd.org right away such that you can look at Perl
manuals and see whether it helps, for example

  https://man.openbsd.org/strict

Of course, only core Perl manuals are available on that site, not
the whole of CPAN.

> Btw, link to raw manpage is also in the upper right corner of
> HTMLized Debian page.

Oh, good point, i should have remembered that from my joint work with
Michael, or just seen it when looking at the page...

Thanks again for your useful reports, even though i have been
somewhat slow at understanding them!

Yours,
  Ingo


Log Message:
-----------
Implement the \f(CW and \f(CR (constant width font) escape sequences
for HTML output.  Somewhat relevant because pod2man(1) relies on this.
Missing feature reported by Pali dot Rohar at gmail dot com.

Note that constant width font was already correctly selected before
this when required by semantic markup.  Only attempting physical
markup with the low-level escape sequence was ineffective.

Modified Files:
--------------
    mandoc:
        html.c
        html.h
        mandoc.c
        mandoc.h
        mdoc_markdown.c
        roff.c
        term.c

Revision Data
-------------
Index: term.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/term.c,v
retrieving revision 1.275
retrieving revision 1.276
diff -Lterm.c -Lterm.c -u -p -r1.275 -r1.276
--- term.c
+++ term.c
@@ -510,6 +510,7 @@ term_word(struct termp *p, const char *w
 			term_fontrepl(p, TERMFONT_BI);
 			continue;
 		case ESCAPE_FONT:
+		case ESCAPE_FONTCW:
 		case ESCAPE_FONTROMAN:
 			term_fontrepl(p, TERMFONT_NONE);
 			continue;
Index: mandoc.h
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mandoc.h,v
retrieving revision 1.253
retrieving revision 1.254
diff -Lmandoc.h -Lmandoc.h -u -p -r1.253 -r1.254
--- mandoc.h
+++ mandoc.h
@@ -438,6 +438,7 @@ enum	mandoc_esc {
 	ESCAPE_FONTITALIC, /* italic font mode */
 	ESCAPE_FONTBI, /* bold italic font mode */
 	ESCAPE_FONTROMAN, /* roman font mode */
+	ESCAPE_FONTCW, /* constant width font mode */
 	ESCAPE_FONTPREV, /* previous font mode */
 	ESCAPE_NUMBERED, /* a numbered glyph */
 	ESCAPE_UNICODE, /* a unicode codepoint */
Index: mdoc_markdown.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mdoc_markdown.c,v
retrieving revision 1.26
retrieving revision 1.27
diff -Lmdoc_markdown.c -Lmdoc_markdown.c -u -p -r1.26 -r1.27
--- mdoc_markdown.c
+++ mdoc_markdown.c
@@ -600,6 +600,7 @@ md_word(const char *s)
 				nextfont = "***";
 				break;
 			case ESCAPE_FONT:
+			case ESCAPE_FONTCW:
 			case ESCAPE_FONTROMAN:
 				nextfont = "";
 				break;
Index: html.h
===================================================================
RCS file: /home/cvs/mandoc/mandoc/html.h,v
retrieving revision 1.94
retrieving revision 1.95
diff -Lhtml.h -Lhtml.h -u -p -r1.94 -r1.95
--- html.h
+++ html.h
@@ -72,6 +72,7 @@ enum	htmlfont {
 	HTMLFONT_BOLD,
 	HTMLFONT_ITALIC,
 	HTMLFONT_BI,
+	HTMLFONT_CW,
 	HTMLFONT_MAX
 };
 
Index: mandoc.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mandoc.c,v
retrieving revision 1.107
retrieving revision 1.108
diff -Lmandoc.c -Lmandoc.c -u -p -r1.107 -r1.108
--- mandoc.c
+++ mandoc.c
@@ -304,8 +304,13 @@ mandoc_escape(const char **end, const ch
 	case ESCAPE_FONT:
 		if (*sz == 2) {
 			if (**start == 'C') {
+				if ((*start)[1] == 'W' ||
+				    (*start)[1] == 'R') {
+					gly = ESCAPE_FONTCW;
+					break;
+				}
 				/*
-				 * Treat constant-width font modes
+				 * Treat other constant-width font modes
 				 * just like regular font modes.
 				 */
 				(*start)++;
Index: roff.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/roff.c,v
retrieving revision 1.341
retrieving revision 1.342
diff -Lroff.c -Lroff.c -u -p -r1.341 -r1.342
--- roff.c
+++ roff.c
@@ -3361,6 +3361,7 @@ roff_char(ROFF_ARGS)
 		case ESCAPE_FONTITALIC:
 		case ESCAPE_FONTBOLD:
 		case ESCAPE_FONTBI:
+		case ESCAPE_FONTCW:
 		case ESCAPE_FONTPREV:
 			font++;
 			break;
Index: html.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/html.c,v
retrieving revision 1.241
retrieving revision 1.242
diff -Lhtml.c -Lhtml.c -u -p -r1.241 -r1.242
--- html.c
+++ html.c
@@ -228,6 +228,9 @@ print_metaf(struct html *h, enum mandoc_
 	case ESCAPE_FONTBI:
 		font = HTMLFONT_BI;
 		break;
+	case ESCAPE_FONTCW:
+		font = HTMLFONT_CW;
+		break;
 	case ESCAPE_FONT:
 	case ESCAPE_FONTROMAN:
 		font = HTMLFONT_NONE;
@@ -255,6 +258,9 @@ print_metaf(struct html *h, enum mandoc_
 		h->metaf = print_otag(h, TAG_B, "");
 		print_otag(h, TAG_I, "");
 		break;
+	case HTMLFONT_CW:
+		h->metaf = print_otag(h, TAG_SPAN, "c", "Li");
+		break;
 	default:
 		break;
 	}
@@ -408,6 +414,7 @@ print_encode(struct html *h, const char 
 		case ESCAPE_FONTBOLD:
 		case ESCAPE_FONTITALIC:
 		case ESCAPE_FONTBI:
+		case ESCAPE_FONTCW:
 		case ESCAPE_FONTROMAN:
 			if (0 == norecurse)
 				print_metaf(h, esc);
@@ -737,6 +744,9 @@ print_text(struct html *h, const char *w
 	case HTMLFONT_BI:
 		h->metaf = print_otag(h, TAG_B, "");
 		print_otag(h, TAG_I, "");
+		break;
+	case HTMLFONT_CW:
+		h->metaf = print_otag(h, TAG_SPAN, "c", "Li");
 		break;
 	default:
 		print_indent(h);
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: mandoc & perl documentation

[Pali Rohár]

Hi!

On Thursday 25 October 2018 03:51:33 Ingo Schwarze wrote:
> Hi Pali,
> 
> Pali Rohar wrote on Wed, Oct 24, 2018 at 10:03:22AM +0200:
> 
> > Different font families. E.g. directive C<...> in POD switches font
> > family to typewriter/monospaced, I<...> to italic, B<...> to bold...
> 
> Oh.  Italic and bold are not font *families*, but font *styles*.
> Font families are things like Times, Garamond, and Helvetica.
> Groff does support switching these, but fortunately nobody uses
> that in manual pages, so mandoc(1) doesn't provide font family
> support at all, except that it parses and ignores the \fam request.

Alright!

> > Looks like that bold and italic families are working.
> >
> > But typewriter/monospaced font is somehow ignored or unsupported
> > in html output from mandoc.
> 
> Not in general.  Look at
> 
>   https://man.openbsd.org/strlcpy
>   https://man.openbsd.org/environ
> 
> For example, code samples and environment variables *are* set in
> typewriter/monospaced font.
> 
> > If you look at the output for Email::Address::XS, then whole
> > SYNOPSIS should be written in typewriter/monospaced font.
> 
> On the one hand, no, a SYNOPSIS should absolutely not be written
> in typewriter/monospaced font, consider stuff like
> 
>   https://man.openbsd.org/rpc
> 
> which would look even more horrible than it already does.

In perl documentation it is very common to put code examples into
SYNOPSIS and code examples should be really in monospaced font.

rpc manpage has function prototypes in SYNOPSIS, so it is probably
different thing.

> On the other hand, manpages.debian.org renders absolutely *everything*
> in typewriter/monospaced font.

Yes, I saw it.

> That is a conscious choice by Michael
> Stapelberg (the Debian developer who built and maintains the server,
> including being the author of critical parts of the software running
> on it).  I mildly disagree with that specific choice.  His rationale
> is that manual pages have traditionally been presented in monospaced
> font and people have become used to it.

This is because terminals in most cases do not support non-monospaced
fonts.

> But i don't think anybody
> would have problems reading running text in proportional font, and
> people will quickly get used to it - in particular since almost
> nothing else they read on the web uses a monospaced font as the
> main text font.  I don't think it is wise to artificially make
> manual pages look archaic.

I agree with this. E.g. documentation for cpan modules on metacpan.org
is very very similar to documentation in system manpages, use more font
styles (not only monospaced) and looks much better.

> Anyway, that choice of course kills the distinction between
> proportional and monospaced font, even where that distinction could
> be derived from the markup that is present in the manual page source
> code.

I see that output of monospaced font on debian manpage server is put
into double quotes.

> > Or e.g. section
> > "Deprecated Functions and Variables" has also some keywords in
> > monospaced font and remaining parts are in normal/roman font.
> > Compare it with html output on metacpan to see how it should look like.
> 
> Indeed, you found another bug.
> Thank you very much, in particular for the more specific explanation!
> 
> I fixed it with the commit below and also installed the improved
> code on man.openbsd.org right away such that you can look at Perl
> manuals and see whether it helps, for example
> 
>   https://man.openbsd.org/strict

That is much better! Thank you.

I have there 3 points:

1) It is still needed to double quote text which is written in
monospaced font?

Compare first sentence in DESCRIPTION https://man.openbsd.org/strict and
https://metacpan.org/pod/strict On man.openbsd is word "strict" put into
double quotes, but on metacpan not.

2) When I try to select any code block (e.g. SYNOPSIS or "strict subs"
section) on man.openbsd, then every code line is prefixed by four
spaces. When I select it on metacpan, then there is no leading space. Is
there particular reason for it?

3) On that https://man.openbsd.org/strict page is section name "strict
refs" fully invisible. It is joined together with previous paragraph and
also with description of that section. Reader does not see that there is
paragraph about "strict refs" section. It should be visually separated.
To compare, look at metacpan page and search for "strict refs".

> Of course, only core Perl manuals are available on that site, not
> the whole of CPAN.
> 
> > Btw, link to raw manpage is also in the upper right corner of
> > HTMLized Debian page.
> 
> Oh, good point, i should have remembered that from my joint work with
> Michael, or just seen it when looking at the page...
> 
> Thanks again for your useful reports, even though i have been
> somewhat slow at understanding them!

No problem! I'm happy even with slow improvements in rendering manpages.

> Yours,
>   Ingo
> 
> 
> Log Message:
> -----------
> Implement the \f(CW and \f(CR (constant width font) escape sequences
> for HTML output.  Somewhat relevant because pod2man(1) relies on this.
> Missing feature reported by Pali dot Rohar at gmail dot com.
> 
> Note that constant width font was already correctly selected before
> this when required by semantic markup.  Only attempting physical
> markup with the low-level escape sequence was ineffective.
> 
> Modified Files:
> --------------
>     mandoc:
>         html.c
>         html.h
>         mandoc.c
>         mandoc.h
>         mdoc_markdown.c
>         roff.c
>         term.c
> 
> Revision Data
> -------------
> Index: term.c
> ===================================================================
> RCS file: /home/cvs/mandoc/mandoc/term.c,v
> retrieving revision 1.275
> retrieving revision 1.276
> diff -Lterm.c -Lterm.c -u -p -r1.275 -r1.276
> --- term.c
> +++ term.c
> @@ -510,6 +510,7 @@ term_word(struct termp *p, const char *w
>  			term_fontrepl(p, TERMFONT_BI);
>  			continue;
>  		case ESCAPE_FONT:
> +		case ESCAPE_FONTCW:
>  		case ESCAPE_FONTROMAN:
>  			term_fontrepl(p, TERMFONT_NONE);
>  			continue;
> Index: mandoc.h
> ===================================================================
> RCS file: /home/cvs/mandoc/mandoc/mandoc.h,v
> retrieving revision 1.253
> retrieving revision 1.254
> diff -Lmandoc.h -Lmandoc.h -u -p -r1.253 -r1.254
> --- mandoc.h
> +++ mandoc.h
> @@ -438,6 +438,7 @@ enum	mandoc_esc {
>  	ESCAPE_FONTITALIC, /* italic font mode */
>  	ESCAPE_FONTBI, /* bold italic font mode */
>  	ESCAPE_FONTROMAN, /* roman font mode */
> +	ESCAPE_FONTCW, /* constant width font mode */
>  	ESCAPE_FONTPREV, /* previous font mode */
>  	ESCAPE_NUMBERED, /* a numbered glyph */
>  	ESCAPE_UNICODE, /* a unicode codepoint */
> Index: mdoc_markdown.c
> ===================================================================
> RCS file: /home/cvs/mandoc/mandoc/mdoc_markdown.c,v
> retrieving revision 1.26
> retrieving revision 1.27
> diff -Lmdoc_markdown.c -Lmdoc_markdown.c -u -p -r1.26 -r1.27
> --- mdoc_markdown.c
> +++ mdoc_markdown.c
> @@ -600,6 +600,7 @@ md_word(const char *s)
>  				nextfont = "***";
>  				break;
>  			case ESCAPE_FONT:
> +			case ESCAPE_FONTCW:
>  			case ESCAPE_FONTROMAN:
>  				nextfont = "";
>  				break;
> Index: html.h
> ===================================================================
> RCS file: /home/cvs/mandoc/mandoc/html.h,v
> retrieving revision 1.94
> retrieving revision 1.95
> diff -Lhtml.h -Lhtml.h -u -p -r1.94 -r1.95
> --- html.h
> +++ html.h
> @@ -72,6 +72,7 @@ enum	htmlfont {
>  	HTMLFONT_BOLD,
>  	HTMLFONT_ITALIC,
>  	HTMLFONT_BI,
> +	HTMLFONT_CW,
>  	HTMLFONT_MAX
>  };
>  
> Index: mandoc.c
> ===================================================================
> RCS file: /home/cvs/mandoc/mandoc/mandoc.c,v
> retrieving revision 1.107
> retrieving revision 1.108
> diff -Lmandoc.c -Lmandoc.c -u -p -r1.107 -r1.108
> --- mandoc.c
> +++ mandoc.c
> @@ -304,8 +304,13 @@ mandoc_escape(const char **end, const ch
>  	case ESCAPE_FONT:
>  		if (*sz == 2) {
>  			if (**start == 'C') {
> +				if ((*start)[1] == 'W' ||
> +				    (*start)[1] == 'R') {
> +					gly = ESCAPE_FONTCW;
> +					break;
> +				}
>  				/*
> -				 * Treat constant-width font modes
> +				 * Treat other constant-width font modes
>  				 * just like regular font modes.
>  				 */
>  				(*start)++;
> Index: roff.c
> ===================================================================
> RCS file: /home/cvs/mandoc/mandoc/roff.c,v
> retrieving revision 1.341
> retrieving revision 1.342
> diff -Lroff.c -Lroff.c -u -p -r1.341 -r1.342
> --- roff.c
> +++ roff.c
> @@ -3361,6 +3361,7 @@ roff_char(ROFF_ARGS)
>  		case ESCAPE_FONTITALIC:
>  		case ESCAPE_FONTBOLD:
>  		case ESCAPE_FONTBI:
> +		case ESCAPE_FONTCW:
>  		case ESCAPE_FONTPREV:
>  			font++;
>  			break;
> Index: html.c
> ===================================================================
> RCS file: /home/cvs/mandoc/mandoc/html.c,v
> retrieving revision 1.241
> retrieving revision 1.242
> diff -Lhtml.c -Lhtml.c -u -p -r1.241 -r1.242
> --- html.c
> +++ html.c
> @@ -228,6 +228,9 @@ print_metaf(struct html *h, enum mandoc_
>  	case ESCAPE_FONTBI:
>  		font = HTMLFONT_BI;
>  		break;
> +	case ESCAPE_FONTCW:
> +		font = HTMLFONT_CW;
> +		break;
>  	case ESCAPE_FONT:
>  	case ESCAPE_FONTROMAN:
>  		font = HTMLFONT_NONE;
> @@ -255,6 +258,9 @@ print_metaf(struct html *h, enum mandoc_
>  		h->metaf = print_otag(h, TAG_B, "");
>  		print_otag(h, TAG_I, "");
>  		break;
> +	case HTMLFONT_CW:
> +		h->metaf = print_otag(h, TAG_SPAN, "c", "Li");
> +		break;
>  	default:
>  		break;
>  	}
> @@ -408,6 +414,7 @@ print_encode(struct html *h, const char 
>  		case ESCAPE_FONTBOLD:
>  		case ESCAPE_FONTITALIC:
>  		case ESCAPE_FONTBI:
> +		case ESCAPE_FONTCW:
>  		case ESCAPE_FONTROMAN:
>  			if (0 == norecurse)
>  				print_metaf(h, esc);
> @@ -737,6 +744,9 @@ print_text(struct html *h, const char *w
>  	case HTMLFONT_BI:
>  		h->metaf = print_otag(h, TAG_B, "");
>  		print_otag(h, TAG_I, "");
> +		break;
> +	case HTMLFONT_CW:
> +		h->metaf = print_otag(h, TAG_SPAN, "c", "Li");
>  		break;
>  	default:
>  		print_indent(h);

-- 
Pali Rohár
pali.rohar@gmail.com
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: mandoc & perl documentation

[Ingo Schwarze]

Hi Pali,

Pali Rohar wrote on Thu, Oct 25, 2018 at 10:10:35AM +0200:
> On Thursday 25 October 2018 03:51:33 Ingo Schwarze wrote:
> > Pali Rohar wrote on Wed, Oct 24, 2018 at 10:03:22AM +0200:

> In perl documentation it is very common to put code examples
> into SYNOPSIS

That is abuse and should not be done.

The SYNOPSIS must only contain authoritative information
and must be as concise as possible.
Examples belong below EXAMPLES and nowhere else.

> and code examples should be really in monospaced font.

Yes, that is true.

> E.g. documentation for cpan modules on metacpan.org
> is very very similar to documentation in system manpages, use more font
> styles (not only monospaced) and looks much better.

Strictly speaking, "monospaced" is a super-family (for example, the
Helvetica family is a proportional family and Courier is a
monospaced family).  But since mandoc does not bother with families
at all, it somewhat incorrectly implements "monospaced" as a font
style alongside roman, bold, italic, and bold-italic.

That said, which other font styles does metacpan.org use besides
roman, bold, italic, and the pseudo-style "monospaced", and what
for?  Having a brief look, i failed to find any.

> I see that output of monospaced font on debian manpage server is put
> into double quotes.

Well, that is pod2man(2)'s doing.  At many places, it says things like

  .ie n .IP """strict refs""" 6
  .el .IP "\f(CWstrict refs\fR" 6

Translating that into plain English in case you are not too familiar
with the admittedly weird roff(7) syntax:

  If we are formatting for non-typesetting output, emit a list tag
  starting with one '"' character, containing the words "strict
  refs", and ending with a matching quote, in a field 6 columns wide;
  otherwise, i.e. when formatting for typeset output (like PostScript
  or PDF), switch to constant width font for the tag, print the
  words "strict refs", and switch to roman font, again in a field
  6 columns wide (with no quotes in this case).

Mandoc always formats for non-typesetting output, so it always gets
the quotes and never switches to constant width font for this
particular input.

This is one of the relatively rare cases where pod2man(1) is doing
something that is a bad idea.  First, in my personal opinion, manual
pages should not use if-statements; though some might argue that in
this case, to get the quotes for terminal output, it might be justified.
But i think the quotes are irrelevant: Because the "strict ref" is
located in a list tag, it is already obvious it is a syntax element
being defined and not some running English text.

Even more importantly, even if pod2man(1) insists on the .ie and
on the quotes, then it should at least say

  .ie n .IP """\f(CWstrict refs\f(CW""" 6
  .el .IP "\f(CWstrict refs\fR" 6

Some non-typesetting output devices (like mandoc HTML) do support
constant width font, so why not tell them?  In particular given
that the running text right below heavily uses \f(CW no matter what:

  This generates a compile-time error if you access a variable that
  was neither explicitly declared (using any of \f(CW\*(C`my\*(C'\fR,
  \f(CW\*(C`our\*(C'\fR, \f(CW\*(C`state\*(C'\fR, ...

You said you could possibly help to improve pod2man(1).  Do you
think you could ask them to get this particular kind of .IP fixed?
Preferably to simply

  .IP "\f(CWstrict refs\fR" 6

or if they really want quotes even in .IP to

  .IP "\f(CW\*(C`strict refs\*(C'\fR" 6

either way without any "if", or if they totally insist at least to

  .ie n .IP """\f(CWstrict refs\f(CW""" 6
  .el .IP "\f(CWstrict refs\fR" 6

> 1) It is still needed to double quote text which is written in
> monospaced font?

In .IP, I don't think so.  I think it was never needed, see above.
But that would have to be changed in pod2man(1), not in mandoc(1).

And no, i cannot change mandoc(1) to attempt rendering for real
typesetting devices.  Code protected by ".if t" or ".ie n .el"
typically uses even more scary low-level roff(7) features that
mandoc doesn't, and can hardly, implement.

> Compare first sentence in DESCRIPTION https://man.openbsd.org/strict and
> https://metacpan.org/pod/strict On man.openbsd is word "strict" put into
> double quotes, but on metacpan not.

That is again a choice by pod2man(1), which this time makes more sense.
The preamble emitted by pod2man(1) defines a strings named "C`" and "C'"
as empty string on typesetting devices and as quotes on non-typesetting
devices, and the main code emitted by pod2man(1) then uses the
idioms "\f(CW\*(C" and "\*(C'\fR" to begin and end in-line code snippets,
such that those get typeset in proportional font without quotes on
typesetting devices and such that they get quoted on terminals -
and, collaterally, *both* set in proportional font and quoted on
non-typesetter devices that support proportional font like mandoc(1)
HTML output.

I think little can be done here.  You probably do not want to take
away *these* quotes because that would make the word look like
running text on the terminal.  And there is no way for the document
to query whether monospace font looks different from the default
font on the current output device, so the ".if n" kludge is half
reasonable.

> 2) When I try to select any code block (e.g. SYNOPSIS or "strict subs"
> section) on man.openbsd, then every code line is prefixed by four
> spaces. When I select it on metacpan, then there is no leading space. Is
> there particular reason for it?

The perlpod(1) manual defines:

   Verbatim Paragraph
       Verbatim paragraphs are usually used for presenting a codeblock
       or other text which does not require any special parsing or
       formatting, and which shouldn't be wrapped.

       A verbatim paragraph is distinguished by having its first
       character be a space or a tab.  (And commonly, all its lines
       begin with spaces and/or tabs.)  It should be reproduced
       exactly, with tabs assumed to be on 8-column boundaries.

The source code of the strict(3p) manual looks like this:

  $ less /usr/src/gnu/usr.bin/perl/lib/strict.pm
  [...]
  =head1 SYNOPSIS

      use strict;

      use strict "vars";
      use strict "refs";
      use strict "subs";
  [...]

So the four space indentation is in the source code.  It's not
totally clear to me what "reproduced exactly" is supposed to mean,
but pod2man(1)'s interpretation that this whitespace should be
preserved doesn't seem totally unreasonable.  It translates
to man(7) as follows:

  $ less $(man -w strict)
  [...]
  .SH "SYNOPSIS"
  .IX Header "SYNOPSIS"
  .Vb 1
  \&    use strict;
  \&
  \&    use strict "vars";
  \&    use strict "refs";
  \&    use strict "subs";
  [...]

I'm not convinced it would be better for pod2man(1) to strip this
whitespace because on the terminal, the code block would not be
distinguished from running text, neither by font nor by indentation.

> 3) On that https://man.openbsd.org/strict page is section name "strict
> refs" fully invisible. It is joined together with previous paragraph and
> also with description of that section. Reader does not see that there is
> paragraph about "strict refs" section. It should be visually separated.
> To compare, look at metacpan page and search for "strict refs".

That is not a section name, not even a subsection name, but merely a
list tag formatted as follows:

  =over 6

  =item C<strict refs>

So the vertical spacing that metacpan does *after* the list tag looks
dubious for me - doesn't that make many other lists look bad?

But you are right that there should be vertical spacing *before*
the list tag.  However, that is very hard to fix in mandoc.css;
the CSS code for ".Bl-tag > dt" (using float) is already excessively
complicated and only barely works.  It is not possible to add some
margin-top to it without breaking it.  Numerous attempts of many
people to improve it have failed.  At EuroBSDCon 2018, i met a
colleague who talked about some new CSS feature that makes formatting
of tagged lists work better if you want short tags left of the body
and long tags above the body.  He promised to send me details, but
didn't come back to me yet.

For now, i have made a TODO entry.

Yours,
  Ingo


Log Message:
-----------
in -man -Thtml, vertical spacing is required before .IP

Modified Files:
--------------
    mandoc:
        TODO

Revision Data
-------------
Index: TODO
===================================================================
RCS file: /home/cvs/mandoc/mandoc/TODO,v
retrieving revision 1.273
retrieving revision 1.274
diff -LTODO -LTODO -u -p -r1.273 -r1.274
--- TODO
+++ TODO
@@ -397,6 +397,12 @@ are mere guesses, and some may be wrong.
    it does seem cleaner.)
   loc **  exist **  algo *  size *  imp ***
 
+- .IP wants vertical spacing before itself;
+  currently, it is formatted like .Bl -compact.
+  Fixing this requires getting rid of the "float"
+  in the CSS for .Bl-tag first.
+  Reminded by Pali Rohar 25 Oct 2018 10:10:35 +0200.
+
 - format ".IP *" etc. as <ul> rather than <dl>
   https://github.com/Debian/debiman/issues/67
   loc ** exist ** algo ** size * imp ***
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: mandoc & perl documentation

[Pali Rohár]

Hi!

On Thursday 25 October 2018 23:30:27 Ingo Schwarze wrote:
> Hi Pali,
> 
> Pali Rohar wrote on Thu, Oct 25, 2018 at 10:10:35AM +0200:
> > On Thursday 25 October 2018 03:51:33 Ingo Schwarze wrote:
> > > Pali Rohar wrote on Wed, Oct 24, 2018 at 10:03:22AM +0200:
> 
> > In perl documentation it is very common to put code examples
> > into SYNOPSIS
> 
> That is abuse and should not be done.
> 
> The SYNOPSIS must only contain authoritative information
> and must be as concise as possible.
> Examples belong below EXAMPLES and nowhere else.
> 
> > and code examples should be really in monospaced font.
> 
> Yes, that is true.
> 
> > E.g. documentation for cpan modules on metacpan.org
> > is very very similar to documentation in system manpages, use more font
> > styles (not only monospaced) and looks much better.
> 
> Strictly speaking, "monospaced" is a super-family (for example, the
> Helvetica family is a proportional family and Courier is a
> monospaced family).  But since mandoc does not bother with families
> at all, it somewhat incorrectly implements "monospaced" as a font
> style alongside roman, bold, italic, and bold-italic.
> 
> That said, which other font styles does metacpan.org use besides
> roman, bold, italic, and the pseudo-style "monospaced", and what
> for?  Having a brief look, i failed to find any.

I<...> - italic text
B<...> - bold text
C<...> - code text in a typewriter font (indication that this
         represents program text or some other form of computerese)
F<...> - filenames, displayed in italics

And you can do any combination of them (e.g. typewriter font which is
both bold and italic together).

Mapping table to troff font styles in Pod::Man source code is here:
https://metacpan.org/source/RRA/podlators-4.11/lib/Pod/Man.pm#L190-205

> > I see that output of monospaced font on debian manpage server is put
> > into double quotes.
> 
> Well, that is pod2man(2)'s doing.  At many places, it says things like
> 
>   .ie n .IP """strict refs""" 6
>   .el .IP "\f(CWstrict refs\fR" 6
> 
> Translating that into plain English in case you are not too familiar
> with the admittedly weird roff(7) syntax:
> 
>   If we are formatting for non-typesetting output, emit a list tag
>   starting with one '"' character, containing the words "strict
>   refs", and ending with a matching quote, in a field 6 columns wide;
>   otherwise, i.e. when formatting for typeset output (like PostScript
>   or PDF), switch to constant width font for the tag, print the
>   words "strict refs", and switch to roman font, again in a field
>   6 columns wide (with no quotes in this case).
> 
> Mandoc always formats for non-typesetting output, so it always gets
> the quotes and never switches to constant width font for this
> particular input.
> 
> This is one of the relatively rare cases where pod2man(1) is doing
> something that is a bad idea.  First, in my personal opinion, manual
> pages should not use if-statements; though some might argue that in
> this case, to get the quotes for terminal output, it might be justified.
> But i think the quotes are irrelevant: Because the "strict ref" is
> located in a list tag, it is already obvious it is a syntax element
> being defined and not some running English text.
> 
> Even more importantly, even if pod2man(1) insists on the .ie and
> on the quotes, then it should at least say
> 
>   .ie n .IP """\f(CWstrict refs\f(CW""" 6
>   .el .IP "\f(CWstrict refs\fR" 6
> 
> Some non-typesetting output devices (like mandoc HTML) do support
> constant width font, so why not tell them?  In particular given
> that the running text right below heavily uses \f(CW no matter what:
> 
>   This generates a compile-time error if you access a variable that
>   was neither explicitly declared (using any of \f(CW\*(C`my\*(C'\fR,
>   \f(CW\*(C`our\*(C'\fR, \f(CW\*(C`state\*(C'\fR, ...

Now I'm looking into Pod::Man sources and that ".ie n" condition is
generated only at one place (there are comments in code):
https://metacpan.org/source/RRA/podlators-4.11/lib/Pod/Man.pm#L651-705

Plus decision if quoting is needed or not has some strange heuristic...
https://metacpan.org/source/RRA/podlators-4.11/lib/Pod/Man.pm#L419-454

Looks like a big mess.

> You said you could possibly help to improve pod2man(1).  Do you
> think you could ask them to get this particular kind of .IP fixed?
> Preferably to simply
> 
>   .IP "\f(CWstrict refs\fR" 6
> 
> or if they really want quotes even in .IP to
> 
>   .IP "\f(CW\*(C`strict refs\*(C'\fR" 6
> 
> either way without any "if", or if they totally insist at least to
> 
>   .ie n .IP """\f(CWstrict refs\f(CW""" 6
>   .el .IP "\f(CWstrict refs\fR" 6

Looks like that those ".ie n" conditions are there as a workaround for
some Solaris bugs.

Anyway, on terminal output everything is in typewriter/monospaced font,
so double quotes make sense on terminal as some optical visualization
that text is in different font style. For output devices which support
also different font styles and not only typewriter (html, ps, pdf, ...),
double quotes should not be used.

So I guess some condition is still needed. In groff it could be possible
to check for typewriter-like device via .T register, but such thing is
not portable...

I would ask maintainers of Pod::Man module what can be done with this
problem or how can be situation improved.

Question 1) below is just same problem as this.

> > 1) It is still needed to double quote text which is written in
> > monospaced font?
> 
> In .IP, I don't think so.  I think it was never needed, see above.
> But that would have to be changed in pod2man(1), not in mandoc(1).
> 
> And no, i cannot change mandoc(1) to attempt rendering for real
> typesetting devices.  Code protected by ".if t" or ".ie n .el"
> typically uses even more scary low-level roff(7) features that
> mandoc doesn't, and can hardly, implement.
> 
> > Compare first sentence in DESCRIPTION https://man.openbsd.org/strict and
> > https://metacpan.org/pod/strict On man.openbsd is word "strict" put into
> > double quotes, but on metacpan not.
> 
> That is again a choice by pod2man(1), which this time makes more sense.
> The preamble emitted by pod2man(1) defines a strings named "C`" and "C'"
> as empty string on typesetting devices and as quotes on non-typesetting
> devices, and the main code emitted by pod2man(1) then uses the
> idioms "\f(CW\*(C" and "\*(C'\fR" to begin and end in-line code snippets,
> such that those get typeset in proportional font without quotes on
> typesetting devices and such that they get quoted on terminals -
> and, collaterally, *both* set in proportional font and quoted on
> non-typesetter devices that support proportional font like mandoc(1)
> HTML output.
> 
> I think little can be done here.  You probably do not want to take
> away *these* quotes because that would make the word look like
> running text on the terminal.  And there is no way for the document
> to query whether monospace font looks different from the default
> font on the current output device, so the ".if n" kludge is half
> reasonable.
> 
> > 2) When I try to select any code block (e.g. SYNOPSIS or "strict subs"
> > section) on man.openbsd, then every code line is prefixed by four
> > spaces. When I select it on metacpan, then there is no leading space. Is
> > there particular reason for it?
> 
> The perlpod(1) manual defines:
> 
>    Verbatim Paragraph
>        Verbatim paragraphs are usually used for presenting a codeblock
>        or other text which does not require any special parsing or
>        formatting, and which shouldn't be wrapped.
> 
>        A verbatim paragraph is distinguished by having its first
>        character be a space or a tab.  (And commonly, all its lines
>        begin with spaces and/or tabs.)  It should be reproduced
>        exactly, with tabs assumed to be on 8-column boundaries.
> 
> The source code of the strict(3p) manual looks like this:
> 
>   $ less /usr/src/gnu/usr.bin/perl/lib/strict.pm
>   [...]
>   =head1 SYNOPSIS
> 
>       use strict;
> 
>       use strict "vars";
>       use strict "refs";
>       use strict "subs";
>   [...]
> 
> So the four space indentation is in the source code.  It's not)
> totally clear to me what "reproduced exactly" is supposed to mean,

Yea, this is also something which is not clear to me...

I tried to find something about it... and in Pod::Simple documentation
is explanation:

https://metacpan.org/pod/Pod::Simple#$parser-%3Estrip_verbatim_indent(-SOMEVALUE-)

Metacpan uses Pod::Simple::XHTML for converting POD to HTML and probably
has its own function which do some magic with these leading spaces in
source code blocks.

> but pod2man(1)'s interpretation that this whitespace should be
> preserved doesn't seem totally unreasonable.  It translates
> to man(7) as follows:
> 
>   $ less $(man -w strict)
>   [...]
>   .SH "SYNOPSIS"
>   .IX Header "SYNOPSIS"
>   .Vb 1
>   \&    use strict;
>   \&
>   \&    use strict "vars";
>   \&    use strict "refs";
>   \&    use strict "subs";
>   [...]
> 
> I'm not convinced it would be better for pod2man(1) to strip this
> whitespace because on the terminal, the code block would not be
> distinguished from running text, neither by font nor by indentation.

So mandoc here cannot do nothing.

> > 3) On that https://man.openbsd.org/strict page is section name "strict
> > refs" fully invisible. It is joined together with previous paragraph and
> > also with description of that section. Reader does not see that there is
> > paragraph about "strict refs" section. It should be visually separated.
> > To compare, look at metacpan page and search for "strict refs".
> 
> That is not a section name, not even a subsection name, but merely a
> list tag formatted as follows:
> 
>   =over 6
> 
>   =item C<strict refs>
> 
> So the vertical spacing that metacpan does *after* the list tag looks
> dubious for me - doesn't that make many other lists look bad?

=item directive is used lot of times for describing functions or methods
of some class.

In perlpod documentation is written:

And perhaps most importantly, keep the items consistent: either use
"=item *" for all of them, to produce bullets; or use "=item 1.",
"=item 2.", etc., to produce numbered lists; or use "=item foo",
"=item bar", etc.--namely, things that look nothing like bullets or
numbers. If you start with bullets or numbers, stick with them, as
formatters use the first "=item" type to decide how to format the list.

So it is questionable... Maybe bullets and numbers specified via =item
should be formatted differently as "=item text"?

> But you are right that there should be vertical spacing *before*
> the list tag.  However, that is very hard to fix in mandoc.css;
> the CSS code for ".Bl-tag > dt" (using float) is already excessively
> complicated and only barely works.  It is not possible to add some
> margin-top to it without breaking it.  Numerous attempts of many
> people to improve it have failed.  At EuroBSDCon 2018, i met a
> colleague who talked about some new CSS feature that makes formatting
> of tagged lists work better if you want short tags left of the body
> and long tags above the body.  He promised to send me details, but
> didn't come back to me yet.
> 
> For now, i have made a TODO entry.
> 
> Yours,
>   Ingo
> 
> 
> Log Message:
> -----------
> in -man -Thtml, vertical spacing is required before .IP
> 
> Modified Files:
> --------------
>     mandoc:
>         TODO
> 
> Revision Data
> -------------
> Index: TODO
> ===================================================================
> RCS file: /home/cvs/mandoc/mandoc/TODO,v
> retrieving revision 1.273
> retrieving revision 1.274
> diff -LTODO -LTODO -u -p -r1.273 -r1.274
> --- TODO
> +++ TODO
> @@ -397,6 +397,12 @@ are mere guesses, and some may be wrong.
>     it does seem cleaner.)
>    loc **  exist **  algo *  size *  imp ***
>  
> +- .IP wants vertical spacing before itself;
> +  currently, it is formatted like .Bl -compact.
> +  Fixing this requires getting rid of the "float"
> +  in the CSS for .Bl-tag first.
> +  Reminded by Pali Rohar 25 Oct 2018 10:10:35 +0200.
> +
>  - format ".IP *" etc. as <ul> rather than <dl>
>    https://github.com/Debian/debiman/issues/67
>    loc ** exist ** algo ** size * imp ***

-- 
Pali Rohár
pali.rohar@gmail.com
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: mandoc & perl documentation

[Ingo Schwarze]

Hi Pali,

getting back to this matter, i had another, closer look and it seems
to me that two aspects were still open:

Pali Rohar wrote on Fri, Oct 26, 2018 at 10:15:19AM +0200:
> On Thursday 25 October 2018 23:30:27 Ingo Schwarze wrote:
>> Pali Rohar wrote on Thu, Oct 25, 2018 at 10:10:35AM +0200:
>>> On Thursday 25 October 2018 03:51:33 Ingo Schwarze wrote:
>>>> Pali Rohar wrote on Wed, Oct 24, 2018 at 10:03:22AM +0200:


FIRST ASPECT:
Does mandoc support all font styles that perlpod(1) can request?

>>> E.g. documentation for cpan modules on metacpan.org is very very
>>> similar to documentation in system manpages, use more font
>>> styles (not only monospaced) and looks much better.

[...]
>> Strictly speaking, "monospaced" is a super-family (for example, the
>> Helvetica family is a proportional family and Courier is a
>> monospaced family).
>>
>> But since mandoc does not bother with families at all,
>> it somewhat incorrectly implements "monospaced" as a font
>> style alongside roman, bold, italic, and bold-italic.
>> 
>> That said, which other font styles does metacpan.org use besides
>> roman, bold, italic, and the pseudo-style "monospaced", and what
>> for?  Having a brief look, i failed to find any.

> I<...> - italic text
> B<...> - bold text
> C<...> - code text in a typewriter font (indication that this
>          represents program text or some other form of computerese)
> F<...> - filenames, displayed in italics

I checked all these, pod2man(1) translates them as follows:

 * I<...>   to   \fI...\fR
 * B<...>   to   \fB...\fR
 * C<...>   to   \f(CW\*(C`...\*(C'\fR   ==   \f(CW"..."\fR
 * F<...>   to   \fI...\fR

Mandoc handles all of \fI \fR \fB \f(CW, so there should be nothing
to fix so far, right?

It appears F<...> behaves exactly like I<...>, so i'll disregard it
below.

> And you can do any combination of them (e.g. typewriter font which is
> both bold and italic together).

So, let's check the combinations:

 * I<B<...>>      to   \fI\f(BI...\fI\fR
 * I<C<...>>      to   \fI\f(CI"..."\fI\fR
 * B<I<...>>      to   \fB\f(BI...\fB\fR
 * B<C<...>>      to   \fB\f(CB"..."\fB\fR
 * C<I<...>>      to   \f(CW"\f(CI...\f(CW"\fR
 * C<B<...>>      to   \f(CW"\f(CB...\f(CW"\fR
 * C<I<...>>      to   \f(CW"\f(CI...\f(CW"\fR
 * I<B<C<...>>>   to   \fI\f(BI\f(CB"..."\f(BI\fI\fR
 * I<B<C<...>>>   to   \fI\f(CI"\f(CB...\f(CI"\fI\fR
 * B<I<C<...>>>   to   \fB\f(BI\f(CB"..."\f(BI\fB\fR
 * B<C<I<...>>>   to   \fB\f(CB"\f(CB...\f(CB"\fB\fR
 * C<I<B<...>>>   to   \f(CW"\f(CI\f(CB...\f(CI\f(CW"\fR
 * C<B<I<...>>>   to   \f(CW"\f(CB\f(CB...\f(CB\f(CW"\fR

Mandoc also handles \f(BI \f(CI \f(CB,
so all of that that should work, too.

Of course, in terminal output,

  \f(CW = \fR
  \f(CI = \fI
  \f(CB = \fB

which can't be helped, but apart from that, i don't see anything
that is still unimplemented, or do i overlook something?


SECOND ASPECT:
Does mandoc handle the man(7) code generated from =over/=item
as well as possible?

>>> 3) On that https://man.openbsd.org/strict page is section name "strict
>>> refs" fully invisible. It is joined together with previous paragraph and
>>> also with description of that section. Reader does not see that there is
>>> paragraph about "strict refs" section. It should be visually separated.
>>> To compare, look at metacpan page and search for "strict refs".

>> That is not a section name, not even a subsection name, but merely a
>> list tag formatted as follows:
>> 
>>   =over 6
>> 
>>   =item C<strict refs>
>> 
>> So the vertical spacing that metacpan does *after* the list tag looks
>> dubious for me - doesn't that make many other lists look bad?

> =item directive is used lot of times for describing functions or methods
> of some class.
> 
> In perlpod documentation is written:
> 
> And perhaps most importantly, keep the items consistent: either use
> "=item *" for all of them, to produce bullets; or use "=item 1.",
> "=item 2.", etc., to produce numbered lists; or use "=item foo",
> "=item bar", etc.--namely, things that look nothing like bullets or
> numbers. If you start with bullets or numbers, stick with them, as
> formatters use the first "=item" type to decide how to format the list.
> 
> So it is questionable... Maybe bullets and numbers specified via =item
> should be formatted differently as "=item text"?

Maybe, not sure.  But am i right that if so, that is a task for pod2man(1),
not for mandoc(1)?  Right now, it seems to me that pod2man(1) formats
bulleted and numbered lists as

  .IP "\(bu" 6
  First item.
  .IP "\(bu" 6
  Second item.

which is definitely fine,
and lists with "=item foo" in just the same way as

  .IP "foo" 6
  Description of foo.
  .IP "bar" 6
  Description of bar.

which is probably also fine for many cases, but maybe not ideal for
the specific case you are quoting.

That man(7) code does not permit inserting a blank output line
between the .IP "foo" and the "Description of foo."
If "foo" is short enough, i.e. less than 6n, it does not even ask
for a line break between the two.

If pod2man(1) wanted blank lines between each =item header and
the subsequent body, it would have to emit something like the
following - right?  That's certainly not the only possibility
way to request such blank lines, but one option:

  foo
  .PP
  .RS 6n
  Description of foo.
  .RE
  .PP
  bar
  .PP
  .RS 6n
  Description of bar.
  .RE

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: mandoc & perl documentation

[Pali Rohár]

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

On Saturday 24 November 2018 20:31:52 Ingo Schwarze wrote:
> Hi Pali,
> 
> getting back to this matter, i had another, closer look and it seems
> to me that two aspects were still open:
> 
> Pali Rohar wrote on Fri, Oct 26, 2018 at 10:15:19AM +0200:
> > On Thursday 25 October 2018 23:30:27 Ingo Schwarze wrote:
> >> Pali Rohar wrote on Thu, Oct 25, 2018 at 10:10:35AM +0200:
> >>> On Thursday 25 October 2018 03:51:33 Ingo Schwarze wrote:
> >>>> Pali Rohar wrote on Wed, Oct 24, 2018 at 10:03:22AM +0200:
> 
> 
> FIRST ASPECT:
> Does mandoc support all font styles that perlpod(1) can request?
> 
> >>> E.g. documentation for cpan modules on metacpan.org is very very
> >>> similar to documentation in system manpages, use more font
> >>> styles (not only monospaced) and looks much better.
> 
> [...]
> >> Strictly speaking, "monospaced" is a super-family (for example, the
> >> Helvetica family is a proportional family and Courier is a
> >> monospaced family).
> >>
> >> But since mandoc does not bother with families at all,
> >> it somewhat incorrectly implements "monospaced" as a font
> >> style alongside roman, bold, italic, and bold-italic.
> >> 
> >> That said, which other font styles does metacpan.org use besides
> >> roman, bold, italic, and the pseudo-style "monospaced", and what
> >> for?  Having a brief look, i failed to find any.
> 
> > I<...> - italic text
> > B<...> - bold text
> > C<...> - code text in a typewriter font (indication that this
> >          represents program text or some other form of computerese)
> > F<...> - filenames, displayed in italics
> 
> I checked all these, pod2man(1) translates them as follows:
> 
>  * I<...>   to   \fI...\fR
>  * B<...>   to   \fB...\fR
>  * C<...>   to   \f(CW\*(C`...\*(C'\fR   ==   \f(CW"..."\fR
>  * F<...>   to   \fI...\fR
> 
> Mandoc handles all of \fI \fR \fB \f(CW, so there should be nothing
> to fix so far, right?

Yes, seems this is working fine.

> It appears F<...> behaves exactly like I<...>, so i'll disregard it
> below.
> 
> > And you can do any combination of them (e.g. typewriter font which is
> > both bold and italic together).
> 
> So, let's check the combinations:
> 
>  * I<B<...>>      to   \fI\f(BI...\fI\fR
>  * I<C<...>>      to   \fI\f(CI"..."\fI\fR
>  * B<I<...>>      to   \fB\f(BI...\fB\fR
>  * B<C<...>>      to   \fB\f(CB"..."\fB\fR
>  * C<I<...>>      to   \f(CW"\f(CI...\f(CW"\fR
>  * C<B<...>>      to   \f(CW"\f(CB...\f(CW"\fR
>  * C<I<...>>      to   \f(CW"\f(CI...\f(CW"\fR
>  * I<B<C<...>>>   to   \fI\f(BI\f(CB"..."\f(BI\fI\fR
>  * I<B<C<...>>>   to   \fI\f(CI"\f(CB...\f(CI"\fI\fR
>  * B<I<C<...>>>   to   \fB\f(BI\f(CB"..."\f(BI\fB\fR
>  * B<C<I<...>>>   to   \fB\f(CB"\f(CB...\f(CB"\fB\fR
>  * C<I<B<...>>>   to   \f(CW"\f(CI\f(CB...\f(CI\f(CW"\fR
>  * C<B<I<...>>>   to   \f(CW"\f(CB\f(CB...\f(CB\f(CW"\fR

Question is if last 6 lines are correctly translated. Should not it be
typewriter font which has both italic and bold style? Because currently
it is just bold typewriter and not italic.

Has troff, groff or mandoc some sequence of italic bold typewriter font?
It is probably something very unusual as a big Computer Modern font
family does not have such style too.

> Mandoc also handles \f(BI \f(CI \f(CB,
> so all of that that should work, too.
> 
> Of course, in terminal output,
> 
>   \f(CW = \fR
>   \f(CI = \fI
>   \f(CB = \fB
> 
> which can't be helped, but apart from that, i don't see anything
> that is still unimplemented, or do i overlook something?
> 
> 
> SECOND ASPECT:
> Does mandoc handle the man(7) code generated from =over/=item
> as well as possible?
> 
> >>> 3) On that https://man.openbsd.org/strict page is section name "strict
> >>> refs" fully invisible. It is joined together with previous paragraph and
> >>> also with description of that section. Reader does not see that there is
> >>> paragraph about "strict refs" section. It should be visually separated.
> >>> To compare, look at metacpan page and search for "strict refs".
> 
> >> That is not a section name, not even a subsection name, but merely a
> >> list tag formatted as follows:
> >> 
> >>   =over 6
> >> 
> >>   =item C<strict refs>
> >> 
> >> So the vertical spacing that metacpan does *after* the list tag looks
> >> dubious for me - doesn't that make many other lists look bad?
> 
> > =item directive is used lot of times for describing functions or methods
> > of some class.
> > 
> > In perlpod documentation is written:
> > 
> > And perhaps most importantly, keep the items consistent: either use
> > "=item *" for all of them, to produce bullets; or use "=item 1.",
> > "=item 2.", etc., to produce numbered lists; or use "=item foo",
> > "=item bar", etc.--namely, things that look nothing like bullets or
> > numbers. If you start with bullets or numbers, stick with them, as
> > formatters use the first "=item" type to decide how to format the list.
> > 
> > So it is questionable... Maybe bullets and numbers specified via =item
> > should be formatted differently as "=item text"?
> 
> Maybe, not sure.  But am i right that if so, that is a task for pod2man(1),

Yes.

> not for mandoc(1)?  Right now, it seems to me that pod2man(1) formats
> bulleted and numbered lists as
> 
>   .IP "\(bu" 6
>   First item.
>   .IP "\(bu" 6
>   Second item.
> 
> which is definitely fine,

I'm not sure if it is fine.

Here is simple test.pod file:

$ cat test.pod
=pod

=over

=item *

Description of item1

=item *

Description of item2

=back

=cut

Converting it directly to HTML via pod2html results in:

$ pod2html test.pod
...
<ul>
<li><p>Description of item1</p>
</li>
<li><p>Description of item2</p>
</li>
</ul>
...

But converting it into man and then via mandoc converting it into HTML
results in:

$ pod2man test.pod | ./mandoc -Thtml
...
<div class="manual-text">
<div>&#x00A0;</div>
<dl class="Bl-tag">
  <dt>&#x2022;</dt>
  <dd>Description of item1</dd>
</dl>
<dl class="Bl-tag">
  <dt>&#x2022;</dt>
  <dd>Description of item2</dd>
</dl>
</div>
...

Bullet (&#2022) generated by mandoc is on previous line as description
text. So something is not there fine. I see it in chrome and also in
elinks:

$ pod2man test.pod | ./mandoc -Thtml | elinks -dump
...
   •
           Description of item1

   •
           Description of item2
...

And when I print mandoc output on terminal, then description and bullet
are on the same line:

$ pod2man test.pod | ./mandoc
...
       •   Description of item1

       •   Description of item2
...

So this looks like a problem in mandoc's HTML output.

> and lists with "=item foo" in just the same way as
> 
>   .IP "foo" 6
>   Description of foo.
>   .IP "bar" 6
>   Description of bar.
> 
> which is probably also fine for many cases, but maybe not ideal for
> the specific case you are quoting.
> 
> That man(7) code does not permit inserting a blank output line
> between the .IP "foo" and the "Description of foo."
> If "foo" is short enough, i.e. less than 6n, it does not even ask
> for a line break between the two.
> 
> If pod2man(1) wanted blank lines between each =item header and
> the subsequent body, it would have to emit something like the
> following - right?  That's certainly not the only possibility
> way to request such blank lines, but one option:
> 
>   foo
>   .PP
>   .RS 6n
>   Description of foo.
>   .RE
>   .PP
>   bar
>   .PP
>   .RS 6n
>   Description of bar.
>   .RE
> 
> Yours,
>   Ingo

-- 
Pali Rohár
pali.rohar@gmail.com

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 195 bytes --]

Re: mandoc & perl documentation

[Ingo Schwarze]

Hi Pali,

Pali Rohar wrote on Sun, Nov 25, 2018 at 02:34:26PM +0100:
> On Saturday 24 November 2018 20:31:52 Ingo Schwarze wrote:
>> Pali Rohar wrote on Fri, Oct 26, 2018 at 10:15:19AM +0200:

>>> And you can do any combination of them (e.g. typewriter font
>>> which is both bold and italic together).

>> So, let's check the combinations:
>> 
>>  * I<B<...>>      to   \fI\f(BI...\fI\fR
>>  * I<C<...>>      to   \fI\f(CI"..."\fI\fR
>>  * B<I<...>>      to   \fB\f(BI...\fB\fR
>>  * B<C<...>>      to   \fB\f(CB"..."\fB\fR
>>  * C<I<...>>      to   \f(CW"\f(CI...\f(CW"\fR
>>  * C<B<...>>      to   \f(CW"\f(CB...\f(CW"\fR
>>  * C<I<...>>      to   \f(CW"\f(CI...\f(CW"\fR
>>  * I<B<C<...>>>   to   \fI\f(BI\f(CB"..."\f(BI\fI\fR
>>  * I<B<C<...>>>   to   \fI\f(CI"\f(CB...\f(CI"\fI\fR
>>  * B<I<C<...>>>   to   \fB\f(BI\f(CB"..."\f(BI\fB\fR
>>  * B<C<I<...>>>   to   \fB\f(CB"\f(CB...\f(CB"\fB\fR
>>  * C<I<B<...>>>   to   \f(CW"\f(CI\f(CB...\f(CI\f(CW"\fR
>>  * C<B<I<...>>>   to   \f(CW"\f(CB\f(CB...\f(CB\f(CW"\fR
 
> Question is if last 6 lines are correctly translated.

That is a question about pod2man(1), not a question about mandoc(1).
Regarding mandoc(1), the question only is whether it correctly
handles whatever pod2man(1) produces.

> Should not it be typewriter font which has both italic and bold
> style? Because currently it is just bold typewriter and not italic.

In principle, yes, and i don't doubt that in the typesetting business,
you can find fixed-width font families looking typewriter-like and
providing a font with style bold+italic.

> Has troff, groff

That hardly matters.  If groff (or any other full roff implementation)
does not provide a font with certain properties users desire, they
can usually install additional fonts themselves.

> or mandoc some sequence of italic bold typewriter font?

For terminal, PostScript, and PDF output, mandoc does not provide
any typewriter font whatsoever.  For terminal output, no other
formatter can portably do so, either.

Regarding HTML output, there is actually a (rather tricky) way to
request a typewriter-bold-italic font, and it does work in mandoc:

   $ cat tmp.man
  .TH TEST 1
  .SH NAME
  test \(en test
  .SH DESCRIPTION
  initial text
  .EX
  .B
  .I typewriter-bold-italic
  .EE
  final text

   $ mandoc -T html -O style=mandoc.css tmp.man
  [...]
  initial text
  <pre>
  <b><i>typewriter-bold-italic</i></b>
  </pre>
  final text

Now, <pre> requests monospace by default, so browsers typically
render this text in a monospace bold-italic font.

Note that even though the above example file is correct and unambiguous,
groff -T html totally mishandles it: it renders

  initial text
  <i><br>
  typewriter-bold-italic</i> <br>
  final text

So both the typewriter and the bold a totally lost - the reason
being that groff -T html cannot do structural analysis, and on the
presentational level, .EX simply does ".ft CW", which the \fB from .B
overrides, and which the \fI from .I overrides yet again.


It is not obvious to me how the above could be made useful for Perl
documentation.  The pod2man(1) program certainly cannot translate C<...>
to .EX - not only because that is a man-ext GNU extension, but even
more so because it is a block macro rather than an inline macro
which would totally break both horizontal and vertical spacing.
And i don't see any other macro in the man(7) language to request
a typewriter font.  Even resorting to the low-level roff(7) .ft request
wouldn't help because it would get overridden by the subsequent .B
macro rather than stacking up with it.

So making all this useful for Perl would probably require using
\f[CBI], but i have doubts about the portability.  Mandoc could
easily be taught to cope (it doesn't right now, but would simply
ignore \f[CBI]), but what about other formatters?


>> Right now, it seems to me that pod2man(1) formats
>> bulleted and numbered lists as
>> 
>>   .IP "\(bu" 6
>>   First item.
>>   .IP "\(bu" 6
>>   Second item.
>> 
>> which is definitely fine,

> I'm not sure if it is fine.

Well, the rendering by pod2man(1) shown above certainly *is* fine,
i don't see in which other way it could reasonably format such a list.

What you are calling into question below is whether mandoc(1) -T html
handles the above man(7) code well.

> Here is simple test.pod file:
> 
> $ cat test.pod
> =pod
> 
> =over
> 
> =item *
> 
> Description of item1
> 
> =item *
> 
> Description of item2
> 
> =back
> 
> =cut
> 
> Converting it directly to HTML via pod2html results in:
> 
> $ pod2html test.pod
> ...
> <ul>
> <li><p>Description of item1</p>
> </li>
> <li><p>Description of item2</p>
> </li>
> </ul>
> ...
> 
> But converting it into man and then via mandoc converting it into HTML
> results in:
> 
> $ pod2man test.pod | ./mandoc -Thtml
> ...
> <div class="manual-text">
> <div>&#x00A0;</div>
> <dl class="Bl-tag">
>   <dt>&#x2022;</dt>
>   <dd>Description of item1</dd>
> </dl>
> <dl class="Bl-tag">
>   <dt>&#x2022;</dt>
>   <dd>Description of item2</dd>
> </dl>
> </div>
> ...

You have a point here.  The mandoc -man -T html formatter could be
improved in two respects:

 * If the argument to .IP is a single bullet-like character,
   it could be rendered as <ul> rather than <dl>.

   Heh, checking the TODO file, i just noticed this was already
   reported in https://github.com/Debian/debiman/issues/67 .

 * Subsequent .IP macros could be rendered into a common list
   rather than opening a new list for each item.

   I just add a new TODO entry for this idea, see the commit below.


> Bullet (&#2022) generated by mandoc is on previous line as description
> text. So something is not there fine. I see it in chrome and also in
> elinks:
> 
> $ pod2man test.pod | ./mandoc -Thtml | elinks -dump
> ...
>    •
>            Description of item1
> 
>    •
>            Description of item2
> ...
> 
> And when I print mandoc output on terminal, then description and bullet
> are on the same line:
> 
> $ pod2man test.pod | ./mandoc
> ...
>        •   Description of item1
> 
>        •   Description of item2
> ...
> 
> So this looks like a problem in mandoc's HTML output.

No, *that* is not the problem.  The unusual line breaking is merely
caused by your omission of "-O style=/path/to/mandoc.css".
Without using a style sheet, expecting beauty in HTML rendering is
not reasonable.

Unfortunately, i cannot make "-O style" the default because no
sane default can be designed for "/path/to/".

Yours,
  Ingo


Log Message:
-----------
HTML formatting of .IP

Modified Files:
--------------
    mandoc:
        TODO

Revision Data
-------------
Index: TODO
===================================================================
RCS file: /home/cvs/mandoc/mandoc/TODO,v
retrieving revision 1.275
retrieving revision 1.276
diff -LTODO -LTODO -u -p -r1.275 -r1.276
--- TODO
+++ TODO
@@ -399,8 +399,14 @@ are mere guesses, and some may be wrong.
   in the CSS for .Bl-tag first.
   Reminded by Pali Rohar 25 Oct 2018 10:10:35 +0200.
 
+- format multiple subsequent .IP as a single list
+  rather than opening a new list for each item
+  Pali Rohar 25 Nov 2018 14:34:26 +0100
+  loc *  exist **  algo *  size *  imp ***
+
 - format ".IP *" etc. as <ul> rather than <dl>
   https://github.com/Debian/debiman/issues/67
+  reminded by Pali Rohar 25 Nov 2018 14:34:26 +0100
   loc ** exist ** algo ** size * imp ***
 
 - .Bf at the beginning of a paragraph inserts a bogus 1ex horizontal
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: mandoc & perl documentation

[Pali Rohár]

On Sunday 25 November 2018 19:20:08 Ingo Schwarze wrote:
> Hi Pali,
> 
> Pali Rohar wrote on Sun, Nov 25, 2018 at 02:34:26PM +0100:
> > On Saturday 24 November 2018 20:31:52 Ingo Schwarze wrote:
> >> Pali Rohar wrote on Fri, Oct 26, 2018 at 10:15:19AM +0200:
> 
> >>> And you can do any combination of them (e.g. typewriter font
> >>> which is both bold and italic together).
> 
> >> So, let's check the combinations:
> >> 
> >>  * I<B<...>>      to   \fI\f(BI...\fI\fR
> >>  * I<C<...>>      to   \fI\f(CI"..."\fI\fR
> >>  * B<I<...>>      to   \fB\f(BI...\fB\fR
> >>  * B<C<...>>      to   \fB\f(CB"..."\fB\fR
> >>  * C<I<...>>      to   \f(CW"\f(CI...\f(CW"\fR
> >>  * C<B<...>>      to   \f(CW"\f(CB...\f(CW"\fR
> >>  * C<I<...>>      to   \f(CW"\f(CI...\f(CW"\fR
> >>  * I<B<C<...>>>   to   \fI\f(BI\f(CB"..."\f(BI\fI\fR
> >>  * I<B<C<...>>>   to   \fI\f(CI"\f(CB...\f(CI"\fI\fR
> >>  * B<I<C<...>>>   to   \fB\f(BI\f(CB"..."\f(BI\fB\fR
> >>  * B<C<I<...>>>   to   \fB\f(CB"\f(CB...\f(CB"\fB\fR
> >>  * C<I<B<...>>>   to   \f(CW"\f(CI\f(CB...\f(CI\f(CW"\fR
> >>  * C<B<I<...>>>   to   \f(CW"\f(CB\f(CB...\f(CB\f(CW"\fR
>  
> > Question is if last 6 lines are correctly translated.
> 
> That is a question about pod2man(1), not a question about mandoc(1).
> Regarding mandoc(1), the question only is whether it correctly
> handles whatever pod2man(1) produces.
> 
> > Should not it be typewriter font which has both italic and bold
> > style? Because currently it is just bold typewriter and not italic.
> 
> In principle, yes, and i don't doubt that in the typesetting business,
> you can find fixed-width font families looking typewriter-like and
> providing a font with style bold+italic.
> 
> > Has troff, groff
> 
> That hardly matters.  If groff (or any other full roff implementation)
> does not provide a font with certain properties users desire, they
> can usually install additional fonts themselves.
> 
> > or mandoc some sequence of italic bold typewriter font?
> 
> For terminal, PostScript, and PDF output, mandoc does not provide
> any typewriter font whatsoever.  For terminal output, no other
> formatter can portably do so, either.
> 
> Regarding HTML output, there is actually a (rather tricky) way to
> request a typewriter-bold-italic font, and it does work in mandoc:
> 
>    $ cat tmp.man
>   .TH TEST 1
>   .SH NAME
>   test \(en test
>   .SH DESCRIPTION
>   initial text
>   .EX
>   .B
>   .I typewriter-bold-italic
>   .EE
>   final text
> 
>    $ mandoc -T html -O style=mandoc.css tmp.man
>   [...]
>   initial text
>   <pre>
>   <b><i>typewriter-bold-italic</i></b>
>   </pre>
>   final text
> 
> Now, <pre> requests monospace by default, so browsers typically
> render this text in a monospace bold-italic font.
> 
> Note that even though the above example file is correct and unambiguous,
> groff -T html totally mishandles it: it renders
> 
>   initial text
>   <i><br>
>   typewriter-bold-italic</i> <br>
>   final text
> 
> So both the typewriter and the bold a totally lost - the reason
> being that groff -T html cannot do structural analysis, and on the
> presentational level, .EX simply does ".ft CW", which the \fB from .B
> overrides, and which the \fI from .I overrides yet again.
> 
> 
> It is not obvious to me how the above could be made useful for Perl
> documentation.  The pod2man(1) program certainly cannot translate C<...>
> to .EX - not only because that is a man-ext GNU extension, but even
> more so because it is a block macro rather than an inline macro
> which would totally break both horizontal and vertical spacing.
> And i don't see any other macro in the man(7) language to request
> a typewriter font.  Even resorting to the low-level roff(7) .ft request
> wouldn't help because it would get overridden by the subsequent .B
> macro rather than stacking up with it.
> 
> So making all this useful for Perl would probably require using
> \f[CBI], but i have doubts about the portability.  Mandoc could
> easily be taught to cope (it doesn't right now, but would simply
> ignore \f[CBI]), but what about other formatters?

It looks like there is no standard way to support it. So I guess current
behavior of pod2man is the best what can be done.

> 
> >> Right now, it seems to me that pod2man(1) formats
> >> bulleted and numbered lists as
> >> 
> >>   .IP "\(bu" 6
> >>   First item.
> >>   .IP "\(bu" 6
> >>   Second item.
> >> 
> >> which is definitely fine,
> 
> > I'm not sure if it is fine.
> 
> Well, the rendering by pod2man(1) shown above certainly *is* fine,
> i don't see in which other way it could reasonably format such a list.

You are right, it is really OK.

> What you are calling into question below is whether mandoc(1) -T html
> handles the above man(7) code well.
> 
> > Here is simple test.pod file:
> > 
> > $ cat test.pod
> > =pod
> > 
> > =over
> > 
> > =item *
> > 
> > Description of item1
> > 
> > =item *
> > 
> > Description of item2
> > 
> > =back
> > 
> > =cut
> > 
> > Converting it directly to HTML via pod2html results in:
> > 
> > $ pod2html test.pod
> > ...
> > <ul>
> > <li><p>Description of item1</p>
> > </li>
> > <li><p>Description of item2</p>
> > </li>
> > </ul>
> > ...
> > 
> > But converting it into man and then via mandoc converting it into HTML
> > results in:
> > 
> > $ pod2man test.pod | ./mandoc -Thtml
> > ...
> > <div class="manual-text">
> > <div>&#x00A0;</div>
> > <dl class="Bl-tag">
> >   <dt>&#x2022;</dt>
> >   <dd>Description of item1</dd>
> > </dl>
> > <dl class="Bl-tag">
> >   <dt>&#x2022;</dt>
> >   <dd>Description of item2</dd>
> > </dl>
> > </div>
> > ...
> 
> You have a point here.  The mandoc -man -T html formatter could be
> improved in two respects:
> 
>  * If the argument to .IP is a single bullet-like character,
>    it could be rendered as <ul> rather than <dl>.
> 
>    Heh, checking the TODO file, i just noticed this was already
>    reported in https://github.com/Debian/debiman/issues/67 .
> 
>  * Subsequent .IP macros could be rendered into a common list
>    rather than opening a new list for each item.
> 
>    I just add a new TODO entry for this idea, see the commit below.

Ok, so resolving these two points on TODO list should fix above reported
problem.

> 
> > Bullet (&#2022) generated by mandoc is on previous line as description
> > text. So something is not there fine. I see it in chrome and also in
> > elinks:
> > 
> > $ pod2man test.pod | ./mandoc -Thtml | elinks -dump
> > ...
> >    •
> >            Description of item1
> > 
> >    •
> >            Description of item2
> > ...
> > 
> > And when I print mandoc output on terminal, then description and bullet
> > are on the same line:
> > 
> > $ pod2man test.pod | ./mandoc
> > ...
> >        •   Description of item1
> > 
> >        •   Description of item2
> > ...
> > 
> > So this looks like a problem in mandoc's HTML output.
> 
> No, *that* is not the problem.  The unusual line breaking is merely
> caused by your omission of "-O style=/path/to/mandoc.css".
> Without using a style sheet, expecting beauty in HTML rendering is
> not reasonable.
> 
> Unfortunately, i cannot make "-O style" the default because no
> sane default can be designed for "/path/to/".
> 
> Yours,
>   Ingo
> 
> 
> Log Message:
> -----------
> HTML formatting of .IP
> 
> Modified Files:
> --------------
>     mandoc:
>         TODO
> 
> Revision Data
> -------------
> Index: TODO
> ===================================================================
> RCS file: /home/cvs/mandoc/mandoc/TODO,v
> retrieving revision 1.275
> retrieving revision 1.276
> diff -LTODO -LTODO -u -p -r1.275 -r1.276
> --- TODO
> +++ TODO
> @@ -399,8 +399,14 @@ are mere guesses, and some may be wrong.
>    in the CSS for .Bl-tag first.
>    Reminded by Pali Rohar 25 Oct 2018 10:10:35 +0200.
>  
> +- format multiple subsequent .IP as a single list
> +  rather than opening a new list for each item
> +  Pali Rohar 25 Nov 2018 14:34:26 +0100
> +  loc *  exist **  algo *  size *  imp ***
> +
>  - format ".IP *" etc. as <ul> rather than <dl>
>    https://github.com/Debian/debiman/issues/67
> +  reminded by Pali Rohar 25 Nov 2018 14:34:26 +0100
>    loc ** exist ** algo ** size * imp ***
>  
>  - .Bf at the beginning of a paragraph inserts a bogus 1ex horizontal

-- 
Pali Rohár
pali.rohar@gmail.com
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: mandoc & perl documentation

[Ingo Schwarze]

Hi,

i just implement yet another suggestion that came up in this conversation,
see the commit below.

The only TODO item i'm aware of that is still open following the
reports from Pali Rohar is this one:

 - format ".IP *" etc. as <ul> rather than <dl>
   https://github.com/Debian/debiman/issues/67
   reminded by Pali Rohar 25 Nov 2018 14:34:26 +0100
   loc ** exist ** algo ** size * imp ***

It will eventually get done, too.

Yours,
  Ingo


Log Message:
-----------
Format multiple subsequent .IP or multiple subsequent .TP/.TQ
as a single <dl> list rather than opening a new list for each item;
feature suggested by Pali dot Rohar at gmail dot com.

Modified Files:
--------------
    mandoc:
        TODO
        man_html.c

Revision Data
-------------
Index: man_html.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/man_html.c,v
retrieving revision 1.170
retrieving revision 1.171
diff -Lman_html.c -Lman_html.c -u -p -r1.170 -r1.171
--- man_html.c
+++ man_html.c
@@ -233,7 +233,25 @@ print_man_node(MAN_ARGS)
 
 	/* This will automatically close out any font scope. */
 	t->refcnt--;
-	print_stagq(h, t);
+	if (n->type == ROFFT_BLOCK &&
+	    (n->tok == MAN_IP || n->tok == MAN_TP || n->tok == MAN_TQ)) {
+		t = h->tag;
+		while (t->tag != TAG_DL)
+			t = t->next;
+		/*
+		 * Close the list if no further item of the same type
+		 * follows; otherwise, close the item only.
+		 */
+		if (n->next == NULL ||
+		    (n->tok == MAN_IP && n->next->tok != MAN_IP) ||
+		    (n->tok != MAN_IP &&
+		     n->next->tok != MAN_TP && n->next->tok != MAN_TQ)) {
+			print_tagq(h, t);
+			t = NULL;
+		}
+	}
+	if (t != NULL)
+		print_stagq(h, t);
 
 	if (n->flags & NODE_NOFILL && n->tok != MAN_YS &&
 	    (n->next != NULL && n->next->flags & NODE_LINE)) {
@@ -399,7 +417,15 @@ man_IP_pre(MAN_ARGS)
 	switch (n->type) {
 	case ROFFT_BLOCK:
 		html_close_paragraph(h);
-		print_otag(h, TAG_DL, "c", "Bl-tag");
+		/*
+		 * Open a new list unless there is an immediately
+		 * preceding item of the same type.
+		 */
+		if (n->prev == NULL ||
+		    (n->tok == MAN_IP && n->prev->tok != MAN_IP) ||
+		    (n->tok != MAN_IP &&
+		     n->prev->tok != MAN_TP && n->prev->tok != MAN_TQ))
+			print_otag(h, TAG_DL, "c", "Bl-tag");
 		return 1;
 	case ROFFT_HEAD:
 		print_otag(h, TAG_DT, "");
Index: TODO
===================================================================
RCS file: /home/cvs/mandoc/mandoc/TODO,v
retrieving revision 1.283
retrieving revision 1.284
diff -LTODO -LTODO -u -p -r1.283 -r1.284
--- TODO
+++ TODO
@@ -349,11 +349,6 @@ are mere guesses, and some may be wrong.
    it does seem cleaner.)
   loc **  exist **  algo *  size *  imp ***
 
-- format multiple subsequent .IP as a single list
-  rather than opening a new list for each item
-  Pali Rohar 25 Nov 2018 14:34:26 +0100
-  loc *  exist **  algo *  size *  imp ***
-
 - format ".IP *" etc. as <ul> rather than <dl>
   https://github.com/Debian/debiman/issues/67
   reminded by Pali Rohar 25 Nov 2018 14:34:26 +0100
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: mandoc & perl documentation

[Ingo Schwarze]

Hi Pali,

i just implemented the last feature request mentioned in the
mail cited below, see the commit at the end, and i believe
that everything touched in that conversation has now been
taken care of.

If there is something i missed, pleasde speak up!

Yours,
  Ingo


Pali Rohar wrote on Sun, Nov 25, 2018 at 02:34:26PM +0100:

> Here is simple test.pod file:
> 
> $ cat test.pod
> =pod
> 
> =over
> 
> =item *
> 
> Description of item1
> 
> =item *
> 
> Description of item2
> 
> =back
> 
> =cut
> 
> Converting it directly to HTML via pod2html results in:
> 
> $ pod2html test.pod
> ...
> <ul>
> <li><p>Description of item1</p>
> </li>
> <li><p>Description of item2</p>
> </li>
> </ul>
> ...

Mandoc from CVS HEAD nor renders:

<div class="manual-text">
<ul class="Bl-bullet">
  <li>Description of item1</li>
  <li>Description of item2</li>
</ul>
</div>



Log Message:
-----------
Represent multiple subsequent .IP blocks having a consistent
head argument of *, \-, or \(bu as <ul> rather than as <dl>,
using a bit of heuristics.

Basic idea suggested by Dagfinn Ilmari Mannsaker <ilmari at github>
in https://github.com/Debian/debiman/issues/67 and independently by
<Pali dot Rohar at gmail dot com> on <discuss at mandoc dot bsd dot lv>.

Modified Files:
--------------
    mandoc:
        TODO
        man_html.c

Revision Data
-------------
Index: TODO
===================================================================
RCS file: /home/cvs/mandoc/mandoc/TODO,v
retrieving revision 1.285
retrieving revision 1.286
diff -LTODO -LTODO -u -p -r1.285 -r1.286
--- TODO
+++ TODO
@@ -342,11 +342,6 @@ are mere guesses, and some may be wrong.
 
 --- HTML issues --------------------------------------------------------
 
-- format ".IP *" etc. as <ul> rather than <dl>
-  https://github.com/Debian/debiman/issues/67
-  reminded by Pali Rohar 25 Nov 2018 14:34:26 +0100
-  loc ** exist ** algo ** size * imp ***
-
 - .Bf at the beginning of a paragraph inserts a bogus 1ex horizontal
   space, see for example random(3).  Introduced in
   http://mdocml.bsd.lv/cgi-bin/cvsweb/mdoc_html.c.diff?r1=1.91&r2=1.92
Index: man_html.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/man_html.c,v
retrieving revision 1.172
retrieving revision 1.173
diff -Lman_html.c -Lman_html.c -u -p -r1.172 -r1.173
--- man_html.c
+++ man_html.c
@@ -46,6 +46,8 @@ static	void		  print_man_head(const stru
 				struct html *);
 static	void		  print_man_nodelist(MAN_ARGS);
 static	void		  print_man_node(MAN_ARGS);
+static	char		  list_continues(const struct roff_node *,
+				const struct roff_node *);
 static	int		  man_B_pre(MAN_ARGS);
 static	int		  man_IP_pre(MAN_ARGS);
 static	int		  man_I_pre(MAN_ARGS);
@@ -236,16 +238,13 @@ print_man_node(MAN_ARGS)
 	if (n->type == ROFFT_BLOCK &&
 	    (n->tok == MAN_IP || n->tok == MAN_TP || n->tok == MAN_TQ)) {
 		t = h->tag;
-		while (t->tag != TAG_DL)
+		while (t->tag != TAG_DL && t->tag != TAG_UL)
 			t = t->next;
 		/*
 		 * Close the list if no further item of the same type
 		 * follows; otherwise, close the item only.
 		 */
-		if (n->next == NULL ||
-		    (n->tok == MAN_IP && n->next->tok != MAN_IP) ||
-		    (n->tok != MAN_IP &&
-		     n->next->tok != MAN_TP && n->next->tok != MAN_TQ)) {
+		if (list_continues(n, n->next) == '\0') {
 			print_tagq(h, t);
 			t = NULL;
 		}
@@ -416,29 +415,82 @@ man_PP_pre(MAN_ARGS)
 	return 1;
 }
 
+static char
+list_continues(const struct roff_node *n1, const struct roff_node *n2)
+{
+	const char *s1, *s2;
+	char c1, c2;
+
+	if (n1 == NULL || n1->type != ROFFT_BLOCK ||
+	    n2 == NULL || n2->type != ROFFT_BLOCK)
+		return '\0';
+	if ((n1->tok == MAN_TP || n1->tok == MAN_TQ) &&
+	    (n2->tok == MAN_TP || n2->tok == MAN_TQ))
+		return ' ';
+	if (n1->tok != MAN_IP || n2->tok != MAN_IP)
+		return '\0';
+	n1 = n1->head->child;
+	n2 = n2->head->child;
+	s1 = n1 == NULL ? "" : n1->string;
+	s2 = n2 == NULL ? "" : n2->string;
+	c1 = strcmp(s1, "*") == 0 ? '*' :
+	     strcmp(s1, "\\-") == 0 ? '-' :
+	     strcmp(s1, "\\(bu") == 0 ? 'b' : ' ';
+	c2 = strcmp(s2, "*") == 0 ? '*' :
+	     strcmp(s2, "\\-") == 0 ? '-' :
+	     strcmp(s2, "\\(bu") == 0 ? 'b' : ' ';
+	return c1 != c2 ? '\0' : c1 == 'b' ? '*' : c1;
+}
+
 static int
 man_IP_pre(MAN_ARGS)
 {
 	const struct roff_node	*nn;
+	const char		*list_class;
+	enum htmltag		 list_elem, body_elem;
+	char			 list_type;
+
+	nn = n->type == ROFFT_BLOCK ? n : n->parent;
+	if ((list_type = list_continues(nn->prev, nn)) == '\0') {
+		/* Start a new list. */
+		if ((list_type = list_continues(nn, nn->next)) == '\0')
+			list_type = ' ';
+		switch (list_type) {
+		case ' ':
+			list_class = "Bl-tag";
+			list_elem = TAG_DL;
+			break;
+		case '*':
+			list_class = "Bl-bullet";
+			list_elem = TAG_UL;
+			break;
+		case '-':
+			list_class = "Bl-dash";
+			list_elem = TAG_UL;
+			break;
+		default:
+			abort();
+		}
+	} else {
+		/* Continue a list that was started earlier. */
+		list_class = NULL;
+		list_elem = TAG_MAX;
+	}
+	body_elem = list_type == ' ' ? TAG_DD : TAG_LI;
 
 	switch (n->type) {
 	case ROFFT_BLOCK:
 		html_close_paragraph(h);
-		/*
-		 * Open a new list unless there is an immediately
-		 * preceding item of the same type.
-		 */
-		if (n->prev == NULL ||
-		    (n->tok == MAN_IP && n->prev->tok != MAN_IP) ||
-		    (n->tok != MAN_IP &&
-		     n->prev->tok != MAN_TP && n->prev->tok != MAN_TQ))
-			print_otag(h, TAG_DL, "c", "Bl-tag");
+		if (list_elem != TAG_MAX)
+			print_otag(h, list_elem, "c", list_class);
 		return 1;
 	case ROFFT_HEAD:
+		if (body_elem == TAG_LI)
+			return 0;
 		print_otag(h, TAG_DT, "");
 		break;
 	case ROFFT_BODY:
-		print_otag(h, TAG_DD, "");
+		print_otag(h, body_elem, "");
 		return 1;
 	default:
 		abort();
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: mandoc & perl documentation

[Ingo Schwarze]

Hi Pali,

Pali Rohar wrote on Thu, Oct 25, 2018 at 10:10:35AM +0200:

> 3) On that https://man.openbsd.org/strict page is section name "strict
> refs" fully invisible. It is joined together with previous paragraph and
> also with description of that section. Reader does not see that there is
> paragraph about "strict refs" section. It should be visually separated.
> To compare, look at metacpan page and search for "strict refs".

i believe this is one of the issues that got fixed by recent work
on HTML and CSS formatting of paragraphs and tagged list items,
in particular regarding vertical spacing, see

  https://man.openbsd.org/strict

It now looks better because that work allowed adding these CSS rules
(showing a shortened version):

.Bl-tag {	margin-top: 0.6em; }
.Bl-tag > dd {	margin-bottom: 0.6em; }

It seems that all issues discussed in this mail were now taken care
of.  Don't hesitate to speak up in case i missed something.

Yours,
  Ingo
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv

Re: mandoc & perl documentation

[Pali Rohár]

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

On Thursday 25 October 2018 03:51:33 Ingo Schwarze wrote:
> Pali Rohar wrote on Wed, Oct 24, 2018 at 10:03:22AM +0200:
> > If you look at the output for Email::Address::XS, then whole
> > SYNOPSIS should be written in typewriter/monospaced font.
> 
> On the one hand, no, a SYNOPSIS should absolutely not be written
> in typewriter/monospaced font

Hi! Now I found perlpodstyle documentation which says about SYNOPSIS:
https://perldoc.perl.org/perlpodstyle.html#SYNOPSIS

"For Perl module documentation, it's usually convenient to have the
contents of this section be a verbatim block showing some (brief)
examples of typical ways the module is used."

And verbatim block is formatted by typewriter font style.

perlpodstyle documentation is "general guideline for how to write POD
documentation for Perl scripts and modules".

-- 
Pali Rohár
pali.rohar@gmail.com

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 195 bytes --]