Re: mandoc & perl documentation

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

On Sunday 25 November 2018 19:20:08 Ingo Schwarze wrote:
> Hi Pali,
> 
> Pali Rohar wrote on Sun, Nov 25, 2018 at 02:34:26PM +0100:
> > On Saturday 24 November 2018 20:31:52 Ingo Schwarze wrote:
> >> Pali Rohar wrote on Fri, Oct 26, 2018 at 10:15:19AM +0200:
> 
> >>> And you can do any combination of them (e.g. typewriter font
> >>> which is both bold and italic together).
> 
> >> So, let's check the combinations:
> >> 
> >>  * I<B<...>>      to   \fI\f(BI...\fI\fR
> >>  * I<C<...>>      to   \fI\f(CI"..."\fI\fR
> >>  * B<I<...>>      to   \fB\f(BI...\fB\fR
> >>  * B<C<...>>      to   \fB\f(CB"..."\fB\fR
> >>  * C<I<...>>      to   \f(CW"\f(CI...\f(CW"\fR
> >>  * C<B<...>>      to   \f(CW"\f(CB...\f(CW"\fR
> >>  * C<I<...>>      to   \f(CW"\f(CI...\f(CW"\fR
> >>  * I<B<C<...>>>   to   \fI\f(BI\f(CB"..."\f(BI\fI\fR
> >>  * I<B<C<...>>>   to   \fI\f(CI"\f(CB...\f(CI"\fI\fR
> >>  * B<I<C<...>>>   to   \fB\f(BI\f(CB"..."\f(BI\fB\fR
> >>  * B<C<I<...>>>   to   \fB\f(CB"\f(CB...\f(CB"\fB\fR
> >>  * C<I<B<...>>>   to   \f(CW"\f(CI\f(CB...\f(CI\f(CW"\fR
> >>  * C<B<I<...>>>   to   \f(CW"\f(CB\f(CB...\f(CB\f(CW"\fR
>  
> > Question is if last 6 lines are correctly translated.
> 
> That is a question about pod2man(1), not a question about mandoc(1).
> Regarding mandoc(1), the question only is whether it correctly
> handles whatever pod2man(1) produces.
> 
> > Should not it be typewriter font which has both italic and bold
> > style? Because currently it is just bold typewriter and not italic.
> 
> In principle, yes, and i don't doubt that in the typesetting business,
> you can find fixed-width font families looking typewriter-like and
> providing a font with style bold+italic.
> 
> > Has troff, groff
> 
> That hardly matters.  If groff (or any other full roff implementation)
> does not provide a font with certain properties users desire, they
> can usually install additional fonts themselves.
> 
> > or mandoc some sequence of italic bold typewriter font?
> 
> For terminal, PostScript, and PDF output, mandoc does not provide
> any typewriter font whatsoever.  For terminal output, no other
> formatter can portably do so, either.
> 
> Regarding HTML output, there is actually a (rather tricky) way to
> request a typewriter-bold-italic font, and it does work in mandoc:
> 
>    $ cat tmp.man
>   .TH TEST 1
>   .SH NAME
>   test \(en test
>   .SH DESCRIPTION
>   initial text
>   .EX
>   .B
>   .I typewriter-bold-italic
>   .EE
>   final text
> 
>    $ mandoc -T html -O style=mandoc.css tmp.man
>   [...]
>   initial text
>   <pre>
>   <b><i>typewriter-bold-italic</i></b>
>   </pre>
>   final text
> 
> Now, <pre> requests monospace by default, so browsers typically
> render this text in a monospace bold-italic font.
> 
> Note that even though the above example file is correct and unambiguous,
> groff -T html totally mishandles it: it renders
> 
>   initial text
>   <i><br>
>   typewriter-bold-italic</i> <br>
>   final text
> 
> So both the typewriter and the bold a totally lost - the reason
> being that groff -T html cannot do structural analysis, and on the
> presentational level, .EX simply does ".ft CW", which the \fB from .B
> overrides, and which the \fI from .I overrides yet again.
> 
> 
> It is not obvious to me how the above could be made useful for Perl
> documentation.  The pod2man(1) program certainly cannot translate C<...>
> to .EX - not only because that is a man-ext GNU extension, but even
> more so because it is a block macro rather than an inline macro
> which would totally break both horizontal and vertical spacing.
> And i don't see any other macro in the man(7) language to request
> a typewriter font.  Even resorting to the low-level roff(7) .ft request
> wouldn't help because it would get overridden by the subsequent .B
> macro rather than stacking up with it.
> 
> So making all this useful for Perl would probably require using
> \f[CBI], but i have doubts about the portability.  Mandoc could
> easily be taught to cope (it doesn't right now, but would simply
> ignore \f[CBI]), but what about other formatters?

It looks like there is no standard way to support it. So I guess current
behavior of pod2man is the best what can be done.

> 
> >> Right now, it seems to me that pod2man(1) formats
> >> bulleted and numbered lists as
> >> 
> >>   .IP "\(bu" 6
> >>   First item.
> >>   .IP "\(bu" 6
> >>   Second item.
> >> 
> >> which is definitely fine,
> 
> > I'm not sure if it is fine.
> 
> Well, the rendering by pod2man(1) shown above certainly *is* fine,
> i don't see in which other way it could reasonably format such a list.

You are right, it is really OK.

> What you are calling into question below is whether mandoc(1) -T html
> handles the above man(7) code well.
> 
> > Here is simple test.pod file:
> > 
> > $ cat test.pod
> > =pod
> > 
> > =over
> > 
> > =item *
> > 
> > Description of item1
> > 
> > =item *
> > 
> > Description of item2
> > 
> > =back
> > 
> > =cut
> > 
> > Converting it directly to HTML via pod2html results in:
> > 
> > $ pod2html test.pod
> > ...
> > <ul>
> > <li><p>Description of item1</p>
> > </li>
> > <li><p>Description of item2</p>
> > </li>
> > </ul>
> > ...
> > 
> > But converting it into man and then via mandoc converting it into HTML
> > results in:
> > 
> > $ pod2man test.pod | ./mandoc -Thtml
> > ...
> > <div class="manual-text">
> > <div>&#x00A0;</div>
> > <dl class="Bl-tag">
> >   <dt>&#x2022;</dt>
> >   <dd>Description of item1</dd>
> > </dl>
> > <dl class="Bl-tag">
> >   <dt>&#x2022;</dt>
> >   <dd>Description of item2</dd>
> > </dl>
> > </div>
> > ...
> 
> You have a point here.  The mandoc -man -T html formatter could be
> improved in two respects:
> 
>  * If the argument to .IP is a single bullet-like character,
>    it could be rendered as <ul> rather than <dl>.
> 
>    Heh, checking the TODO file, i just noticed this was already
>    reported in https://github.com/Debian/debiman/issues/67 .
> 
>  * Subsequent .IP macros could be rendered into a common list
>    rather than opening a new list for each item.
> 
>    I just add a new TODO entry for this idea, see the commit below.

Ok, so resolving these two points on TODO list should fix above reported
problem.

> 
> > Bullet (&#2022) generated by mandoc is on previous line as description
> > text. So something is not there fine. I see it in chrome and also in
> > elinks:
> > 
> > $ pod2man test.pod | ./mandoc -Thtml | elinks -dump
> > ...
> >    •
> >            Description of item1
> > 
> >    •
> >            Description of item2
> > ...
> > 
> > And when I print mandoc output on terminal, then description and bullet
> > are on the same line:
> > 
> > $ pod2man test.pod | ./mandoc
> > ...
> >        •   Description of item1
> > 
> >        •   Description of item2
> > ...
> > 
> > So this looks like a problem in mandoc's HTML output.
> 
> No, *that* is not the problem.  The unusual line breaking is merely
> caused by your omission of "-O style=/path/to/mandoc.css".
> Without using a style sheet, expecting beauty in HTML rendering is
> not reasonable.
> 
> Unfortunately, i cannot make "-O style" the default because no
> sane default can be designed for "/path/to/".
> 
> Yours,
>   Ingo
> 
> 
> Log Message:
> -----------
> HTML formatting of .IP
> 
> Modified Files:
> --------------
>     mandoc:
>         TODO
> 
> Revision Data
> -------------
> Index: TODO
> ===================================================================
> RCS file: /home/cvs/mandoc/mandoc/TODO,v
> retrieving revision 1.275
> retrieving revision 1.276
> diff -LTODO -LTODO -u -p -r1.275 -r1.276
> --- TODO
> +++ TODO
> @@ -399,8 +399,14 @@ are mere guesses, and some may be wrong.
>    in the CSS for .Bl-tag first.
>    Reminded by Pali Rohar 25 Oct 2018 10:10:35 +0200.
>  
> +- format multiple subsequent .IP as a single list
> +  rather than opening a new list for each item
> +  Pali Rohar 25 Nov 2018 14:34:26 +0100
> +  loc *  exist **  algo *  size *  imp ***
> +
>  - format ".IP *" etc. as <ul> rather than <dl>
>    https://github.com/Debian/debiman/issues/67
> +  reminded by Pali Rohar 25 Nov 2018 14:34:26 +0100
>    loc ** exist ** algo ** size * imp ***
>  
>  - .Bf at the beginning of a paragraph inserts a bogus 1ex horizontal

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