Re: mandoc & perl documentation

[Ingo Schwarze <schwarze@usta.de>]

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