Proposed v2: an eqn keyword change: gfont -> gifont

[G. Branden Robinson]

Thanks to Damian, Ralph, and Doug for the feedback.

At 2023-04-08T15:54:55+1000, Damian McGuckin wrote:
> On Fri, 7 Apr 2023, G. Branden Robinson wrote:
> 
> > Crazy?  Sensible?  A long time coming?
> 
> Answers areL No. Yes. At long last.
> 
> The fix does not look quite right but maybe my brain is not switched
> on.

It seems to work okay.  I'm attaching a sample document with PostScript.

At 2023-04-08T11:46:14+0100, Ralph Corderoy wrote:
>     gbfont f
>         Set the bold font to f.
> 
>     gfont f
>     gifont f
>         Set the italic font to f.  gifont is a GNU extension.
> 
>     grfont f
>         Set the roman font to f.
> 
> I think ‘is a GNU extension’ is typical language for GNU documentation.

Yes.  Our eqn(1) is organized a bit funny because it doesn't attempt to
be a comprehensive reference, but rather a primer on GNU extensions.
This always makes it hard for me to settle on who my audience is.

> > -  { "gfont", GIFONT },
> > +  { "gifont", GIFONT },
> > +  { "gfont", GIFONT }, // for backward compatibility
> ...
> > -    lex_error("invalid argument to gfont primitive");
> > +    lex_error("invalid argument to gifont primitive");
> 
> The user should see a message which uses the keyword they entered.
> It's annoying to search for ‘gifont’ and not find it, as will be
> typical.

Yes.  I had a twinge of conscience about it when I did this; I have high
expectations of diagnostic messages.  The days when one could excuse
oneself by saying "we don't have enough room in core to store
diagnostics that help anyone but the program author" are long gone.

> One way to do this would be to have GFONT and GIFONT and only treat
> them the same later on.

Yes; they now both wrap `set_gifont()`, which takes care of it.

At 2023-04-08T09:53:37-0400, Douglas McIlroy wrote:
> The proposal is clean and well defended.
> 
> Perfecting tweaks for the proposed man page:
> 
> 1. Delete the parenthesized remark about boldface. At best it is TMI,
> at worst, condescending.

Done.  This arose from my casting about confusedly for an audience as
noted above.

> 2. To parallel the phrase "to be set in italic", delete "type" from
> "to be set in roman type".

Done.  (And strictly, we should be saying "oblique" and "upright", but
that ship has probably sailed for eqn(1).)

> 3. Delete the last sentence from the main paragraph. This complicated
> statement (check that adverbial participial phrase with a quintuple
> noun, "groff font selection escape sequences") offers little return on
> a reader's effort to understand it..One can figure the lesson out for
> oneself when needed.

*laugh*  Granted.  Fixed.  I am put in mind of a story about a basement
wall sign somewhere that read:

  SUMP PUMP BACKUP ALARM SILENCER SWITCH

Some Chomskian grammarians had fun with that one.

> 4. Shorten the sentence about compatibility to
> 
>         gfont f
>             Synonym for gifont f

I don't want to have a tagged paragraph for this primitive at all.  The
term is locatable in the page with a / search in the pager.  I don't
think any eqn veterans who used gfont will ever forget its existence,
but they will still be able to find (and use) it.  I want the tagged
paragraphs to present the contemporary dialect of the language.

Here are the revised sections of the man page.  The introductory
paragraph to "New primitives" is new; heretofore it said nothing about
whether the subsequent list was comprehensive (it wasn't).

  New primitives
    The GNU extension primitives "type" and chartype are discussed in
    subsection "Automatic spacing" above; "set" in subsection
    "Customization" below; and gbfont, gifont, and grfont in subsection
    "Fonts" below.

...

  Fonts
    eqn uses up to three typefaces to set an equation: an italic face
    for letters, a roman face for everything else, and a bold face.  The
    defaults for these correspond to the groff font styles I, R, and B,
    respectively, using the font family that is current when the
    equation is set.  The primitives gifont, grfont, and gbfont assign a
    groff typeface to each of eqn's faces.  Control which characters are
    treated as letters (and therefore set in italics) with the chartype
    primitive described above.  A character assigned the type letter is
    set in italics; a digit is set in roman.

    gbfont f
        Set the bold font to f.

    gifont f
        Set the italic font to f.  For AT&T eqn compatibility, gfont is
        recognized as a synonym for gifont.

    grfont f
        Set the roman font to f.

Further feedback is welcome.

Regards,
Branden

eqn-gifont-v2.diff
Description: Text Data

demo-gifont.ms
Description: Troff MS-macros document

demo-gifont.ps
Description: PostScript document

signature.asc
Description: PGP signature