From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout-kit-02.scc.kit.edu (scc-mailout-kit-02.scc.kit.edu [129.13.231.82]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 05dff416 for ; Sat, 24 Nov 2018 14:31:56 -0500 (EST) Received: from asta-nat.asta.uni-karlsruhe.de ([172.22.63.82] helo=hekate.usta.de) by scc-mailout-kit-02.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1gQdek-00037t-DP; Sat, 24 Nov 2018 20:31:55 +0100 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1gQdei-0001CA-IM; Sat, 24 Nov 2018 20:31:52 +0100 Received: from athene.usta.de ([172.24.96.10]) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1gQdei-0001GC-Dk; Sat, 24 Nov 2018 20:31:52 +0100 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id f14e597e; Sat, 24 Nov 2018 20:31:52 +0100 (CET) Date: Sat, 24 Nov 2018 20:31:52 +0100 From: Ingo Schwarze To: Pali Rohar Cc: discuss@mandoc.bsd.lv Subject: Re: mandoc & perl documentation Message-ID: <20181124193152.GC16061@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> X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20181026081519.jbqkllanc4x7snod@pali> User-Agent: Mutt/1.8.0 (2017-02-23) Hi Pali, getting back to this matter, i had another, closer look and it seems to me that two aspects were still open: Pali Rohar wrote on Fri, Oct 26, 2018 at 10:15:19AM +0200: > On Thursday 25 October 2018 23:30:27 Ingo Schwarze wrote: >> 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: FIRST ASPECT: Does mandoc support all font styles that perlpod(1) can request? >>> 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 I checked all these, pod2man(1) translates them as follows: * I<...> to \fI...\fR * B<...> to \fB...\fR * C<...> to \f(CW\*(C`...\*(C'\fR == \f(CW"..."\fR * F<...> to \fI...\fR Mandoc handles all of \fI \fR \fB \f(CW, so there should be nothing to fix so far, right? It appears F<...> behaves exactly like I<...>, so i'll disregard it below. > 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 Mandoc also handles \f(BI \f(CI \f(CB, so all of that that should work, too. Of course, in terminal output, \f(CW = \fR \f(CI = \fI \f(CB = \fB which can't be helped, but apart from that, i don't see anything that is still unimplemented, or do i overlook something? SECOND ASPECT: Does mandoc handle the man(7) code generated from =over/=item as well as possible? >>> 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 >> >> 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"? Maybe, not sure. But am i right that if so, that is a task for pod2man(1), not for mandoc(1)? 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, and lists with "=item foo" in just the same way as .IP "foo" 6 Description of foo. .IP "bar" 6 Description of bar. which is probably also fine for many cases, but maybe not ideal for the specific case you are quoting. That man(7) code does not permit inserting a blank output line between the .IP "foo" and the "Description of foo." If "foo" is short enough, i.e. less than 6n, it does not even ask for a line break between the two. If pod2man(1) wanted blank lines between each =item header and the subsequent body, it would have to emit something like the following - right? That's certainly not the only possibility way to request such blank lines, but one option: foo .PP .RS 6n Description of foo. .RE .PP bar .PP .RS 6n Description of bar. .RE Yours, Ingo -- To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv