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

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

[Alejandro Colomar]

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

Hi Ingo,

mandoc -man -Thtml produces a line break after a .IP \[bu] 3
groff(1) doesn't, which is consistent with how both mandoc(1) and
groff(1) format that code in a terminal.

Is that behavior intended, or accidental?

You can check it in the same ftm(7) page that I reported a bug recently.

Cheers,
Alex

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

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

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

[Ingo Schwarze]

Hi Alejandro,

Alejandro Colomar wrote on Mon, Oct 16, 2023 at 03:17:07PM +0200:

> mandoc -man -Thtml produces a line break after a .IP \[bu] 3
> groff(1) doesn't, which is consistent with how both mandoc(1) and
> groff(1) format that code in a terminal.
> 
> Is that behavior intended, or accidental?

So far, i'm unable to reproduce your problem.

With the test file appended below and the command

  mandoc -Thtml -Ostyle=mandoc.css test.1 > test.html

i get the expected semantically correct output containing
dl, dt, and dd elements, but not the br element that you claim
to be present in the output you get.  Specifically:

  <p class="Pp">initial text</p>
  <dl class="Bl-tag">
    <dt>&#x2022;</dt>
    <dd>final text</dd>
  </dl>

For testing, i have also put up the file here:

  https://man.bsd.lv/Test/test.1

The output looks correct to me.  There certainly isn't any line break
after the bullet; as expected, the "final text" follows on the same
line.

Needless to say, when you worry about white space issues in web
design, correctly using CSS is essential, because obviously, the
HTML code only specifies the semantic structure of the text but
does *not* specifiy physical formatting details like white space
or line breaks.

Can you be more specific which input file, which mandoc command,
and which CSS file you are using?

If you worry about the relatively wide indentation of the "final text",
that's because mandoc.css hardcodes "margin-left: 5.5em;"
for the .Bl-tag class.  Theoretically, mandoc(1) could honour
the .IP width argument by adding an explicit, physical-formatting
"style" attribute to the individial HTML dl element.  But adding
style attributes to individual HTML elements is considered
deprecated and very bad style in modern HTML, so mandoc doesn't
do that.

This really isn't specific to mandoc but applies to all web design
in general.  If you use any HTML autogeneration tool (not just
mandoc) and embed any *physical* formatting instructions into
your document source code (in this case, the width argument "3"),
such crowbar-style coding will usually result in poor formatting
or be ignored outright by the HTML generation tool.

> You can check it in the same ftm(7) page that I reported a bug
> recently.

After copying

  https://manpages.debian.org/bullseye/manpages/ftm.7.en.html

to my server at

  https://man.bsd.lv/Test/ftm.7#Feature_test_macros_understood_by_glibc

i can't see the problem neither there nor on manpages.debian.org.
Note that manpages.debian.org *does* use the mandoc rendering engine,
so having a bug in mandoc that does not show up on manpages.debian.org
would be slightly surprising, unless the bug was recently introduced
in mandoc.

Anyway, on both servers, i do not see line breaks after the bullets.
For example, look at the lines:

  The macros that you most likely need to use ...
  Defining _XOPEN_SOURCE with a value of 700 or greater ...

Yours,
  Ingo


.TH TEST 1
.SH NAME
test \- test
.SH DESCRIPTION
initial text
.IP \[bu] 3
final text
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv

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

[Jan Stary]

On Oct 16 16:52:14, schwarze@usta.de wrote:
> as expected, the "final text" follows on the same line.

For completeness: it doesn't, in lynx.
But that's on lynx, which seems to make the break after <dt>

--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv

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

[Ingo Schwarze]

Hi Jan,

Jan Stary wrote on Mon, Oct 16, 2023 at 05:20:19PM +0200:
> On Oct 16 16:52:14, schwarze@usta.de wrote:

>> as expected, the "final text" follows on the same line.

> For completeness: it doesn't, in lynx.
> But that's on lynx, which seems to make the break after <dt>

Does Lynx provide any support for CSS whatsoever?

The lynx(1) manual page doesn't seem to mention CSS.

Using a web search engine to search the Lynx homepage for "CSS"
brings up a single page,

  https://lynx.invisible-island.net/lynx2.8.8/breakout/CHANGES

and the two instances of the string "CSS" on that page give me
the impression that lynx(1) likely does not have any CSS support.

The non-authoritative page

  https://shkspr.mobi/blog/2020/12/how-and-why-to-use-lynx-the-faster-web-browser/

explicitly claims that it has no CSS support.

As i said, expecting any particular whitespace formatting when
processing HTML input is completely unreasonable without correctly
working CSS support.  The HTML language simply isn't designed for
anything like that.

Yours,
  Ingo
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv

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

[Ingo Schwarze]

Hi Jan,

sorry for not realizing before sending my first reply how easy it is
to actually test this.  So here is a second reply:

Jan Stary wrote on Mon, Oct 16, 2023 at 05:20:19PM +0200:
> On Oct 16 16:52:14, schwarze@usta.de wrote:

>> as expected, the "final text" follows on the same line.

> For completeness: it doesn't, in lynx.
> But that's on lynx, which seems to make the break after <dt>

   $ ktrace lynx tmp.html  # once in lynx, hit the "q" and "y" keys
   $ kdump | grep css     
     <link rel="stylesheet" href="mandoc.css" type="text/css" media="all"\
   $ ls -al mandoc.css
     -rw-r--r--  1 schwarze  wsrc  8920 Mar 17  2022 mandoc.css

So, lynx(1) sees the link element in the input file,
the CSS file is present in the right place and readable,
but lynx(1) does not even attempt to read it.

So, not really a surprise that whitespace does not work at all
in lynx(1).

Yours,
  Ingo
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv

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

[Alejandro Colomar]

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

Hi Ingo,

On Mon, Oct 16, 2023 at 04:52:14PM +0200, Ingo Schwarze wrote:
> Hi Alejandro,
> 
> Alejandro Colomar wrote on Mon, Oct 16, 2023 at 03:17:07PM +0200:
> 
> > mandoc -man -Thtml produces a line break after a .IP \[bu] 3
> > groff(1) doesn't, which is consistent with how both mandoc(1) and
> > groff(1) format that code in a terminal.
> > 
> > Is that behavior intended, or accidental?
> 
> So far, i'm unable to reproduce your problem.
> 
> With the test file appended below and the command

I could reproduce it with the test file you sent.

	$ mandoc -Thtml test.1 > test.html

I can reproduce with both:

	$ lynx test.html
	$ firefox test.html

> 
>   mandoc -Thtml -Ostyle=mandoc.css test.1 > test.html

Where's this mandoc.css?  Is it a file you have locally?

> 
> i get the expected semantically correct output containing
> dl, dt, and dd elements, but not the br element that you claim
> to be present in the output you get.  Specifically:
> 
>   <p class="Pp">initial text</p>
>   <dl class="Bl-tag">
>     <dt>&#x2022;</dt>
>     <dd>final text</dd>
>   </dl>

Agree, I get this same HTML code.  I don't see an html <br/> element.

> 
> For testing, i have also put up the file here:
> 
>   https://man.bsd.lv/Test/test.1

Yes, that looks good to me.

> 
> The output looks correct to me.  There certainly isn't any line break
> after the bullet; as expected, the "final text" follows on the same
> line.
> 
> Needless to say, when you worry about white space issues in web
> design, correctly using CSS is essential, because obviously, the
> HTML code only specifies the semantic structure of the text but
> does *not* specifiy physical formatting details like white space
> or line breaks.
> 
> Can you be more specific which input file, which mandoc command,
> and which CSS file you are using?

I'm not using any.  mandoc(1) seems to be requesting mandoc.css, which
doesn't exist in my system, so that's probably the problem.

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
	$

But the mandoc(1) manual page says that if no CSS file is specified, it
should embed a style sheet in the HTML, which seems to contradict the
resulting HTML:

```html
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8"/>
  <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
  <link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
  <title>TEST(1)</title>
</head>
```

mandoc(1):
   HTML Output
       ...

       The   file   /usr/share/misc/mandoc.css  documents  style‐sheet
       classes available for customising output.  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.


Is this a mandoc(1) bug?  Or a packaging bug?

> 
> If you worry about the relatively wide indentation of the "final text",
> that's because mandoc.css hardcodes "margin-left: 5.5em;"
> for the .Bl-tag class.  Theoretically, mandoc(1) could honour
> the .IP width argument by adding an explicit, physical-formatting
> "style" attribute to the individial HTML dl element.  But adding
> style attributes to individual HTML elements is considered
> deprecated and very bad style in modern HTML, so mandoc doesn't
> do that.
> 
> This really isn't specific to mandoc but applies to all web design
> in general.  If you use any HTML autogeneration tool (not just
> mandoc) and embed any *physical* formatting instructions into
> your document source code (in this case, the width argument "3"),
> such crowbar-style coding will usually result in poor formatting
> or be ignored outright by the HTML generation tool.
> 
> > You can check it in the same ftm(7) page that I reported a bug
> > recently.
> 
> After copying
> 
>   https://manpages.debian.org/bullseye/manpages/ftm.7.en.html
> 
> to my server at
> 
>   https://man.bsd.lv/Test/ftm.7#Feature_test_macros_understood_by_glibc
> 
> i can't see the problem neither there nor on manpages.debian.org.
> Note that manpages.debian.org *does* use the mandoc rendering engine,
> so having a bug in mandoc that does not show up on manpages.debian.org
> would be slightly surprising, unless the bug was recently introduced
> in mandoc.
> 
> Anyway, on both servers, i do not see line breaks after the bullets.
> For example, look at the lines:
> 
>   The macros that you most likely need to use ...
>   Defining _XOPEN_SOURCE with a value of 700 or greater ...

Hmm, in the bookworm page there's the bug, but not on buster.  They
probably format the pages with with the corresponding system.  As a
welcome side effect, this also helps trace the regression.

Check here:
<https://manpages.debian.org/bookworm/manpages/ftm.7.en.html>

I uploaded your test page in my server:
<https://www.alejandro-colomar.es/man/man0/test-20231016-01.0.html>
(your browser will complain about the SSL cert; read here:
<https://www.alejandro-colomar.es/ssl>).

This is what I'm using:
$ dpkg -l | grep mandoc
ii  mandoc     1.14.6-1+b1      amd64       BSD manpage compiler toolset


Cheers,
Alex

> 
> Yours,
>   Ingo
> 
> 
> .TH TEST 1
> .SH NAME
> test \- test
> .SH DESCRIPTION
> initial text
> .IP \[bu] 3
> final text
> --
>  To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv
> 

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

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

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

[Alejandro Colomar]

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

On Mon, Oct 16, 2023 at 07:10:22PM +0200, Alejandro Colomar wrote:
> Hi Ingo,
> 
> On Mon, Oct 16, 2023 at 04:52:14PM +0200, Ingo Schwarze wrote:
> > Hi Alejandro,
> > 
> > Alejandro Colomar wrote on Mon, Oct 16, 2023 at 03:17:07PM +0200:
> > 
> > > mandoc -man -Thtml produces a line break after a .IP \[bu] 3
> > > groff(1) doesn't, which is consistent with how both mandoc(1) and
> > > groff(1) format that code in a terminal.
> > > 
> > > Is that behavior intended, or accidental?
> > 
> > So far, i'm unable to reproduce your problem.
> > 
> > With the test file appended below and the command
> 
> I could reproduce it with the test file you sent.
> 
> 	$ mandoc -Thtml test.1 > test.html
> 
> I can reproduce with both:
> 
> 	$ lynx test.html

(I've seen your messages about lynx(1) now; never mind this line.)

> 	$ firefox test.html
> 
> > 
> >   mandoc -Thtml -Ostyle=mandoc.css test.1 > test.html
> 
> Where's this mandoc.css?  Is it a file you have locally?
> 
> > 
> > i get the expected semantically correct output containing
> > dl, dt, and dd elements, but not the br element that you claim
> > to be present in the output you get.  Specifically:
> > 
> >   <p class="Pp">initial text</p>
> >   <dl class="Bl-tag">
> >     <dt>&#x2022;</dt>
> >     <dd>final text</dd>
> >   </dl>
> 
> Agree, I get this same HTML code.  I don't see an html <br/> element.
> 
> > 
> > For testing, i have also put up the file here:
> > 
> >   https://man.bsd.lv/Test/test.1
> 
> Yes, that looks good to me.
> 
> > 
> > The output looks correct to me.  There certainly isn't any line break
> > after the bullet; as expected, the "final text" follows on the same
> > line.
> > 
> > Needless to say, when you worry about white space issues in web
> > design, correctly using CSS is essential, because obviously, the
> > HTML code only specifies the semantic structure of the text but
> > does *not* specifiy physical formatting details like white space
> > or line breaks.
> > 
> > Can you be more specific which input file, which mandoc command,
> > and which CSS file you are using?
> 
> I'm not using any.  mandoc(1) seems to be requesting mandoc.css, which
> doesn't exist in my system, so that's probably the problem.
> 
> 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
> 	$
> 
> But the mandoc(1) manual page says that if no CSS file is specified, it
> should embed a style sheet in the HTML, which seems to contradict the
> resulting HTML:
> 
> ```html
> <!DOCTYPE html>
> <html>
> <head>
>   <meta charset="utf-8"/>
>   <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
>   <link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
>   <title>TEST(1)</title>
> </head>
> ```
> 
> mandoc(1):
>    HTML Output
>        ...
> 
>        The   file   /usr/share/misc/mandoc.css  documents  style‐sheet
>        classes available for customising output.  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.
> 
> 
> Is this a mandoc(1) bug?  Or a packaging bug?
> 
> > 
> > If you worry about the relatively wide indentation of the "final text",
> > that's because mandoc.css hardcodes "margin-left: 5.5em;"
> > for the .Bl-tag class.  Theoretically, mandoc(1) could honour
> > the .IP width argument by adding an explicit, physical-formatting
> > "style" attribute to the individial HTML dl element.  But adding
> > style attributes to individual HTML elements is considered
> > deprecated and very bad style in modern HTML, so mandoc doesn't
> > do that.
> > 
> > This really isn't specific to mandoc but applies to all web design
> > in general.  If you use any HTML autogeneration tool (not just
> > mandoc) and embed any *physical* formatting instructions into
> > your document source code (in this case, the width argument "3"),
> > such crowbar-style coding will usually result in poor formatting
> > or be ignored outright by the HTML generation tool.
> > 
> > > You can check it in the same ftm(7) page that I reported a bug
> > > recently.
> > 
> > After copying
> > 
> >   https://manpages.debian.org/bullseye/manpages/ftm.7.en.html
> > 
> > to my server at
> > 
> >   https://man.bsd.lv/Test/ftm.7#Feature_test_macros_understood_by_glibc
> > 
> > i can't see the problem neither there nor on manpages.debian.org.
> > Note that manpages.debian.org *does* use the mandoc rendering engine,
> > so having a bug in mandoc that does not show up on manpages.debian.org
> > would be slightly surprising, unless the bug was recently introduced
> > in mandoc.
> > 
> > Anyway, on both servers, i do not see line breaks after the bullets.
> > For example, look at the lines:
> > 
> >   The macros that you most likely need to use ...
> >   Defining _XOPEN_SOURCE with a value of 700 or greater ...
> 
> Hmm, in the bookworm page there's the bug, but not on buster.  They
> probably format the pages with with the corresponding system.  As a
> welcome side effect, this also helps trace the regression.
> 
> Check here:
> <https://manpages.debian.org/bookworm/manpages/ftm.7.en.html>
> 
> I uploaded your test page in my server:
> <https://www.alejandro-colomar.es/man/man0/test-20231016-01.0.html>
> (your browser will complain about the SSL cert; read here:
> <https://www.alejandro-colomar.es/ssl>).
> 
> This is what I'm using:
> $ dpkg -l | grep mandoc
> ii  mandoc     1.14.6-1+b1      amd64       BSD manpage compiler toolset
> 
> 
> Cheers,
> Alex
> 
> > 
> > Yours,
> >   Ingo
> > 
> > 
> > .TH TEST 1
> > .SH NAME
> > test \- test
> > .SH DESCRIPTION
> > initial text
> > .IP \[bu] 3
> > final text
> > --
> >  To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv
> > 
> 
> -- 
> <https://www.alejandro-colomar.es/>



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

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

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

[Alejandro Colomar]

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

On Mon, Oct 16, 2023 at 07:10:22PM +0200, Alejandro Colomar wrote:
> 
> But the mandoc(1) manual page says that if no CSS file is specified, it
> should embed a style sheet in the HTML, which seems to contradict the
> resulting HTML:
> 
> ```html
> <!DOCTYPE html>
> <html>
> <head>
>   <meta charset="utf-8"/>
>   <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
>   <link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
>   <title>TEST(1)</title>
> </head>
> ```

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, as it seems to produce the same results on firefox.

Here you can inspect the page with embedded CSS:
<https://www.alejandro-colomar.es/man/man0/test-20231016-02.0.html>

> 
> mandoc(1):
>    HTML Output
>        ...
> 
>        The   file   /usr/share/misc/mandoc.css  documents  style‐sheet
>        classes available for customising output.  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.
> 
> 
> Is this a mandoc(1) bug?  Or a packaging bug?

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

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

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

[Ingo Schwarze]

Hi Alejandro,

Alejandro Colomar wrote on Mon, 16 Oct 2023 19:10:22 +0200:

> I could reproduce it with the test file you sent.
>    $ mandoc -Thtml test.1 > test.html

Well, that isn't surprising.  As i explained, if you do not use CSS,
you cannot expect any particular white space behaviour - nor any
particular fonts, font sizes, colours etc. etc. for that matter, simply
because the HTML language (at least the modern version, HTML 5) is
not designed to contain any such information.  Historical versions of
HTML, i.e. HTML 4 (standardized in 1997) and earlier, provided limited
physical formatting capabilities, but those didn't really work well.
Nowadays, using anything but HTML 5 wouldn't really make sense.
It has been standardized for almost a decade now (since 2014).

All the above doesn't apply to mandoc only, but it applies to *any*
HTML code and to *any* web site: remove the CSS, and you remove almost
all of the formatting and web design.

If you ask me, HTML 5 still isn't a very good language, typical
design by committee, but certainly better than HTML 4.  Oh well,
what can we do...  I don't think i'm the guy who will save the web.

>>   mandoc -Thtml -Ostyle=mandoc.css test.1 > test.html
> where's this mandoc.css?  Is it a file you have locally?

https://cvsweb.bsd.lv/mandoc/mandoc.css
https://man.bsd.lv/mandoc.css
https://cvsweb.openbsd.org/src/usr.bin/mandoc/mandoc.css
https://man.openbsd.org/mandoc.css
https://man.voidlinux.org/mandoc.css

So it's kind of all over the place.  :-)

It is also contained in the release tarballs:

schwarze@fantadrom $ tar -tzvf mandoc-1.14.6.tar.gz | grep css
-rw-r--r--  1 schwarze schwarze 8906 Sep 23 2021 mandoc-1.14.6/mandoc.css

schwarze@fantadrom $ tar -tzvf mdocml-1.14.1.tar.gz | grep css 
-rw-r--r--  1 schwarze wsrc     3932 Feb 21 2017 mdocml-1.14.1/mandoc.css

> 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.

> 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.


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.

Yours,
  Ingo
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv

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

[Alejandro Colomar]

[-- 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 --]

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

[Ingo Schwarze]

Hi Alejandro,

Alejandro Colomar wrote on Tue, Oct 17, 2023 at 11:39:23PM +0200:

> Here's what I see in the bookworm one: <https://i.imgur.com/EW9B5Cq.png>
> And buster: <https://i.imgur.com/6WBolqG.png>

Ah, thank you for pointing me to the specific place where you found
a difference.  Yes, you are right, there is a difference there.

However, that difference is caused by a difference in the manual page
source code, not by a difference in the formatter.

The bookworm manual pages contains:

  First, though, a summary of a few details for the impatient:
  .IP \[bu] 3
  The macros that you most likely need to use in modern source code are

mandoc(1) renders that as:

  <p class="Pp">First, though, a summary of a few details
  for the impatient:</p>
  <dl class="Bl-tag">
    <dt>&#x2022;</dt>
    <dd>The macros that you most likely need to use in modern source...

that is, as a tagged list, because it is not (yet) smart enough to
figure out the ".IP \[bu]" is intended as a bullet list.

By contrast, the buster manual page contains:

  First, though a summary of a few details for the impatient:
  .IP * 3
  The macros that you most likely need to use in modern source code are

mandoc(1) renders that as:

  <p class="Pp">First, though a summary of a few details
  for the impatient:</p>
  <ul class="Bl-bullet">
    <li>The macros that you most likely need to use in modern source...

which is obviously much more visually pleasing and also makes more sense
semantically.

The problem here is that just like it is *significantly* more difficult
to write a good man(7) page than a good mdoc(7) page - due to the fact
that the man(7) language is totally inadequate, by its fundamental
design, to express semantic markup - it is *massively* more difficult
to produce good HTML output from man(7) than from mdoc(7), and for
exactly the same reason that makes writing man87) so difficult
for humans in the first place: The man(7) language is a purely
presentational language with no feature whatsoever to convey anything
semantic, whereas the HTML language is a purely semantic language
with no feature whatsoever for expressing anything presentational.

Consequently, the mdoc(7) HTML formatter is very straightforward:
  .Bl -tag      becomes   <dl>
  .Bl -bullet   becomes   <ul>
  .Bl -enum     becomes   <ol>
and we are *certain* that we have met the manual page author's intention.
End of the story, everybody is happy now.

For man(7), almost anything we do involves crude guesswork.
Both .TP and .IP can become any of <dl>, <ul>, or <ol> and which
is the right one has to be *guessed* from the content.
In addition, while mdoc(7) makes it explicit where a list begins
and where that list ends, in man(7), we have to *guess* whether
any given .TP/.IP macro begins, continues, or ends a list.

Look at https://cvsweb.bsd.lv/mandoc/man_html.c?rev=HEAD ,
function man_IP_pre().  Right now, it maps
  .IP *           to   .Bl -bullet
  .IP \(bu        to   .Bl -bullet
  .IP -           to   .Bl -dash
  anything else   to   .Bl -tag
together with its helper function list_continues().

Now, the function list_continues() already recognizes \(bu as a
potential marker for a bullet list.  But that buster manual page
uses \[bu] instead.  I'm not saying that is wrong, mind you.

What i am saying is that parsing and formatting the man(7) language
is a nightmare and fragile as hell.  The fundamental design of that
language is totally 1970ies-style, and it shows in each and every
corner.  I'm not blaming Doug; at the time man(7) was designed, it was
a monumental step forward, and nobody could have been expected to do
better in the 1970ies.  But after Cynthia Livingston invented mdoc(7)
in 1989/90 and Tim Berners-Lee invented HTML in 1989/90, the fundamental
concept of man(7) was totally outdated with no redeeming qualities
and no hope for healing, and it should have been completely abandoned
by 1995 at the latest.  A documentation language that is essentially
presentational obviously has no place in this millenium.

All the same, this conversation has been useful, and i need to change
three aspects of mandoc.  So, thanks for reporting!

 1. change the Makefile to always install mandoc.css
 2. better document what mandoc.css is needed for,
    what the embedded default CSS does and does not provide,
    and that using a custom CSS file requires a high level of
    proficiency in both the CSS and the mdoc(7) languages
 3. teach list_continues() that \[bu] is the same as \(bu.

But this is really an uphill battle.  As long as you rely on man(7),
the fundamental design of that language implies that you will again
and again bump into similar formatting issues - even with mandoc.

Still, as long as man(7) is used in the wild, please keep reporting
such issues.  I rarely look at man(7) pages, so i need reports from
the field to be able to make progress.

Yours,
  Ingo
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv

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

[Alejandro Colomar]

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

Hi Ingo,


On Wed, Oct 18, 2023 at 02:04:46AM +0200, Ingo Schwarze wrote:
[...]
> 
> The problem here is that just like it is *significantly* more difficult
> to write a good man(7) page than a good mdoc(7) page - due to the fact
> that the man(7) language is totally inadequate, by its fundamental
> design, to express semantic markup - it is *massively* more difficult
> to produce good HTML output from man(7) than from mdoc(7), and for
> exactly the same reason that makes writing man87) so difficult
> for humans in the first place: The man(7) language is a purely
> presentational language with no feature whatsoever to convey anything
> semantic, whereas the HTML language is a purely semantic language
> with no feature whatsoever for expressing anything presentational.
> 
> Consequently, the mdoc(7) HTML formatter is very straightforward:
>   .Bl -tag      becomes   <dl>
>   .Bl -bullet   becomes   <ul>
>   .Bl -enum     becomes   <ol>
> and we are *certain* that we have met the manual page author's intention.
> End of the story, everybody is happy now.

Yup.  I've set some rules (as much as the Linux man-pages can set any
standard) for writing lists consistently in man(7) pages.  Maybe that
helps get better heuristics if authors follow them:

   Lists
       There are different kinds of lists:

       Tagged paragraphs
              These are used for a list of  tags  and  their  descrip‐
              tions.   When  the  tags are constants (either macros or
              numbers) they are in bold.  Use the .TP macro.

              An example is this "Tagged paragraphs" subsection is it‐
              self.

       Ordered lists
              Elements are preceded by a number  in  parentheses  (1),
              (2).  These represent a set of steps that have an order.

              When  there  are  substeps,  they  will be numbered like
              (4.2).

       Positional lists
              Elements are preceded by  a  number  (index)  in  square
              brackets  [4],  [5].   These  represent fields in a set.
              The first index will be:

              0      When it represents fields of a C data  structure,
                     to be consistent with arrays.
              1      When  it  represents fields of a file, to be con‐
                     sistent with tools like cut(1).

       Alternatives list
              Elements are preceded by a letter  in  parentheses  (a),
              (b).   These represent a set of (normally) exclusive al‐
              ternatives.

       Bullet lists
              Elements are preceded by bullet symbols  (\[bu]).   Any‐
              thing  that  doesn’t fit elsewhere is usually covered by
              this type of list.

       Numbered notes
              Not really a list, but the syntax is identical to "posi‐
              tional lists".

       There should always be exactly 2 spaces between the list symbol
       and the elements.  This doesn’t apply to  "tagged  paragraphs",
       which use the default indentation rules.

The Linux man-pages project already uses them, with only 2 exceptions:

$ grep -rh '^\.IP .*' man* | sort | uniq -c
     42 .IP (1) 5
      1 .IP (1.1) 7
      1 .IP (1.2)
      1 .IP (1.3)
      1 .IP (1.4)
     42 .IP (2)
      1 .IP (2.1) 7
      1 .IP (2.2)
     31 .IP (3)
     20 .IP (4)
     14 .IP (5)
      1 .IP (5.1) 7
      1 .IP (5.2)
      6 .IP (6)
      4 .IP (7)
      3 .IP (8)
      2 .IP (9)
      7 .IP (a) 5
      7 .IP (b)
      2 .IP (c)
     28 .IP *
      5 .IP * 2
      3 .IP [0] 5
      3 .IP [1]
      7 .IP [1] 5
      9 .IP [2]
      7 .IP [3]
      5 .IP [4]
      3 .IP [5]
      3 .IP [6]
      2 .IP [7]
      1 .IP [8]
     96 .IP \(bu 2
   1017 .IP \[bu]
    387 .IP \[bu] 3

The exceptions are from pages that I don't control (bpf-helpers.7 is
autogenerated; I've asked the tz project if they are interested in using
this style):

$ grep -rl '\\(bu' man*
man7/bpf-helpers.7
$ grep -rl '\.IP \*' man*
man5/tzfile.5

> 
> For man(7), almost anything we do involves crude guesswork.
> Both .TP and .IP can become any of <dl>, <ul>, or <ol> and which
> is the right one has to be *guessed* from the content.
> In addition, while mdoc(7) makes it explicit where a list begins
> and where that list ends, in man(7), we have to *guess* whether
> any given .TP/.IP macro begins, continues, or ends a list.
> 
> Look at https://cvsweb.bsd.lv/mandoc/man_html.c?rev=HEAD ,
> function man_IP_pre().  Right now, it maps
>   .IP *           to   .Bl -bullet
>   .IP \(bu        to   .Bl -bullet
>   .IP -           to   .Bl -dash
>   anything else   to   .Bl -tag
> together with its helper function list_continues().

Seems good.  As you say, it's just missing \[bu].

> 
> Now, the function list_continues() already recognizes \(bu as a
> potential marker for a bullet list.  But that buster manual page
> uses \[bu] instead.  I'm not saying that is wrong, mind you.
> 
> What i am saying is that parsing and formatting the man(7) language
> is a nightmare and fragile as hell.  The fundamental design of that
> language is totally 1970ies-style, and it shows in each and every
> corner.  I'm not blaming Doug; at the time man(7) was designed, it was
> a monumental step forward, and nobody could have been expected to do
> better in the 1970ies.  But after Cynthia Livingston invented mdoc(7)
> in 1989/90 and Tim Berners-Lee invented HTML in 1989/90, the fundamental
> concept of man(7) was totally outdated with no redeeming qualities
> and no hope for healing, and it should have been completely abandoned
> by 1995 at the latest.  A documentation language that is essentially
> presentational obviously has no place in this millenium.
> 
> All the same, this conversation has been useful, and i need to change
> three aspects of mandoc.  So, thanks for reporting!

You're welcome!

> 
>  1. change the Makefile to always install mandoc.css
>  2. better document what mandoc.css is needed for,
>     what the embedded default CSS does and does not provide,
>     and that using a custom CSS file requires a high level of
>     proficiency in both the CSS and the mdoc(7) languages
>  3. teach list_continues() that \[bu] is the same as \(bu.
> 
> But this is really an uphill battle.  As long as you rely on man(7),
> the fundamental design of that language implies that you will again
> and again bump into similar formatting issues - even with mandoc.
> 
> Still, as long as man(7) is used in the wild, please keep reporting
> such issues.  I rarely look at man(7) pages, so i need reports from
> the field to be able to make progress.

:-)

Cheers,
Alex

> 
> Yours,
>   Ingo
> --
>  To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv
> 

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

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

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

[Ingo Schwarze]

Hi Alejandro,

Ingo Schwarze wrote on Wed, Oct 18, 2023 at 02:04:46AM +0200:

>  2. better document what mandoc.css is needed for,
>     what the embedded default CSS does and does not provide,
>     and that using a custom CSS file requires a high level of
>     proficiency in both the CSS and the mdoc(7) languages

That part is now done, see the commit below.

For easier access, i have also installed the updated file here:

  https://man.openbsd.org/mandoc.1#HTML_Output

Yours,
  Ingo


Log Message:
-----------
Better document the purpose and features of the file mandoc.css
and the purpose and limitations of the embedded stylesheet.

Triggered by a conversation with Alejandro Colomar <alx at kernel dot org>.

Modified Files:
--------------
    mandoc:
        mandoc.1

Revision Data
-------------
Index: mandoc.1
===================================================================
RCS file: /home/cvs/mandoc/mandoc/mandoc.1,v
retrieving revision 1.264
retrieving revision 1.265
diff -Lmandoc.1 -Lmandoc.1 -u -p -r1.264 -r1.265
--- mandoc.1
+++ mandoc.1
@@ -345,17 +345,6 @@ conforms to HTML5 using optional self-cl
 Equations rendered from
 .Xr eqn 7
 blocks use MathML.
-.Pp
-The file
-.Pa /usr/share/misc/mandoc.css
-documents style-sheet classes available for customising output.
-If a style-sheet is not specified with
-.Fl O Cm style ,
-.Fl T Cm html
-defaults to simple output (via an embedded style-sheet)
-readable in any graphical or text-based web
-browser.
-.Pp
 Non-ASCII characters are rendered
 as hexadecimal Unicode character references.
 .Pp
@@ -406,9 +395,49 @@ otherwise, the second format is used.
 .It Cm style Ns = Ns Ar style.css
 The file
 .Ar style.css
-is used for an external style-sheet.
+is used as an external stylesheet.
 This must be a valid absolute or
 relative URI.
+.Pp
+Using the file
+.Pa mandoc.css
+that is distributed with
+.Nm
+is recommended.
+It provides an appearance similar to terminal output with some additional
+features specific to
+.Nm
+HTML output, in particular making anchor locations that support
+deep linking stand out visually by putting a dotted line under them,
+providing tooltips showing the semantic function of elements (macro
+names), providing some simple aspects of responsive web design, and
+providing simple support for users who prefer a dark color scheme.
+.Pp
+Using a custom CSS file is possible, but writing it requires
+proficiency in all of the languages HTML 5, CSS 4, and
+.Xr mdoc 7
+and familiarity with the
+.Nm Ns -specific
+classes used in
+.Pa mandoc.css .
+Besides, while the file
+.Pa mandoc.css
+is always adapted to the HTML output generated by the
+.Nm
+version it is distributed with, maintaining a custom CSS file usually
+requires adaptations each time
+.Nm
+is upgraded to a new version.
+.Pp
+If a stylesheet is not specified with
+.Fl O Cm style ,
+.Fl T Cm html
+embeds a minimal stylesheet into the HTML output, mostly to select
+adequate font-style and font-weight attributes for various macros.
+The result is readable in any graphical or text-based web browser,
+but does not aim for looking similar to terminal output.
+Instead, formatting is mostly left to browser defaults
+and to user settings in the browser configuration.
 .It Cm tag Ns Op = Ns Ar term
 Same syntax and semantics as for
 .Sx ASCII Output .
@@ -738,7 +767,7 @@ To page manuals to the terminal:
 .Pp
 To produce HTML manuals with
 .Pa /usr/share/misc/mandoc.css
-as the style-sheet:
+as the stylesheet:
 .Pp
 .Dl $ mandoc \-T html -O style=/usr/share/misc/mandoc.css mdoc.7 > mdoc.7.html
 .Pp
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv

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

[Alejandro Colomar]

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

On Wed, Oct 18, 2023 at 04:48:16PM +0200, Ingo Schwarze wrote:
> Hi Alejandro,
> 
> Ingo Schwarze wrote on Wed, Oct 18, 2023 at 02:04:46AM +0200:
> 
> >  2. better document what mandoc.css is needed for,
> >     what the embedded default CSS does and does not provide,
> >     and that using a custom CSS file requires a high level of
> >     proficiency in both the CSS and the mdoc(7) languages
> 
> That part is now done, see the commit below.
> 
> For easier access, i have also installed the updated file here:
> 
>   https://man.openbsd.org/mandoc.1#HTML_Output

Thanks!  LGTM.

> 
> Yours,
>   Ingo
> 
> 
> Log Message:
> -----------
> Better document the purpose and features of the file mandoc.css
> and the purpose and limitations of the embedded stylesheet.
> 
> Triggered by a conversation with Alejandro Colomar <alx at kernel dot org>.
> 
> Modified Files:
> --------------
>     mandoc:
>         mandoc.1
> 
> Revision Data
> -------------
[...]

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

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

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

[Ingo Schwarze]

Hi Alejandro,

Ingo Schwarze wrote on Wed, Oct 18, 2023 at 02:04:46AM +0200:

>  3. teach list_continues() that \[bu] is the same as \(bu.

This part is now fixed, too, see the commit below.

The guesswork required to deal with .IP certainly isn't perfect yet,
but lets walk one step at a time, and let's start with issues that
actually cause inconvenience in real-world manual pages.

Yours,
  Ingo


Log Message:
-----------
Support the GNU-specific syntax ".IP \\[bu]" for bullet lists in man(7) 
pages that Alejandro Colomar recommends in the "Lists" subsection of
https://man7.org/linux/man-pages/man7/man-pages.7.html#STYLE_GUIDE .

For example, this will improve HTML formatting of the first list in 
the subsection "Feature test macros understood by glibc" on the page
https://manpages.debian.org/bookworm/manpages/ftm.7.en.html .

Issue reported by Alejandro Colomar <alx at kernel dot org>.

Modified Files:
--------------
    mandoc:
        man_html.c

Revision Data
-------------
Index: man_html.c
===================================================================
RCS file: /home/cvs/mandoc/mandoc/man_html.c,v
retrieving revision 1.185
retrieving revision 1.186
diff -Lman_html.c -Lman_html.c -u -p -r1.185 -r1.186
--- man_html.c
+++ man_html.c
@@ -433,10 +433,12 @@ list_continues(const struct roff_node *n
 	s2 = n2 == NULL ? "" : n2->string;
 	c1 = strcmp(s1, "*") == 0 ? '*' :
 	     strcmp(s1, "\\-") == 0 ? '-' :
-	     strcmp(s1, "\\(bu") == 0 ? 'b' : ' ';
+	     strcmp(s1, "\\(bu") == 0 ? 'b' :
+	     strcmp(s1, "\\[bu]") == 0 ? 'b' : ' ';
 	c2 = strcmp(s2, "*") == 0 ? '*' :
 	     strcmp(s2, "\\-") == 0 ? '-' :
-	     strcmp(s2, "\\(bu") == 0 ? 'b' : ' ';
+	     strcmp(s2, "\\(bu") == 0 ? 'b' :
+	     strcmp(s2, "\\[bu]") == 0 ? 'b' : ' ';
 	return c1 != c2 ? '\0' : c1 == 'b' ? '*' : c1;
 }
 
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv

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

[Alejandro Colomar]

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

On Wed, Oct 18, 2023 at 06:20:35PM +0200, Ingo Schwarze wrote:
> Hi Alejandro,
> 
> Ingo Schwarze wrote on Wed, Oct 18, 2023 at 02:04:46AM +0200:
> 
> >  3. teach list_continues() that \[bu] is the same as \(bu.
> 
> This part is now fixed, too, see the commit below.
> 
> The guesswork required to deal with .IP certainly isn't perfect yet,
> but lets walk one step at a time, and let's start with issues that
> actually cause inconvenience in real-world manual pages.
> 
> Yours,
>   Ingo
> 
> 
> Log Message:
> -----------
> Support the GNU-specific syntax ".IP \\[bu]" for bullet lists in man(7) 
> pages that Alejandro Colomar recommends in the "Lists" subsection of
> https://man7.org/linux/man-pages/man7/man-pages.7.html#STYLE_GUIDE .
> 
> For example, this will improve HTML formatting of the first list in 
> the subsection "Feature test macros understood by glibc" on the page
> https://manpages.debian.org/bookworm/manpages/ftm.7.en.html .
> 
> Issue reported by Alejandro Colomar <alx at kernel dot org>.

LGTM.  Thanks,
Alex

> 
> Modified Files:
> --------------
>     mandoc:
>         man_html.c
> 
> Revision Data
> -------------
> Index: man_html.c
> ===================================================================
> RCS file: /home/cvs/mandoc/mandoc/man_html.c,v
> retrieving revision 1.185
> retrieving revision 1.186
> diff -Lman_html.c -Lman_html.c -u -p -r1.185 -r1.186
> --- man_html.c
> +++ man_html.c
> @@ -433,10 +433,12 @@ list_continues(const struct roff_node *n
>  	s2 = n2 == NULL ? "" : n2->string;
>  	c1 = strcmp(s1, "*") == 0 ? '*' :
>  	     strcmp(s1, "\\-") == 0 ? '-' :
> -	     strcmp(s1, "\\(bu") == 0 ? 'b' : ' ';
> +	     strcmp(s1, "\\(bu") == 0 ? 'b' :
> +	     strcmp(s1, "\\[bu]") == 0 ? 'b' : ' ';
>  	c2 = strcmp(s2, "*") == 0 ? '*' :
>  	     strcmp(s2, "\\-") == 0 ? '-' :
> -	     strcmp(s2, "\\(bu") == 0 ? 'b' : ' ';
> +	     strcmp(s2, "\\(bu") == 0 ? 'b' :
> +	     strcmp(s2, "\\[bu]") == 0 ? 'b' : ' ';
>  	return c1 != c2 ? '\0' : c1 == 'b' ? '*' : c1;
>  }
>  
> --
>  To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv
> 

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

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

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

[Ingo Schwarze]

Hi Alejandro,

Ingo Schwarze wrote on Wed, Oct 18, 2023 at 02:04:46AM +0200:

>  1. change the Makefile to always install mandoc.css

Done with the commit appended below.

I believe all issues discovered in the thread "unwanted line break
after bullet" have now been fixed.  In case i missed something,
please speak up!

Yours,
  Ingo


Log Message:
-----------
Install mandoc.css by default even if man.cgi(8) is not built.
It matters because users of "mandoc -T html" typically need it.

Issue found in a conversation with Alejandro Colomar <alx at kernel aot org>.

Modified Files:
--------------
    mandoc:
        Makefile
        configure
        configure.local.example

Revision Data
-------------
Index: configure
===================================================================
RCS file: /home/cvs/mandoc/mandoc/configure,v
retrieving revision 1.82
retrieving revision 1.83
diff -Lconfigure -Lconfigure -u -p -r1.82 -r1.83
--- configure
+++ configure
@@ -111,6 +111,7 @@ BIN_FROM_SBIN=
 INCLUDEDIR=
 LIBDIR=
 MANDIR=
+MISCDIR=
 READ_ALLOWED_PATH=
 
 WWWPREFIX="/var/www"
@@ -620,6 +621,7 @@ exec > Makefile.local
 [ -z "${INCLUDEDIR}"      ] && INCLUDEDIR="${PREFIX}/include/mandoc"
 [ -z "${LIBDIR}"          ] && LIBDIR="${PREFIX}/lib/mandoc"
 [ -z "${MANDIR}"          ] && MANDIR="${PREFIX}/man"
+[ -z "${MISCDIR}"         ] && MISCDIR="${PREFIX}/share/misc"
 
 [ -z "${HTDOCDIR}"        ] && HTDOCDIR="${WWWPREFIX}/htdocs"
 [ -z "${CGIBINDIR}"       ] && CGIBINDIR="${WWWPREFIX}/cgi-bin"
@@ -658,6 +660,7 @@ BIN_FROM_SBIN	= ${BIN_FROM_SBIN}
 INCLUDEDIR	= ${INCLUDEDIR}
 LIBDIR		= ${LIBDIR}
 MANDIR		= ${MANDIR}
+MISCDIR		= ${MISCDIR}
 WWWPREFIX	= ${WWWPREFIX}
 HTDOCDIR	= ${HTDOCDIR}
 CGIBINDIR	= ${CGIBINDIR}
Index: Makefile
===================================================================
RCS file: /home/cvs/mandoc/mandoc/Makefile,v
retrieving revision 1.542
retrieving revision 1.543
diff -LMakefile -LMakefile -u -p -r1.542 -r1.543
--- Makefile
+++ Makefile
@@ -416,6 +416,7 @@ base-install: mandoc demandoc soelim
 	mkdir -p $(DESTDIR)$(MANDIR)/man5
 	mkdir -p $(DESTDIR)$(MANDIR)/man7
 	mkdir -p $(DESTDIR)$(MANDIR)/man8
+	mkdir -p $(DESTDIR)$(MISCDIR)
 	$(INSTALL_PROGRAM) mandoc demandoc $(DESTDIR)$(BINDIR)
 	$(INSTALL_PROGRAM) soelim $(DESTDIR)$(BINDIR)/$(BINM_SOELIM)
 	cd $(DESTDIR)$(BINDIR) && $(LN) mandoc $(BINM_MAN)
@@ -438,6 +439,7 @@ base-install: mandoc demandoc soelim
 	$(INSTALL_MAN) mandoc_char.7 $(DESTDIR)$(MANDIR)/man7
 	$(INSTALL_MAN) makewhatis.8 \
 		$(DESTDIR)$(MANDIR)/man8/$(BINM_MAKEWHATIS).8
+	$(INSTALL_DATA) mandoc.css $(DESTDIR)$(MISCDIR)
 
 lib-install: libmandoc.a
 	mkdir -p $(DESTDIR)$(LIBDIR)
Index: configure.local.example
===================================================================
RCS file: /home/cvs/mandoc/mandoc/configure.local.example,v
retrieving revision 1.44
retrieving revision 1.45
diff -Lconfigure.local.example -Lconfigure.local.example -u -p -r1.44 -r1.45
--- configure.local.example
+++ configure.local.example
@@ -108,11 +108,15 @@ OSNAME="OpenBSD 7.0"
 # there is no need to copy the whole block.
 # Even if you set PREFIX to something else, the other variables
 # pick it up without copying them all over.
+# MISCDIR is only used for installing the file mandoc.css.
+# That is important because users of "mandoc -T html" often need it
+# even if they are not using man.cgi(8), see mandoc(1) for details.
 
 PREFIX="/usr/local"
 BINDIR="${PREFIX}/bin"
 SBINDIR="${PREFIX}/sbin"
 MANDIR="${PREFIX}/man"
+MISCDIR="${PREFIX}/share/misc"
 
 # If BINDIR and SBINDIR are not subdirectories of the same parent
 # directory or if the basename(1) of BINDIR differs from "bin",
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv

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

[Alejandro Colomar]

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

Hi Ingo,

On Thu, Oct 19, 2023 at 01:59:22PM +0200, Ingo Schwarze wrote:
> Hi Alejandro,
> 
> Ingo Schwarze wrote on Wed, Oct 18, 2023 at 02:04:46AM +0200:
> 
> >  1. change the Makefile to always install mandoc.css
> 
> Done with the commit appended below.
> 
> I believe all issues discovered in the thread "unwanted line break
> after bullet" have now been fixed.  In case i missed something,
> please speak up!

Thanks!  Not as far as I can see.

Cheers,
Alex

> 
> Yours,
>   Ingo
> 
> 
> Log Message:
> -----------
> Install mandoc.css by default even if man.cgi(8) is not built.
> It matters because users of "mandoc -T html" typically need it.
> 
> Issue found in a conversation with Alejandro Colomar <alx at kernel aot org>.
> 
> Modified Files:
> --------------
>     mandoc:
>         Makefile
>         configure
>         configure.local.example
> 
> Revision Data
> -------------
> Index: configure
> ===================================================================
> RCS file: /home/cvs/mandoc/mandoc/configure,v
> retrieving revision 1.82
> retrieving revision 1.83
> diff -Lconfigure -Lconfigure -u -p -r1.82 -r1.83
> --- configure
> +++ configure
> @@ -111,6 +111,7 @@ BIN_FROM_SBIN=
>  INCLUDEDIR=
>  LIBDIR=
>  MANDIR=
> +MISCDIR=
>  READ_ALLOWED_PATH=
>  
>  WWWPREFIX="/var/www"
> @@ -620,6 +621,7 @@ exec > Makefile.local
>  [ -z "${INCLUDEDIR}"      ] && INCLUDEDIR="${PREFIX}/include/mandoc"
>  [ -z "${LIBDIR}"          ] && LIBDIR="${PREFIX}/lib/mandoc"
>  [ -z "${MANDIR}"          ] && MANDIR="${PREFIX}/man"
> +[ -z "${MISCDIR}"         ] && MISCDIR="${PREFIX}/share/misc"
>  
>  [ -z "${HTDOCDIR}"        ] && HTDOCDIR="${WWWPREFIX}/htdocs"
>  [ -z "${CGIBINDIR}"       ] && CGIBINDIR="${WWWPREFIX}/cgi-bin"
> @@ -658,6 +660,7 @@ BIN_FROM_SBIN	= ${BIN_FROM_SBIN}
>  INCLUDEDIR	= ${INCLUDEDIR}
>  LIBDIR		= ${LIBDIR}
>  MANDIR		= ${MANDIR}
> +MISCDIR		= ${MISCDIR}
>  WWWPREFIX	= ${WWWPREFIX}
>  HTDOCDIR	= ${HTDOCDIR}
>  CGIBINDIR	= ${CGIBINDIR}
> Index: Makefile
> ===================================================================
> RCS file: /home/cvs/mandoc/mandoc/Makefile,v
> retrieving revision 1.542
> retrieving revision 1.543
> diff -LMakefile -LMakefile -u -p -r1.542 -r1.543
> --- Makefile
> +++ Makefile
> @@ -416,6 +416,7 @@ base-install: mandoc demandoc soelim
>  	mkdir -p $(DESTDIR)$(MANDIR)/man5
>  	mkdir -p $(DESTDIR)$(MANDIR)/man7
>  	mkdir -p $(DESTDIR)$(MANDIR)/man8
> +	mkdir -p $(DESTDIR)$(MISCDIR)
>  	$(INSTALL_PROGRAM) mandoc demandoc $(DESTDIR)$(BINDIR)
>  	$(INSTALL_PROGRAM) soelim $(DESTDIR)$(BINDIR)/$(BINM_SOELIM)
>  	cd $(DESTDIR)$(BINDIR) && $(LN) mandoc $(BINM_MAN)
> @@ -438,6 +439,7 @@ base-install: mandoc demandoc soelim
>  	$(INSTALL_MAN) mandoc_char.7 $(DESTDIR)$(MANDIR)/man7
>  	$(INSTALL_MAN) makewhatis.8 \
>  		$(DESTDIR)$(MANDIR)/man8/$(BINM_MAKEWHATIS).8
> +	$(INSTALL_DATA) mandoc.css $(DESTDIR)$(MISCDIR)
>  
>  lib-install: libmandoc.a
>  	mkdir -p $(DESTDIR)$(LIBDIR)
> Index: configure.local.example
> ===================================================================
> RCS file: /home/cvs/mandoc/mandoc/configure.local.example,v
> retrieving revision 1.44
> retrieving revision 1.45
> diff -Lconfigure.local.example -Lconfigure.local.example -u -p -r1.44 -r1.45
> --- configure.local.example
> +++ configure.local.example
> @@ -108,11 +108,15 @@ OSNAME="OpenBSD 7.0"
>  # there is no need to copy the whole block.
>  # Even if you set PREFIX to something else, the other variables
>  # pick it up without copying them all over.
> +# MISCDIR is only used for installing the file mandoc.css.
> +# That is important because users of "mandoc -T html" often need it
> +# even if they are not using man.cgi(8), see mandoc(1) for details.
>  
>  PREFIX="/usr/local"
>  BINDIR="${PREFIX}/bin"
>  SBINDIR="${PREFIX}/sbin"
>  MANDIR="${PREFIX}/man"
> +MISCDIR="${PREFIX}/share/misc"
>  
>  # If BINDIR and SBINDIR are not subdirectories of the same parent
>  # directory or if the basename(1) of BINDIR differs from "bin",
> --
>  To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv
> 

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

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