docutils-develop

[Docutils-develop] Test failure: manpage writer

[Guenter M. <mi...@us...>]

Dear Engelbert,

running the test suite with r9464 resulted in a failure

FAIL: test_publish (test_writers.test_manpage.WriterPublishTestCase)
      (id="totest['table'][0]")

The following patch fixes it:



diff --git a/docutils/test/test_writers/test_manpage.py b/docutils/test/test_writers/test_manpage.py
index e13adedc3..9ed182c33 100644
--- a/docutils/test/test_writers/test_manpage.py
+++ b/docutils/test/test_writers/test_manpage.py
@@ -20,6 +20,9 @@
 
 
 class WriterPublishTestCase(unittest.TestCase):
+    
+    maxDiff = None
+    
     def test_publish(self):
         writer_name = 'manpage'
         for name, cases in totest.items():
@@ -251,9 +254,8 @@ def test_publish(self):
 .INDENT 0.0
 .INDENT 3.5
 .TS
-center;
-|l|l|.
-_
+box center;
+l|l.
 T{
 head
 T}\tT{
@@ -271,7 +273,6 @@ def test_publish(self):
 T}\tT{
 so
 T}
-_
 .TE
 .UNINDENT
 .UNINDENT


It this the intended output?
Is it tested with groff?

Günter

Re: [Docutils-develop] Test failure: manpage writer

[G. B. R. <g.b...@gm...>]

Hi Guenter,

I'm CCing you because it seems like everytime I post to this list, I get
a bounce telling me I'm not subscribed.  But I am...

At 2023-11-03T18:15:33-0000, Guenter Milde via Docutils-develop wrote:
> Dear Engelbert,
> 
> running the test suite with r9464 resulted in a failure
> 
> FAIL: test_publish (test_writers.test_manpage.WriterPublishTestCase)
>       (id="totest['table'][0]")
[...]
> It this the intended output?
> Is it tested with groff?

The output of groff in 1.23.0 changed slightly here.

Here's some 1.22.4/1.23.0 comparison on my system.  UTF-8 output
follows.

$ /usr/bin/nroff -v
GNU nroff (groff) version 1.22.4
$ nroff -v
GNU nroff (groff) version 1.23.0
GNU groff version 1.23.0
Copyright (C) 2022 Free Software Foundation, Inc.
GNU groff comes with ABSOLUTELY NO WARRANTY.
You may redistribute copies of groff and its subprograms
under the terms of the GNU General Public License.
For more information about these matters, see the file
named COPYING.

called subprograms:

GNU grotty (groff) version 1.23.0
GNU troff (groff) version 1.23.0

First let's look at how the original table exhibit is handled.

$ cat /tmp/docu.man
.TH foo 1 2023-11-03 "groff test suite"
.SH Name
foo \- frobnicate a bar
.TS
center;
|l|l|.
_
T{
head
T}      T{
and
T}
_
T{
1
T}      T{
2
T}
_
T{
abc
T}      T{
so
T}
_
.TE

$ /usr/bin/nroff -t -man /tmp/docu.man
foo(1)                      General Commands Manual                     foo(1)



Name
       foo - frobnicate a bar
                                    ┌─────┬─────┐
                                    │head │ and │
                                    ├─────┼─────┤
                                    │1    │ 2   │
                                    ├─────┼─────┤
                                    │abc  │ so  │
                                    └─────┴─────┘



groff test suite                  2023‐11‐03                            foo(1)
$ nroff -t -man /tmp/docu.man
foo(1)                      General Commands Manual                     foo(1)

Name
       foo - frobnicate a bar
                                   ┌──────┬─────┐
                                   │ head │ and │
                                   ├──────┼─────┤
                                   │ 1    │ 2   │
                                   ├──────┼─────┤
                                   │ abc  │ so  │
                                   └──────┴─────┘

groff test suite                  2023‐11‐03                            foo(1)

Notice:

A.  Fewer blank lines in the output after the page header; and
B.  There is now a space after the left border of the table.

With your patch, let see what we get.

$ cat /tmp/docu2.man
.TH foo 1 2023-11-03 "groff test suite"
.SH Name
foo \- frobnicate a bar
.TS
box center;
l|l.
T{
head
T}      T{
and
T}
_
T{
1
T}      T{
2
T}
_
T{
abc
T}      T{
so
T}
.TE
$ /usr/bin/nroff -t -man /tmp/docu2.man
foo(1)                      General Commands Manual                     foo(1)



Name
       foo - frobnicate a bar
                                    ┌─────┬─────┐
                                    │head │ and │
                                    ├─────┼─────┤
                                    │1    │ 2   │
                                    ├─────┼─────┤
                                    │abc  │ so  │
                                    └─────┴─────┘


groff test suite                  2023‐11‐03                            foo(1)
$ nroff -t -man /tmp/docu2.man
foo(1)                      General Commands Manual                     foo(1)

Name
       foo - frobnicate a bar
                                   ┌──────┬─────┐
                                   │ head │ and │
                                   ├──────┼─────┤
                                   │ 1    │ 2   │
                                   ├──────┼─────┤
                                   │ abc  │ so  │
                                   └──────┴─────┘

groff test suite                  2023‐11‐03                            foo(1)

Notice again:

A.  Fewer blank lines in the output after the page header; and
B.  There is now a space after the left border of the table.

I fixed several bugs in table formatting for terminal devices in groff
1.23.0, and while I was at it I made the box border handling more
consistent.

Here's the relevant commit.

commit 8f066786ea3cb5e1dbade1149e7d50ae978da202
Author: G. Branden Robinson <g.b...@gm...>
Date:   Fri Feb 3 02:22:02 2023 -0600

    [tbl]: Improve symmetry of tables in nroff mode.

    * src/preproc/tbl/table.cpp (table::compute_column_positions): If a
      table has "left separation" (it is boxed, or has a vertical rule on
      the left-hand side), increase the first column's start register value
      by 1n, for symmetry with the right-hand size.

    * src/preproc/tbl/tests/check-horizontal-line-length.sh:
    * src/preproc/tbl/tests/check-line-intersections.sh:
    * src/preproc/tbl/tests/check-vertical-line-length.sh: Update output
      expectations.

    * src/preproc/tbl/tbl.am (tbl_XFAIL_TESTS): Remove now-passing test.

    Before:

    +--+---+---+
    |a | b | c |
    +--+---+---+
    |d | e | f |
    +--+---+---+
    |g | h | i |
    +--+---+---+

    After:

    +---+---+---+
    | a | b | c |
    +---+---+---+
    | d | e | f |
    +---+---+---+
    | g | h | i |
    +---+---+---+

Further, if you want a table where every cell is boxed, that's what the
"allbox" option is for.  You can use that instead of putting "|" in your
row descriptions and adding rows consisting solely of "_".

tbl(1):
     allbox          Enclose each table entry in a box; implies box.

Regards,
Branden

Re: [Docutils-develop] Test failure: manpage writer

[Guenter M. <mi...@us...>]

Dear Branden,

thank you for the fast and comprehensive answer.

On 2023-11-03, G. Branden Robinson wrote:
> At 2023-11-03T18:15:33-0000, Guenter Milde via Docutils-develop wrote:


>> running the test suite with r9464 resulted in a failure

>> FAIL: test_publish (test_writers.test_manpage.WriterPublishTestCase)
>>       (id="totest['table'][0]")
> [...]
>> It this the intended output?
>> Is it tested with groff?

> The output of groff in 1.23.0 changed slightly here.
> Here's some 1.22.4/1.23.0 comparison on my system.  UTF-8 output
> follows.

...

> A.  Fewer blank lines in the output after the page header; and
> B.  There is now a space after the left border of the table.

My patch adapts the "expected" output to what Docutils' manpage writer emits
since the recent changes.

If I understand this right, then the changes work as intended,
we can change the "expected" output sample and
by this endorse the new manpage writer behaviour.

...

> Further, if you want a table where every cell is boxed, that's what the
> "allbox" option is for.  You can use that instead of putting "|" in your
> row descriptions and adding rows consisting solely of "_".

> tbl(1):
>      allbox          Enclose each table entry in a box; implies box.

This would be even cleaner and the preferred solution for tables

* if it is supported by all relevant workflows
* if support is not too new.

Thanks again,

Günter

Re: [Docutils-develop] Test failure: manpage writer

[G. B. R. <g.b...@gm...>]

Hi Günter,

At 2023-11-04T19:11:19-0000, Guenter Milde via Docutils-develop wrote:
> thank you for the fast and comprehensive answer.

No worries; glad to be of help when I can.

> My patch adapts the "expected" output to what Docutils' manpage writer
> emits since the recent changes.
> 
> If I understand this right, then the changes work as intended, we can
> change the "expected" output sample and by this endorse the new
> manpage writer behaviour.

That sounds correct to me.  The change in groff 1.23.0's table
formatting for terminals was deliberate.  I didn't put this in the
"NEWS" file because there is no specification for tbl's behavior on
terminals with respect to whether box borders or vertical rules get
space "inboard" of them with respect to cell contents.

In fact, tbl(1) support on terminal devices is often neglected.
Documenter's Workbench troff and Heirloom Doctools troff produce fairly
dire output to terminals for anything but the simplest tables.

mandoc(1), by contrast, does fine (as does groff, of course).

> > Further, if you want a table where every cell is boxed, that's what
> > the "allbox" option is for.  You can use that instead of putting "|"
> > in your row descriptions and adding rows consisting solely of "_".
> 
> > tbl(1):
> >      allbox          Enclose each table entry in a box; implies box.
> 
> This would be even cleaner and the preferred solution for tables
> 
> * if it is supported by all relevant workflows

That, I cannot answer...

> * if support is not too new.

...this, I can.  The "allbox" feature is documented as far back as the
"tbl" white paper by Mike Lesk that was distributed with Seventh Edition
Unix.  That's 1979.  :)

(If you can find a copy of _Unix Time-Sharing System Programmer's Manual
Seventh Edition Volume 2A_ online, you'll find this region option
documented on or near page 155.)

Again, terminal output using DWB or Heirloom nroff is bad, but it's bad
either way, and has been for as long as the Python docutils have
existed.  My experiments show that "allbox" makes it neither better or
worse; I suspect the problem lies with computations around the line
drawing operations themselves.

Regards,
Branden

Re: [Docutils-develop] Test failure: manpage writer

[engelbert g. <eng...@gm...>]

Hei

thanks for fixing my badness günter

On Sat, 4 Nov 2023 at 20:31, G. Branden Robinson <
g.b...@gm...> wrote:

> Hi Günter,
>
> At 2023-11-04T19:11:19-0000, Guenter Milde via Docutils-develop wrote:
> > thank you for the fast and comprehensive answer.
>
>
SNIP


> > > tbl(1):
> > >      allbox          Enclose each table entry in a box; implies box.
> >
> > This would be even cleaner and the preferred solution for tables
>

then i try again ... last time box worked but allbox no so good

> * if it is supported by all relevant workflows
>
>
> That, I cannot answer...
>
> > * if support is not too new.
>
> ...this, I can.  The "allbox" feature is documented as far back as the
> "tbl" white paper by Mike Lesk that was distributed with Seventh Edition
> Unix.  That's 1979.  :)
>
>
thanks for aiding