Re: [Quilt-dev] [patch 26/26] Rewrite discussion of QUILT_COLORS configuration variable.

[Jean Delvare]

Hi Branden,

On Fri, 29 Jun 2018 09:13:02 -0400, G. Branden Robinson wrote:
> At 2018-06-26T19:00:48+0200, Jean Delvare wrote:
> > > +'\\" t  
> > 
> > A comment might be in order? Within a week I'll have forgotten the
> > meaning of this line.
> > 
> > How portable is this construct?  
> 
> Well, if we precede it with a comment, it probably gets less portable.
> No fooling.  :-|
> 
> Various man(1) implementations use this as a hint to decide which
> preprocessors to run.
> 
> groff_man(7) says:
> 
>        If a preprocessor like tbl or eqn is needed, it has become common
>        to make the first line of the man page look like this:
> 
>               '\" word
> 
>        Note the single space character after the double quote.  word
>        consists of letters for the needed preprocessors: ‘e’ for eqn,
>        ‘r’ for refer, and ‘t’ for tbl.  Modern implementations of the
>        man program read this first line and automatically call the right
>        preprocessor(s).
> 
> So if the implementation is dumb, it looks _only_ at the first line and
> preceding it with a comment line defeats the purpose.

Adding a comment explaining the purpose of it *after* would be an
option then?

> > > (...)
> > >  .I quilt
> > > -uses its predefined color set in order to be more
> > > -comprehensible when distiguishing various types of patches, e.g.\\&
> > > -applied/unapplied, failed, etc.
> > > +which ANSI escape sequences to associate with an output context,
> > > +overriding the defaults.  
> > 
> > This description does not mention the purpose of the escape sequences.
> > Maybe "with ANSI color escape sequences" would make it clearer?  
> 
> That omission was deliberate, though perhaps I could make it clearer
> why.  You're passing through the escape sequences uninterpreted so
> you're not limited to color changes.  You could stick a "1;" into one of
> these variables to turn on boldface, for example.

That's not allowed. The variable is named QUILT_COLORS for a reason.
Anyone abusing it for non-color settings will be prosecuted! :-D

> > >  .IP
> > > -To override one or more color settings, set the
> > > +To override one or more settings, set  
> > 
> > And here again your remove the word "color", while I think it was
> > valuable.  
> 
> Right.  And what I'm saying is that passing these escape sequences makes
> more rendition changes than just color available.  QUILT_COLORS is
> unfortunately named, unless you want to add code to filter out SGR
> values that _aren't_ color changes.  And I would recommend against that.

Bah, you ruined my attempt at a joke above by anticipating it. I'll
remember that, you will not get away with it! ;-)

> I did some experimenting and things like bold ("1;") and "standout"
> (reverse video, "7;") worked perfectly.  In fact I added them to the
> in-page example, with explanatory comments.

I noticed, and approve.

> Another advantage of thinking more expansively is that you achieve
> broader portability and accessibility for people who are using
> monochrome displays, have a defect in color vision, or simply prefer to
> use alternative graphic renditions instead of or in addition to color
> changes.
> 
> I doubt you're opposed to the goal; my challenge is to find wording that
> communicates the traditional utility of this variable to your audience.
> :)

My point is that I believe that over 90% of people who would use
QUILT_COLORS will do to actually change the colors. I am worried that
just talking about "ANSI sequences" will lose most of the audience,
even if it is technically correct. So I'd rather mention colors and
then mention other attributes, than not mention either.

Believe it or not, I have myself been working on the topic of ANSI
escape sequences, both colors and attributes, back in year 2000. At the
time, I was in an engineering school with a mixed computing
environment, and had to struggle with the inconsistent ANSI escape
sequence support across the various systems I had to use (AIX, SunOS,
Windows NT, plus Linux at home.) I still have an archive of my work
back then, although I removed it from my home page long ago as I doubt
the results are still useful or even relevant today. A trace of it is
still visible publicly though, in the documentation of the
Term::ANSIColor perl module [1].

> > patch_offs is missing from the list, but that's not your fault, it was
> > already missing from the manual page before.  
> 
> Okay.  I'm noting that to fix it in the next cycle.  Thanks for the
> catch!
> 
> > > +series_app       series  applied patch names     32 (green)
> > > +series_top       series  top patch name  33 (yellow)
> > > +series_una       series  unapplied patch names   0 (none)  
> > 
> > series_app, series_top and series_una are also used by "quilt patches".  
> 
> I'll have to get creative; that table is already pushing the 80-column
> limit.  :)

I know. This is why I am telling you that they are missing, but not how
to add them. Because I have no freakin' idea ;-)

> > > +.TE
> > > +.IP
> > > +The special
> > > +.I format-name
> > > +\\[lq]clear\\[rq] is used to turn off special graphics renditions and
> > > +return to the terminal defaults.
> > > +Changing its definition should
> > > +.I not  
> > 
> > Is it really worth an emphasis?  
> 
> If people fiddle with that, they will find their display hideous, and
> will probably kill the terminal window in disgust.  Honestly, I would
> un-document this entirely.

Feel free to remove any mention of it from the man page if you think it
does more harm than good. Keeping the focus on what actually matters is
always a good thing, as Antoine de Saint-Exupéry nicely expressed [2].

> I've never heard of a terminal or emulator
> that supported ANSI SGR sequences that managed to screw up SGR 0.  I

I did. As part of my work on ANSI escape sequences in 2000, I awarded
the 1st prize of broken terminal to aixterm, which ignored SGR 0 and
required an explicit setting of the original colors instead. The
misbehavior was quite painful. I had to write a small perl script to
filter the output of any colored command when running in an aixterm.

Thankfully, the following year, the school replaced that old IBM server
with a Solaris one, and I could stop bothering. Probably (hopefully)
nobody is using AIX anymore, so it would no longer matter.

> could ask Thomas Dickey; as ncurses and xterm maintainer and a vigorous
> monitor of portability issues, he would know better than I.  I pay
> attention to this sort of thing but he's a true expert.

It's a small world... I got to collaborate with Thomas before (on
diffstat). We did not always agree on everything but he is indeed very
knowledgeable on such topics.

> > > +.UR https://\\:www.ecma\\-international.org/\\:publications/\\
> > > +\\:standards/\\:Ecma\\-048.htm  
> > 
> > Would seem more simple to keep it on a single line. There is no hard
> > limit to the line length.  
> 
> Fair enough.  A lot of people don't know that *roff supports
> syntactically transparent newline escapes, like C compilers always have.
> (It shouldn't be a surprise, the same people at Bell Labs brought us
> both.)

I was part of these ignorant monkeys, until you enlightened me ;-)

> > > +See
> > > +.BR console_codes (4)
> > > +for a more convenient,
> > > +if less canonical,
> > > +resource.  
> > 
> > Why split over 3 lines when it fits easily on one?  
> 
> This is advice from the GNU Troff Manual:
> 
> $ info -n '(groff)Basics' | grep -A 2 'In keeping'
>    * In keeping with this, it is helpful to begin a new line after every
>      comma or phrase, since common corrections are to add or delete
>      sentences or phrases.

Hmm. While you convinced me for sentences, breaking after every comma
seems overkill to me. I doubt it will actually make further diffs
easier to read on average, while it makes the "source code" less
convenient to work with in my opinion.

> > (...)
> > Do you have any plans to also clean up the formatting issues in the
> > QUILT COMMANDS REFERENCE section? I have the feeling that it is not
> > what it should be. In particular there are too many blank lines in my
> > opinion. This section is generated automatically from the -h output of
> > each command, with an intermediate checkpoint as doc/reference. The
> > troff formatting is added in the Makefile with a sed command:
> > 
> >             $(SED) -e 's/^quilt \([^ ]*\)\(.*\)/.IP "\\fB\1\\fP\2 " 4/' \
> >                    -e $$'s/^  \\(-[^\t]*\\)\t\\?/.IP "    \\1" 8\\\n/'  \
> >                    -e $$'s/^  \t\\?//'                                  \
> >             < doc/reference                                             \
> > 
> > This is admittedly cryptic, but if you tell me how the output should be
> > modified, I can look into fixing the sed command to get there.  
> 
> This is probably going to be a significant challenge to do right.  It
> would mean solving a problem that generations of Unix people have failed
> at.
> 
> Depending on your definition of "right", of course.

I would define "right" as "acceptable" here. I'm not asking for
perfection, I only would like the generated part of the man page to
be *roff compliant, and displayed with proper spacing and alignment,
consistent with the non-generated part which you are polishing at the
moment.

The main problem I see is that there are extra blank lines everywhere,
repeatedly leading to 2 or even 3 consecutive blank lines. This
requires a lot of scrolling to read the whole thing.

I do not mean to the contents, which I think is pretty good already;
only the formatting.

> Conceptually, what quilt is doing is great.  It's literate (well, only
> "semi-literate" in the Knuthian sense, but Knuth has demanding standards
> for literate programming).  It keeps the documentation of the interface
> close to the interface.
> 
> It honors DRY (Don't Repeat Yourself).
> 
> Almost no man pages can make that claim of their topics.  Just this week
> I took a pass over groff's own man pages and compared their documented
> command synopses with the reality of their calls to getopt_long() and
> similar.  I doubt you will be surprised when I tell you there was some
> divergence.
> 
> So I figured there are three ways to solve this:
> 
> 1.  Make the man page the source for the usage message.
> 
>     Pro:
>     * We can use man page markup freely and correctly.
>     * nroff knows how to cleanly and consistently degrade that into
>       plain text.
>     * Contributors to the command scripts don't have to understand
>       anything about *roff (unless they need to document an interface
>       change).
> 
>     Con:
>     * All the command scripts would get a layer of indirection, becoming
>       *.in files in the repository and having their real versions
>       generated during the build.  Ugh.

That's already the case.

>     * It would move the usage message out of the command script
>       entirely, to be replaced with some ugly text-expanded thing.
>       This puts a lot of separation between the interface and its
>       description.  Double ugh.  This is the #2 reason documentation
>       gets out of date.  (#1 is, of course, "developers can't be
>       bothered to write it in the first place".)

Doesn't sound appealing at all.

> 2.  Keep the command scripts the canonical source, but stuff the usage
>     messages into strings complete with *roff markup, and then call
>     nroff to write them out in normal operation.
> 
>     Pro:
>     * Most similar to the current approach.
>     * The documentation stays close to the implementation.
>     * We can use man page markup freely and correctly.
>     * nroff knows how to cleanly and consistently degrade that into
>       plain text.
> 
>     Con:
>     * Requires either adding special marker lines to the command scripts
>       to that the marked-up usage messages can be sedded out, or adding
>       a special flag to all command scripts that dumps the raw usage
>       string (with markup) so it can be interpolated into the man page.
>     * Unorthodox and, as far as I know, unprecedented.  Might scare
>       and/or discourage developers and contributors.  Many shell
>       programmers never learn a thing about *roff or its man macro
>       package.  Patches will require extra-diligent review to ensure
>       that they're not only correctly implemented, but following the
>       fiddly details of correct markup.

    * Translation burden increases.

> 
> 3.  Like 2, but define and implement a limited, special-purpose, simple
>     markup language that is easily stripped for text output and easily
>     transformed into man macros for inclusion in the man page.
> 
>     Pro:
>     * The documentation stays close to the implementation.
>     * We only define the markup we actually need.
> 
>     Con:
>     * It's a new thing for contributors to learn.
>     * The support burden for our private markup language is completely
>       ours.
>     * We get the potential excitement and joy of mistakes in language
>       design.
>     * This wheel has already been invented by Perl hackers; it is called
>       POD, and as a *roff journeyman I have to say I do not like the
>       results.  (However, the POD people are slam-dunk winners over the
>       monstrosity that is docbook-to-man, which is so horrible that it
>       has been repeatedly orphaned by a series of maintainers over the
>       years.  I don't mean in Linux distributions--I mean at its
>       origin.  Somehow, docbook-to-man proved irresistibly attractive to
>       the Git project. :| )
> 
> Which way do you lean, or would you rather I went out on a limb with a
> recommendation?
> 
> Or maybe you have an option 4 that will slice this Gordian knot!

My option 4 would be to come up with a super-smart sed command which
actually guesses the proper *roff markup right from text-only usage
messages. Which is kind of what we are doing already, except that our
sed command isn't smart enough. I wonder how far this approach could
fly... Probably this is crazy and we would need Terence to bring us
loads of pixie dust on a regular basis.

And then there is option 5, which is what I had in mind originally,
which is to leave the usage messages alone for now, and only take care
of the general spacing and alignment. Each day has enough trouble of
its own.

[1] https://metacpan.org/pod/Term::ANSIColor#NOTES
[2] "Perfection is achieved, not when there is nothing more to add, but
    when there is nothing left to take away." -- Antoine de
    Saint-Exupéry

Thanks again,
-- 
Jean Delvare
SUSE L3 Support