find.1: Markup primaries with Fl not Cm for easier tags

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

find.1: Markup primaries with Fl not Cm for easier tags

Klemens Nanni-2
In both command line usage and manual output format, find's options
and primaries behave the same, but their mdoc(7) markup is different and
therefore causes different tag names:

-x (option) can be looked up with ":tx<Enter>" in the manual pager,
whereas -amin (primary) requires ":t-amin<Enter>" including the dash.

I'd like primaries to behave the same like options when it comes to tags
in manuals, is that a reasonable expectation?

If so, diff below switches all primaries from `Cm -amin' to `Fl amin'
markup such that their resulting tag name is "amin" not "-amin";  man's
output stays identical.

Feedback? OK?


Index: find.1
===================================================================
RCS file: /cvs/src/usr.bin/find/find.1,v
retrieving revision 1.98
diff -u -p -U0 -r1.98 find.1
--- find.1 2 Sep 2019 21:18:41 -0000 1.98
+++ find.1 19 Mar 2020 22:59:33 -0000
@@ -149 +149 @@ the last option given overrides the othe
-.It Ic -amin Ar n
+.It Fl amin Ar n
@@ -156 +156 @@ minutes.
-.It Ic -anewer Ar file
+.It Fl anewer Ar file
@@ -160 +160 @@ True if the current file has a more rece
-.It Ic -atime Ar n
+.It Fl atime Ar n
@@ -167 +167 @@ was started, rounded up to the next full
-.It Ic -cmin Ar n
+.It Fl cmin Ar n
@@ -175 +175 @@ minutes.
-.It Ic -cnewer Ar file
+.It Fl cnewer Ar file
@@ -179 +179 @@ True if the current file has a more rece
-.It Ic -ctime Ar n
+.It Fl ctime Ar n
@@ -187 +187 @@ was started, rounded up to the next full
-.It Ic -delete
+.It Fl delete
@@ -205 +205 @@ Following symlinks is incompatible with
-.It Ic -depth
+.It Fl depth
@@ -211 +211 @@ option.
-.It Ic -empty
+.It Fl empty
@@ -214,2 +214,2 @@ True if the current file or directory is
-.It Ic -exec Ar utility Oo Ar argument ... Oc \&;
-.It Ic -exec Ar utility Oo Ar argument ... Oc {} +
+.It Fl exec Ar utility Oo Ar argument ... Oc \&;
+.It Fl exec Ar utility Oo Ar argument ... Oc {} +
@@ -256 +256 @@ does not exceed
-.It Ic -execdir Ar utility Oo Ar argument ... Oc \&;
+.It Fl execdir Ar utility Oo Ar argument ... Oc \&;
@@ -284 +284 @@ flags specified exactly match those of t
-.It Ic -follow
+.It Fl follow
@@ -290 +290 @@ option.
-.It Ic -fstype Ar type
+.It Fl fstype Ar type
@@ -303 +303 @@ mounted read-only.
-.It Ic -group Ar gname
+.It Fl group Ar gname
@@ -312 +312 @@ is treated as a group ID.
-.It Ic -iname Ar pattern
+.It Fl iname Ar pattern
@@ -317 +317 @@ primary except that the matching is done
-.It Ic -inum Ar n
+.It Fl inum Ar n
@@ -321 +321 @@ True if the file has inode number
-.It Ic -links Ar n
+.It Fl links Ar n
@@ -326 +326 @@ links.
-.It Ic -ls
+.It Fl ls
@@ -339 +339 @@ The format is identical to that produced
-.It Ic -maxdepth Ar n
+.It Fl maxdepth Ar n
@@ -343 +343 @@ True if the current search depth is less
-.It Ic -mindepth Ar n
+.It Fl mindepth Ar n
@@ -347 +347 @@ True if the current search depth is at l
-.It Ic -mmin Ar n
+.It Fl mmin Ar n
@@ -354 +354 @@ minutes.
-.It Ic -mtime Ar n
+.It Fl mtime Ar n
@@ -361 +361 @@ was started, rounded up to the next full
-.It Ic -name Ar pattern
+.It Fl name Ar pattern
@@ -367 +367 @@ which may use any of the special charact
-.It Ic -newer Ar file
+.It Fl newer Ar file
@@ -371 +371 @@ True if the current file has a more rece
-.It Ic -nogroup
+.It Fl nogroup
@@ -374 +374 @@ True if the file belongs to an unknown g
-.It Ic -nouser
+.It Fl nouser
@@ -377 +377 @@ True if the file belongs to an unknown u
-.It Ic -ok Ar utility Oo Ar argument ... Oc \&;
+.It Fl ok Ar utility Oo Ar argument ... Oc \&;
@@ -393 +393 @@ expression is false.
-.It Ic -path Ar pattern
+.It Fl path Ar pattern
@@ -427 +427 @@ Note, the first character of a symbolic
-.It Ic -print
+.It Fl print
@@ -434 +434 @@ character.
-.It Ic -print0
+.It Fl print0
@@ -442 +442 @@ option to
-.It Ic -prune
+.It Fl prune
@@ -453 +453 @@ option was specified.
-.It Ic -size Ar n Ns Op Cm c
+.It Fl size Ar n Ns Op Cm c
@@ -465 +465 @@ bytes.
-.It Ic -type Ar t
+.It Fl type Ar t
@@ -486 +486 @@ socket
-.It Ic -user Ar uname
+.It Fl user Ar uname
@@ -495 +495 @@ is treated as a user ID.
-.It Ic -xdev
+.It Fl xdev

Reply | Threaded
Open this post in threaded view
|

Re: find.1: Markup primaries with Fl not Cm for easier tags

Jason McIntyre-2
On Fri, Mar 20, 2020 at 12:12:39AM +0100, Klemens Nanni wrote:

morning.

> In both command line usage and manual output format, find's options
> and primaries behave the same, but their mdoc(7) markup is different and
> therefore causes different tag names:
>

i'm not sure what you mean by behaving the same, but essentially you
could think of options and primaries as being different (as the page
does now). so i'm not surprised. i don;t really think of -group, for
example, as being an option.

> -x (option) can be looked up with ":tx<Enter>" in the manual pager,
> whereas -amin (primary) requires ":t-amin<Enter>" including the dash.
>
> I'd like primaries to behave the same like options when it comes to tags
> in manuals, is that a reasonable expectation?
>

i'm not going to answer that, but...

> If so, diff below switches all primaries from `Cm -amin' to `Fl amin'
> markup such that their resulting tag name is "amin" not "-amin";  man's
> output stays identical.
>

you mean Ic, not Cm, right? if we do decide to do this, the diff would
have to be more comprehensive. there are are a lot of places where
primaries are discussed, which would need to be changed too (i.e. not
just list items).

note also that /-x and /-amin work pretty well, without source changes!

jmc

> Feedback? OK?
>
>
> Index: find.1
> ===================================================================
> RCS file: /cvs/src/usr.bin/find/find.1,v
> retrieving revision 1.98
> diff -u -p -U0 -r1.98 find.1
> --- find.1 2 Sep 2019 21:18:41 -0000 1.98
> +++ find.1 19 Mar 2020 22:59:33 -0000
> @@ -149 +149 @@ the last option given overrides the othe
> -.It Ic -amin Ar n
> +.It Fl amin Ar n
> @@ -156 +156 @@ minutes.
> -.It Ic -anewer Ar file
> +.It Fl anewer Ar file
> @@ -160 +160 @@ True if the current file has a more rece
> -.It Ic -atime Ar n
> +.It Fl atime Ar n
> @@ -167 +167 @@ was started, rounded up to the next full
> -.It Ic -cmin Ar n
> +.It Fl cmin Ar n
> @@ -175 +175 @@ minutes.
> -.It Ic -cnewer Ar file
> +.It Fl cnewer Ar file
> @@ -179 +179 @@ True if the current file has a more rece
> -.It Ic -ctime Ar n
> +.It Fl ctime Ar n
> @@ -187 +187 @@ was started, rounded up to the next full
> -.It Ic -delete
> +.It Fl delete
> @@ -205 +205 @@ Following symlinks is incompatible with
> -.It Ic -depth
> +.It Fl depth
> @@ -211 +211 @@ option.
> -.It Ic -empty
> +.It Fl empty
> @@ -214,2 +214,2 @@ True if the current file or directory is
> -.It Ic -exec Ar utility Oo Ar argument ... Oc \&;
> -.It Ic -exec Ar utility Oo Ar argument ... Oc {} +
> +.It Fl exec Ar utility Oo Ar argument ... Oc \&;
> +.It Fl exec Ar utility Oo Ar argument ... Oc {} +
> @@ -256 +256 @@ does not exceed
> -.It Ic -execdir Ar utility Oo Ar argument ... Oc \&;
> +.It Fl execdir Ar utility Oo Ar argument ... Oc \&;
> @@ -284 +284 @@ flags specified exactly match those of t
> -.It Ic -follow
> +.It Fl follow
> @@ -290 +290 @@ option.
> -.It Ic -fstype Ar type
> +.It Fl fstype Ar type
> @@ -303 +303 @@ mounted read-only.
> -.It Ic -group Ar gname
> +.It Fl group Ar gname
> @@ -312 +312 @@ is treated as a group ID.
> -.It Ic -iname Ar pattern
> +.It Fl iname Ar pattern
> @@ -317 +317 @@ primary except that the matching is done
> -.It Ic -inum Ar n
> +.It Fl inum Ar n
> @@ -321 +321 @@ True if the file has inode number
> -.It Ic -links Ar n
> +.It Fl links Ar n
> @@ -326 +326 @@ links.
> -.It Ic -ls
> +.It Fl ls
> @@ -339 +339 @@ The format is identical to that produced
> -.It Ic -maxdepth Ar n
> +.It Fl maxdepth Ar n
> @@ -343 +343 @@ True if the current search depth is less
> -.It Ic -mindepth Ar n
> +.It Fl mindepth Ar n
> @@ -347 +347 @@ True if the current search depth is at l
> -.It Ic -mmin Ar n
> +.It Fl mmin Ar n
> @@ -354 +354 @@ minutes.
> -.It Ic -mtime Ar n
> +.It Fl mtime Ar n
> @@ -361 +361 @@ was started, rounded up to the next full
> -.It Ic -name Ar pattern
> +.It Fl name Ar pattern
> @@ -367 +367 @@ which may use any of the special charact
> -.It Ic -newer Ar file
> +.It Fl newer Ar file
> @@ -371 +371 @@ True if the current file has a more rece
> -.It Ic -nogroup
> +.It Fl nogroup
> @@ -374 +374 @@ True if the file belongs to an unknown g
> -.It Ic -nouser
> +.It Fl nouser
> @@ -377 +377 @@ True if the file belongs to an unknown u
> -.It Ic -ok Ar utility Oo Ar argument ... Oc \&;
> +.It Fl ok Ar utility Oo Ar argument ... Oc \&;
> @@ -393 +393 @@ expression is false.
> -.It Ic -path Ar pattern
> +.It Fl path Ar pattern
> @@ -427 +427 @@ Note, the first character of a symbolic
> -.It Ic -print
> +.It Fl print
> @@ -434 +434 @@ character.
> -.It Ic -print0
> +.It Fl print0
> @@ -442 +442 @@ option to
> -.It Ic -prune
> +.It Fl prune
> @@ -453 +453 @@ option was specified.
> -.It Ic -size Ar n Ns Op Cm c
> +.It Fl size Ar n Ns Op Cm c
> @@ -465 +465 @@ bytes.
> -.It Ic -type Ar t
> +.It Fl type Ar t
> @@ -486 +486 @@ socket
> -.It Ic -user Ar uname
> +.It Fl user Ar uname
> @@ -495 +495 @@ is treated as a user ID.
> -.It Ic -xdev
> +.It Fl xdev
>

Reply | Threaded
Open this post in threaded view
|

Re: find.1: Markup primaries with Fl not Cm for easier tags

Ingo Schwarze
In reply to this post by Klemens Nanni-2
Hi Klemens,

Klemens Nanni wrote on Fri, Mar 20, 2020 at 12:12:39AM +0100:

> In both command line usage and manual output format, find's options
> and primaries behave the same,

Not really.  In the POSIX sense, options are indeed options while
primaries are arguments.  That has implications, for example that
all options must precede all primaries.

> but their mdoc(7) markup is different

I don't feel very strongly about that, but i think .Cm does make
slightly more sense for primaries than .Fl (and .Ic is probably
acceptable, too, even though .Cm might be better because these are
command line arguments, not stand-alone commands).

> and therefore causes different tag names:
>
> -x (option) can be looked up with ":tx<Enter>" in the manual pager,
> whereas -amin (primary) requires ":t-amin<Enter>" including the dash.
>
> I'd like primaries to behave the same like options when it comes to
> tags in manuals, is that a reasonable expectation?

I think that is reasonable, yes.  I think it makes sense to consider
tags as words, i.e. strings that usually consist of letters and may
sometimes contain digits, but never contain whitespace and usually
do not start with punctuation characters.  I'm not sure this rule of
thumb can be made very strict, but i think it is possible to polish
this by handling a small number of common cases.  For example,
automatic tagging in man(7) already discards leading whitespace,
some escape sequences, and leading dashes from tags.  Automatic
tagging in mdoc(7) already discards leading zero-width spaces
and leading backslashes.  I think it would make sense to also
skip leading dashes here, see the patch below.

Do you agree with that?

Yours,
  Ingo


Index: tag.c
===================================================================
RCS file: /cvs/src/usr.bin/mandoc/tag.c,v
retrieving revision 1.29
diff -u -p -r1.29 tag.c
--- tag.c 13 Mar 2020 16:14:14 -0000 1.29
+++ tag.c 20 Mar 2020 15:50:33 -0000
@@ -87,8 +87,24 @@ tag_put(const char *s, int prio, struct
  if (n->child == NULL || n->child->type != ROFFT_TEXT)
  return;
  s = n->child->string;
- if (s[0] == '\\' && (s[1] == '&' || s[1] == 'e'))
- s += 2;
+ switch (s[0]) {
+ case '-':
+ s++;
+ break;
+ case '\\':
+ switch (s[1]) {
+ case '&':
+ case '-':
+ case 'e':
+ s += 2;
+ break;
+ default:
+ break;
+ }
+ break;
+ default:
+ break;
+ }
  }
 
  /*

Reply | Threaded
Open this post in threaded view
|

Re: find.1: Markup primaries with Fl not Cm for easier tags

Klemens Nanni-2
On Fri, Mar 20, 2020 at 04:53:19PM +0100, Ingo Schwarze wrote:
> Not really.  In the POSIX sense, options are indeed options while
> primaries are arguments.  That has implications, for example that
> all options must precede all primaries.
Fair point.

> I don't feel very strongly about that, but i think .Cm does make
> slightly more sense for primaries than .Fl (and .Ic is probably
> acceptable, too, even though .Cm might be better because these are
> command line arguments, not stand-alone commands).
It does, however because the resulting effect is usually the same, I see
no problem in using `Fl' for primaries.

> I think that is reasonable, yes.  I think it makes sense to consider
> tags as words, i.e. strings that usually consist of letters and may
> sometimes contain digits, but never contain whitespace and usually
> do not start with punctuation characters.  I'm not sure this rule of
> thumb can be made very strict, but i think it is possible to polish
> this by handling a small number of common cases.  For example,
> automatic tagging in man(7) already discards leading whitespace,
> some escape sequences, and leading dashes from tags.  Automatic
> tagging in mdoc(7) already discards leading zero-width spaces
> and leading backslashes.  I think it would make sense to also
> skip leading dashes here, see the patch below.
>
> Do you agree with that?
Yes, I very much do.  Given the fact man(7) already works that way,
I'm happy to see mdoc(7) follow;  it seems like the right approach, my
attempt seems more of a workaround for special cases like find(1).

OK kn

Reply | Threaded
Open this post in threaded view
|

Re: find.1: Markup primaries with Fl not Cm for easier tags

Ingo Schwarze
Hi Klemens,

Klemens Nanni wrote on Sat, Mar 21, 2020 at 12:49:20AM +0100:
> On Fri, Mar 20, 2020 at 04:53:19PM +0100, Ingo Schwarze wrote:

>> I don't feel very strongly about that, but i think .Cm does make
>> slightly more sense for primaries than .Fl (and .Ic is probably
>> acceptable, too, even though .Cm might be better because these are
>> command line arguments, not stand-alone commands).

> It does, however because the resulting effect is usually the same,
> I see no problem in using `Fl' for primaries.

Yes, it wouldn't be a big deal.  It might make a difference in
unusual situations though, for example if some website would
customize .Fl and .Cm differently in mandoc.css.

>> I think that is reasonable, yes.  I think it makes sense to consider
>> tags as words, i.e. strings that usually consist of letters and may
>> sometimes contain digits, but never contain whitespace and usually
>> do not start with punctuation characters.  I'm not sure this rule of
>> thumb can be made very strict, but i think it is possible to polish
>> this by handling a small number of common cases.  For example,
>> automatic tagging in man(7) already discards leading whitespace,
>> some escape sequences, and leading dashes from tags.  Automatic
>> tagging in mdoc(7) already discards leading zero-width spaces
>> and leading backslashes.  I think it would make sense to also
>> skip leading dashes here, see the patch below.
>>
>> Do you agree with that?

> Yes, I very much do.  Given the fact man(7) already works that way,
> I'm happy to see mdoc(7) follow;  it seems like the right approach, my
> attempt seems more of a workaround for special cases like find(1).
>
> OK kn

Committed, thanks for pointing out the issue and for the feedback
on the patch.

Yours,
  Ingo