From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-wm1-f44.google.com (mail-wm1-f44.google.com [209.85.128.44]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 844a6da8 for ; Mon, 26 Nov 2018 03:48:26 -0500 (EST) Received: by mail-wm1-f44.google.com with SMTP id z18so2585252wmc.4 for ; Mon, 26 Nov 2018 00:48:26 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=date:from:to:cc:subject:message-id:references:mime-version :content-disposition:content-transfer-encoding:in-reply-to :user-agent; bh=fEOx6rGmY2QnaBKSehbQOKsS83/h2xiY6Vmi2oVeu1k=; b=OZKmBLqjW4TiTBvuDdnUZYGPo7YDC6/RKLEPKyjZ+25QB47AoWd2OsONiCIj9M+LAM lBEUDur94BKLRotVFpoOyN/RZTRhSTZ37eIcwbeqEf3HNb2NNvoindfSo+ajF8tn8EZm BWcF5pcWY8gR7P8/uBkeWAW9R3DiZJkUQrColB68DvQFPTWWCIptttAda3vrx7a1QKcA 2tWK+vf4C0zbrQR/lz4UQMIeqTKNaKbX4NBbwNk/loWukcKAEthYzVeDLb5Tnrua2Yut KW9rcQm1SmW22ACs9U60ELDdRr83I1y6wJ2PE0jfKYSMLGUl0/gG+KCfRKXDe6olBqGV gKwg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:content-transfer-encoding :in-reply-to:user-agent; bh=fEOx6rGmY2QnaBKSehbQOKsS83/h2xiY6Vmi2oVeu1k=; b=O3KGMYbkqICtjOfmHvzs8RYEBkKVX1kV8XTKRbkL/A/M949pFJ+hs3GTZOYcjwR3IN ZsQAeMxXGJAPWCas7TjVG/unZs0VhprSJNo7kAlooVhU01Fs/KvkAEL3ROcERzjhoj29 LRL4Q7mNrwMUq/rtExipEjuv2lRehn2M/YMhjcc/S1oZu4WlI3dP+J1Ws5Nh8urfZzqf ntX67Weyrjjsk3Lt6UNFvgu+v77CdLC9MnAAf5J7WVfAVbTjrXXdG/Ix03TuwdkNvZo8 +wMnnOikHFzxbSrhhlAQJ3Fi24ZLpp3a5IyC15q6SPJQEK1cHugdaNtK5DUHMCpeIikS CPTw== X-Gm-Message-State: AA+aEWbzluTWas6GAVlTGS49sdHDyVoxbBQnhl5cmHG4BSNZYX6YRx9e TF96To7HEZr7hRq3sm1y1Bo= X-Google-Smtp-Source: AFSGD/XZTbKaaILvkftWmU809QKRRlf9AOsd10PIjCimscMixpU05cdqq1fywhIqHYMMI82esF+xsg== X-Received: by 2002:a7b:c044:: with SMTP id u4mr22243336wmc.50.1543222102643; Mon, 26 Nov 2018 00:48:22 -0800 (PST) Received: from pali ([2a02:2b88:2:1::5cc6:2f]) by smtp.gmail.com with ESMTPSA id l15sm34796641wrw.4.2018.11.26.00.48.21 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Mon, 26 Nov 2018 00:48:21 -0800 (PST) Date: Mon, 26 Nov 2018 09:48:20 +0100 From: Pali =?utf-8?B?Um9ow6Fy?= To: Ingo Schwarze Cc: discuss@mandoc.bsd.lv Subject: Re: mandoc & perl documentation Message-ID: <20181126084820.qcnoxobkontrodqv@pali> References: <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> <20181125182008.GB45828@athene.usta.de> 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: <20181125182008.GB45828@athene.usta.de> User-Agent: NeoMutt/20170113 (1.7.2) 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> 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?

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

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

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

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