[bug #59290] ms: add register to enable backtraces on diagnostics

[G. Branden Robinson]

Follow-up Comment #2, bug #59290 (project groff):

[comment #1 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.

(file #50006)
    _______________________________________________________

Additional Item Attachment:

File name: lesk_ms_railroad.png           Size:15 KB
    <https://file.savannah.gnu.org/file/lesk_ms_railroad.png?file_id=50006>



    _______________________________________________________

Reply to this item at:

  <https://savannah.gnu.org/bugs/?59290>

_______________________________________________
  Message sent via Savannah
  https://savannah.gnu.org/