At 2025-08-26T21:24:31+0200, Ingo Schwarze wrote: > Colin Watson wrote on Tue, Aug 26, 2025 at 06:01:47PM +0100: > > I could have it produce a warning message on stderr with an explicit > > deprecation. But one of the classes of wrappers around man(1) is > > graphical applications, and quite often nobody pays attention to > > their stderr. So would such a deprecation method actually be > > effective? > > To get started with deprecation, one might change the manual page to > say, at the place where the feature is described, that it is > deprecated.
I'd go further here and just de-document it.
That's what I'm doing with some renamings in groff_mm(7). Admittedly, I
risk annoying far fewer people than use man(1).
NEWS:
* The m (mm) macro package's `Iso` register is now named `Isodate` to
make its meaning less ambiguous. The old name remains as an alias.
* The m (mm) macro package's `Rpe` register is now named `Rpej` for
better symmetry with `Ej`. The old name remains as an alias.
* The m (mm) macro package has renamed several strings to make their
purposes less obscure; they determine the content of captions, not
list items.
`Licon` -> `Capcon`
`Liec` -> `Capec`
`Liex` -> `Capex`
`Lifg` -> `Capfg`
`Litb` -> `Captb`
The old names remain as aliases.
* The m (mm) macro package has renamed the `Tcst` string to `Tcstatus`
to make its purpose less obscure. The old name remains as an alias.
* The m (mm) macro package recognizes new register names `Ftnum` and
`Rfnum` for the automatically incrementing footnote and reference
counters. The old, DWB-compatible but cryptic, names `:p` and `:R`
remain supported.
The NEWS file doesn't _say_ that the old names are gone from the man
page, but they are.
> On might also mention it in upcoming release notes, saying that people
> should prepare for future removal.
Seconded.
Not precisely on topic is that I wish that man-db man had a separate
tool to do *just* the "librarian" part of its function ("man -w" or "man
-aw"). I kind of want to call it lookman(1), but Plan 9 already has a
tool of that name and its interface isn't quite the same.
$ 9 lookman acme
man 1 0intro # 0intro(1)
man 1 9p # 9p(1)
man 1 9term # 9term(1)
man 1 acme # acme(1)
man 1 acmeevent # acmeevent(1)
man 1 cat # cat(1)
man 1 dict # dict(1)
man 1 label # label(1)
man 1 mc # mc(1)
man 1 wintext # wintext(1)
man 3 complete # complete(3)
man 3 dial # dial(3)
man 3 mousescrollsize # mousescrollsize(3)
man 4 acme # acme(4)
man 7 plumb # plumb(7)
lkman(1) would be shorter. My reason is selfish; that's all I really
need from man(1). Once the documents are located, I have shell
functions that go to groff(1) with them (often via grog(1) or nroff(1)).
I originally wrote these functions when I first started hacking on
groff, so that I could clearly perceive the impact of experiments on the
code. I have found that I seldom actually use man(1) for its idiomatic
purpose.
The only real PITA about this is Debian's insistence on gzipping man
pages, which complicates matters significantly. (I think Steffen
Nurpesmo or Bjarni or somebody has proposed hacking up nroff to run
gunzip itself. I have declined.)
For example, here's my "agman" function (reformatted from bash's output
to restore line continuation). It measures the width of the terminal
and formats the page using 80 character cells, centered in the window,
and does some other things to help me give man pages the hairy eyeball.
agman is a function
agman ()
{
local opts=;
while expr "$1" : "-..*" > /dev/null; do
opts="$opts $1";
shift;
done;
local width=$(stty size | cut -d' ' -f2);
local linelength=80;
local pageoffset=0;
if [ $width -gt $linelength ]; then
pageoffset=$(( (width - linelength) / 2 ));
fi;
set -- $(man -w "$@");
local need_gunzip=;
for arg in "$@";
do
local filetype=$(file "$arg");
case "$filetype" in
*gzip\ compressed\ data*)
need_gunzip=yes
;;
*troff\ or\ preprocessor\ input*)
;;
*)
;;
esac;
done;
local cmd;
if [ -n "$need_gunzip" ]; then
cmd=$(gzip -cdf "$@" | grog -Tutf8 -b -ww -P-i -rU1 -rCHECKSTYLE=4\
-rPO=${PO:-$pageoffset}n\
-rLL=${LL:-$linelength}n $opts);
else
cmd=$(grog -Tutf8 -b -ww -P-i -rU1 -rCHECKSTYLE=4\
-rPO=${PO:-$pageoffset}n\
-rLL=${LL:-$linelength}n $opts "$@");
fi;
if [ $? -eq 0 ]; then
if [ -n "$need_gunzip" ]; then
gzip -cdf "$@" | $cmd | less -R;
else
$cmd | less -R;
fi;
else
echo "$0: grog failed" 1>&2;
fi
}
Regards,
Branden
signature.asc
Description: PGP signature
