Re: mandoc -man -Thtml: unwanted line break after bullet (.IP)

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 6430 bytes --]

On Tue, Oct 17, 2023 at 09:02:55PM +0200, Ingo Schwarze wrote:
> Hi Alejandro,
> 

[...]

> 
> > 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
> >       $
> 
> Hmmm...
> 
> https://salsa.debian.org/debian/mdocml/-/blob/master/debian/patches/configure.local.patch
> 
> tells me that the Debian port doesn't include man.cgi(8).
> Now unfortunately, my upstream Makefile,
> 
>   https://cvsweb.openbsd.org/src/usr.bin/mandoc/Makefile
> 
> 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.
> 
> 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.
> 
> 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.
> 
> Portable mandoc probably ought to do something similar.
> 
> So arguably, the packaging issue on Debian was caused by questionable
> upstream defaults.

Makes sense.

> 
> > Hmm, in the bookworm page there's the bug, but not on buster.  They
> > probably format the pages with with the corresponding system.
> 
> 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.
> 
> 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?
> 
> Besides, on first sight, i don't see which difference between
> 
>   https://manpages.debian.org/bookworm/manpages/ftm.7.en.html   and
>   https://manpages.debian.org/buster/manpages/ftm.7.en.html
> 
> 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: <https://i.imgur.com/EW9B5Cq.png>
And buster: <https://i.imgur.com/6WBolqG.png>

> 
> 
> Alejandro Colomar wrote on Mon, Oct 16, 2023 at 07:28:40PM +0200:
> 
> > 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=mandoc.css, it embeds CSS.  However, that CSS seems to
> > be defective,
> 
> The embedded style sheet is not "defective"; it is "simple".
> Here is what the mandoc(1) manual page says:
> 
>   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.
> 
> 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.
> 
> 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.
> 
> 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.
> 
> 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.
> 
> 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

> 
> Yours,
>   Ingo

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]