bugGNU roff - Bugs: bug #59290, add register to enable/disable...

 
 

bug #59290: add register to enable/disable backtraces on diagnostics

Submitter:  G. Branden Robinson <gbranden>
Submitted:  Sat 17 Oct 2020 10:21:00 PM UTC
   
 
Category:  Core Severity:  1 - Wish
Item Group:  Feature change Status:  None
Privacy:  Public Assigned to:  None
Open/Closed:  Open Planned Release:  None
* Mandatory Fields

Add a New Comment Rich Markup
   

Sat 16 Jul 2022 08:46:58 PM UTC, comment #5: 

I think I have it.


backtrace.


...with the trailing dot, following Kernighan's addition of `c.` to device-independent troff (1981).

There is no need to add a counterpart read-only, leading-dot register like `.c`.  I think Kernighan's idea was that that register didn't need to be read-only in the first place.

Un-postponing, but not sure when I will work on this.

G. Branden Robinson <gbranden>
Group administrator
Fri 30 Apr 2021 03:13:57 PM UTC, comment #4: 

I agree with Ingo that this is a generalizable issue.

Unfortunately the only naming convention that the groff core honors is that a leading dot means a register is read-only.  By definition, this one would be writable.

I therefore have no brilliant ideas what to call it.  The one most congruent with existing "core" writable registers suggests a choice of `backtrace`, which is also pretty likely users' choice for a name.

On the other hand, it's hard to imagine what use user code would have for such a variable name unless it was to do something similar to what we already have in mind.  I.e., it's conceivable someone is doing something like this.


.de my*deep*macro
.if \n[backtrace] .backtrace


While this would step on such a hypothetical roff author's toes, there is no way to ask the formatter whether it recently issued an error or warning message, so I can see the above sort of thing being written to work around such a deficiency, possibly with hand-written and possibly redundant validity checks on string or register contents.

(I'm on the record--but I'll reiterate here--that I am not a fan of Thompsonesque abbreviation practices. `bt` is not only uncommunicative but even more likely to collide with user-selected names.)

Worthy of consideration for groff 1.23.1, maybe.

G. Branden Robinson <gbranden>
Group administrator
Sun 18 Oct 2020 04:01:31 PM UTC, comment #3: 

Re comment #2: These are all fair points, so probably you are right that a register makes sense here.

Another aspect to consider:  the task is generic, not specific to ms.  So ideally, the naming would harmonize with the naming schemes of all macro sets (or with the naming of roff core registers?) such that it can be used in whatever macro set desires such functionality.


The problem that getting a message about a "diversion" is likely to look like a diversion from hell to the user seems like a generic problem of languages that do preprocessing.  If you abuse #defines or C++ templates creatively enough, the compiler is likely to throw messages at you such that you ask yourself, "what's this? i never wrote anything remotely similar to what the compiler is complaining about!"

Often, the preprocessor will transform the input without being able to fully check validity, and then a later stage of processing may end up emitting a confusing error message.  Some issues of this kind can sometimes be caught by doing preliminary validation in the preprocessor, but that shouldn't be overdone because it can add excessive complexity and is prone to causing bugs.  Apart from that, there is not much that can be done, short of designing a coherent one-level language in the first place and refraining from code autogeneration.


The graph seems confusing and ambigous to me: are the crossings common crossings or switches?  I had to look at the manual page to figure out that they are almost certainly intended as switches.  But then, why are there two different tracks leading from AI to NH?  My impression is the following plain text description would be smaller, less confusing, more accessible, and more precise:

  [RP] [TL AU AI] [AB AE] [ [NH | SH] [[PP | LP] text]* ]*

In general, redundant use of drawings in documentation is evil.

Ingo Schwarze <schwarze>
Group Member
Sun 18 Oct 2020 02:41:14 PM UTC, comment #2: 

comment #1:

> From a user perspective, this should be a command line option, not a register.  Registers make sense for properties of the document itself, set on a source line inside the document file itself.  They are well-suited to properties that are the same every time the document is formatted.  Command line options are for properties of the individual formatting run, independent of the document being formatted, for example -w, -W, -E.


There's not much distinction between command-line options and registers in groff (or in AT&T troff either, if the register name is short enough, I reckon), because the -r option is always there; you can inject arbitrary registers into the name space used by the document run.

See my recent changes to tmac/an-old.tmac for examples of validation and manipulation of parameters we expect to see on the command line, and rejection of unsupported combinations.

I think register-oriented advice is slightly more apropos for ms sources, because the package can be used to prepare very large documents (which man and mdoc generally aren't, or at least shouldn't be).  The user therefore may be faced with multiple problems to solve, and may want to turn this backtrace-requesting register on and off at various points as they subdivide their debugging process.

I should note that because the .backtrace request wasn't broken for thirty years--only the -b option--my suggestion could have been implemented long ago.

I will also note a fifth problem with the diagnostic above, which is also a tougher one to solve.  An ms user is quite within their rights to ask "what the hell's a 'diversion'?"  Reading the ms manual, one is exposed only to the concept of "keeps", which can be "released".  It is only behind the scenes, at *roff level, that diversions are used.  Moreover, Lesk's ms manual and its descendants nowhere imply that anything resembling a "keep" is used for cover page content macros like .TL, .AU, and .AI, but diversions implement them nonetheless.

There may be nothing to do in the example given; the input is ill-formed but document recovery is successful.  A blank document with an empty title produces a single blank page as output--what else would we expect?

I am therefore ambivalent about this diagnostic; it's helpful for a roff user with some background in the underlying language, but not so much for macro package users.  Perhaps the thing to do is document it in a section of the manual (ms.ms and/or groff_ms(7)) dedicated to some of the less scrutable diagnostic messages, noting that they often arise from an ill-formed document[1] and to consult a roff expert if the structural problem cannot be located.

[1] Lesk went to the trouble of devising a sort of proto-railroad diagram in the ms user manual to explicate the sequences of acceptable macro calls for document structuring.  In fact, I find it so noteworthy, I'll attach it.


G. Branden Robinson <gbranden>
Group administrator
Sun 18 Oct 2020 01:54:08 PM UTC, comment #1: 

From a user perspective, this should be a command line option, not a register.  Registers make sense for properties of the document itself, set on a source line inside the document file itself.  They are well-suited to properties that are the same every time the document is formatted.  Command line options are for properties of the individual formatting run, independent of the document being formatted, for example -w, -W, -E.

This comment is not yet a fully developed solution, but more like one aspect to consider among many.

Ingo Schwarze <schwarze>
Group Member
Sat 17 Oct 2020 10:21:00 PM UTC, original submission:  

I'm about to close bug #55109 but its heart is in the right place.

I don't think spewing the name of the macro that emits every diagnostic is a good first-order remedy for problems.  Why would the user care about the name of the macro?

It's easy to see why the submitter reached for that tool, however; GNU ms's diagnostics, while immeasurably more generous and helpful than AT&T ms's, plainly leave a lot to be desired in the rather common case when a user inputs a macro that opens a diversion and then EOF is seen.  Here's a trivial example:


$ groff -z -ms
.TL
:0: macro error: diversion open while ejecting page (recovering)


This seems almost indecipherable.  There are four problems as I count them.

1. The macro package doesn't prefix all diagnostics with its own name.

2. After the end of input, \n[.F] is empty.  ms doesn't check that before emitting a diagnostic, leading to the first ":".

3. After the end of input, \n[.c] is zero.  ms doesn't check that before emitting a diagnostic, leading to "0:".

4. If ms is being run as part of some build process, you don't know what the last file it processed was when the diagnostic was emitted.  Terribly unhelpful.  Only an error exit status could possibly save you, and ms doesn't cause troff to exit nonzero in this case.

So you're pretty deeply hosed.  How many people has this turned off over the years, I ask myself with a sense of dread.

I have a fix for the first three problems, but all that's more of a bug #55109 discussion.

It did occur to me, however, the backtracey stuff might be useful for someone needing to really dig in.  If only we had useful backtraces...

In groff 1.23, we will.  See bug #58153.

So I propose an opt-in number register that the user can set.  If it's truthy when a diagnostic is emitted, call .backtrace.

This is really easy to implement.  The hard part is what to call the register.  Maybe just BACKTRACE?

Then we'd have:


.        if \\n[BACKTRACE] .backtrace


G. Branden Robinson <gbranden>
Group administrator

 

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

Attach Files:
   
   
Comment:
   

Attached Files
file #50006:  lesk_ms_railroad.png added by gbranden (16KiB - image/png)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by schwarze (Posted a comment)
  • -email is unavailable- added by gbranden (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 6 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2022-07-16 gbranden StatusPostponed None
    2021-05-02 gbranden StatusNone Postponed
    2021-04-30 gbranden CategoryMacro package ms Core
        Summary[ms]: add register to enable backtraces on diagnostics add register to enable/disable backtraces on diagnostics
    2021-02-10 gbranden Summaryms: add register to enable backtraces on diagnostics [ms]: add register to enable backtraces on diagnostics
    2020-10-18 gbranden Attached File- Added lesk_ms_railroad.png, #50006

    Back to the top

    Powered by Savane 3.13-0159.
    Corresponding source code