Re: mandoc & perl documentation

["Pali Rohár" <pali.rohar@gmail.com>]

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