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

[G. Branden Robinson]

At 2020-09-16T01:21:14+0200, Steffen Nurpmeso wrote:
> C64 had no login.  And DMR would not have used it.
> I am all with Tadziu Hoffmann in this thread.

Did Tadziu comment on this thread?  I don't see any such message in the
list archive in my mail folder... :-?

> I see.  For Ingo's mandoc it will be an either/or thing i think.

Sure, but that's reasonable.  Implementors should have this sort of
flexibility.

> Well.  I have no other opinion than what i expressed already.  More
> and more software packages only generate manual pages, in fact more
> and more do not even ship with generated manual pages but leave that
> up to the packager, as a build time dependency.  So it is.

Yes--developers for "embedded" systems have been ripping out as much
documentation as possible for years now.  Even when such embedded
systems have orders of magnitude more RAM and persistent storage than
the PDP-11 on which man pages were born...

>  |               .so \V[HOME]/.man.local
> 
> More and more projects support $XDG_DATA_HOME aka _CONFIG_.

Yes, I started noticing a hierarchy under .local in my $HOME some years
ago.  :)

This would work as well, but the barriers are as noted below:

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

Until those issues are resolved I don't think this solution can be
pursued as a shipping default.

>  |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?
> 
> Well i personally .. would do it like this.  Or better, i would
> switch for .T == pdf or html and keep the default.  But that is
> really just me.  Shall anyone use scripts they need to be
> adjusted, for example.  A quickly thought hack would be a script
> called synopsis which does
> 
>  man "$1" | sed -e '/^SYNO/,/^[A-Z]/p;d'
> 
> which goes two to far, but .. what i mean.

I provided a sed script to do the transformation on man page titles in
a commit message last year, not having a better place to put it.

(Sub)section headings require a more considered approach, particularly
ones that aren't standardized.

commit 592275f73fd364627f82184e64c52be2089c2be3
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Tue Sep 10 00:11:27 2019 +1000

    **/*.man: Downcase man page titles.

    ...except for glilypond and roff2*, which did not require it.

    Here's a sed script for the aid of those who have a corpus of man pages
    to migrate.

            # Downcase man page titles.
            #
            # Use the first line to skip any .TH lines that require
            # special handling, perhaps because the name of the
            # command gets externally macro-expanded.  In groff, the
            # "roff2.1.man" page is an example.
            #
            # This script operates _only_ on .TH lines.
            #
            # usage: sed -i -f this_script.sed your_man_page.1 ...
            /@ROFF2MODE@/b
            /^\.\s*TH/{
            h
            s/^\.\s*TH \+\([^ ]\+\) .*/\1/
            y/ABCDEFGHIJKLMNOPQRSTUVWXYZ/abcdefghijklmnopqrstuvwxyz/
            G
            s/\([^ ]\+\)\n\(^\.\s*TH \+\)[^ ]\+\( .*\)/\2\1\3/
            }

Even the first line (ending in /b) can be dropped if no files need to be
skipped.  roff2.1.man is now dead in groff git HEAD.

Regards,
Branden

signature.asc
Description: PGP signature