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

[John Gardner]

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


Oops, I completely forgot we added that recently. My bad. :(

On Wed, 16 Sep 2020 at 04:34, G. Branden Robinson <
g.branden.robinson@gmail.com> wrote:

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