bugGNU troff - Bugs: bug #61379, [tmac] report failure to run tbl...

 
 

bug #61379: [tmac] report failure to run tbl when its macros are used

Submitted by:  Bjarni Ingi Gislason <bjarniig>
Submitted on:  Mon 25 Oct 2021 03:31:19 AM UTC
 
Category:  Macro - others/general Severity:  3 - Normal
Item Group:  Feature change Status:  None
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Open Planned Release:  None
* Mandatory Fields

Add a New Comment (Rich Markup)
   

Comment Type & Canned Response:
       No canned response available

 

Fri 28 Jan 2022 06:51:12 PM UTC, comment #5: 

comment #3:

>   The subject "Detect ... "table wider than line" is
>   misleading.
>
>   "tbl" already reports that, but gives no information about
>   the line length and width of the table.


tbl(1) is a preprocessor.  That means that when it runs, the
document has not been formatted.  The output device's DESC
file has not been read, therefore the line length is not known
to it.

tbl cannot report this information when it runs; it can, at
best, generate groff code to produce it, as cited in comment #4.

However, at the time those diagnostics are emitted, the
table's own width is not yet known; the `TW` register is not
defined until the table region ends.

So the only ways to get both pieces of information out are to
(1) have multiple diagnostics or (2) suppress diagnostics from
tbl (with the "nowarn" option) and have the macro package's `TE`
macro emit both data in one message.

I don't support having man(7) issue an additional diagnostic
on top of the one tbl(1) already emits when a table row is too
wide.  Since bug #61854 is now fixed, we can be confident that
that is the case.

Option (2) is also unacceptable because we can't just tell
people to rewrite all their table regions to include "nowarn";
further, that would suppress legitimate diagnostics.  Having
"nowarn" be the default would be even worse.

On top of the aforementioned bug being fixed, bug #60598 is as
well.  This means that when tbl's generated groff diagnostics
complain, they do so about the correct line number.

This seems entirely adequate to me.  We tell the people when
their table row is overrunning, and we tell them what line of
source input to look at to resolve the issue.

The scope of this bug should be limited to adding `TW`-checking
diagnostics to other macro packages' `TE` macros.

The rest of it, I consider invalid.

G. Branden Robinson <gbranden>
Project Administrator
Sat 27 Nov 2021 04:54:03 PM UTC, comment #4: 

comment #3:

>   The subject "Detect ... "table wider than line" is misleading.
>
>   "tbl" already reports that, but gives no information about the line
> length and width of the table.
>
>   I did not see any simple way to add that information to "tbl",
> so I added it to the patch.
>


The format-time diagnostics are constructed using `tm1` and `tmc` requests in table.cpp.  Grepping turns them up pretty easily.

$ grep tm1 src/preproc/tbl/*
src/preproc/tbl/table.cpp:           ".  tm1 \" table row will not fit on page \\n%\n"
src/preproc/tbl/table.cpp:         ".  tm1 \" use .TS H/.TH with a supporting macro package\n"
src/preproc/tbl/table.cpp:         ".tm1 \" table wider than line width\n");
src/preproc/tbl/table.cpp:         ".tm1 \" table column separation set to zero\n"
src/preproc/tbl/table.cpp:         ".tm1 \" table squeezed horizontally to fit line length\n");

Setting to "need info"; the part I have clear idea how to deal with is already committed.

G. Branden Robinson <gbranden>
Project Administrator
Sat 30 Oct 2021 11:33:24 PM UTC, comment #3: 

  The subject "Detect ... "table wider than line" is misleading.

  "tbl" already reports that, but gives no information about the line
length and width of the table.

  I did not see any simple way to add that information to "tbl",
so I added it to the patch.

Bjarni Ingi Gislason <bjarniig>
Fri 29 Oct 2021 02:42:31 AM UTC, comment #2: 

Some progress.

commit 80ee140eb0616b794b853bbad623263cbea06abc
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Thu Oct 28 15:14:48 2021 +1100

    [man]: Warn if `TE` called but \n[TW] undefined.

    [man]: Warn if `TE` table macro but `TW` register (set by tbl(1))
    undefined.  Arrange it so that we warn only once per man(7) document,
    not per table.

    * tmac/an.tmac (TH): Remove `TW` register when processing new document
      and clear `an-was-tbl-failure-reported` register.

      (TE): Check `TW` and `an-was-tbl-failure-reported` registers; if the
      former is undefined and the latter false, emit the message and set
      `an-was-tbl-failure-reported`.

    Addresses part of <https://savannah.gnu.org/bugs/?61379>.  Thanks to
    Bjarni Ingi Gislason for the suggestion.

G. Branden Robinson <gbranden>
Project Administrator
Thu 28 Oct 2021 03:15:35 AM UTC, comment #1: 

I think some of this is a good idea.

1. I agree that it's helpful to tell the user that they forgot to run tbl, and TW is a pretty reliable proxy for that (or for a very serious error in tbl itself).

2. I don't agree that we should abort processing over this.  Failed table rendering is pretty ugly, but ugliness is not a fatal problem.

3. That said, if a document has multiple tables, this diagnostic should not be reported over and over again.

4. I'm leaning away from including information about the table being wider than the line length.  Doesn't tbl already emit diagnostics in this case?  I'm pretty sure I've seen them.

Here's my first cut at applying this (modified) idea to an.tmac.  The diagnostic message is pretty long, but especially for man(1) users I want to be helpful without fibbing to them.  I tested it and it seems okay.

(On the bright side, as I recall, Colin Watson's man-db is coded such that it always calls groff with `-t`, so this diagnostic should only appear if there is a terrible tbl failure, or people are trying to render man pages with a troff command (or a wrapper) themselves, in which case I'm not disturbed by the idea of dumping this much info on them.)

diff --git a/tmac/an.tmac b/tmac/an.tmac
index ff6fc977f..de399e954 100644
--- a/tmac/an.tmac
+++ b/tmac/an.tmac
@@ -905,6 +905,16 @@
 .de1 TE
 .  HTML-IMAGE-END
 .  if \\n[an-is-output-html] .ll \\n[an-TS-ll]u
+.  if !r TW \{\
+.    if !r an-was-tbl-failure-reported \{\
+.      ds an-msg tbl preprocessor failed or was not run;\"
+.      as an-msg " table(s) likely not rendered\"
+.      as an-msg " (TE macro called with TW register undefined)\"
+.      an-warn \\*[an-msg]
+.      rm an-msg
+.      nr an-was-tbl-failure-reported 1
+.    \}
+.  \}
 ..
 .
 .\" eqn(1) equation support

This works fine in testing.  I may chain the .ifs in the version I push.  Feedback welcome.

If this experiment is a success, we can adapt it to the other full-service packages (modulus mom, which is Peter's bailiwick, though he is of course welcome to delegate).

G. Branden Robinson <gbranden>
Project Administrator
Mon 25 Oct 2021 03:31:19 AM UTC, original submission:  

[*.tmac] Detect use of preprocessor "tbl" and "table wider than line"

  Add this to the beginning of the definition of macro "TE" (End of
Table):

.  if !r TW \{\
.\" nroff in contiuous mode (default) can output a lot of empty lines
.\" to fill the page with the defined number of lines after aborting
.    pl 0v
.    ds msg \\n[.F]: table preprocessing is missing, \"
.    as msg for example option '-t'; aborting\"
.    ab \\*[msg]
.  \}
.
.\"If table is wider than the line
.  if \\n[.l]-\\n[.i]-\\n[TW]<0 \{\
.    tm1 "        .l = \\n[.l]u .i = \\n[.i]u TW (table width) = \\n[TW]u
.  \}
.

####

  The macro "TE" is used in "an.tmac", "e.tmac", "m.tmac", "om.tmac",
"s.tmac", and "www.tmac.in".

Bjarni Ingi Gislason <bjarniig>

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by gbranden (Posted a comment)
  • -email is unavailable- added by bjarniig (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

     

     

     

    Follow 7 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2022-01-28 gbranden CategoryMacro man => Macro - others/general
        StatusNeed Info => None
        Summary[tmac] Detect use of preprocessor "tbl" and "table wider than line" => [tmac] report failure to run tbl when its macros are used
    2021-11-27 gbranden StatusIn Progress => Need Info
    2021-10-29 gbranden Summary[*.tmac] Detect use of preprocessor "tbl" and "table wider than line" => [tmac] Detect use of preprocessor "tbl" and "table wider than line"
    2021-10-28 gbranden StatusNone => In Progress
        Assigned toNone => gbranden

    Back to the top


    Powered by Savane 3.9