[tex-k] kpathsea man pages contain ambigious macro

[frantisek holop]

hi there,

what follows is a (very) minor bug report for the kpathsea
(possibly other tex related projects as well) man pages.
i am not subscribed to the mailing list so please cc: me.

while porting kpathsea to openbsd (for academic reasons,
there is also a texlive port) i found that the bsd
mandoc program (a new groff replacement) cannot parse
the '.rb' macros.  what follows is an analysis from the
mandoc authors regarding this macro:


hmm, on Wed, Jan 19, 2011 at 03:51:42AM +0100, Ingo Schwarze said that
> frantisek holop wrote on Wed, Jan 19, 2011 at 01:34:05AM +0100:
> 
> > kpseaccess.1:1:18: WARNING: cannot parse date argument
> > kpseaccess.1:60:2: ERROR: skipping unknown macro: .rb
> > kpseaccess.1:64:2: ERROR: skipping unknown macro: .rb
> > kpsereadlink.1:1:20: WARNING: cannot parse date argument
> > kpsereadlink.1:24:2: ERROR: skipping unknown macro: .rb
> > kpsereadlink.1:28:2: ERROR: skipping unknown macro: .rb
> > kpsestat.1:1:16: WARNING: cannot parse date argument
> > kpsestat.1:45:2: ERROR: skipping unknown macro: .rb
> > kpsestat.1:49:2: ERROR: skipping unknown macro: .rb
> > kpsewhich.1:1:17: WARNING: cannot parse date argument
> > kpsewhich.1:46:2: ERROR: skipping unknown macro: .rb
> > kpsewhich.1:50:2: ERROR: skipping unknown macro: .rb
> > kpsewhich.1:60:2: ERROR: skipping unknown macro: .rb
> > kpsewhich.1:66:2: ERROR: skipping unknown macro: .rb
> > kpsewhich.1:71:2: ERROR: skipping unknown macro: .rb
> > kpsewhich.1:76:2: ERROR: skipping unknown macro: .rb
> > kpsewhich.1:81:2: ERROR: skipping unknown macro: .rb
> > kpsewhich.1:89:2: ERROR: skipping unknown macro: .rb
> > kpsewhich.1:93:2: ERROR: skipping unknown macro: .rb
> > kpsewhich.1:97:2: ERROR: skipping unknown macro: .rb
> > kpsewhich.1:104:2: ERROR: skipping unknown macro: .rb
> > kpsewhich.1:112:2: ERROR: skipping unknown macro: .rb
> > kpsewhich.1:116:2: ERROR: skipping unknown macro: .rb
> > kpsewhich.1:127:2: ERROR: skipping unknown macro: .rb
> > kpsewhich.1:141:2: ERROR: skipping unknown macro: .rb
> > kpsewhich.1:149:2: ERROR: skipping unknown macro: .rb
> > kpsewhich.1:154:2: ERROR: skipping unknown macro: .rb
> > mktexlsr.1:1:16: WARNING: cannot parse date argument
> > mktexlsr.1:41:2: ERROR: skipping unknown macro: .rb
> > mktexlsr.1:45:2: ERROR: skipping unknown macro: .rb
> > mktexmf.1:1:15: WARNING: cannot parse date argument
> > mktexmf.1:50:2: ERROR: skipping unknown macro: .rb
> > mktexmf.1:54:2: ERROR: skipping unknown macro: .rb
> > mktexpk.1:1:15: WARNING: cannot parse date argument
> > mktexpk.1:59:2: ERROR: skipping unknown macro: .rb
> > mktexpk.1:64:2: ERROR: skipping unknown macro: .rb
> > mktexpk.1:67:2: ERROR: skipping unknown macro: .rb
> > mktexpk.1:76:2: ERROR: skipping unknown macro: .rb
> > mktexpk.1:80:2: ERROR: skipping unknown macro: .rb
> > mktexpk.1:86:2: ERROR: skipping unknown macro: .rb
> > mktexpk.1:89:2: ERROR: skipping unknown macro: .rb
> > mktextfm.1:1:16: WARNING: cannot parse date argument
> > mktextfm.1:53:2: ERROR: skipping unknown macro: .rb
> > mktextfm.1:59:2: ERROR: skipping unknown macro: .rb
> > mktextfm.1:63:2: ERROR: skipping unknown macro: .rb
> > texhash.1:1:16: WARNING: cannot parse date argument
> > texhash.1:41:2: ERROR: skipping unknown macro: .rb
> > texhash.1:45:2: ERROR: skipping unknown macro: .rb
> 
> That's a tough one.  I checked both the Heirloom roff manual,
> the groff-1.20.1 manual and the groff-1.20.1 source code
> and cannot find any reference to or implementation of either
> a roff(7) .rb request or a man(7) .rb macro - besides, being
> lowercase, this is very likely not a man(7) macro, even though
> it clearly appears in a man(7) document.
> 
> The only thing i'm able to find is the me(7) .rb macro -
> not mentioned in meintro.me, mentioned in a single line
> in meref.me, reading "real bold font", whatever that is
> supposed to tell us, and implemented as
> 
> .de rb
> .do check_need_title
> . at E
> .ft 3
> .if \\n(.$ \&\\$1\f\\*(_F\\$2
> .do check_need_title
> ..
> 
> According to the e.tmac sources, check_need_title has no effect
> outside -Thtml, . at E is defined as
> 
> .de @E
> .ie \\n(.f<10 \
> .ds _F \\n(.f
> .el \
> \{\
> .ie \\n(.f<100&\n(.g \
> .ds _F (\\n(.f
> .el \
> .ds _F P
> .\}
> ..
> 
> which basically sets _F to the current font number,
> such that, taking all into account, the .rb me(7) macro
> switches to font 3 (bold), then prints a zero-width space,
> the first argument, switches back to the previous font
> and prints the second argument, similar to .BR in man(7),
> not to be confused with .br, of course.
> However, without arguments, this plainly doesn't seem to
> make make any sense whatsoever.
> 
> With groff-1.20.1 -man, these macros do not appear to have
> any effect.  Loading only -me or both -man and -me in either
> order, the output is completely garbled, and anyway, i never
> heard about a page using a mixture of -man and -me.
> Removing all the .rb requests or macros from kpsewhich.1,
> groff-1.20.1 -man output doesn't change by a single bit.
> 
> Kristaps, can you make head or tail of this?
> 
> If not, we should perhaps ask the upstream documentation author
> what the intended effect of the .rb macro is supposed to be
> before making a decision how to proceed.

--- analysis ends

just to refresh, here is an excerpt of one of the man pages in question:

> .TH KPSEWHICH 1 "7 January 2007" "Kpathsea 6.0.0"
> .\"=====================================================================
> .if n .ds MP MetaPost
> .if t .ds MP MetaPost
> .if n .ds MF Metafont
> .if t .ds MF M\s-2ETAFONT\s0
> .if t .ds TX \fRT\\h'-0.1667m'\\v'0.20v'E\\v'-0.20v'\\h'-0.125m'X\fP
> .if n .ds TX TeX
> .ie t .ds OX \fIT\v'+0.25m'E\v'-0.25m'X\fP for troff
> .el .ds OX TeX for nroff
> .\" the same but obliqued
> .\" BX definition must follow TX so BX can use TX
> .if t .ds BX \fRB\s-2IB\s0\fP\*(TX
> .if n .ds BX BibTeX
> .\" LX definition must follow TX so LX can use TX
> .if t .ds LX \fRL\\h'-0.36m'\\v'-0.15v'\s-2A\s0\\h'-0.15m'\\v'0.15v'\fP\*(TX
> .if n .ds LX LaTeX
> .\"=====================================================================
> .SH NAME
> kpsewhich \- standalone path lookup and and expansion for kpathsea
> .SH SYNOPSIS
> .B kpsewhich
> .RI [ options ]
> .RI [ filenames ]
> .\"=====================================================================
> .SH DESCRIPTION
> This manual page is not meant to be exhaustive.  The complete
> documentation for this version of \*(TX can be found in the info file
> or manual
> .IR "Kpathsea: A library for path searching" .
> .PP
> .B kpsewhich
> is used as a standalone front-end of the kpathsea library that can be
> used to examine variables and find files.  When the
> .B -format
> option is not given, the search path used when looking for a file is
> inferred from the name given, by looking for a known extension.  If
> no known extension is found, the search path for \*(TX source files is
> used.
> .\"=====================================================================
> .SH OPTIONS
> .B kpsewhich
> accepts the following options:
> .TP
> .BI -debug \ num
> .rb
> Set debugging flags.
> .TP
> .BI -D \ num
> .rb
> Use a base resolution of
> .IR num ;
> the default, set by the installer, is typically 600.
> .TP
> .BI -dpi \ num
> As
> .BR -D.
> .TP
> .BI -engine \ string
> .rb
> Set
> .I $engine
> in the environment, which is used in some search paths.
> .TP
> .BI -expand-braces \ string
> .rb
> Print variable and brace expansion of
> .IR string .
> .TP
> .BI -expand-path \ string
> .rb
> Print complete path expansion of
> .IR string .
> .TP
> .BI -expand-var \ string
> .rb
> Print variable expansion of
> .IR string .
> .TP

could anyone from the authors and/or maintainers describe
the desired effect of the macro in question?
i believe Kristaps and Ingo live and breath man page
syntax and could be considered experts in this field :]

i am aware that the man pages were meant for groff
and friends, and an alternative implementation
might not be "authoritative", but according to the
mandoc authors, groff does not know this macro either.

as tex itself is for creating pedantic and beautiful
documents i feel it's documentation should be top notch
and syntactically correct, even if it happens to be
in another typesetting language :]

i'd like to stress again, this is in no way a critical issue.

-f
-- 
evil is a hill.  we stand on ours, speak about others.