Re: [PATCH v2] tzfile.5: Fix indentation

[Alejandro Colomar]

Hi Paul, Branden,

On Sun, Apr 07, 2024 at 11:33:38PM -0700, Paul Eggert wrote:
> On 2024-03-18 01:35, Alejandro Colomar wrote:
> 
> > Hmm, while Ossana's indents might be a bit excessive, TZDB's might be
> > too short.  Maybe I would RS 4 spaces instead of 2 before the tag.
> 
> That'd be too long for the nroff case. The nroff case is a bit too long
> already. It looks like the following in the current TZDB version:
> 
>  The goals of this section are:
> 
>o  to  help  TZif  writers output files that avoid common pitfalls in
>   older or buggy TZif readers,
> 
>o  to help TZif readers avoid  common  pitfalls  when  reading  files
>   generated by future TZif writers, and
> 
> ... and if there were four spaces (instead of two) around the bullets, it'd
> be too much white space.
> 
> Of course we could indent more or less depending on whether it's nroff or
> troff, but that's complexity I'd rather avoid.

Yeah, I was thinking only of the typeset version.  And I agree in not
wanting the complexity of a conditional.

> > I kind of do like pre-indenting bullets; in some cases
> > I've felt that having the bullets not indented was sub-par, but wasn't
> > convinced enough to go and pre-indent them, since that would add
> > complexity, and also allow less room for text in terminals.
> 
> Glad you like preindenting. As you say, once one does it, one should use
> less white space.

I'll think about it.  Maybe I add some preindent to the Linux man-pages.

> > > There are other things not to like about the man page PDF output. The man
> > > pages are confused about when to use constant-width fonts vs varying-width
> > > fonts.
> > 
> > Can you please point to an example of this?  I try to be consistent, but
> > probably there are still cases that I haven't fixed due to lack of time.
> 
> See the attached, which is the output of "groff -man -Tpdf zdump.8".
> 
> First, I had to do shenanigans like this:
> 
>   .ie \n(.g .ds - \f(CR-\fP
>   .el .ds - \-
> 
> and later use \*- every time I wanted to specify a zdump option like -v.
> Using plain "-v" in zdump.8 doesn't work, because it generates a hyphen in
> troff mode and hyphens are too narow. Using "\-v" doesn't work, because it
> generates a mathematical minus sign in the PDF, which differs from "-",
> which means you can't easily search for "-v" in the PDF.

Hmmm.  I use "\-v" in the Linux man-pages, and it works, in the sense
that you can search for "-v" with ^F in the PDF viewer.

See


It works for me in all the readers I tried, which are firefox(1),
atril(1), and okular(1).  In what systems does it not work for you?

> So I have to use
> "\*-v" with the above code. And this means the "-" is in a different font
> than the "v".
> 
> On page 2, there are some examples in constant width font to make things
> line up. But shouldn't we be using constant width font for all code? That's
> what the rest of the world is doing nowadays (or, if you want to be fancy, a
> sans serif font that stands out in a different way).

Hmmm, with a set of macros C CR RC CI and IC to use them it could be a
good idea.  Branden, how does it look to you?  I don't think CB and BC
would be necessary.

> But Linux man page
> fonts are still stuck with a style defined by the limitations of the 1970s
> C/A/T phototypesetter 
> and are using Times Bold and Times Italic to refer to program and file
> names.
> 
> Also, it should be ragged right, in both nroff and troff output.
> Right-adjusted text looks nicer but is less functional, and man pages should
> be all about function. (See the reference below.)

You can probably configure that in man.local, no?  I know at least you
can disable hyphenation, which solves most of the functional problems.

> > > The lines are too long to read comfortably; this is inherent to how a
> > > good font squeezes in more text.
> > 
> > I'm not sure I understand this.  Do you mean there are too many letters
> > in a line in the Linux man-pages PDF or too few?
> 
> Too many. I'm getting about 100 characters per line in the PDF, which is on
> the extreme high end of the usual recommendations (it should be closer to 60
> characters per line).

Completely agree.  CC += groff.  Branden, do you think we can fix that
somehow?  Literally, the first thing I thought about the Linux man-pages
PDF when I saw it was "Lines are so long that it's hard for me to read
them.".  Well, it was the second; I first saw the front page, which was
beautiful; that thought was the first one when I say the first page
after the front.

> There's no single answer here of course (opinions do
> differ), but the man page lines are pretty clearly too long in the PDFs.
> See:
> 
> Nanavati AA, Bias RG. Optimal line length in reading - a literature review.
> Visible Language. 2005;39(2):120-44.
> https://journals.uc.edu/index.php/vl/article/view/5765

H.

Re: Re: Why does groff require psutils?

[Alexis (surryhill)]

On Thu, Apr 04, 2024 at 08:26:44PM -0500, G. Branden Robinson wrote:
> Alexis, would you like to look into this more deeply, and maybe find a
> solution that will enable us to use ps2ps after all?

Of course, Branden. Just to be sure I use the same code-path as you
did which command(s) did you use to build the HTML versions groff of 
man pages?


Alexis

Re: Why does groff require psutils?

[G. Branden Robinson]

Hi Alexis,

At 2024-04-08T15:10:55+0200, Alexis (surryhill) wrote:
> On Thu, Apr 04, 2024 at 08:26:44PM -0500, G. Branden Robinson wrote:
> > Alexis, would you like to look into this more deeply, and maybe find a
> > solution that will enable us to use ps2ps after all?
> 
> Of course, Branden. Just to be sure I use the same code-path as you
> did which command(s) did you use to build the HTML versions groff of
> man pages?

Sure thing.  This is the script I use to inspect groff's man pages (and
a couple of other documents) for regressions before each push I do.
It's saved me from embarrassment countless times.

(So naturally I find other ways to embarrass myself.)

To make it fully useful for regression testing, I keep a cached copy of
the files it creates as of my last push, and then diff the cached and
new directories.  But you shouldn't need that additional infrastructure
to reproduce the problem--if in fact you can, and it's not somehow an
artifact of my environment.

Regards,
Branden
#!/bin/bash

set -e

if [ $# -ne 1 ]
then
echo "need a directory argument (e.g., \"old\", \"new\")" >&2
exit 1
fi

if ! [ -x ./build/test-groff ]
then
echo "./build/test-groff does not exist or is not executable" >&2
exit 2
fi

groff () {
../build/test-groff "$@"
}

BFLAG=
#BFLAG=-b
DIR=$1

MANS=(
./src/utils/lkbib/lkbib.1.man
./src/utils/tfmtodit/tfmtodit.1.man
./src/utils/hpftodit/hpftodit.1.man
./src/utils/pfbtops/pfbtops.1.man
./src/utils/afmtodit/afmtodit.1.man
./src/utils/lookbib/lookbib.1.man
./src/utils/addftinfo/addftinfo.1.man
./src/utils/xtotroff/xtotroff.1.man
./src/utils/indxbib/indxbib.1.man
./src/roff/nroff/nroff.1.man
./src/roff/troff/troff.1.man
./src/roff/groff/groff.1.man
./src/utils/grog/grog.1.man
./src/devices/grodvi/grodvi.1.man
./src/devices/grolbp/grolbp.1.man
./src/devices/grops/grops.1.man
./src/devices/grohtml/grohtml.1.man
./src/devices/grolj4/grolj4.1.man
./src/devices/grotty/grotty.1.man
./src/devices/gropdf/gropdf.1.man
./src/devices/gropdf/pdfmom.1.man
./src/devices/xditview/gxditview.1.man
./src/preproc/preconv/preconv.1.man
./src/preproc/tbl/tbl.1.man
./src/preproc/soelim/soelim.1.man
./src/preproc/eqn/eqn.1.man
./src/preproc/eqn/neqn.1.man
./src/preproc/pic/pic.1.man
./src/preproc/refer/refer.1.man
./src/preproc/grn/grn.1.man
./contrib/pic2graph/pic2graph.1.man
./contrib/hdtbl/groff_hdtbl.7.man
./contrib/mm/groff_mm.7.man
./contrib/mm/mmroff.1.man
./contrib/grap2graph/grap2graph.1.man
./contrib/pdfmark/pdfroff.1.man
./contrib/rfc1345/groff_rfc1345.7.man
./contrib/eqn2graph/eqn2graph.1.man
./contrib/gpinyin/gpinyin.1.man
./contrib/mom/groff_mom.7.man
./contrib/gdiffmk/gdiffmk.1.man
./contrib/glilypond/glilypond.1.man
./contrib/chem/chem.1.man
./contrib/gperl/gperl.1.man
./man/groff_tmac.5.man
./man/groff_out.5.man
./man/groff_diff.7.man
./man/groff_char.7.man
./man/groff.7.man
./man/roff.7.man
./man/groff_font.5.man
./tmac/groff_trace.7.man
./tmac/groff_me.7.man
./tmac/groff_ms.7.man
./tmac/groff_man.7.man
./tmac/groff_man_style.7.man
./tmac/groff_mdoc.7.man
./tmac/groff_www.7.man
)

MANS_SV=(
./contrib/mm/groff_mmse.7.man
)

mkdir "$DIR"
pushd "$DIR" >/dev/null

# the change logs, so we know approximately where we are
cp ../ChangeLog .

for d in chem gdiffmk glilypond gperl gpinyin hdtbl mm mom pdfmark rfc1345 \
sboxes
do
cp ../contrib/$d/ChangeLog ./ChangeLog.$d
done

# our Texinfo manual
cp ../build/doc/groff.txt .

# our Texinfo manual via HTML
cp ../build/doc/groff.html .
lynx -dump groff.html > groff.html.txt

# our ms manuals
groff $BFLAG -ww -Tutf8 -ept -ms ../doc/ms.ms > ms.txt

# our me manuals
#groff $BFLAG -ww -Tutf8 -me ../doc/meintro.me > meintro.txt
#groff $BFLAG -ww -Tutf8 -kt -me -mfr ../doc/meintro_fr.me > meintro_fr.txt
#groff $BFLAG -ww -Tutf8 -me ../doc/meref.me > meref.txt
me_pre=../ATTIC/my.me
groff $BFLAG -ww -Tutf8 -me $me_pre ../build/doc/meintro.me > meintro.txt
groff $BFLAG -ww -Tutf8 -kt -me -mfr $me_pre ../build/doc/meintro_fr.me \
> meintro_fr.txt
groff $BFLAG -ww -Tutf8 -me $me_pre ../build/doc/meref.me > meref.txt

for F in ${MANS[*]} ${MANS_SV[*]}
do
G=../build/${F%.man}
if [ -f "$G" ]
then
cp "$G" .
else
echo "warning: \"$G\" missing" >&2
fi
done

: ${AD:=l}

ARGS="$BFLAG -ww -dAD=$AD -rCHECKSTYLE=3 -rU1 -Tutf8 -e -t -mandoc"
NOCR=-rcR=0
LOCALE=
ARGS_HTML="$BFLAG -ww -rCHECKSTYLE=3 -Thtml -e -t -mandoc -P-C -P-G"

for P in *.[157]
do
if [ "$P" = groff_mmse.7 ]
then
  LOCALE=-msv
else
  LOCALE=
fi

echo $0: $P >&2
echo "groff $ARGS $LOCALE $P" > "$P.cR.txt"
groff $ARGS $LOCALE "$P" >> "$P.cR.txt"
echo "groff $ARGS $LOCALE $NOCR $P" > "$P.no-cR.txt"
groff $ARGS $LOCALE $NOCR "$P" >> "$P.no-cR.txt"
echo "" > "$P.html"
groff $ARGS_HTML $LOCALE -P-I$P $P >> "$P.html"
rm "$P"
done

popd >/dev/null

# vim:set ai et sw=4 ts=4 tw=80:


signature.asc
Description: PGP signature

Re: [PATCH v2] tzfile.5: Fix indentation

[G. Branden Robinson]

[Caveat lector: this is not a short email and I hyperlink to multiple
longer ones]

Hi Paul & Alex,

At 2024-04-07T23:33:38-0700, Paul Eggert wrote:
> On 2024-03-18 01:35, Alejandro Colomar wrote:
> > Hmm, while Ossana's indents might be a bit excessive, TZDB's might
> > be too short.  Maybe I would RS 4 spaces instead of 2 before the
> > tag.
> 
> That'd be too long for the nroff case. The nroff case is a bit too
> long already. It looks like the following in the current TZDB version:
> 
>  The goals of this section are:
> 
>o  to  help  TZif  writers output files that avoid common pitfalls in
>   older or buggy TZif readers,
> 
>o  to help TZif readers avoid  common  pitfalls  when  reading  files
>   generated by future TZif writers, and
> 
> ... and if there were four spaces (instead of two) around the bullets,
> it'd be too much white space.
> 
> Of course we could indent more or less depending on whether it's nroff
> or troff, but that's complexity I'd rather avoid.

Depending on what you want, you can apply a scaling unit to the
measurement.  On terminals, 1 em equals 1 en, but on typesetters they're
different (1 en is one half em).

This doesn't work for Thomas Dickey's case, unfortunately, where he
wants _wider_ spacing on terminals than typesetters.

For example:

man/curs_addwstr.3x:.de bP
man/curs_addwstr.3x-.ie n  .IP \(bu 4
man/curs_addwstr.3x-.el.IP \(bu 2
man/curs_addwstr.3x-..

> > > There are other things not to like about the man page PDF output.
> > > The man pages are confused about when to use constant-width fonts
> > > vs varying-width fonts.
> > 
> > Can you please point to an example of this?  I try to be consistent,
> > but probably there are still cases that I haven't fixed due to lack
> > of time.
> 
> See the attached, which is the output of "groff -man -Tpdf zdump.8".
> 
> First, I had to do shenanigans like this:
> 
>   .ie \n(.g .ds - \f(CR-\fP
>   .el .ds - \-
> 
> and later use \*- every time I wanted to specify a zdump option like
> -v.  Using plain "-v" in zdump.8 doesn't work, because it generates a
> hyphen in troff mode and hyphens are too narow. Using "\-v" doesn't
> work, because it generates a mathematical minus sign in the PDF, which
> differs from "-", which means you can't easily search for "-v" in the
> PDF. So I have to use "\*-v" with the above code. And this means the
> "-" is in a different font than the "v".

Like Alex, I am curious why the PDF CMap isn't solving the
copy-and-paste part of this problem.

> On page 2, there are some examples in constant width font to make
> things line up. But shouldn't we be using constant width font for all
> code?

I'd say no.  For code _displays_, sure.  Inline?  That's less certain.
Used _judiciously_, the way Brian Kernighan does, it's fine.  mdoc
mavens like to pound the table, trumpeting the superiority of their
"semantic" macros.  The problem is that for many years, the coupling of
macros of code/literal semantic denotation to the Courier typeface led
to _horrible_ typography in groff, because things like the square
brackets in "synopsis language" weren't in Courier--logically enough,
because they're not "literal"--but this made it difficult to tell how
wide the spaces you were looking at were, or if space was even present
between a bracket and a semantically muscular adjacent code item.

I submit that mdoc advocates lost sight of basic readability.  I guess
it was more fun (and quite possibly more remunerative from an employer)
performing automated transformations on semantic tags than attending to
the basics of typesetting.  (I'm no great practitioner myself!  But I
assume I'm not alone in preferring to be able to tell whether a space is
present at a given location in the text, especially if it's showing me
how to type in a Unix command, which follow varying conventions.)

I recently drove a bulldozer through this nonsense in groff Git HEAD and
am steeling myself for a summons to the International Criminal Court on
charges of "semantic heresy" levied by people who don't even use groff
anyway, but mandoc(1).

(mandoc(1)'s solution to the typesetting problem is to format HTML and
then use a third-party tool to convert HTML to a PDF.)

https://lists.gnu.org/archive/html/groff/2024-03/msg00163.html

> That's what the rest of the world is doing nowadays (or, if you
> want to be fancy, a sans serif font that stands out in a different
> way). But Linux man page fonts are still stuck with a style defined by
> the limitations of the 1970s C/A/T phototypesetter
>  and are using
> Times Bold and Times Italic to refer to program and file names.

Not exactly.  With groff, you can remap these font names.  I recently
showed a groff mailing list subscriber who _hates_ monospaced fonts (and
especially Courier) how to customize the way it's rendered in his
system.

:
>>> ... I don't think many pe

Re: [PATCH v2] tzfile.5: Fix indentation

[Alejandro Colomar]

Hi Branden!

On Mon, Apr 08, 2024 at 10:59:25AM -0500, G. Branden Robinson wrote:
> [Caveat lector: this is not a short email and I hyperlink to multiple
> longer ones]
> 
> Hi Paul & Alex,
> 
> At 2024-04-07T23:33:38-0700, Paul Eggert wrote:
> > > > The lines are too long to read comfortably; this is inherent to
> > > > how a good font squeezes in more text.
> > > 
> > > I'm not sure I understand this.  Do you mean there are too many
> > > letters in a line in the Linux man-pages PDF or too few?
> > 
> > Too many. I'm getting about 100 characters per line in the PDF, which
> > is on the extreme high end of the usual recommendations (it should be
> > closer to 60 characters per line). There's no single answer here of
> > course (opinions do differ), but the man page lines are pretty clearly
> > too long in the PDFs.
> 
> One straightforward means of addressing this problem is simply to
> typeset the manual at a larger type size.  Say, 11 or 12 points.
> groff's supported that for a couple of decades.  For these sizes, Werner
> Lemberg even chose vertical spacing counterparts inspired by TeX.
> 
> groff_man(7):
>  -rStype‐size
>   Use type‐size for the document’s body text; acceptable
>   values are 10, 11, or 12 points.  See subsection “Font
>   style macros” above for the default.
> 
> > See:
> > 
> > Nanavati AA, Bias RG. Optimal line length in reading - a literature review.
> > Visible Language. 2005;39(2):120-44.
> > https://journals.uc.edu/index.php/vl/article/view/5765
> 
> I've got this queued up to read during a doctor's appointment today.
> (More like a waiting room appointment.)
> 
> I have a personal shell function that exercises the new groff man `PO`
> register to use the default line length but center the man page in the
> terminal window, and have been enjoying it for months.
> 
> An inevitable problem we will face in trying to set man pages on
> narrower lines is the heavy use of tables and other means of filling
> disablement by page authors.  No sooner did they get a feel for the
> additional 13n additional elbow room that groff gave them (over
> historical *roffs' 65n), than they started overrunning that limit too.
> 
> Documenters of C wanted function synopses to look just so, and turned
> off filling to get it.  Other page authors wanted to depict what the
> terminal would look like, and ran roughshod over considerations of
> circumstances under which a man page might actually be typeset.
> 
> I wouldn't be at all averse to reimposing a 65n line length limit as a
> _style_ recommendation.  And I think I know where to poke the formatter
> to get it to emit a warning diagnostic if the line length is overrun
> when filling is disabled.  (This would be kin to TeX's notoriously
> discouraging "overfull hbox" warnings, but if I can't write a diagnostic
> message more intelligible than that, I'll put in for retirement.)

Since manual pages often have a few levels of indentation, lines need to
be rather wide on the terminal (and using those levels of indentation,
the actual length of the text isn't too much).  I wouldn't narrow the
line length in nroff(1) mode.

I find troff(1) mode the one that's hardly readable by default.

> 
> At 2024-04-08T10:31:32+0200, Alejandro Colomar wrote:
> > Hmmm, with a set of macros C CR RC CI and IC to use them it could be a
> > good idea.  Branden, how does it look to you?  I don't think CB and BC
> > would be necessary.
> 
> I don't like that idea at all.  I don't want to add _any_ more font
> macros to man(7).

Okay.

> > > Too many. I'm getting about 100 characters per line in the PDF,
> > > which is on the extreme high end of the usual recommendations (it
> > > should be closer to 60 characters per line).
> > 
> > Completely agree.  CC += groff.  Branden, do you think we can fix that
> > somehow?  Literally, the first thing I thought about the Linux
> > man-pages PDF when I saw it was "Lines are so long that it's hard for
> > me to read them.".  Well, it was the second; I first saw the front
> > page, which was beautiful; that thought was the first one when I say
> > the first page after the front.
> 
> Pass `-rS11` (or -rS12) to the formatter when building and see if you
> like the result.

Hmm, that's much more pleasing!

commit 5ba7ca38f758370c9cbfcb901aa0f0f1efb31f52 (HEAD -> contrib)
Author: Alejandro Colomar 
Date:   Mon Apr 8 19:15:35 2024 +0200

share/mk/: $TROFFFLAGS: Use a larger font size

Link: 
Reported-by: Paul Eggert 
Suggested-by: "G. Branden Robinson" 
Cc: "Thomas E. Dickey" dic...@his.com
Signed-off-by: Alejandro Colomar 

diff --git a/share/mk/configure/build-depends/groff-base/troff.mk 
b/share/mk/configure/build-depends/groff-base/troff.mk
index 051172ce7..b9b7518cf 100644
--- a/share/mk/configure/build-depends/groff-base/troff.mk
+++ b/share/mk/configure/build-depends/groff-base/troff.mk
@@ -6,7 +6,9 @@ ifndef 
M

Re: [PATCH v2] tzfile.5: Fix indentation

[Paul Eggert]

On 2024-04-08 01:31, Alejandro Colomar wrote:


Hmmm.  I use "\-v" in the Linux man-pages, and it works


Ha! I just checked and it works for me too. It did not work in 2014. 
Apparently since 2014 PDF and HTML viewers have gotten smarter about 
searching, so that "-" matches any form of dash. So perhaps I should 
remove this \- complication from the TZDB man pages.




You can probably configure that in man.local, no?  I know at least you
can disable hyphenation, which solves most of the functional problems.


Fine, but that should be the default. Users shouldn't have to fiddle 
with man.local to tailor output format to be good for the usual case. 
man.local should be for the unusual cases.

Re: [tz] [PATCH v2] tzfile.5: Fix indentation

[Paul Eggert]

On 2024-04-08 10:46, Paul Eggert via tz wrote:

On 2024-04-08 01:31, Alejandro Colomar wrote:


Hmmm.  I use "\-v" in the Linux man-pages, and it works


Ha! I just checked and it works for me too. It did not work in 2014. A


Unfortunately I spoke too quickly, as this does not work with Solaris 10 
troff. On that platform, this command:


  printf ' - \\- \\(mi\n' | troff | dpost

outputs a .ps file that, when converted to PDF, gives you U+002D 
(HYPHEN-MINUS), U+2013 (EN DASH), U+2212 (MINUS SIGN). So if TZDB wants 
to play nicely even on this obsolescent platform, it still needs to play 
its game with \*- instead. Oh well.