Re: terminfo, OK, ERR, and other issues

[G. Branden Robinson]

At 2023-01-02T06:53:58-0500, Thomas Dickey wrote:
> On Sun, Jan 01, 2023 at 04:49:40PM -0600, G. Branden Robinson wrote:
> > Hi Thomas,
> > 
> > Congratulations on the 6.4 release!
> > 
> > I've started looking into making grotty(1) a terminfo application,
> > which means I need to learn how to use this library.
> > 
> > I noticed a few things.
> > 
> > 1.  curs_terminfo(3X) documents functions as returning the
> >     (symbolic) integer constants "OK" and "ERR", but these macros
> >     are not defined by <term.h>.  The version of ncurses 6.3 on my
> >     Debian system does not document <curses.h> as required for use
> >     of terminfo functions, but the version of the man page in the
> >     just-released ncurses 6.4 suggests to me that you noticed this
> >     too.
> 
> I omitted that for a short time (two months in 2020), and added it
> back.

How do you feel about #ifndef-ing 'OK' and 'ERR' in term.h so that pure
terminfo application programmers don't need to #include curses.h?  Then
you could re-omit that line from the man page.  :D

Here's what my first terminfo program looks like.

#include <curses.h> // ERR
#include <stdio.h> // puts()
#include <stdlib.h> // exit(), EXIT_FAILURE
#include <term.h> // clr_eol
#include <unistd.h> // STDOUT_FILENO

int main(int argc, char *argv[]) {
    int status = setupterm((char *) NULL, STDOUT_FILENO, (int *) NULL);

    if (ERR == status) {
        (void) puts("could not set up terminal");
        exit(EXIT_FAILURE);
    }

    if (over_strike) {
        (void) puts("we have overstriking capability");
    }

    if ((enter_italics_mode != NULL) && (exit_italics_mode != NULL)) {
        (void) puts("we have an italics mode");
    }
}

// vim:set cin et sw=4 ts=4 tw=80:

> > 2.  Might it make sense to split terminfo into its own shared object,
> 
> terminfo's been configurable that way since ~2000.
> normally that's the tinfo library (the name is configurable).
> There's a ".pc" file for it as well.

Ah!  That's good news.  And sure enough, Debian has a libtinfo6 package.
I missed that because I didn't know what name to look for.

> > 3.  Would you consider merging the content of term_variables(3X) into
> >     curs_terminfo(3X)?  Trying to learn from an existing terminfo
> >     application (not one of yours)--this turned out to be a bad
> >     idea--I wasted some time trying to employ the `CUR` macro to get
> >     at capability names.
> 
> dunno - the latter page is rather long as it is, and merging the
> subtopic into it wouldn't make it clearer.

I don't think that's _necessarily_ true, but I am not (yet) volunteering
to wordsmith the page to the point that it wouldn't be.

> agreed - more hyperlinks can help.
>  
> > 4.  Is `CUR` a published part of historical terminfo implementations'
> 
> It's in the header files, but not a documented feature.
> I mentioned it in that manpage to help clarify a point about
> compatibility.  When I made TERMTYPE opaque, it didn't affect
> the use of CUR.

If it's not a documented feature, who uses it?  I don't understand what
utility it provides that long capability names sitting in the global
name space don't.

> >     interfaces?  I don't see what use anyone would have for it,
> >     since there are exposed and documented ways to access individual
> >     capabilities by name (in C's global name space :-O) and
> >     iteratively (boolfnames, numfnames, strfnames).  Outside of
> >     ncurses's internal definitions, what is a use case for the `CUR`
> >     macro?

I found one--well, almost--which turns out to be wrong.

https://github.com/Davidslv/rogue/blob/master/mdport.c#L257

I can't even tell what the author was trying to do there.  But it
doesn't compile on my ncurses-based system, so I don't see how it was
dodging any System V bullets.

I advocate for the hiding of the `CUR` macro on grounds of its weirdness
as, as far as I can see, superfluity.  Or maybe you can update the man
page to explain what it's good for.  :)

I had a look at volume 3 of the System V Interface Definition document,
and noticed two things.

1.  The CUR macro does not appear to be defined or even referenced.
2.  The curses- and terminfo-related man pages look startlingly
    familiar.  I am reminded immediately of a page of yours.

    https://invisible-island.net/ncurses/ncurses-license.html#ncurses_1_8_5

> > 6.  Terminfo (and ncurses) symbol names sometimes get hyphenated.
> >     If you don't desire this (to ease users' employment of copy and
> >     paste), you can prepend them with the "\%" *roff escape
> >     sequence.
> 
> ...or just turn off hyphenation.  It's a nuisance in the generated
> html, since a lot of hyperlinks end up with 2-character fragements.

What are you using to generate HTML?  I'm a groff guy, maybe I can help.

If you're using groff, pass the option '-rHY=0'.  This will disable
automatic hyphenation in the groff man(7) package.

The grohtml output driver turns off hyphenation itself.[1]  However,
something I learned not very long ago is that hyphenation can sneak back
on when text is formatted in a different environment, because when an
environment is created, it uses the _formatter_'s defaults.  I've been
kicking around the idea of a `hydefault` request or register to expose
more control of this, as well as to make the `hy` request, which was
idiosyncratic even among troff requests in 1976, work more like people
who use `ad`, `in`, `ft` and similar expect.  Historically, `.hy`
without arguments has always been synonymous with `.hy 1`, an inflexible
default that is just flat out wrong for the hyphenation patterns groff
has used for 30+ years.

Any such change to groff will have to wait until after 1.23.0.  But in
the meantime maybe I can help with a workaround.

> hmm - aside from .I, .BR, etc, adding clutter

I guess we'll have to disagree there.  :(  I find them way easier to use
with a variety of spell checkers.

> -- is "\%" groff specific, or will it work with all nroffs?

Good news: it goes all the way back to Ossanna's CSTR #54 in 1976.[2]  I
don't know of any *roff that doesn't support it.  mandoc(1) (which isn't
a *roff) recognizes it but doesn't do anything with it since it doesn't
automatically hyphenate in the first place.

> > +code in the capabilities section of
> > +.BR \%terminfo (\*n).
> > 
> >    I'm happy to help with a migration of the ncurses man page corpus
> >    to the latter convention if that would be of assistance.
> 
> I'd write a script.

That's what I would do, too.  ;-)

Regards,
Branden

[1] https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/html.tmac#n29
[2] https://www.dropbox.com/s/qpk9id0b3w5hu5g/CSTR_54_1976.pdf?dl=0

signature.asc
Description: PGP signature