Re: mdoc(7) .Sq Fl for a dash
On Tue, Jul 16, 2013 at 01:42:13PM +0200, J??r??mie Courr??ges-Anglas wrote: > > \- is afaik treated correctly in all the cases I described above, except > for a very small number of groff versions, when in an UTF-8 locale or > using ps/pdf (there you can get an unicode minus sign). This case was > quickly fixed. You can see lots of reports about all these problems on > the WWW. > > Now if you think \- is wrong for a command-line flag, a litteral "-" > argument, or inside a command name, tell this to Ingo, since that's what > is produced by a Fl inside mandoc. ;) > yes, if you're correct, then we would want to convert "-" to "\-". i had no idea this was the case. where does it happen about? jmc
Re: mdoc(7) .Sq Fl for a dash
Hi, Jason McIntyre writes: > On Tue, Jul 16, 2013 at 12:36:32AM +0200, Jérémie Courrèges-Anglas wrote: >> >> >> >> 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 was thinking encoding-wise: you're typing an ascii minus sign, at the >> cli. If you have a man/mdoc formatter that distinguishes hyphens and >> minus signs, it could produce different output for those, and you would >> not be able to copy-paste examples. Maybe mandoc doesn't, but groff >> can (some distros even disabled this behavior). >> > > i'm not sure i follow. the differing widths of "-" will only happen if > you add mark up. I'm not saying we should add markup, but that some occurences of "-" should be converted to "\-". They do not have the same meaning. > i'm arguing to remove it. That would be a step backwards, I think. > a literal "-", with no mark up, can be copied/pasted no matter what the > output format. well, i say this without actually having tried it. Nope, and that's the whole point: you'd have to try it with mandoc, several versions of groff (possibly with local patches), heirloom troff, using different input *and* output formats *and* different locales. > but if > you can;t, something is not right. Well, I think I understand that one that may prefer a hyphen or an em-dash to be represented differently from a minus sign. Be it on tty, or an ps or an html document. > if you add markup (you suggested "\-"), I suggested using \- because that's the sequence documented as producing a minus sign. See mdoc_char(7), groff_char(7). > then the width will vary for > output formats such as postscript. that might stop you being able to > paste (though again i've never tried). ... \- is afaik treated correctly in all the cases I described above, except for a very small number of groff versions, when in an UTF-8 locale or using ps/pdf (there you can get an unicode minus sign). This case was quickly fixed. You can see lots of reports about all these problems on the WWW. Now if you think \- is wrong for a command-line flag, a litteral "-" argument, or inside a command name, tell this to Ingo, since that's what is produced by a Fl inside mandoc. ;) > jmc > -- Jérémie Courrèges-Anglas PGP Key fingerprint: 61DB D9A0 00A4 67CF 2A90 8961 6191 8FBF 06A1 1494
Re: mdoc(7) .Sq Fl for a dash
On Tue, Jul 16, 2013 at 09:50:14AM +0200, Jan Stary wrote: > On Jul 16 07:52:50, j...@kerhand.co.uk wrote: > > for oldrdist, i also > > used Sq instead of Dq for "-". > > It uses .Dq everywhere else. > For consistency, should we replace them all with .Sq? > no. what we tend to do is use Sq for single letters, and Dq for two or more. the reason is that ``'' tends to swamp single lettters, and `' is harder to notice for words. if you look at other pages, you should see that being done fairly consistently. jmc > Index: oldrdist.1 > === > RCS file: /cvs/src/usr.bin/oldrdist/oldrdist.1,v > retrieving revision 1.20 > diff -u -p -u -p -r1.20 oldrdist.1 > --- oldrdist.13 Sep 2011 22:59:07 - 1.20 > +++ oldrdist.116 Jul 2013 07:42:13 - > @@ -65,18 +65,16 @@ Use the specified > If > .Ar distfile > is > -.Dq - , > +.Sq - , > the standard input is used. > .El > .Pp > -If either the > +If the > .Fl f > -or > -.Sq Fl > option is not specified, the program looks first for > -.Dq Pa distfile , > +.Sq Pa distfile , > then > -.Dq Pa Distfile > +.Sq Pa Distfile > to use as the input. > If no names are specified on the command line, > .Nm > @@ -317,7 +315,7 @@ options on the command line except they > in the source list. > The login name used on the destination host is the same as the local host > unless the destination name is of the format > -.Dq login@host . > +.Sq login@host . > .Pp > The > .Ic notify > @@ -455,7 +453,7 @@ facility. > aborts on files which have a negative mtime (before Jan 1, 1970). > .Pp > There should be a > -.Dq force > +.Sq force > option to allow replacement of non-empty directories > by regular files or symlinks. > A means of updating file modes and owners
Re: mdoc(7) .Sq Fl for a dash
On Jul 16 07:52:50, j...@kerhand.co.uk wrote: > for oldrdist, i also > used Sq instead of Dq for "-". It uses .Dq everywhere else. For consistency, should we replace them all with .Sq? Index: oldrdist.1 === RCS file: /cvs/src/usr.bin/oldrdist/oldrdist.1,v retrieving revision 1.20 diff -u -p -u -p -r1.20 oldrdist.1 --- oldrdist.1 3 Sep 2011 22:59:07 - 1.20 +++ oldrdist.1 16 Jul 2013 07:42:13 - @@ -65,18 +65,16 @@ Use the specified If .Ar distfile is -.Dq - , +.Sq - , the standard input is used. .El .Pp -If either the +If the .Fl f -or -.Sq Fl option is not specified, the program looks first for -.Dq Pa distfile , +.Sq Pa distfile , then -.Dq Pa Distfile +.Sq Pa Distfile to use as the input. If no names are specified on the command line, .Nm @@ -317,7 +315,7 @@ options on the command line except they in the source list. The login name used on the destination host is the same as the local host unless the destination name is of the format -.Dq login@host . +.Sq login@host . .Pp The .Ic notify @@ -455,7 +453,7 @@ facility. aborts on files which have a negative mtime (before Jan 1, 1970). .Pp There should be a -.Dq force +.Sq force option to allow replacement of non-empty directories by regular files or symlinks. A means of updating file modes and owners
Re: mdoc(7) .Sq Fl for a dash
On Tue, Jul 16, 2013 at 12:38:42AM +0200, Jan Stary wrote: > > Index: oldrdist.1 > === > RCS file: /cvs/src/usr.bin/oldrdist/oldrdist.1,v > retrieving revision 1.20 > diff -u -p -u -p -r1.20 oldrdist.1 > --- oldrdist.13 Sep 2011 22:59:07 - 1.20 > +++ oldrdist.115 Jul 2013 22:29:30 - > @@ -69,10 +69,8 @@ is > the standard input is used. > .El > .Pp > -If either the > +If the > .Fl f > -or > -.Sq Fl > option is not specified, the program looks first for > .Dq Pa distfile , > then > Index: cat.1 > === > RCS file: /cvs/src/bin/cat/cat.1,v > retrieving revision 1.32 > diff -u -p -u -p -r1.32 cat.1 > --- cat.1 18 Jan 2013 21:48:43 - 1.32 > +++ cat.1 15 Jul 2013 22:34:45 - > @@ -53,7 +53,7 @@ operands are processed in command-line o > If > .Ar file > is a single dash > -.Pq Sq \&- > +.Pq Sq - > or absent, > .Nm > reads from the standard input. > ok, these and the rest (getty/crontab/diff) fixed. for oldrdist, i also used Sq instead of Dq for "-". jmc
Re: mdoc(7) .Sq Fl for a dash
On Tue, Jul 16, 2013 at 12:36:32AM +0200, J??r??mie Courr??ges-Anglas wrote: > >> > >> 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 was thinking encoding-wise: you're typing an ascii minus sign, at the > cli. If you have a man/mdoc formatter that distinguishes hyphens and > minus signs, it could produce different output for those, and you would > not be able to copy-paste examples. Maybe mandoc doesn't, but groff > can (some distros even disabled this behavior). > i'm not sure i follow. the differing widths of "-" will only happen if you add mark up. i'm arguing to remove it. a literal "-", with no mark up, can be copied/pasted no matter what the output format. well, i say this without actually having tried it. but if you can;t, something is not right. if you add markup (you suggested "\-"), then the width will vary for output formats such as postscript. that might stop you being able to paste (though again i've never tried). jmc
Re: mdoc(7) .Sq Fl for a dash
Jason McIntyre writes: > On Mon, Jul 15, 2013 at 11:34:53PM +0200, Jérémie Courrèges-Anglas wrote: >> Jason McIntyre 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. That makes sense. > 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 was thinking encoding-wise: you're typing an ascii minus sign, at the cli. If you have a man/mdoc formatter that distinguishes hyphens and minus signs, it could produce different output for those, and you would not be able to copy-paste examples. Maybe mandoc doesn't, but groff can (some distros even disabled this behavior). >> 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 > [...] -- Jérémie Courrèges-Anglas PGP Key fingerprint: 61DB D9A0 00A4 67CF 2A90 8961 6191 8FBF 06A1 1494
Re: mdoc(7) .Sq Fl for a dash
On Jul 15 23:24:40, j...@kerhand.co.uk wrote: > i think the previous suggestion (If the -f option is not specified) is > clearer. > > > Why cannot this be just > > .Pq Sq - > > > it should be. so roll this into your diff. Index: oldrdist.1 === RCS file: /cvs/src/usr.bin/oldrdist/oldrdist.1,v retrieving revision 1.20 diff -u -p -u -p -r1.20 oldrdist.1 --- oldrdist.1 3 Sep 2011 22:59:07 - 1.20 +++ oldrdist.1 15 Jul 2013 22:29:30 - @@ -69,10 +69,8 @@ is the standard input is used. .El .Pp -If either the +If the .Fl f -or -.Sq Fl option is not specified, the program looks first for .Dq Pa distfile , then Index: cat.1 === RCS file: /cvs/src/bin/cat/cat.1,v retrieving revision 1.32 diff -u -p -u -p -r1.32 cat.1 --- cat.1 18 Jan 2013 21:48:43 - 1.32 +++ cat.1 15 Jul 2013 22:34:45 - @@ -53,7 +53,7 @@ operands are processed in command-line o If .Ar file is a single dash -.Pq Sq \&- +.Pq Sq - or absent, .Nm reads from the standard input.
Re: mdoc(7) .Sq Fl for a dash
On Mon, Jul 15, 2013 at 11:53:38PM +0200, Jan Stary wrote: > > > > 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. > > You are right: the `-' is actually an argument to -f, > and the manpage wording just confuses things by talking > about "the `-' option". BTW, it uses ".Dq" everywhere else. > > Index: oldrdist.1 > === > RCS file: /cvs/src/usr.bin/oldrdist/oldrdist.1,v > retrieving revision 1.20 > diff -u -p -u -p -r1.20 oldrdist.1 > --- oldrdist.13 Sep 2011 22:59:07 - 1.20 > +++ oldrdist.115 Jul 2013 21:38:51 - > @@ -69,11 +69,9 @@ is > the standard input is used. > .El > .Pp > -If either the > -.Fl f > -or > -.Sq Fl > -option is not specified, the program looks first for > +If the > +.Ar distfile > +is not specified, the program looks first for > .Dq Pa distfile , > then > .Dq Pa Distfile > i think the previous suggestion (If the -f option is not specified) is clearer. > > > > similarly, look at cat(1): > > > > If file is a single dash (`-') or absent, cat reads from the > > standard input. > > > > no mention of "-" in SYNOPSIS. > > Yes; here it does not suggest that `-' is an option, > just that it is recognized as a special value for `file' > (which is described in SYNOPSIS). > > Incidentaly, it uses > > .Pq Sq \&- > > Why cannot this be just > > .Pq Sq - > > ? > it should be. so roll this into your diff. > > but shutdown(8), which lists "-" in > > SYNOPSIS: > > > > If `-' is supplied as an option, the warning message is read > > from standard input. > > > > 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. > > shutdown code actually recognizes `-' as a getopt case: > it is technically an option, meaning "do not expect the message > on the commandline, read it from stdin instead". > ok, so we can leave shutdown alone. jmc
Re: mdoc(7) .Sq Fl for a dash
On Mon, Jul 15, 2013 at 11:34:53PM +0200, J??r??mie Courr??ges-Anglas wrote: > Jason McIntyre 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
Re: mdoc(7) .Sq Fl for a dash
On Jul 15 21:46:21, j...@kerhand.co.uk wrote: > 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. > > > > So I believe it should be simply > > > > .Sq - > > > > Right? > > > > 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? > > 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. You are right: the `-' is actually an argument to -f, and the manpage wording just confuses things by talking about "the `-' option". BTW, it uses ".Dq" everywhere else. Index: oldrdist.1 === RCS file: /cvs/src/usr.bin/oldrdist/oldrdist.1,v retrieving revision 1.20 diff -u -p -u -p -r1.20 oldrdist.1 --- oldrdist.1 3 Sep 2011 22:59:07 - 1.20 +++ oldrdist.1 15 Jul 2013 21:38:51 - @@ -69,11 +69,9 @@ is the standard input is used. .El .Pp -If either the -.Fl f -or -.Sq Fl -option is not specified, the program looks first for +If the +.Ar distfile +is not specified, the program looks first for .Dq Pa distfile , then .Dq Pa Distfile > similarly, look at cat(1): > > If file is a single dash (`-') or absent, cat reads from the > standard input. > > no mention of "-" in SYNOPSIS. Yes; here it does not suggest that `-' is an option, just that it is recognized as a special value for `file' (which is described in SYNOPSIS). Incidentaly, it uses .Pq Sq \&- Why cannot this be just .Pq Sq - ? > but shutdown(8), which lists "-" in > SYNOPSIS: > > If `-' is supplied as an option, the warning message is read > from standard input. > > 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. shutdown code actually recognizes `-' as a getopt case: it is technically an option, meaning "do not expect the message on the commandline, read it from stdin instead".
Re: mdoc(7) .Sq Fl for a dash
Jason McIntyre 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.831 May 2007 19:19:39 - 1.13 >> +++ src/libexec/getty/getty.815 Jul 2013 17:42:42 - >> @@ -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 - 1.41 >> +++ src/usr.bin/diff/diff.1 15 Jul 2013 17:42:53 - >> @@ -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 - 1.28 >> +++ src/usr.sbin/cron/crontab.1 15 Jul 2013 17:42:57 - >> @@ -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
Re: mdoc(7) .Sq Fl for a dash
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. > > So I believe it should be simply > > .Sq - > > Right? > > 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? 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. 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. 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)? 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 - 1.13 > +++ src/libexec/getty/getty.8 15 Jul 2013 17:42:42 - > @@ -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 - 1.41 > +++ src/usr.bin/diff/diff.1 15 Jul 2013 17:42:53 - > @@ -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 - 1.28 > +++ src/usr.sbin/cron/crontab.1 15 Jul 2013 17:42:57 - > @@ -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
