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 3394 invoked from network); 17 Oct 2023 21:39:40 -0000 Received: from bsd.lv (HELO mandoc.bsd.lv) (66.111.2.12) by inbox.vuxu.org with ESMTPUTF8; 17 Oct 2023 21:39:40 -0000 Received: from fantadrom.bsd.lv (localhost [127.0.0.1]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id e79a7a64 for ; Tue, 17 Oct 2023 21:39:37 +0000 (UTC) Received: from sin.source.kernel.org (sin.source.kernel.org [145.40.73.55]) by mandoc.bsd.lv (OpenSMTPD) with ESMTP id dcdccc85 for ; Tue, 17 Oct 2023 21:39:37 +0000 (UTC) Received: from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58]) by sin.source.kernel.org (Postfix) with ESMTP id 75E55CE20E7; Tue, 17 Oct 2023 21:39:34 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 4D4B2C433C8; Tue, 17 Oct 2023 21:39:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1697578773; bh=dcMj1AwlQjxBIWLnwUBFqGb+KRYgEe2VPhV1UDKExMc=; h=Date:From:To:Cc:Subject:References:In-Reply-To:From; b=VSBebT89wBiBjcphtdVP1J1BtLeki9RG9J5P00IsWF17776hSZgcc80o3GMEqtKNW 8oKrlM0PjJZu1OOEcWyA4FW4a2Sdax32RBmu3ZBxXMifjMMbCW1gupeCC3OhDMU6Qa L0Aj5uuQX+k/udECGAIXg7cf5Sn4SvTpR3T2oIQuU/jG+V2KwpeQSqUsJD8/hU/rkC wv8/0FW2O1g7TlqjCy91QS74ypiQks+KRwQpZKSUiijV8kH52lA/+ia4hXYTvUz+4x S2uaP5do6SjbxqvE+0EudspnHw41TmVyWFG7POT7wbawnjuw6pxZmaChAbZljJc7A4 Z+5IZ6Ly+vsDQ== Date: Tue, 17 Oct 2023 23:39:23 +0200 From: Alejandro Colomar To: Ingo Schwarze Cc: tech@mandoc.bsd.lv Subject: Re: mandoc -man -Thtml: unwanted line break after bullet (.IP) 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="qzWCfx8NXcVaOT5A" Content-Disposition: inline In-Reply-To: --qzWCfx8NXcVaOT5A Content-Type: text/plain; protected-headers=v1; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable Date: Tue, 17 Oct 2023 23:39:23 +0200 From: Alejandro Colomar To: Ingo Schwarze Cc: tech@mandoc.bsd.lv Subject: Re: mandoc -man -Thtml: unwanted line break after bullet (.IP) On Tue, Oct 17, 2023 at 09:02:55PM +0200, Ingo Schwarze wrote: > Hi Alejandro, >=20 [...] >=20 > > The Debian package doesn't provide any CSS file, which seems like a > > packaging bug: > > > > $ apt-file show mandoc | grep css > > $ apt-file find mandoc.css > > $ >=20 > Hmmm... >=20 > https://salsa.debian.org/debian/mdocml/-/blob/master/debian/patches/confi= gure.local.patch >=20 > tells me that the Debian port doesn't include man.cgi(8). > Now unfortunately, my upstream Makefile, >=20 > https://cvsweb.openbsd.org/src/usr.bin/mandoc/Makefile >=20 > which Debian appears to use, installs mandoc.css only with "make > cgi-install", not with plain "make install", and i suspect that's > the reason why the *.deb package ends up without it. >=20 > It would probably be better if "make install" in my Makefile also > installed mandoc.css. The original motivation for only installing it > together with man.cgi was that back on the day, i thought using man.cgi > might be the most common way of using mandoc HTML output. Thinking > about it right now, that's probably not even true: there are only a > handful of mandoc-based man.cgi servers wordwide, so there are almost > certainly more people who use mandoc HTML output in different ways. > And as you found out the hard way, when you care about minute > formatting details, CSS is essential, even if you are not running > man.cgi. >=20 > On OpenBSD, we actually install *two* copies of mandoc.css. One copy > is installed by default in /usr/share/misc/mandoc.css. That copy is > intended for users who run mandoc -T html manually. The other copy is > not installed by default, but it is installed when users manually run > "make installcgi" in /usr/src/usr.bin/mandoc/, and it is installed > to /var/www/htdocs/mandoc.css, which is inside the default HTTP server > chroot on OpenBSD such that man.cgi can use it. >=20 > Portable mandoc probably ought to do something similar. >=20 > So arguably, the packaging issue on Debian was caused by questionable > upstream defaults. Makes sense. >=20 > > Hmm, in the bookworm page there's the bug, but not on buster. They > > probably format the pages with with the corresponding system. >=20 > I doubt that. I have talked to Michael Stapelberg several times, and > we discussed various details and various ways in which his setup is > unavoidably complicated, but i don't recall that he ever mentioned > manpages.debian.org transparently - and invisibly for the user - > redirected to several different servers for several different OS > versions running different OS version themselves. Getting such a > system to work would be quite complicated, and maintaining it highly > inconvenient, in particular considering all the other non-trivial > tasks connected to the server that Michael had to take care of. >=20 > Frankly, it also wouldn't make sense. If you serve manual pages > for old Debian versions with the newest software, you get better > formatting quality and more reliable manual page parsing for users. > Why on earth would you expose users who want to look up manual > pages for old versions to formatting bugs that have already been > fixed? >=20 > Besides, on first sight, i don't see which difference between >=20 > https://manpages.debian.org/bookworm/manpages/ftm.7.en.html and > https://manpages.debian.org/buster/manpages/ftm.7.en.html >=20 > you mean. The date and version number in the page footer differ, > but at least on first sight, spacing looks similar to me. Here's what I see in the bookworm one: And buster: >=20 >=20 > Alejandro Colomar wrote on Mon, Oct 16, 2023 at 07:28:40PM +0200: >=20 > > My bad here; I was testing both my command and your command, and > > accidentally mixed the resulting files. I've re-tested, and if I don't > > specify -Ostyle=3Dmandoc.css, it embeds CSS. However, that CSS seems to > > be defective, >=20 > The embedded style sheet is not "defective"; it is "simple". > Here is what the mandoc(1) manual page says: >=20 > If a style-sheet is not specified with -O style, -T html defaults > to simple output (via an embedded style-sheet) readable in any > graphical or text-based web browser. >=20 > All it claims is that the embedded style sheet is simple and that > the output is readable. It does *not* claim that the output > perfectly matches -T utf8 terminal output. Actually, perfectly > matching terminal output is hard even with the complicated mandoc.css > stylesheet. >=20 > It is intentional that the embedded stylesheet only deals with the > most fundamental formatting tasks, in particular selecting > adequate font-styles and font-weights for the various macros > and making sure that the page header doesn't look too bad. > Beyond that, it doesn't bother regarding whitespace. >=20 > I don't think embedding the complete mandoc.css into each and every > output file would be a reasonable choice. When embedded CSS is > used as a fallback, keeping it minimal makes sense, i think. >=20 > Consequently, unless i'm missing something, with respect to what > you reported in the thread "unwanted line break", it seems to me > everything is working as intended. >=20 > Maybe i could clarify the mandoc(1) manual page a bit. Essentially > calling mandoc.css an "example style sheet" may have been adequate > when this text was originally written, but over the years, the file > mandoc.css has been polished so much that nowadays, calling it "the > standard style sheet" would make more sense. There should probably be > a warning that using a different style sheet isn't really recommended > unless the user has an above-average understanding of both CSS and > of the custom classes used in mandoc HTML output. Otherwise, using > a different stylesheet is more likely to degrade the user experience > than to customize formatting according to the wishes of the person > writing their own CSS. Agree. By reading the manual, I expected that the embedded would be somewhat similar to mandoc.css, but I agree that keeping it simple is fine. Just that maybe it needs to be clarified that one will usually want to specify the mandoc.css file (which we should get in the .deb). Thanks, Alex >=20 > Yours, > Ingo --=20 --qzWCfx8NXcVaOT5A Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAABCgAdFiEE6jqH8KTroDDkXfJAnowa+77/2zIFAmUu/wsACgkQnowa+77/ 2zJ0DxAAlgaSZLxojDy0MkPJ33GvZqHY7dTiQppjmiBvLA/OxuYLqJflS46r3neT K93jaK1KugPKg4FGdo93gBT76UOkehAEgvsQ95wj4TkD3XF+TQoWDnKz3mnvAJnJ YSoh8tOYiY/sM01xE5uh00Tz00WcfIVcuga2X8NumjKTBtO/f8uCKH4QXRpZ1VHt +YLfDLraMi7AB06WiNRR8YXWTAX6XiLvMN/c31pD8SeJ28dfg2vSmc9jJkaOileG E9kUA+vl1O88tpj7aoH4dpELISWtXgbYNshAKSPDarxfYi0UprEB5BnpgnPak7X8 WDjBhf4h5JAZ3pxZr64CHbgiYNDDZbpn+IgUrQ1u5HQPpti0+htCdDmk8i8RsW8m e50W/oDP1SSeykgcSv6G0mKac50eCdn04D/HEaUspXulcTae0rYcNa/Mp0gFp8yr wpMHS4yVN9uI1BFwwE6Prp6WeF/qtHMYuumcQFbDweGoptjhFS8/5S2xiXaylI3F +AjpWMS+vP7VwYofxQh3e+N5EgDPg/O4OhKqrom17vwbTtLVhf/4vsuOZzX14SL/ zrSfumH6kpHH4jTBZZKLtSkB6XvI4+9iaI9nVFRppjenQoB/Uv5YInuN6QbMuBaJ 218A7zyTO2nCU8+ryc2b5HHYSUukWbAQu954bWfJQX8btiSGSOw= =Dh+H -----END PGP SIGNATURE----- --qzWCfx8NXcVaOT5A-- -- To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv