On Mon, Jul 15, 2013 at 11:34:53PM +0200, J??r??mie Courr??ges-Anglas wrote: > Jason McIntyre <j...@kerhand.co.uk> writes: > > > On Mon, Jul 15, 2013 at 07:53:04PM +0200, Jan Stary wrote: > >> Some of the manpages, e.g. crontab(1), > >> markup the folklore phrase > >> > >> named file, or standard input > >> if the pseudo-filename `-' is given > >> > >> as > >> > >> named file, or standard input > >> if the pseudo-filename > >> .Sq Fl > >> is given. > >> > >> Is this correct semantic markup? IMHO not: > >> it just abuses the fact that the flags (Fl) > >> happen to start with a dash; but that's not > >> what is meant here; this is not a flag; > >> it is the literal dash that is recognized > >> in place of a filename. > > Then it is an argument (Ar). >
not really. Ar represents an argument name - this is a literal argument. it should therefore be Li, but because the markup on a single character is hard to spot, we use Sq. there is a Ql macro which "does the right thing", but the effect would be the same as using Sq. Sq is probably best, i think. > >> So I believe it should be simply > >> > >> .Sq - > >> > >> Right? > > See below. > > >> The diff below replaces those occurences > >> that a grep revealed for me in /usr/share/man; > >> Another grep reveals that most other manpages > >> actually use ".Sq -". > >> > >> I left out oldrdist(1) and shutdown(8) > >> where it _is_ actually a flag > >> and the code processes it as such. > >> > >> Jan > >> > > > > ok, i agree with this. Fl seems wrong. however there's some ambiguity, > > for me anyway - do oldrdist and shutdown actually process "-" > > differently, or do the manuals talk about them differently? > > Fl may seem wrong because we're talking about an argument, but I don't > think a bare `-' (a hyphen) would be better. We're talking about an > ascii minus sign here; mandoc_char(7) says a minus sign can be obtained > with \- . > it's not a minus sign. it's a literal "-". > I wonder about cat(1) using > .Pq Sq \&- > is that really telling mandoc to treat it as a minus sign? > > What about: > .Pq Sq Ar \- > the \& is wrong, yes. but so is Ar > > for oldrdist, "-" is actually the argument to -f. so it's not an option, > > as far as i can see. just the manual seems to blur things by documenting > > "If either the -f or `-' option is not specified", whereas above, the > > text suggests "-f-" or "-f -" is how it would work. > > Yup, sounds weird. The text above is right, the next sentence should be > changed. Why not: > > If the > .Fl f > option is not specified, the program looks first for... > that seems right. > I've just discovered oldrdist, btw. I hope tedu isn't reading this > mail. :) > > > similarly, look at cat(1): > > > > If file is a single dash (`-') or absent, cat reads from the > > standard input. > > > > no mention of "-" in SYNOPSIS. but shutdown(8), which lists "-" in > > SYNOPSIS: > > > > If `-' is supplied as an option, the warning message is read > > from standard input. > > shutdown.c uses '-' in its getopt string, so that it can be passed > before (and probably between) other options (see SYNOPSIS). This does > not match the way most utilities from the base system handle options and > arguments, so I think the current wording is ok (see getopt(3), > STANDARDS). > > > so, it looks like oldrdist and shutdown are just talking about "-" > > differently to other manuals, but not behaving differently to other > > apps. i.e. we should tweak oldrdist and shutdown too. > > > > can anyone confirm if there is a technical difference (and, if there is, > > does it translate into practical difference for users)? > > Both use it as "read input from stdin", but I think only oldrdist needs > a tweak. > i think you're right. jmc
