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). >> 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 \- . 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 \- > 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... 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. > jmc > >> >> Index: src/libexec/getty/getty.8 >> =================================================================== >> RCS file: /cvs/src/libexec/getty/getty.8,v >> retrieving revision 1.13 >> diff -u -p -u -p -r1.13 getty.8 >> --- src/libexec/getty/getty.8 31 May 2007 19:19:39 -0000 1.13 >> +++ src/libexec/getty/getty.8 15 Jul 2013 17:42:42 -0000 >> @@ -55,7 +55,7 @@ is the special device file in >> .Pa /dev >> to open for the terminal (for example, ``ttyh0''). >> If there is no argument or the argument is >> -.Sq Fl , >> +.Sq - , >> the tty line is assumed to be open as file descriptor 0. >> .Pp >> The >> Index: src/usr.bin/diff/diff.1 >> =================================================================== >> RCS file: /cvs/src/usr.bin/diff/diff.1,v >> retrieving revision 1.41 >> diff -u -p -u -p -r1.41 diff.1 >> --- src/usr.bin/diff/diff.1 20 Jan 2013 11:19:12 -0000 1.41 >> +++ src/usr.bin/diff/diff.1 15 Jul 2013 17:42:53 -0000 >> @@ -331,7 +331,7 @@ If either >> or >> .Ar file2 >> is >> -.Sq Fl , >> +.Sq - , >> the standard input is >> used in its place. >> .Ss Output Style >> Index: src/usr.sbin/cron/crontab.1 >> =================================================================== >> RCS file: /cvs/src/usr.sbin/cron/crontab.1,v >> retrieving revision 1.28 >> diff -u -p -u -p -r1.28 crontab.1 >> --- src/usr.sbin/cron/crontab.1 31 Jan 2011 19:13:31 -0000 1.28 >> +++ src/usr.sbin/cron/crontab.1 15 Jul 2013 17:42:57 -0000 >> @@ -48,7 +48,7 @@ they are not intended to be edited direc >> .Pp >> The first form of this command is used to install a new crontab from some >> named file, or standard input if the pseudo-filename >> -.Sq Fl >> +.Sq - >> is given. >> .Pp >> If the > -- Jérémie Courrèges-Anglas PGP Key fingerprint: 61DB D9A0 00A4 67CF 2A90 8961 6191 8FBF 06A1 1494
