From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=0.2 required=5.0 tests=DKIM_INVALID,DKIM_SIGNED, T_TVD_MIME_EPI autolearn=no autolearn_force=no version=3.4.4 Received: (qmail 16725 invoked from network); 19 Oct 2023 21:32:56 -0000 Received: from bsd.lv (HELO mandoc.bsd.lv) (66.111.2.12) by inbox.vuxu.org with ESMTPUTF8; 19 Oct 2023 21:32:56 -0000 Received: from fantadrom.bsd.lv (localhost [127.0.0.1]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 4fa896f4 for ; Thu, 19 Oct 2023 21:32:53 +0000 (UTC) Received: from dfw.source.kernel.org (dfw.source.kernel.org [139.178.84.217]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id 4a06e491 for ; Thu, 19 Oct 2023 21:32:53 +0000 (UTC) Received: from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58]) by dfw.source.kernel.org (Postfix) with ESMTP id B91D961DA5; Thu, 19 Oct 2023 21:32:52 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 99C06C433C7; Thu, 19 Oct 2023 21:32:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1697751172; bh=ZKeocx0X525PS0/3mfaNVa02NutXakOjhndP3kvKziY=; h=Date:From:To:Cc:Subject:References:In-Reply-To:From; b=jtYI1r7KbnlCSPETSF59Ono2bIhQckotEZWJn3HfAY1hZxuunbWsiyAZ5K0QdezB/ USqdpw8YqTlyUEmX6AKzK6YtPvuDdzastHF7hi4U30A12Cn5MOxQBFr2Ib5mBOF32W DOhBGBiRS09A5fkasx5UmNZRF2QFOlm+kzIEC4VHBG+666zWLODA6EJM0IfAaA/AQi n8TaWs6DBONpq1CUS3fFeBLiIECWouQVM7FwpzTfuu7N5ThiFch1qGa/4Dcqp319M/ mGlHLJNb/vMwvU7oYHzAMvtU+gxatABpubhG2WtUPKo3sdP3pgQIQCOQn/+1ubAsGq l+aaeNHpQsL4Q== Date: Thu, 19 Oct 2023 23:32:42 +0200 From: Alejandro Colomar To: Ingo Schwarze Cc: tech@mandoc.bsd.lv, branden@debian.org Subject: Re: mandoc -man -Thtml bug: inconsistent vertical space before .TP Message-ID: References: X-Mailinglist: mandoc-tech Reply-To: tech@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="eD8bkbfynv8Do8I7" Content-Disposition: inline In-Reply-To: --eD8bkbfynv8Do8I7 Content-Type: text/plain; protected-headers=v1; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable Date: Thu, 19 Oct 2023 23:32:42 +0200 From: Alejandro Colomar To: Ingo Schwarze Cc: tech@mandoc.bsd.lv, branden@debian.org Subject: Re: mandoc -man -Thtml bug: inconsistent vertical space before .TP On Thu, Oct 19, 2023 at 06:19:23PM +0200, Ingo Schwarze wrote: > Hi Alejandro, >=20 > Alejandro Colomar wrote on Thu, Oct 19, 2023 at 05:17:10PM +0200: >=20 > > I had this gripe with man(7) some years ago. I thought of using the > > following instead, which slightly complicates the source code, but makes > > it more logical. > >=20 > > $ cat nested_indent.man=20 > > .TH nested_indent 7 2023-10-19 experiments > > .SH Ingo said: > > .TP > > Todo > > Currently, when formatting .TP or .IP with a non-empty head, > > [yada yada] > > .RS > > .PP > > When formatting .IP or .RS with an empty head, mandoc needs > > [yada yada] > > .RE > >=20 > > As you can see, here the indentation is controlled by a single RS/RE > > pair, and everything within it uses PP as a normal paragraph separator. >=20 > While that also generates correct terminal and typographical (PS, PDF) > output in the same purely presentational sense as .TP .IP .TP, it > does not help with respect to the semantic problem we are discussing > here. >=20 > Look at the AST generated by mandoc(1): >=20 > $ mandoc -T tree nested_indent.man > title =3D "nested_indent" > sec =3D "7" > vol =3D "Miscellaneous Information Manual" > os =3D "experiments" > date =3D "2023-10-19" > =20 > SH (block) *2:2 > SH (head) 2:2 ID=3DHREF=3DIngo_said: > Ingo (text) 2:5 > said: (text) 2:10 > SH (body) 2:2 > TP (block) *3:2 > TP (head) 3:2 ID=3DHREF > Todo (text) *4:1 > TP (body) 4:1 > Currently, when formatting .TP or .IP \ > with a nonempty head, (text) *5:1 > [yada yada] (text) *6:1 > RS (block) *7:2 > RS (head) 7:2 > RS (body) 7:2 > PP (block) *8:2 > PP (head) 8:2 > PP (body) 8:2 > When formatting .IP or .RS with an empty head, > mandoc needs (text) *9:1 > [yada yada] (text) *10:1 > TP (block) *12:2 > TP (head) 12:2 ID=3DHREF=3Dfinal > final tag (text) *13:1 > TP (body) 13:1 > final body (text) *14:1 >=20 > You see that the first .TP, the .RS, and the second .TP are all child > nodes of the top-level .SH. The .RS is not a child of the .TP but > a sibling. The two .TP nodes still aren't siblings of each other. >=20 > Now on first sight, you might blame me for that and call it a mandoc > artifact, arguing that mandoc instead ought to treat the .RS as a > child of the first .TP. But no, that would be incorrect parsing > for the following reason: the .TP inmplies an indentation, and > the .RS also implies an indentation. If the .RS were a child of > the .TP, we would get double indentation. You can make that > argument even more convincing by adding a width argument to .RS > and varying that argument. That way, you see that the .RS is > indented relative to the .SH, not relative to the .TP. >=20 > There are some cases where it is not completely clear whether one > man(7) node following another man(7) node is a child or a sibling. > mandoc(1) makes arbitrary choices in such ambiguous cases, usually > opting for sibling relations where possible and avoiding unnecessary > child relationships. But this is not an ambiguous case. Just like > the .IP, the .RS is definitely a sibling and not a child of the .TP. > As i said, no block can nest inside .TP. >=20 > That's why i brought up .RS in my reply and developed rules > for handling it in a similar way as .IP, even though you did > not mention .RS before. >=20 > > You could put the RS before the first paragraph, but then an unwanted > > line break appears after the tag. >=20 > No matter where you put the .RS, it will never be a child of .TP. >=20 > > (Maybe man(7) could be tweaked so > > that RS doesn't insert the line break after a TP.) >=20 > Not really a useful idea because .RS doesn't help with the actual > problem in the first place. >=20 > > In the end I didn't switch to that scheme, because IP just worked, but > > I might consider it if it proves to be useful. What do you think? >=20 > As i said, i am not aware of a better solution than .TP .IP .TP. > In particular, .RS is not better because it causes exactly the > same trouble and potentially more trouble besides. >=20 > But i also said that trying to define "good style" for man(7) > is a fool's errand. Because man(7) code is so exceedingly difficult > to write, man(7) code that is very clearly bad style is very often > found in the wild, so there is ample opportunity for saying "this > is bad style." In some cases, it is also possible to point out > better style, for example >=20 > .BR "some word" . >=20 > is clearly better style than >=20 > .B some word\c > \&. >=20 > even though both are correct man(7) code and even though there are > situations in man(7) where \c is unavoidable. >=20 > But very frequently, situations arise where man(7) doesn't really > allow any good solution, and the best you can do is not making > the source gratuitiously worse than it needs to be. >=20 > The .TP .IP .TP idiom is such an example. It's definitely ugly from > both semantic and stylistic points of view, but no good solution > is available. I'm willing to go further and claim that no better > solution can be designed even if you are willing to introduce a new > macro or change the way the .TP API is defined, even in incompatible > ways, because it's not this particular macro that is broken. What is > broken is the fundamental design of the language: the language not > only predates the concept of semantic markup, but it also predates > the concept of block nesting in markup languages. Yes, that is hard > to believe for people born after 1970 because those people have > essentially grown up with HTML and LaTeX and those two markup > languages have defined their concept of what a markup language is, > but let's face it, man(7) predates those fundamental concepts, > and it shows all over the place. >=20 > As long as people are using the language, mandoc(1) needs to somehow > deal with the mess. I'm not happy with that because it is wasting a > lot of development time which could be spent in more productive ways, > but what can i do... >=20 > Yours, > Ingo Hi Ingo, Hmmm. You convinced me (about the problems of man(7)), I think. Cheers, Alex --=20 --eD8bkbfynv8Do8I7 Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAABCgAdFiEE6jqH8KTroDDkXfJAnowa+77/2zIFAmUxoHoACgkQnowa+77/ 2zLnLQ/+K9r90rlxEK5JmTh3C2/R5ZZb4w6LXAFvpr5wWisgkuD/jJQZbkWPFuHo XnfJt7adfd8Mffw9r+7/1V3eHgfBHQKKSQx3wV5vMJHMfUrC14F7n0xBtmEy1kJJ 9ZVUNcRPEwLbGr7zaefBsQvWB9FcCDdjhApjour8HsljZQ5X/sn5Y2az1MUhqTG4 KfLMPl3QeUZwPjhyXHr14eteMfvWybkc2zpjn7C4dGoPiZoN4/k0hdAVfbvp3Lx3 RJmol0IdRRSZUPRRdUY6A79OdXxhqJIvlhSeHIMDVV2csENvGwe9g3/q3oeCr2KZ r+RHi7NubbvRhE9lWeSYHDXimU5/UudqDd24rReOY7wHVjtyO0hknvOOFrJa0jDH F1uqid3eSoa2+VP+NqOqhKP5EoKDGsrbF7iwTIhvkiaPXLgiEjttkyWREu/j1yhi loctA2u3j1pCBlffhUrpotRGhfHyinqeJCHbhiGyyVgPtjbMwQmX2d10rxdCwUPM MUW/ijdhQbo94PzlfJ/XFiL95OUubjDDAkV70SuW4/vVK8v5sWrAXH+1gVSrCz9g dq65WarT9VDS0U/1TL7B1i0w4w2gLwkfs98D8EwACDrZq456LIQ54uM6stikJ7/J 8sReKDwrlOfgoR5Aq93Ng7OdwqfFRJ1tcGpPu/dBjeXE9TeNU7w= =o748 -----END PGP SIGNATURE----- --eD8bkbfynv8Do8I7-- -- To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv