From owner-cvs-all Thu May 30 8:12: 9 2002 Delivered-To: cvs-all@freebsd.org Received: from whale.sunbay.crimea.ua (whale.sunbay.crimea.ua [212.110.138.65]) by hub.freebsd.org (Postfix) with ESMTP id 4F51F37B40D; Thu, 30 May 2002 08:11:41 -0700 (PDT) Received: (from ru@localhost) by whale.sunbay.crimea.ua (8.11.6/8.11.2) id g4UFBZE31686; Thu, 30 May 2002 18:11:35 +0300 (EEST) (envelope-from ru) Date: Thu, 30 May 2002 18:11:35 +0300 From: Ruslan Ermilov To: John Baldwin Cc: cvs-all@FreeBSD.org, cvs-committers@FreeBSD.org, "J. Mallett" Subject: Re: cvs commit: src/usr.bin/split split.1 Message-ID: <20020530151135.GA30858@sunbay.com> References: <20020530062446.GC60627@sunbay.com> Mime-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="XsQoSWH+UP9D9v3l" Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.3.99i Sender: owner-cvs-all@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.ORG --XsQoSWH+UP9D9v3l Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Thu, May 30, 2002 at 11:03:19AM -0400, John Baldwin wrote: >=20 > On 30-May-2002 Ruslan Ermilov wrote: > > On Wed, May 29, 2002 at 11:19:25PM -0700, J. Mallett wrote: > >> * From Ruslan Ermilov > >> > On Wed, May 29, 2002 at 11:09:45PM -0700, J. Mallett wrote: > >> > > * From Ruslan Ermilov > >> > > > ru 2002/05/29 23:07:29 PDT > >> > > >=20 > >> > > > Modified files: > >> > > > usr.bin/split split.1=20 > >> > > > Log: > >> > > > mdoc(7) police: use .Fl to denote stdin. > >> > >=20 > >> > > Is this really right? It certainly isn't a flag in the case of: > >> > > diff -u foo - > >> > >=20 > >> > > is it? > >> > >=20 > >> > > Wouldn't .Pa be more appropriate, or something? > >> > >=20 > >> > No, using .Pa wouldn't be more appropriate, as ``-'' isn't a real pa= th. > >> > Current mdoc(7) practices tell us: > >> >=20 > >> > : The `.Fl' macro without any arguments results in a dash represe= nting > >> > : stdin/stdout. > >>=20 > >> What about .Ar then, as this is an explicit argument that a program mu= st grok, > >> it is not handled like a flag, and in fact none of our flag processing= stuff > >> handles it, namely getopt(3). Seems to me it's just a special .Ar fil= e ... > >> possibility. Just because it is symbolic doesn't mean it should be no= tated > >> differently, unless you show all possible usages including where stdin= could > >> be used as a file... Doesn't seem right to me... What was the logic = in the > >> .Fl macro being used for it? > >>=20 > > .Ar isn't right either because it denotes argument names, not the actual > > values. There isn't currently a macro like ``argument's value'', and I > > routinely use the .Cm macro for that (for well-known argument names). > > In this case, the file's argument value is (``-''), i.e. ``.Cm \&-'', b= ut > > then again (from mdoc(7)): > >=20 > >: Command Modifiers > >: The command modifier is identical to the `.Fl' (flag) command with = the > > ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ > >: exception that the `.Cm' macro does not assert a dash in front of e= very > >: argument. Traditionally flags are marked by the preceding dash, ho= wever, > >: some commands or subsets of commands do not use them. Command modi= fiers > >: may also be specified in conjunction with interactive commands such= as > >: editor commands. See Flags. >=20 > You should not markup based on appearance like HTML does, but based on ac= tual > content like DocBook. The macros should then render the appropriate appe= arance > for the content. How would you mark up this: >=20 > diff -u foo bar >=20 =2ENm diff Fl u Pa foo bar > You should mark up >=20 > diff -u foo - >=20 =2ENm diff Fl u Pa foo Fl > in exactly the same manner as '-' is playing the same role as 'bar' in the > first one. Surely you aren't going to say '.Fl bar' are you? :) >=20 No, `-' is special, it's not the real path, it's a "flag" for a program that tells it to substitute stdin/stdout. I'm not against breaking the traditions, we just happen to have this documented, and have much more .Fl examples to denote stdin/stdout than with either ``.Ql \&-'' or ``.Pa \&-''. And I am for consistency. Cheers, --=20 Ruslan Ermilov Sysadmin and DBA, ru@sunbay.com Sunbay Software AG, ru@FreeBSD.org FreeBSD committer, +380.652.512.251 Simferopol, Ukraine http://www.FreeBSD.org The Power To Serve http://www.oracle.com Enabling The Information Age --XsQoSWH+UP9D9v3l Content-Type: application/pgp-signature Content-Disposition: inline -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.0.7 (FreeBSD) iD8DBQE89kEnUkv4P6juNwoRAnLnAKCFJ/aXljTL8fui1Sz44uNMyvB8SwCcCUje jhZNEw299RxO76lFtIAS28E= =6HKo -----END PGP SIGNATURE----- --XsQoSWH+UP9D9v3l-- To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe cvs-all" in the body of the message