On 1/25/22 01:29, G. Branden Robinson wrote:
Hi, Alex!
At 2022-01-24T21:48:51+0100, Alejandro Colomar wrote:
I wrote a filter chess game a few days ago, and wrote some manual
pages for it. When I decided to serve the manual pages online on my
website, I found a few bugs, that I guess are groff responsibility,
since I produced the html pages this way:
$ <chess-init.6 groff -m man -T html >chess-init.6.html
Yup, nothing wrong with this. (Though as you probably know, most people
don't perform input redirections before command words in the shell. It
does have the piquant effect of making the input _look_ superficially
more like HTML itself...)
I know that people don't have my preferences for redirections. In case
of a long pipeline, I clearly have this preference, since it makes more
sense logically: <input filter | filter | filter >output
which I typically format as:
<input \
filter \
|filter \
|filter \
>output
When there's just one filter, I have doubts about which one I prefer.
The logical ordering is, well, logical. But the common way of putting
the redirections in the end is also nice, since it clearly shows what
the command is. You'll see both orderings from me, depending on the
phase of the moon :/
I'll report one of them here, and expect a few more email threads for
other bugs.
Full speed ahead! The list's been quiet this month. (bug-groff@, not
so much.)
Yup, I didn't expect to contribute so much to groff by writing such a
small game! Wanna play? :p
So, the first problem I met is, for the following code:
[
.PP
This `PP` call is superfluous in light of the `TP` immediately after it.
However, it doesn't seem to have any effect on the bug.
.TP
Board:
.RS
.TP
.B \(aq \(aq
Empty black cell.
[snip]
But, on the html file, I see (firefox and chrome show the same thing):
[
Board:
' ' Empty black cell.
'-' Empty white cell.
Pieces:
B, b Bishop.
K, k King.
N, n Knight.
P, p Pawn.
Q, q Queen.
R, r Rook.
]
Can reproduce with Firefox.
With the first block incorrectly indented. Text-based browsers such
as w3m(1) or links(1) also show weird indentation; you can check them
too.
With lynx(1) I get no indentation at all from the relative insets, so
it's inconsistent, but also invisible.
I haven't seen any browser that displays the proper indentation,
so I guess it's not a browser problem (but it might very well be).
I'm not sure, but I lean against it. grohtml(1), which I don't fully
understand, uses an HTML table to represent essentially the entire body
of this document.
It does that even if I comment out the RS/RE calls. I guess grohtml
imposes a table on the document body unconditionally.
You can check the manual page full source code at
<http://www.alejandro-colomar.es/src/alx/alx/games/chessutils.git/tree/share/man/man6/chess-init.6>
and the html page at
<http://www.alejandro-colomar.es/man/man6/chess-init.6.html>
I see no problems with your input apart from the aforementioned harmless
redundancy, but then I expect such high quality from someone who's
ground through as many pages as you have. :D
I would have expected to do it correctly too :D.
The thing is, I thought myself, "is this .PP necessary?", and I didn't
think too much, and was lazy enough to not read the manual, so I left it
just in case. But I should have remembered that I had answered this to
myself many months ago, and created a mental rule that consecutive .?P
macros are redundant, since they open new paragraphs. I hope I will
remember next time.
By reporting this, you have become the first contributor to chessutils
[1]. Thanks you! :-)
I think you've identified a legitimate grohtml bug. Could you file it
with the Savannah bug tracker
<https://savannah.gnu.org/bugs/?group=groff&func=additem>? I'd title it
"grohtml does not track man(7) relative insets accurately" or something
like that.
Nice, will do!
Cheers,
Alex
Regards,
Branden
[1]:
http://www.alejandro-colomar.es/src/alx/alx/games/chessutils.git/commit/?id=5ea1fac6d2ebc9861f976db00f29f41a4f3ea10f
--
Alejandro Colomar
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/