Re: man(7) DS and DE macros (was: [PATCH 4/5] tm.3type: describe tm_zone, tm_gmtoff)

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 5913 bytes --]

Hi Branden,

On 7/23/22 00:20, G. Branden Robinson wrote:
> [dropped наб from CC list; added groff@]
> 
> At 2022-07-22T12:57:53+0200, Alejandro Colomar (man-pages) wrote:
>> You answered all that I thought you would, and even more.  As always,
>> you surprise me with great knowledge that I didn't even know I could
>> ask for, and that's the main reason I tend to not try to direct your
>> answers.  They're always welcome (although sometimes the knowledge is
>> too much for me, a novice groff(7) user, to understand it; but I try
>> to).
> 
> Aww, shucks.  Well, never hesitate to correct or challenge me; the best
> knowledge is tested knowledge.

:-}

Sure!

> 
>> On 7/22/22 05:33, G. Branden Robinson wrote:
>>> Oh, bother.  Bash autocompletion for "man" on my Debian bullseye is
>>> too dumb to recognize this new man page suffix.  I trust someone
>>> reading this is aware of the problem and is fixing it for the next
>>> Debian release.  (Has someone filed this as a bug with the Debian
>>> BTS?)
>>
>> I don't think it's been reported.  I've detected some unpleasantness,
>> but since I also had some unpleasantness with pages in the main
>> sections, I didn't know if there was even more of it with subsections.
>>
>> Was it trying to read a manual page from a relative path?
> 
> Yup.  I was "man -l"-ing inside my Git checkout of man-pages.

Since I don't see a big benefit in being able to normally read old 
releases of the manpages, I recommend you installing them into 
/usr/local.  If you even need to read an old man page, you can find it 
manually.

> No indeed.  My Logitech thumb-operated trackball hates me, as does the
> company--they don't even sell a corded version anymore.  Due to some
> diabolical collusion with the alkaline cartel, their devices refuse to
> operate reliably after a fresh battery has been installed for more than
> about 71 seconds.

Do you recommend those things?  I had contact with one when I was very 
little (like 10 yr old?) in a library, and have never seen one of those 
again.  I didn't like it at the time, but I might change my opinion now 
that I hate more and more the mouse every day.

> 
>> Anyway, I used pdfman()[1] to read the page in PDF, and I get your
>> point.
> 
> I'm trying the attachment again for the benefit of list readers.

I guess you forgot it, 'cause I can't see it :/.


> 
> I think going ahead and using tabs as a first cut is a good idea.  I
> would recommend _against_ adding supplemental adjacent tabs to manually
> correct cases of misalignment.  A tab character always causes motion to
> the next tab stop to the right of the current drawing position, so it
> should never happen that text overrunning a tab stop will get
> overprinted.

That's why I don't use (I did, but not anymore) tabs for alignment in C. 
  tabs for indentation, spaces for alignment.

Since we're doing alignment here, you're right, and I shouldn't use 
multiple tabs.  But I don't want to go so far as to configuring the tab 
width, not even with a macro.  That's too complex.

So in the end, I decided tbl(1) is the only sane way to do it (you don't 
need to think; at least not any more than the learning curve of tbl(1)). 
  When many pages use tbl(1) for the SYNOPSIS of types, even new 
contributors should find it easy to write a new structure following the 
examples.

>>> C3. The above has the problem that it relies upon the writer to know
>>>       which pieces of text between the tab stops are the longest.
>>>       This sounds like an obvious thing that no one would ever screw
>>>       up.  I think that assumption would be swiftly overturned.
>>
>> Maybe you can set up .TA so that it takes the longest of a set of
>> consecutive .TA?  That's already kind of tbl(1).  Maybe we should use
>> tbl(1) for that :P.
> 
> Yes, that seems a bridge too far to me.  If its features are needed,
> there is no shame in reaching for tbl(1).

I very much want those features (no need to think about which field will 
be the widest).  So, that leaves me with good ol' tbl(1).

> 
>> Would you recommend me using tbl(1), or .EX, or tabs (in the simple
>> way)?

We agree that we would like to avoid .EX.
tabs would be either imperfect, or too complicated, or we would be 
reinventing tbl(1), so let it be.
> 
>>> D. Congratulations, you've discovered tbl(1).[1]
>>
>> So it seems.

So it seems...

> 
> I fancy that I reconstructed the sequence of events that led Mike Lesk
> to write it.  This could of course be completely wrong.  ;-)

I guess, yes :D

> 
>> So no single-sided space for em dashes --such as this one--, right?
>> Maybe that's a construction of my brain, trying to make them a bit
>> more logic...
> 
> I haven't seen that outside of things like more(1) prompts; my few
> memories of such feel decades old, probably of bespoke implementations
> for 1980s micros.

I think books in Spanish tend to use single-spaced em dashes.  I'll try 
to remember to check when reading.

> 
> Or maybe I'm thinking of NetHack.[1]

Oh, yes, the other page in man6 :D

> 
> So here's the crazy idea.
> 

[...]

Sorry to completely drop it from the email, but I think it would be 
harder to use than tbl(1), for less functionality.  I'm already trying 
tbl(1).  Good news is I'll review your page!  I'll try to make it work 
without reading anything other than that page.

 > So it can't be wrong, and will never be issued spuriously.[2]


Cheers,

Alex

> 
> Regards,
> Branden
> 
> [1] https://github.com/NetHack/NetHack/blob/NetHack-3.7/doc/Guidebook.mn#L428
> [2] famous last words

Oh, that made me remember of someone that I know, that said the day of a 
release: "It must work, I tested it on my computer". LOL!

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]