Re: terminfo, OK, ERR, and other issues

[Thomas Dickey]

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.
 
> That leads me to my next observation.
> 
> 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.

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

dunno - the latter page is rather long as it is, and merging the
subtopic into it wouldn't make it clearer.

providing for more pertinent linkages between the pages would be
an improvement.  I generally do that using the aliases file in
the misc directory, and adjust the layout so that I can post-process
a name like "setupterm" to point to the subsection in the manpage.

If you compare the distributed source/html to my webpage,
you'll notice a few cases of that.
 
>     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.

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.

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

an error (not sure how I did _that_, since it dates from 2010, and doesn't
appear to be copied from some other place).
 
> 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.
 
> -\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

hmm - aside from .I, .BR, etc, adding clutter -- is "\%" groff specific,
or will it work with all nroffs?

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



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

signature.asc
Description: PGP signature