From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-wr1-f68.google.com (mail-wr1-f68.google.com [209.85.221.68]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id d274dd5d for ; Thu, 25 Oct 2018 03:10:38 -0500 (EST) Received: by mail-wr1-f68.google.com with SMTP id d2-v6so8263886wro.7 for ; Thu, 25 Oct 2018 01:10:38 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=date:from:to:cc:subject:message-id:references:mime-version :content-disposition:content-transfer-encoding:in-reply-to :user-agent; bh=pFvXL3oO++tB81eWOzPtqLRbNU4Ih8G1uMXIrw4kn4g=; b=MhhHtuF9VGTbtfvthLckdi0Fk+nPsef2zzqXZxWOov5eFS4bGaINB+OOM9hR+SoIcj G6s9C5sFVAtaAswAlEQ3JpEQDKR3XyDPrgzV2yBkC8L31zhskp2bnP2OJT7fy8okhUw6 Tvwgh+GkWgR6fKM4CYH4RavwDmFiBDc5Zr561tFvjpE1LCQd8LZdwjbFczP38qegYWrj 7V46zyI3mqV7MA/7RB4KrbYZy+RlWGlk7Fg6oVzJdk2VJvn0AAq2Pv3Ff/ph/IWm9d8F iqfgEmee4dxXcCi0YO+1FJ0tTZc/zH4mUvtWNHIQZ5ME7/z2vIdeEpGw5U1Kt0dzPUFa +WbQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:content-transfer-encoding :in-reply-to:user-agent; bh=pFvXL3oO++tB81eWOzPtqLRbNU4Ih8G1uMXIrw4kn4g=; b=ICOKAadaNR8ysGTdm4ZYivhX0/3fUEMzNu5RXmDuhjKoV7imKL0yu+BxleaYqQEGRn +6IHRcreKMkRk8NzsJGrQON5uIJKQ1hW8r+DF/s42cvf4b4B7BV9AsEJuyPNdAVd6llr LLjT+Q8yXy+DgFjE34eg/uAIMIO111ZGctpCdUcA9U2j0H7mMFl95DnNJx91rO/H+2T3 GITSEuT9X9SHqEOnbIG2eKqk1RzYhn2UeR7SetWQTvxW1ydiXaWElTzsJHzswi1u6WCm fuuTFDft0J9RHBSJ4p8116KU0HlPhcMIbJaD8Uxk4F5+1nmViMp5QbeaHDTMi6/MZa7v KyeQ== X-Gm-Message-State: AGRZ1gLbPxxn7jdVR7NiYNmUhnLeiIjaS1In4pSKiBNUlh+Tfy3be1g4 QLkaBojYm9HjVCaKDtKYmD4= X-Google-Smtp-Source: AJdET5faDJGlmUvBP0+5Cy3L2OirLbjDxVpVARUxg99Pk7nLt172qQE4PVOU6SOywR05oF+IctT/yg== X-Received: by 2002:a5d:6511:: with SMTP id x17-v6mr782864wru.150.1540455036877; Thu, 25 Oct 2018 01:10:36 -0700 (PDT) Received: from pali ([2a02:2b88:2:1::5cc6:2f]) by smtp.gmail.com with ESMTPSA id l125-v6sm2100846wmb.1.2018.10.25.01.10.35 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Thu, 25 Oct 2018 01:10:36 -0700 (PDT) Date: Thu, 25 Oct 2018 10:10:35 +0200 From: Pali =?utf-8?B?Um9ow6Fy?= To: Ingo Schwarze Cc: discuss@mandoc.bsd.lv Subject: Re: mandoc & perl documentation Message-ID: <20181025081035.qo3i4vrrkm2nwnbf@pali> References: <20180913151226.oaon3nvlvgcqioau@pali> <20181011075247.2jo4of7bkpvhkekm@pali> <20181023174545.GD58247@athene.usta.de> <20181024080322.hc6ifwgydpccjif3@pali> <20181025015133.GD20422@athene.usta.de> X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: <20181025015133.GD20422@athene.usta.de> User-Agent: NeoMutt/20170113 (1.7.2) 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