Re: [bug #59962] soelim(1) man page uses pic diagram--should it?

[G. Branden Robinson]

Hi, Helge!

At 2021-05-15T17:40:44+0200, Helge Kreutzmann wrote:
> Hello Branden,
> On Mon, May 10, 2021 at 09:38:52AM +1000, G. Branden Robinson wrote:
> > [redirecting to groff@ rather than bug-groff@, which isn't really a
> > discussion list; and dropping Dave from Cc list because I know he's
> > subscribed]
> 
> I suppose we are off-list altogether? If this is done by mistake, feel
> free to forward and/or include the list.

It was indeed a mistake--thank you!  I'll leave a few things untrimmed
so that (potential) groff mailing list discussants can see how patient
you've been with me.  :)

[section heading capitalization and the user-configurable CS register]
> > > Thanks, I'll discuss with Mario if and how we can integrate this
> > > in our workflow.
> > 
> > If you have any difficulties, please loop us in.
> 
> Thanks for the offer.

> > The man page source, however, should record the mixed-case
> > information in the event it is required, because there is no
> > (programmatic) way to recover it if it is discarded there.
> 
> Yes, I agree.

[less(1)'s idiosyncratic but useful pattern matching snipped]

> I'm aware of this, but thanks for the pointer. So in practice this
> problem will occur less often than I anticapted, also many man pages
> are rather short. But at least I often skim around man pages and
> having good eye catchers is valuable there.

Sure.  I'm not trying to take fully-capitalized section headings _away_
from anyone.  :D

> > The groff_man_style(7) page[2] includes a few examples of
> > customizable man page rendering parameters.  For too many years
> > readers of man pages have labored under the misconception that they
> > have no influence over how man pages are rendered on their system.
> > Most of these configurable parameters have been supported by groff
> > for over a decade.  Over the past 4 years we've greatly improved
> > documentation of these matters, and extended the principle with new
> > registers and strings (AD, CS, and CT).
> 
> In fact, I was not aware of this. Thanks for the explanation and
> pointers.

No worries.  When I first came to the groff project in 2017 I was
frustrated by my poor understanding of many things, and resolved to
contribute documentation improvements so that even numbskulls like me
had a fighting chance to acquire some competency with it.

> > Unfortunately, people with that misconception have sometimes gone on
> > to write tools that generate man pages as output, and force many
> > stylistic preferences on readers, in ignorance of the man page
> > interface for letting the user exercise individual preferences.
> 
> I definitly belief this.

This configurability is, admittedly, a GNU innovation; I've learned a
fair amount about this history of the man(7) language over the past few
years and there were few such hooks in it 1990--with the exception, of
course, that if you processed your man pages with man(1), a *roff
formatter was going to interpret it on the back end and therefore man
page rendering was _immensely_ customizable.  You could redefine any
macro or string, or manipulate any register, even macro package
"internals", however you pleased.

We both gained and lost something when it became fashionable to parse
the man(7) language with something other than a *roff.

> > Yup.  It is a problem dating back to the first man(7) implementation
> > in 1979, and it has cast a long shadow.
> 
> Limited resources with non optimal design choices probably.

I never cease to be impressed with what people sqeezed out of a
PDP-11/40.  :D  Unfortunately I think some people made icons out of the
system and the personalities behind it, instead of recognizing it as the
product of _engineering_, with tradeoffs and compromises.

> > > First, the rationale given above for the CAPS case applies. Users
> > > want efficient man pages.
> > 
> > ...except they have different opinions about what constitutes
> > efficiency.
> 
> I agree, I did not do a study on this.

I would certainly be interested to learn of any research along these
lines.  I know someone who learned English as a second language, coming
from a language without lettercase distinctions, and the experience of
reading full caps is cognitively more tiring for them than mixed-case.

> > Yes; as I said previously, I think that "bold -> literal, italics ->
> > variable" is a sound rule of thumb.  What I reject is
> > over-application of the principle.  The dearth of font styling
> > options in man(7), which is ultimately attributable to an equal
> > dearth on the Graphic Systems C/A/T typesetter at Bell Labs in
> > Murray Hill, New Jersey in the 1970s, means that sometimes style
> > choices are going to collide.  If someone uses italics for emphasis,
> > as in "do I<not> pass this function a pointer to a buffer that is
> > not known to be null-terminated", do we permit our principles of
> > efficiency to force us to regard the word "not" as some kind of
> > metasyntactic variable here?  No.
> 
> Yes, here the limits are clearly visible. And I've seen this quite a
> few times. So of course you cannot blindly assign font styling to
> meaning. Just (right now) it sometimes helps when I'm unsure if it is
> an option name or a variable.

Yup.  I have no interest in reversing this convention.  (I don't think
of the names of man page topics as literals any more than I would any
other bibliographic reference, like _Communications of the ACM_.)  The
use of italics for "variables" is well established in mathematics, for
example.  The provenance of bold for literals is not clear to me,
however; in technical literature outside of terminal (emulators), the
use of a different font family altogether--often a fixed-width one--is
common.

> > There's only so much semantic markup that it is wise to add to the
> > man(7) language.  There are two risks: first, that in doing so
> > conscientiously we will bloat the lexicon of the system beyond the
> > point where occasional man page authors can acquire it, say to the
> > dimensions of DocBook (which has hundreds of tags, according to one
> > of our mailing list's contributors), or even to the more modest
> > scale of mandoc(7), which has failed to take over the Unix world
> > outside of the BSDs.
> 
> I agree, that there is a limit. SGML itself failed for a reason.
> However, for writing man pages I actually liked the limited set
> required by docbook-to-man. 

I have no particular quibble with the input lexicon of docbook-to-man; I
can't even remember it.  (I do recall that "full" DocBook, as documented
by the O'Reilly book, is huge.)  My violent opinions about
docbook-to-man almost exclusively derive from the poor quality of its
man(7) output, which I think blackens the reputation of man(7) by
misleading readers into thinking of it as an unlearnable, write-only
language.

> > A more serious problem is that docbook-to-man has been chronically
> > unmaintained for 20 years.  As I noted a few years ago, it seems to
> > poison everyone who touches it.
> 
> … and yes, that's why I haven't used it for about 15 years. 

:)

> > To be fair, I understate; another part of my planned semantic
> > revolution is arguably to regress it, by deprecating the .OP macro.
> > It's too feeble to do its job--it cannot handle GNU-style long
> > options with an equals sign separating the flag name from its
> > argument, and people misuse it outside of synopsis macro pairs
> > (SY/YS) (which it technically predates; it seems to have made its
> > way into Documenter's Workbench troff at some point by the 1990s).
> 
> I guess I'm taking a good tour of groff right now :-)). Thanks.

I've been working not just on our man pages but on our Texinfo manual.

> > * Fully capitalized section headings are user-configurable.
> > * If I get .MR and \*[MF] implemented, you can have your tools render
> >   man page cross-references in bold if you like.
> 
> I just pointed out the issue, I agree that is probably orthogonal.
> Right now, I mainly translate whatever the upstream provides and
> sometimes (like now) get into the discussion with the various tool
> authors (e.g. po4a, you, …) if I perceive a problem. 

Sure, and I am glad you spoke up.  There has been much less resistance
to my mooting of .MR than I expected, but on the other hand I haven't
posted a specification yet.  I think of settled on an extension of the
one Russ Cox implemented for Plan 9 troff.

Basically it would have two syntax forms:

.MR topic section

.MR [pre] topic section post

"pre" and "post" are for puctuation characters that must abut the man
page reference without intervening space.

> > I can easily see that, and I don't want to break it.  I fully expect
> > some distributors to modify the copies of man.local they install to
> > impose a set of style rules, merrily discarding the case distinction
> > information I've gone to the trouble of adding to groff's own man
> > pages.
> 
> Yes, and I was not aware of this configuration option (see above). And
> now that I understand the issue more into detail, I'll see with Mario
> how to handle it.

Please let us know how it wears in practice.

> > So, I think, groff 1.23.0 will make the world look _more_ like you
> > want it (for translation purposes, at least), not less.  groff
> > 1.22.4 does not manipulate section names in man pages at all.
> 
> Thanks for the explanation.

> > I strongly encourage you to check out groff_man_style(7).  I am in
> > communication with the Linux man-pages project (Michael and
> > Alejandro).
> 
> Good to know.

> > > What would be horrible is that each project invents its own
> > > conventions, both for the readers and the translators.
> > 
> > That's where we are already, unfortunately.  My initiatives are an
> > attempt to remedy the problem.
> 
> Thanks.

> > > So please coordinate and disseminate the change to as many
> > > projects as possible and make it easy for them to switch to
> > > whatever is agreed upoon, and do so quickly.
> > 
> > In my experience people cannot be driven in this way, at least not
> > by someone who is seen as having a subjective investment in the
> > issue.  My role as implementor is to put together the best possible
> > case I can in terms of technology and ergonomics, but the driving of
> > adoption is going to have to be done by people whom I have already
> > convinced, who then become advocates within or closely affiliated
> > with individual projects.
> 
> I agree. Then time will tell. Sigh.

The really hard part involves me learning how to use pdfmark and groff's
HTML output driver to really make those "manrefs" into hyperlinks.  If I
can accomplish that I think it will dangle a pretty fat carrot.

> > I encourage you to experiment once in a while with rendering man
> > pages to PostScript, PDF, DVI, and HTML.  Not necessarily often; I
> > simply want you to be aware of some of the other design constraints
> > that apply to the man(7) language.
> 
> I perfectly understand you here. My focus is quite limited and I'm
> aware that there is much more too it. My background is LaTeX for
> typesetting and visual documents. So yes, my use case is just a tiny
> fraction of the target space and possibliities.

That's fine; groff is a big system and my own progress in learning new
pieces feels agonizingly slow.  I acknowledge that, numerically, most
groff users care about nothing except man pages in terminal emulators.
It was _my_ path into the system.

> > Thus, personally, I strive to achieve a discipline which says that
> > the user should have a fighting chance to comprehend a man page even
> > if it is rendered in attribute-less US-ASCII.  Hence my rules of
> > thumb, which you snipped.  :)
> 
> Ok, I always us the man command on my Debian system (or I read the
> source as processed by po4a when translating).

There's more than one man(1) implementation out there (historically, the
Red Hat one and the Debian one were different--I don't know what Red
Hat/Fedora uses today).  I _think_ Colin Watson (Debian/man-db man's
longtime developer, and groff package maintainer as well) turns off SGR
escapes in grotty(1) by default because that way more(1) and less(1)
will both render bold, italics, and bold-italics correctly that way, at
the cost of incorrect rendering in some corner cases.

[...my adventures in embedded systems grief snipped...]
> Yes, this is as I would do as well, but again, I've not used such
> systems myself so far.

> > I think a major driver behind this is that people either don't
> > understand typographical quotation or how to achieve it in a man
> > page.  I've documented this more prominently, too--see
> > groff_char(7)[5].  It has an example dedicated specifically to
> > quotation marks.
> 
> Ok, thanks for the pointer.
> 
> > Thanks very much for the discussion.
> 
> Yes, it was interested and I'll store it carefully to review it when I
> dwelve more into this realm.
> 
> Thanks again and good sucess in the transition!

May it be!

Regards,
Branden

signature.asc
Description: PGP signature