From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout-kit-01.scc.kit.edu (scc-mailout-kit-01.scc.kit.edu [129.13.231.81]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 1d90741c for ; Wed, 24 Oct 2018 20:51:36 -0500 (EST) Received: from asta-nat.asta.uni-karlsruhe.de ([172.22.63.82] helo=hekate.usta.de) by scc-mailout-kit-01.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1gFUoA-0001Cq-8H; Thu, 25 Oct 2018 03:51:35 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1gFUo9-00062t-ER; Thu, 25 Oct 2018 03:51:33 +0200 Received: from athene.usta.de ([172.24.96.10]) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1gFUoC-0005kz-1e; Thu, 25 Oct 2018 03:51:36 +0200 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id d20b4348; Thu, 25 Oct 2018 03:51:33 +0200 (CEST) Date: Thu, 25 Oct 2018 03:51:33 +0200 From: Ingo Schwarze To: Pali Rohar Cc: discuss@mandoc.bsd.lv Subject: Re: mandoc & perl documentation Message-ID: <20181025015133.GD20422@athene.usta.de> References: <20180913151226.oaon3nvlvgcqioau@pali> <20181011075247.2jo4of7bkpvhkekm@pali> <20181023174545.GD58247@athene.usta.de> <20181024080322.hc6ifwgydpccjif3@pali> X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20181024080322.hc6ifwgydpccjif3@pali> User-Agent: Mutt/1.8.0 (2017-02-23) 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