Hi Branden,
On 7/22/22 05:33, G. Branden Robinson wrote:
Hi Alex,
At 2022-07-19T14:17:15+0200, Alejandro Colomar wrote:
Hi, наб and Branden!
I'm not exactly sure what you wanted me to comment on in this patch
submission.
Keep in mind that I am a bear of little brain--please be clear what it
is you're asking of me. ;-)
I will assume that it is my *roff/man(7) expertise (such as it is) and
will respond on that assumption.
I will also comment on English usage because I can't help myself.
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).
Thanks!
diff --git a/man3/tm.3type b/man3/tm.3type
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? That's where
I find a lot of problems, and that's why I always `sudo make install`
the pages, then read them from the system as usual. That makes it
easier. I improved the Makefile to make that loop experience something
nice.
Anyway, would you mind reporting the bug you notice and CCing me?
Other distributions may have similar concerns.
index 1931d890d..8b6f8d9bf 100644
--- a/man3/tm.3type
+++ b/man3/tm.3type
@@ -25,8 +25,26 @@ Standard C library
.BR " int tm_yday;" \
" /* Day of the year [" 0 ", " 365 "] (Jan/01 = " 0 ") */"
.BR " int tm_isdst;" " /* Daylight savings flag */"
+
+.BR " long tm_gmtoff;" " /* Seconds East of UTC */"
+.BR " char*tm_zone;" " /* Timezone abbreviation */"
Please add cosmetic whitespace (at least 1 for every member, possibly
2, depending on your taste) :)
Hmmm. I'm attaching a screenshot of Okular's rendering of the current
state of tm(3type) in the Linux man-pages Git repository to PostScript.
I only see a black 180 bytes image. Probably not what you expected to send?
Anyway, I used pdfman()[1] to read the page in PDF, and I get your point.
[1]:
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/scripts/bash_aliases#n179>
To use that bash_aliases file, I have the following in my
.bash_aliases:
if [ -f ~/src/linux/man-pages/man-pages/scripts/bash_aliases ]; then
. ~/src/linux/man-pages/man-pages/scripts/bash_aliases;
fi;
Recall the advice in groff's Texinfo manual. This is from groff 1.22.4.
5.1.6 Input Conventions
-----------------------
[...]
* Do not try to do any formatting in a WYSIWYG manner (i.e., don't
try using spaces to get proper indentation).
Synopses in man pages, whether for section [168] commands or section
[23] C function calls or data types, are not typically set in a
monospaced typeface, nor do I think they should be. A proportional
typeface generally looks better.
The price of that improved appearance is that the use of sequences of
spaces to get columnar alignment breaks as soon as there is variation in
the content.
I know. And I tend to agree that proportional typeface is nicer for
SYNOPSIS.
The traditional solution to this problem in the *roff language is to set
tab stops. However, man-pages(7) calls out tab stop manipulation as
unportable man(7) usage.
* Example programs should be laid out according to Kernighan
and Ritchie style, with 4‐space indents. (Avoid the use of
TAB characters in source code!)
Now, section 2 and 3 synopses are not _example program_ source code, so
a defense of tab usage could be made here, but a man page author simply
trying to get their stuff documented could be forgiven for feeling that
drawing such a distinction is hair-splitting.
Using spaces is, however, in my opinion, worse simply due to the effect
on rendered output for everything that isn't a terminal.
I'm generally a tab user, so you won't find resistance from me to use
them, especially if they improve the situation.
There are a few ways to address this issue.
A. Don't worry about it and let HTML/PostScript/PDF output look ugly.
I'd prefer to help them if I can.
B. Stick synopses, at least for section 2 and 3 man pages, in EX/EE
blocks [...]. My recollection is that Michael Kerrisk opposed this
practice. I too don't think it's a great idea; the average glyph
width is lower in proportional fonts, so using it, you can fit more
content on an output line.
It would be an easy fix, if nothing else works nicely. We can restrict
it to type pages, where there is an objective reason to do that, and let
function pages continue using proportinal typeface.
C. Use tabs anyway. For results that will actually get what you want,
you will need to set the tab stops to ensure they're wide enough to
achieve the desired alignment. The use of custom tab stops requires
invoking the `ta` request, and this is warned against in the
"Portability" section of groff_man(7) (to be part of
groff_man_style(7) in groff 1.23). But by invoking the `nf` and `fi`
requests for other reasons, this project's pages have already crossed
that bridge.
That will be my first attempt. But I won't try setting the width, since
you've shown in the below explanations how brittle and difficult it is.
So, if the defaults work nicely (maybe using double tabs at some
places), I'll use tabs. Otherwise, I'm probably going to fallback to
.EX/.EE. What's your opinion on this? Or do you prefer going directly
to .EX/.EE for 3type/2type pages?
C1. Actually selecting values for the tab stops can be tedious. You can
[...]
C2. Clever roff writers (sometimes too clever) reach for the \w escape
[...]
.ta \w'char*' \w'tm_gmtoff'
Not a nice thing.
[...]
.TA char gmtoff
This certainly looks much cleaner, and in fact it closely resembles
Texinfo's @multitable command. But it is just a mask over the
`ta` request of frightening appearance above, not a silver bullet.
May be nice.
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.
Would you recommend me using tbl(1), or .EX, or tabs (in the simple way)?
[...]
D. Congratulations, you've discovered tbl(1).[1]
So it seems.
I guess my advice is to choose your poison. I'll advise as best I can.
I'll try a few things.
I tend to prefer the em dash to be next to (no whitespace) the
enclosed clause. That makes it easier to mentally associate (as in a
set of parentheses) to the clause. I'm not sure if it's a thing of
mine, or if it's standard practise?
"Spacing around an em dash varies. Most newspapers insert a space before
and after the dash, and many popular magazines do the same, but most
books and journals omit spacing, closing whatever comes before and after
the em dash right up next to it. This website prefers the latter, its
style requiring the closely held em dash in running text."
https://www.merriam-webster.com/words-at-play/em-dash-en-dash-how-to-use
In the groff man pages, I too "close up" any space around em dashes, but
I freely admit that this (1) doesn't look all that great in terminal
rendering [it too closely resembles other dashes--a "fullwidth" dash
taking two character cells would be preferable on purely esthetic
grounds, and probably a nightmare to get terminal emulators to cope
with] and (2) it frustrates my input style; since I don't want to use
the `\c` escape sequence, I end up putting the words immediately outside
the em-dashed aside on the "wrong" lines semantically. Maybe I should
just get over my allergy to `\c` now that I understand how it
works.[citation needed]
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...
Cheers,
Alex
What is "&a."? Is that documented somewhere? I didn't know that
abbreviature.
Having seen наб's reply, it seems of a piece with "&c.", which was
in English formerly (ca. 150 years ago) a common abbreviation for the
Latin "et cetera". Nowadays "etc." has fully supplanted "&c." while
many native English speakers are shaky on what, exactly, it abbreviates,
even spelling it "ect." because that better aligns with English language
phonotactics.
I admit never having seen "&a." before in English writing. Like
Germans' use of "resp.", it may be a thing non-native speakers assume
"ports" into English, but doesn't.
Regards,
Branden
[1] https://git.savannah.gnu.org/cgit/groff.git/tree/src/preproc/tbl/tbl.1.man
--
Alejandro Colomar
Linux man-pages comaintainer; http://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
