Re: mandoc & perl documentation

[Ingo Schwarze <schwarze@usta.de>]

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?


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

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.


> 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
--
 To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv