From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout-kit-01.scc.kit.edu (scc-mailout-kit-01.scc.kit.edu [129.13.231.81]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id cc842865 for ; Sun, 25 Nov 2018 13:20:10 -0500 (EST) Received: from asta-nat.asta.uni-karlsruhe.de ([172.22.63.82] helo=hekate.usta.de) by scc-mailout-kit-01.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1gQz0q-0002ZT-KQ; Sun, 25 Nov 2018 19:20:10 +0100 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1gQz0q-0004yj-Eg; Sun, 25 Nov 2018 19:20:08 +0100 Received: from athene.usta.de ([172.24.96.10]) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1gQz0q-0004we-Bc; Sun, 25 Nov 2018 19:20:08 +0100 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id 68170c1e; Sun, 25 Nov 2018 19:20:08 +0100 (CET) Date: Sun, 25 Nov 2018 19:20:08 +0100 From: Ingo Schwarze To: Pali Rohar Cc: discuss@mandoc.bsd.lv Subject: Re: mandoc & perl documentation Message-ID: <20181125182008.GB45828@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> <20181025213027.GA41690@athene.usta.de> <20181026081519.jbqkllanc4x7snod@pali> <20181124193152.GC16061@athene.usta.de> <20181125133426.s77sfsadbkz6jhcl@pali> 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: <20181125133426.s77sfsadbkz6jhcl@pali> User-Agent: Mutt/1.8.0 (2017-02-23) 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> to \fI\f(BI...\fI\fR >> * I> to \fI\f(CI"..."\fI\fR >> * B> to \fB\f(BI...\fB\fR >> * B> to \fB\f(CB"..."\fB\fR >> * C> to \f(CW"\f(CI...\f(CW"\fR >> * C> to \f(CW"\f(CB...\f(CW"\fR >> * C> to \f(CW"\f(CI...\f(CW"\fR >> * I>> to \fI\f(BI\f(CB"..."\f(BI\fI\fR >> * I>> to \fI\f(CI"\f(CB...\f(CI"\fI\fR >> * B>> to \fB\f(BI\f(CB"..."\f(BI\fB\fR >> * B>> to \fB\f(CB"\f(CB...\f(CB"\fB\fR >> * C>> to \f(CW"\f(CI\f(CB...\f(CI\f(CW"\fR >> * C>> 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 
  typewriter-bold-italic
final text Now, 
 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
  

  typewriter-bold-italic 

  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
> ...
> 
    
> 
  • Description of item1
    
> 
    • 
> 
  • Description of item2
    
> 
    • 
> 

> ...
> 
> But converting it into man and then via mandoc converting it into HTML
> results in:
> 
> $ pod2man test.pod | ./mandoc -Thtml
> ...
> 

> 
 

> 

>   
•

>   
Description of item1

> 

> 

>   
•

>   
Description of item2

> 

> 

> ...

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

   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 (ߦ) 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 
       rather than 
      
   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