tech@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Alejandro Colomar <alx@kernel.org>
To: tech@mandoc.bsd.lv
Subject: Re: mandoc -man -Thtml: unwanted line break after bullet (.IP)
Date: Mon, 16 Oct 2023 19:10:22 +0200	[thread overview]
Message-ID: <ZS1uhPglIoQJivIP@debian> (raw)
In-Reply-To: <ZS1OHqdIbZyF3ROu@asta-kit.de>

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

  parent reply	other threads:[~2023-10-16 17:10 UTC|newest]

Thread overview: 18+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2023-10-16 13:17 Alejandro Colomar
2023-10-16 14:52 ` Ingo Schwarze
2023-10-16 15:20   ` Jan Stary
2023-10-16 15:43     ` Ingo Schwarze
2023-10-16 16:03     ` Ingo Schwarze
2023-10-16 17:10   ` Alejandro Colomar [this message]
2023-10-16 17:16     ` Alejandro Colomar
2023-10-16 17:28     ` Alejandro Colomar
2023-10-17 19:02       ` Ingo Schwarze
2023-10-17 21:39         ` Alejandro Colomar
2023-10-18  0:04           ` Ingo Schwarze
2023-10-18 11:32             ` Alejandro Colomar
2023-10-18 14:48             ` Ingo Schwarze
2023-10-18 14:56               ` Alejandro Colomar
2023-10-18 16:20             ` Ingo Schwarze
2023-10-18 18:52               ` Alejandro Colomar
2023-10-19 11:59             ` Ingo Schwarze
2023-10-19 12:48               ` Alejandro Colomar

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=ZS1uhPglIoQJivIP@debian \
    --to=alx@kernel.org \
    --cc=tech@mandoc.bsd.lv \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body. 
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).