Re: mandoc & perl documentation

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

Hi!

On Thursday 25 October 2018 23:30:27 Ingo Schwarze wrote:
> 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<...> - italic text
B<...> - bold text
C<...> - code text in a typewriter font (indication that this
         represents program text or some other form of computerese)
F<...> - filenames, displayed in italics

And you can do any combination of them (e.g. typewriter font which is
both bold and italic together).

Mapping table to troff font styles in Pod::Man source code is here:
https://metacpan.org/source/RRA/podlators-4.11/lib/Pod/Man.pm#L190-205

> > 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, ...

Now I'm looking into Pod::Man sources and that ".ie n" condition is
generated only at one place (there are comments in code):
https://metacpan.org/source/RRA/podlators-4.11/lib/Pod/Man.pm#L651-705

Plus decision if quoting is needed or not has some strange heuristic...
https://metacpan.org/source/RRA/podlators-4.11/lib/Pod/Man.pm#L419-454

Looks like a big mess.

> 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

Looks like that those ".ie n" conditions are there as a workaround for
some Solaris bugs.

Anyway, on terminal output everything is in typewriter/monospaced font,
so double quotes make sense on terminal as some optical visualization
that text is in different font style. For output devices which support
also different font styles and not only typewriter (html, ps, pdf, ...),
double quotes should not be used.

So I guess some condition is still needed. In groff it could be possible
to check for typewriter-like device via .T register, but such thing is
not portable...

I would ask maintainers of Pod::Man module what can be done with this
problem or how can be situation improved.

Question 1) below is just same problem as this.

> > 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,

Yea, this is also something which is not clear to me...

I tried to find something about it... and in Pod::Simple documentation
is explanation:

https://metacpan.org/pod/Pod::Simple#$parser-%3Estrip_verbatim_indent(-SOMEVALUE-)

Metacpan uses Pod::Simple::XHTML for converting POD to HTML and probably
has its own function which do some magic with these leading spaces in
source code blocks.

> 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.

So mandoc here cannot do nothing.

> > 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<strict refs>
> 
> So the vertical spacing that metacpan does *after* the list tag looks
> dubious for me - doesn't that make many other lists look bad?

=item directive is used lot of times for describing functions or methods
of some class.

In perlpod documentation is written:

And perhaps most importantly, keep the items consistent: either use
"=item *" for all of them, to produce bullets; or use "=item 1.",
"=item 2.", etc., to produce numbered lists; or use "=item foo",
"=item bar", etc.--namely, things that look nothing like bullets or
numbers. If you start with bullets or numbers, stick with them, as
formatters use the first "=item" type to decide how to format the list.

So it is questionable... Maybe bullets and numbers specified via =item
should be formatted differently as "=item text"?

> 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 <ul> rather than <dl>
>    https://github.com/Debian/debiman/issues/67
>    loc ** exist ** algo ** size * imp ***

-- 
Pali Rohár
pali.rohar@gmail.com
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv