terminfo, OK, ERR, and other issues

[G. Branden Robinson]

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.

That leads me to my next observation.

2.  Might it make sense to split terminfo into its own shared object,
    perhaps for ncurses 7?  Maybe this would ease migration of lingering
    termcap-using applications to the superior capabilities of terminfo
    while combatting any presumption or myth that the "heavyweight"
    curses library is required to come with it.  (And there will remain
    applications, like grotty, that want to interact with terminals in a
    portable way but do not run interactively and don't need curses
    features.)

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.

    I had been reading only curs_terminfo(3X); when I finally happened
    across term_variables(3X) and saw this:

      In addition to the variables, <term.h> also defines a symbol for
      each terminfo capability long name.

    I knew terminfo(5) already existed, but for people even greener than
    I, a cross reference to that page after the foregoing sentence might
    be helpful.

    I would have been helped if something in the vicinity of subsections
    "Terminal Capability Functions" and "Terminal Capability Names" had
    cross-referenced term_variables(3X), but as noted, perhaps importing
    much of the content of that page into curs_terminfo(3X) would
    improve coherence.

4.  Is `CUR` a published part of historical terminfo implementations'
    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?

5.  I see an error in term_variables(3X).

      The long terminfo capability names use a “l” (ell) in their names:
      boolfnames, numfnames, and strfnames.

    It seems "“l” (ell)" should be "“f”".

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.

-\fIcapname\fP code in the capabilities section of \fBterminfo\fP(\*n).
+\%\fIcapname\fP code in the capabilities section of \%\fBterminfo\fP(\*n).

7.  You've heard it before from me, but I advocate the use of man(7)'s
    font macros over *roff font selection escape sequences where
    possible (which is almost everywhere[1]).

-\fIcapname\fP code in the capabilities section of \fBterminfo\fP(\*n).
+.I \%capname
+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 think use of the termcap and slang libraries should be eliminated from
contemporary POSIX systems.  I'd like to make the path to that goal
easier to follow for those who share it.

Regards,
Branden

[1] The only exception I'm aware of is when one wants to change the
    typeface inside a (sub)section heading,[2] which should be quite
    rare.

[2] There is a way to use font macros even there, but it requires an
    unorthodox idiom that I never see in man pages in the wild and which
    I don't wish to promote, because there is a major advantage to
    locking in existing (and overwhelming) current practice, and that is
    the automatic generation of PDF bookmarks for man(7) section and
    (sub)section headings, as can be seen in the following.

    
https://www.dropbox.com/s/o5h9xt80hwindrd/groff-man-pages.2022-12-27.pdf?dl=0

    (That link will probably not live very long.)

signature.asc
Description: PGP signature