Re: [PATCH 04/17] man/curs_add{,_w}ch.3x: Relocate material.

[G. Branden Robinson]

Hi Thomas,

At 2024-03-16T15:34:09-0400, Thomas Dickey wrote:
> On Wed, Mar 13, 2024 at 01:09:59PM -0500, G. Branden Robinson wrote:
> > Move a paragraph so it no longer appears to fall under the "TABSIZE"
> > subsection heading, with which it has nothing to do.
> > ---
> >  man/curs_add_wch.3x | 12 ++++++------
> >  man/curs_addch.3x   | 12 ++++++------
> >  2 files changed, 12 insertions(+), 12 deletions(-)
> > 
> > diff --git a/man/curs_add_wch.3x b/man/curs_add_wch.3x
> > index 01307815a..8fda68c84 100644
> > --- a/man/curs_add_wch.3x
> > +++ b/man/curs_add_wch.3x
> > @@ -325,6 +325,12 @@ .SH NOTES
> >  .SH PORTABILITY
> >  These functions are described in the XSI Curses standard, Issue 4.
> >  The defaults specified for line-drawing characters apply in the POSIX 
> > locale.
> > +.PP
> > +If \fIwch\fP is a carriage return,
> > +.I curses
> > +moves the cursor to the beginning of the current row of the window.
> > +This is true of other implementations,
> > +but is not documented.
> 
> Actually it is documented.

This language ultimately comes from addch, where it dates back at least
to the 20150627 snapshot.  (It's hard for me to trace back before that
because at around this point each snapshot comprises two commits, one
which deletes the entire source tree, and one which restores it.)
If the language should be taken out, that should probably happen in both
places.

> The addch description is referred to in several manpages,
> to reduce repetition.

On the other hand, addch() and add_wch() take differently typed
parameters.  Assuming the reader will figure things out mutatis mutandis
has a limit point somewhere.  I think the ncurses man pages would work
better for programmers if they could pick an API (wide or "narrow"), and
stick to its pages.

I'm all for the DRY principle, but...

There's a lot of repetition in the pages already (particularly in
discussions of return values, what X/Open Curses doesn't standardize
about errors/failure conditions, and how SVr4 "defined" `ERR`); it
didn't appear to me that you were trying to minimize it.  (Granted, much
of this repetition was inherited from the Solaris 2.3 corpus--or
something like it--that Eric Raymond, uh, tripped over on the ground one
day and "accidentally" dumped into the ncurses source tree to solve its
conspicuous lack-of-man-pages problem.)

I wonder if Eric has offered President Trump similar advice regarding
his classified documents case.  Ol' Donnie didn't retain anything
illegally, he just "reverse nroffed" it.[1]

In need of original expression?  Mechanical transformation to the
rescue!

But I digress...the topic was repetition.

One of the more striking examples, to me, is the fact that there are
_three_ copies of the ACS symbol tables (curs_addch.3x, curs_add_wch.3x,
and terminfo.tail).  Probably only 2 of those are needed, since WACS_*
_is_ different, not just using different symbol names, but by featuring
additional ones.

I'm glad you brought this up because I want to propose a solution,
probably for after the 6.5 release.

Move any boilerplates, if they aren't parameterized in anything, into
snippet files, have the man page source files `so`-request them where
desired, and run soelim(1) (along with the existing sed(1) stuff) in the
man page installation target.

I'd also like to see the "install" target become really just an
"install" target, not something that performs further textual
transformations.  But achieving that will, I predict, require file
renames and would be even more disruptive than the foregoing.

> The X/Open Curses pages put that sort of thing in a separate location,
> e.g.,
> 
> https://pubs.opengroup.org/onlinepubs/7908799/xcurses/intov.html#tag_001_004_003
> 
> ...which would be awkward for a manpage
> (unless one gives in and puts everything in the same manpage).

It's not a bad idea for the standard to have some kind of foundation
and/or glossary document, and in implementations of other libraries,
similar things have been done, like having a section 7 page to cover
concepts.

I don't know if ncurses needs anything that heavy.  I would cover the
commonalities in ncurses.3x, personally.

> That reminds me of the time that I got mail from someone who thought
> it was inconvenient to have dialog split into several source files...

They missed the good old days of having to split up your source files in
arbitrary places because they stopped fitting in core with the
compiler.  ;-)

Regards,
Branden

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

signature.asc
Description: PGP signature