Re: [groff] 01/08: mdoc: Accept mixed-case section headings.

[G. Branden Robinson]

Hi, Steffen!

At 2020-09-15T13:59:04+0200, Steffen Nurpmeso wrote:
> Just out of interest: why do you change an omnipresent idiom that
> is in use for standard section headers in Unix manual pages since
> at least fourty years?

As Ingo noted, this was discussed on this list some time ago.

  https://lists.gnu.org/archive/html/groff/2018-12/msg00141.html

And done for groff_man(7) several months later.

  https://lists.gnu.org/archive/html/groff/2019-07/msg00026.html

But to answer your question in this historical spirit whence it was
posed: for the same reason that Unix was case-sensitive internally while
still being operable with uppercase-only terminals.  Remember this?

  login: DMR
  PASSWORD:

A system should be implemented without incorporating superfluous
external limitations into its design.

> This commit changes the world and will affect the generations of
> programmers to come, shall they experience it.

It is a change with some impact, yes, but my intention is that people be
able to see fully-capitalized page titles and section headings without
much effort on their part if that is their desire.  That is why I
implemented "CT" and "CS" registers in groff_man(7).  Please see the
following commits.

  https://lists.gnu.org/archive/html/groff-commit/2019-09/msg00009.html
  https://lists.gnu.org/archive/html/groff-commit/2019-09/msg00018.html

I intend to do the same for groff_mdoc(7); it already happily has
compatible configuration semantics, and I've recently been increasing
the parallels between our mdoc and man implementations in this respect.
Here's an example.

  https://lists.gnu.org/archive/html/groff-commit/2020-08/msg00075.html

The only reason you don't already see CT and CS support in groff_mdoc(7)
is simply that I haven't done it yet and it wasn't logically necessary
for the change set I've already made.  I'll move this work higher on the
priority list since others may be as distressed as you were.

> I mean, it is ok, why not, it only strives me as mysterious.

I hope the citations by Ingo and John to previous discussions have
resolved the mystery.  Again, the intention is not to impose someone
else's preferences upon you, but to make the expression of preferences
differing from yours _possible_.

> And i think i will unsubscribe now, shall i ever find
> time for my groff clone, .. i do not know.  Not that it matters
> anyway.

I don't think unsubscribing is necessary.  I'm happy to explain and
discuss any changes I make.  I appreciate all reviews of my work.

[Ingo wrote]
> The advantages of "Name" compared to "NAME" for separation of content
> and presentation, for typographic quality, and in particular for
> accessibility were discussed at length on this list, please consult
> the archives.

Thanks, Ingo!  I've supplied some URLs above for the lazy.  :D

[Steffen wrote]
> Well, now that you say it have fuzzy memories .. and refreshed
> them.  Used to and living in text consoles only (though in
> graphical environment, again) i .. have mixed feelings, because
> now i am used to this notation for over twenty years.  I think it
> does make sense for several output devices, notably PDF, maybe
> even HTML, or markdown even, but for manual page output i feel
> differently.  Anyhow, if i make it, maybe i even follow but place
> a switch in site- and user-local configurations, for noone to find
> it ^_^.

Except for the "no one being able to find it" part, that is precisely
what is intended.  From groff_man_style(7) on the master branch we have:

 /usr/local/share/groff/site-tmac/man.local
        Put local changes and customizations into this file.

               .\" Use narrower indentation on terminals and similar.
               .if n .nr IN 4n
               .\" Put only one space after the end of a sentence.
               .ss 12 0 \" See groff(7).
               .\" Keep pages narrow even on wide terminals.
               .if n .if \n[LL]>78 .nr LL 78n

        On multi-user systems, it is more considerate to users whose
        preferences may differ from the administrator's to be less ag‐
        gressive with such settings, or to permit their override with a
        user-specific man.local file.  One way to achieve the latter is
        by placing the following at the end of /usr/local/share/groff/
        site-tmac/.man.local.
               .so \V[HOME]/.man.local
        Note that the above request will produce a warning if $HOME/
        man.local does not exist; you may wish to include one in /etc/
        skel or an equivalent account configuration system.  Further‐
        more, a security-sandboxed man(1) program may lack permission to
        open the file.

I reckon I could add
               .\" Put page titles and section headings in full caps.
               .if n .nr CT 1
               .if n .nr CS 1
to the above.  Do you think that would be helpful?

At 2020-09-16T00:13:30+1000, John Gardner wrote:
> For output destined for terminal display, it's easy to uphold this
> convention:
> 
> .if n \{\
> .tr aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ
> \\$1
> .tr aabbccddeeffgghhiijjkkllmmnnooppqqrrssttuuvvwwxxyyzz
> .\}

Oh, no!  I went to the trouble of implementing new requests (.stringup,
.stringdown) to keep people from having to type (or copy and paste)
messes like the above, and more importantly to prevent such material
from squirming into man page sources, where it would be most unwelcome.

  https://lists.gnu.org/archive/html/groff-commit/2019-09/msg00006.html

> The important part is that the source argument be expressed using
> "proper" capitalisation. This simply isn't possible if it's originally
> uppercase:
> 
> .SH "INTRODUCTION TO HTML" \" BAAAAAD
> 
> .SH "Introduction to HTML" \" Good

Right.  As groff_man(7) says (on the master branch)...

 -rCS=1 Capitalize section headings.  Set section headings (the argu‐
        ment(s) to .SH) in full capitals.  This transformation is off by
        default because it discards case distinction information.

 -rCT=1 Capitalize titles.  Set the man page title (the first argument
        to .TH) in full capitals in headers and footers.  This transfor‐
        mation is off by default because it discards case distinction
        information.

> The man(7) and mdoc(7) macros should be updated to do this, provided
> they've not been updated more recently to do so.

Our man(7) implementation was updated a year ago to do this.

  https://lists.gnu.org/archive/html/groff-commit/2019-09/msg00009.html

A parallel change to our mdoc(7) is on my short list, as noted above.
(The itch to enable Colin Watson to kill the .ll hack[1] is slightly
stronger, though, and I have a private branch to rebase and get sorted.)

I didn't do any mdoc development at all until I could regression test
it.  Now that is done[2], and I suspect Ingo is quietly hoping that in
matters of man pages, I will be seduced to the DOC side of the Force!

3;-)

Regards,
Branden

[1] https://lists.gnu.org/archive/html/groff/2020-08/msg00083.html
[2]
https://lists.gnu.org/archive/html/groff-commit/2020-08/msg00071.html

signature.asc
Description: PGP signature