Re: [groff] 04/04: tmac: Move macro diagnostics away from `quotes'.

[G. Branden Robinson]

Hi Steffen!

At 2017-11-19T02:57:36+0100, Steffen Nurpmeso wrote:
>  |commit 1294c8d2272e1c43b1b683e287deb1749865e642
>  |Author: G. Branden Robinson <address@hidden>
>  |Date:   Sat Nov 18 17:55:26 2017 -0500
>  |
>  |    tmac: Move macro diagnostics away from `quotes'.
[...]
> Now i really think you are going too far.

You know, I was _certain_ that it would be the other commit I made to
the tmac directory that would draw the first complaint.

Good thing I'm not a betting man!

> These BSD mdoc(7) macros are not your private property

Well of course not.  Such a claim is not implicit in making a change to
FLOSS[1].

> or only in sofar as BSD does no longer use groff at all, at least for
> manual purposes.

According to the git logs, comments, and a plain reading of the macro
package sources, these mdoc macros diverged from the BSD originals long,
long ago.  James Clark migrated them to use many groffisms (prominently,
long names for macros, registers, and strings) long ago.

> But that surely does not get better when someone who has no conscious
> contact with usage of those macros (given that Linux prefers man(7))

One of these statements is false and the other one is too vague to be
decidable.

I do in fact have deliberate, conscious contact with mdoc; as I said
months ago on this list, I admire its design even if I feel its
ergonomics are challenging.

And your claim that "Linux prefers man" can be interpreted several ways,
the most obvious of them (to me) being false:

1. Linus Torvalds established the proud[2] tradition of refusing to
   write man pages for the Linux kernel at all over 20 years ago.
   Instead, that job, long after the fact, was taken up by Michael
   Kerrisk and friends.

2. GNU has deprecated man(7) for even longer.

3. Plenty of application developers in GNU/Linux, particularly for "the
   desktop", have taken a path popular among junior software engineers
   worldwide, which is to get away with writing as little documentation
   as possible in _any_ form.

> selfishly decides over a style issue and then starts trampling over
> those macros.

I've been rolling this change out in stages.  But it's not simply my
personal preference, it's the recommendation of the GNU Coding
Standards[3].

> That said, feel free to do whatever you want.  But if you move away
> from americanish `' quotes,

As an American acutely aware of orthographic differences in U.S. and
British usage, I must protest.  U.S. quotation practice is for the
innermost set of quotation marks to be double quotes (directional where
available).  The practice of using single quotes for the innermost set
of quotation marks is a British convention.  Nevertheless...

> why the heck is it '' that you go for, instead of "".

Because users might wish to cut and paste the material between the
single quotes into a terminal window running a shell, and the vast
majority of shells in use require less escaping of the unpredictable
contents of those quotation marks.

> Thank you, and good night.

Thanks for your feedback.

I intend to continue my conscious contact with mdoc(7) by figuring out
the best way to fix groff_mdoc(7) with respect to the following
warnings.  It's an item on my very long to-do list...

Usage: .Ql argument ... (#809)
Usage: .Li argument ... (#809)
Usage: .Ql argument ... (#812)
Usage: .Li argument ... (#812)
Usage: .Rv -std in sections 2 and 3 only (#1634)
Usage: .Ex -std in sections 1, 6 and 8 only (#1664)

[1] Free/Libre/Open Source Software: my preferred term, but one that is
    sadly not as popular as others.
[2] You may wish to infer irony at this point.
[3] https://www.gnu.org/prep/standards/html_node/Quote-Characters.html

-- 
Regards,
Branden

signature.asc
Description: PGP signature