From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout-kit-02.scc.kit.edu (scc-mailout-kit-02.scc.kit.edu [129.13.231.82]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 5bb5f50d for ; Thu, 25 Oct 2018 16:30:31 -0500 (EST) Received: from asta-nat.asta.uni-karlsruhe.de ([172.22.63.82] helo=hekate.usta.de) by scc-mailout-kit-02.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1gFnD2-0005IM-PY; Thu, 25 Oct 2018 23:30:30 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1gFnD2-00082A-5T; Thu, 25 Oct 2018 23:30:28 +0200 Received: from athene.usta.de ([172.24.96.10]) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1gFnD4-0002fS-NF; Thu, 25 Oct 2018 23:30:30 +0200 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id 5950f68a; Thu, 25 Oct 2018 23:30:27 +0200 (CEST) Date: Thu, 25 Oct 2018 23:30:27 +0200 From: Ingo Schwarze To: Pali =?utf-8?B?Um9ow6Fy?= Cc: discuss@mandoc.bsd.lv Subject: Re: mandoc & perl documentation Message-ID: <20181025213027.GA41690@athene.usta.de> References: <20180913151226.oaon3nvlvgcqioau@pali> <20181011075247.2jo4of7bkpvhkekm@pali> <20181023174545.GD58247@athene.usta.de> <20181024080322.hc6ifwgydpccjif3@pali> <20181025015133.GD20422@athene.usta.de> <20181025081035.qo3i4vrrkm2nwnbf@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: <20181025081035.qo3i4vrrkm2nwnbf@pali> User-Agent: Mutt/1.8.0 (2017-02-23) 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 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
    rather than
    https://github.com/Debian/debiman/issues/67 loc ** exist ** algo ** size * imp *** -- To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv