Re: terminfo, OK, ERR, and other issues

[Thomas Dickey]

On Mon, Jan 02, 2023 at 07:04:26AM -0600, G. Branden Robinson wrote:
> 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

That would work for ncurses.

For portable applications (such as the ncurses-examples), it wouldn't help.
ymmv, of course.

In a quick check, X/Open Curses says that setupterm is declared in term.h,
however the various Unix systems declared that in curses.h (except for
the less-used Solaris xpg4 curses).

(NetBSD uses an ifdef as you suggest).
 
> 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.

That's partly for readability, and partly to simplify redefinition (to
point the definitions to a different base).

ncurses does the latter internally, and looking at the Unix headers, the same.

Since it's in the namespace, documenting it doesn't hurt.
 
> > >     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 don't see CUR there - only cur_term:

        int
        md_hasclreol()
        {
        #if defined(clr_eol)
        #ifdef NCURSES_VERSION
            if (cur_term == NULL)
                return(0);
            if (cur_term->type.Strings == NULL)
                return(0);
        #endif
            return((clr_eol != NULL) && (*clr_eol != 0));
        #elif defined(__PDCURSES__)
            return(TRUE);
        #else
            return((CE != NULL) && (*CE != 0));
        #endif
        }
 
CUR is used in the definition of clr_eol.  Perhaps you're referring to that.
But that's documented ("faster"):

https://invisible-island.net/ncurses/man/term_variables.3x.html#h3-Terminfo-Names

> 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.  :)

maybe
 
> 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.

actually - see my various historical/portability notes - they didn't
document most of that stuff.

> 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

yes - old news.

On the other hand, the changes I've made aren't a copy/paste.
 
> > > 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.

The in-tree pages are formatted with nroff (e.g., groff) and lynx.

> 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.

codespell doesn't appear to be confused by the markup.
I generally use the spelling highlighter I made in vile.
 
> > -- 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



-- 
Thomas E. Dickey <dickey@invisible-island.net>
https://invisible-island.net

signature.asc
Description: PGP signature