From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-wr1-f66.google.com (mail-wr1-f66.google.com [209.85.221.66]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 270f36af for ; Sun, 25 Nov 2018 08:34:29 -0500 (EST) Received: by mail-wr1-f66.google.com with SMTP id x10so16219381wrs.8 for ; Sun, 25 Nov 2018 05:34:29 -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:in-reply-to:user-agent; bh=HL5S/NTrKc36VdTlff2Wkzda12ko5UQmJPefJ+LlaZQ=; b=nzijANRNw/8Loa2s1+m2s+GWSbaAsuiPtp6a5aIloN3lXBWkVty1ySPIRsbxfuJqVa JYeEJRlT+7hqb03jgw07eQnT9u4/+HrYAJ5thwBkmAxDgtdPbLcenQfjk/LsyWxDV4H/ 06rCOAo0oN67GVLH5jN0D2HBGYYoaLnpqSUgJZVUfyp7gUSKjGi83JtuFUSFhBUQYyou 11qvbKDWGRApGEs3anHiC1kp/QDkUyeqARh681R1JyZcvu+wDQMclRfHQ7OuhO6Grl1y gDvWIm4AjTrPuNXPz1pOqOiN4ZDpitXKtIRmZKq+eKvhoMiQE4t01im1FNnEE2dEi8SC Hr3g== 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:in-reply-to:user-agent; bh=HL5S/NTrKc36VdTlff2Wkzda12ko5UQmJPefJ+LlaZQ=; b=JuLed4eb8aaWnk4k1TQ1aAN4rwc1vmkmFjR8S/WNUxGfrXzYQvYIZseK68o+9VNoAM qJovsGTS1TXD2tDL/y9v1SpQsCL79Bze/RWigP0wFcN9N0QoSNKBMJGsL74Z6QeWinLd W50QAddvx5XVznMmSloU+pnX0VLD8dFJML0rslYn2dzo2WsQLcWb5LChSok2YAAyU7tS J6sAVOkopYpBoQetf8JtZ82ZtkYWQpWFSM+AwtrXBjSWf2y6AsAYVfAf6RbyAY1DzhUE 2y0XDyhhRimLqPsGexENrP7VPZ6hQHgUsSTGIAlHJIPp6/lSzvBstFH2QtK6VpyXxqhO +njQ== X-Gm-Message-State: AA+aEWZNcsBIf4dhzz7IW/PF1M2hxf2pEy7vNub2ft2nXfe6GB9Gvnx7 HKV9TAksw+gGWF5fQLwtGqE= X-Google-Smtp-Source: AFSGD/XZ/2w3LGdHTTd7pObyAeLftVZoNnDaQuKRZMize8Wr9I80PGjo4hL9H6bznz+XkHXrnB3yag== X-Received: by 2002:adf:9d4a:: with SMTP id o10-v6mr18933953wre.94.1543152868341; Sun, 25 Nov 2018 05:34:28 -0800 (PST) Received: from pali ([2a02:2b88:2:1::5cc6:2f]) by smtp.gmail.com with ESMTPSA id l3sm40492849wru.36.2018.11.25.05.34.26 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Sun, 25 Nov 2018 05:34:27 -0800 (PST) Date: Sun, 25 Nov 2018 14:34:26 +0100 From: Pali =?utf-8?B?Um9ow6Fy?= To: Ingo Schwarze Cc: discuss@mandoc.bsd.lv Subject: Re: mandoc & perl documentation Message-ID: <20181125133426.s77sfsadbkz6jhcl@pali> 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> X-Mailinglist: mandoc-discuss Reply-To: discuss@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="v5fs4jmwsoaue6wb" Content-Disposition: inline In-Reply-To: <20181124193152.GC16061@athene.usta.de> User-Agent: NeoMutt/20170113 (1.7.2) --v5fs4jmwsoaue6wb Content-Type: text/plain; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Saturday 24 November 2018 20:31:52 Ingo Schwarze wrote: > Hi Pali, >=20 > getting back to this matter, i had another, closer look and it seems > to me that two aspects were still open: >=20 > 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: >=20 >=20 > FIRST ASPECT: > Does mandoc support all font styles that perlpod(1) can request? >=20 > >>> 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. >=20 > [...] > >> 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. > >>=20 > >> 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. >=20 > > 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 >=20 > I checked all these, pod2man(1) translates them as follows: >=20 > * I<...> to \fI...\fR > * B<...> to \fB...\fR > * C<...> to \f(CW\*(C`...\*(C'\fR =3D=3D \f(CW"..."\fR > * F<...> to \fI...\fR >=20 > Mandoc handles all of \fI \fR \fB \f(CW, so there should be nothing > to fix so far, right? Yes, seems this is working fine. > It appears F<...> behaves exactly like I<...>, so i'll disregard it > below. >=20 > > And you can do any combination of them (e.g. typewriter font which is > > both bold and italic together). >=20 > So, let's check the combinations: >=20 > * 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. Should not it be typewriter font which has both italic and bold style? Because currently it is just bold typewriter and not italic. Has troff, groff or mandoc some sequence of italic bold typewriter font? It is probably something very unusual as a big Computer Modern font family does not have such style too. > Mandoc also handles \f(BI \f(CI \f(CB, > so all of that that should work, too. >=20 > Of course, in terminal output, >=20 > \f(CW =3D \fR > \f(CI =3D \fI > \f(CB =3D \fB >=20 > which can't be helped, but apart from that, i don't see anything > that is still unimplemented, or do i overlook something? >=20 >=20 > SECOND ASPECT: > Does mandoc handle the man(7) code generated from =3Dover/=3Ditem > as well as possible? >=20 > >>> 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 separate= d. > >>> To compare, look at metacpan page and search for "strict refs". >=20 > >> That is not a section name, not even a subsection name, but merely a > >> list tag formatted as follows: > >>=20 > >> =3Dover 6 > >>=20 > >> =3Ditem C > >>=20 > >> So the vertical spacing that metacpan does *after* the list tag looks > >> dubious for me - doesn't that make many other lists look bad? >=20 > > =3Ditem directive is used lot of times for describing functions or meth= ods > > of some class. > >=20 > > In perlpod documentation is written: > >=20 > > And perhaps most importantly, keep the items consistent: either use > > "=3Ditem *" for all of them, to produce bullets; or use "=3Ditem 1.", > > "=3Ditem 2.", etc., to produce numbered lists; or use "=3Ditem foo", > > "=3Ditem 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 "=3Ditem" type to decide how to format the lis= t. > >=20 > > So it is questionable... Maybe bullets and numbers specified via =3Ditem > > should be formatted differently as "=3Ditem text"? >=20 > Maybe, not sure. But am i right that if so, that is a task for pod2man(1= ), Yes. > not for mandoc(1)? Right now, it seems to me that pod2man(1) formats > bulleted and numbered lists as >=20 > .IP "\(bu" 6 > First item. > .IP "\(bu" 6 > Second item. >=20 > which is definitely fine, I'm not sure if it is fine. Here is simple test.pod file: $ cat test.pod =3Dpod =3Dover =3Ditem * Description of item1 =3Ditem * Description of item2 =3Dback =3Dcut Converting it directly to HTML via pod2html results in: $ pod2html test.pod =2E..

  • Description of item1

  • Description of item2

=2E.. But converting it into man and then via mandoc converting it into HTML results in: $ pod2man test.pod | ./mandoc -Thtml =2E..
 
•
Description of item1
•
Description of item2
=2E.. 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 =2E.. =E2=80=A2 Description of item1 =E2=80=A2 Description of item2 =2E.. And when I print mandoc output on terminal, then description and bullet are on the same line: $ pod2man test.pod | ./mandoc =2E.. =E2=80=A2 Description of item1 =E2=80=A2 Description of item2 =2E.. So this looks like a problem in mandoc's HTML output. > and lists with "=3Ditem foo" in just the same way as >=20 > .IP "foo" 6 > Description of foo. > .IP "bar" 6 > Description of bar. >=20 > which is probably also fine for many cases, but maybe not ideal for > the specific case you are quoting. >=20 > 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. >=20 > If pod2man(1) wanted blank lines between each =3Ditem 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: >=20 > foo > .PP > .RS 6n > Description of foo. > .RE > .PP > bar > .PP > .RS 6n > Description of bar. > .RE >=20 > Yours, > Ingo --=20 Pali Roh=C3=A1r pali.rohar@gmail.com --v5fs4jmwsoaue6wb Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iF0EABECAB0WIQS4VrIQdKium2krgIWL8Mk9A+RDUgUCW/qk3gAKCRCL8Mk9A+RD UkS1AJ9v07Tc0+2daRD+xBZJYPyAuJlCbgCghd6a0+gmNJm8VZnxqm98dZmV4ow= =5N4n -----END PGP SIGNATURE----- --v5fs4jmwsoaue6wb-- -- To unsubscribe send an email to discuss+unsubscribe@mandoc.bsd.lv