Hi Klemens and Jason, Jason McIntyre wrote on Wed, Apr 05, 2023 at 07:12:05PM +0100: > On Wed, Apr 05, 2023 at 01:07:18PM +0000, Klemens Nanni wrote:
>> To find out what a particular letter means, you must arrive at this list >> why generic means because the first column has no markup. >> >> As mdoc(7) 'constant symbol' the lookup is much quicker, e.g. >> man -Otag=h route >> makes this the first line in the pager: >> M RTF_MODIFIED Modified dynamically (by redirect). > tag=h? is that a typo? > > anyway, i personally am not convinced that anyone would do this. I use "-O tag" occasionally, in particular with very long and complex manual pages (and route(8) is complex and somewhat long), and i know Klemens uses it often. Since implementing -O tag, i occasionally also got feedback from others who like it, though there are certainly many people who do not use it. On top of that, the feature is very useful when providing user support for sending web links like https://man.openbsd.org/route.8#show which points to the same place as $ man -O tag=show route > i mean, it is easier just to type "man route" then page down. That works, too, but can become tedious in long and complex pages. > is the added complexity really worth it? The complexity feels minimal to me, it does nothing more than formally announcing that these flags serve a syntactic purpose, exactly like we already do it for the RTF_* flags on the same lines. While the .Dv macro is not a perfect fit, i agree with Klemens that it is the best one available. > we must have a ton of pages with lists explaining flags. I see no need to hunt down similar cases in the tree, but when people get annoyed with specific pages, i think it's fair to add tags if it's logically sound and easily possible. There is one very minor gotcha with short tags like these. With Klemens' patch, try $ man -l -O tag=n route.8 which brings you to the -n command line option; then hit the "t" key once: it brings you to the RTF_CONNECTED ("n") flag... So short tags tend to clash with unrelated stuff marked up with different macros, in this case .Fl and .Dv. But that's not a game-breaker. In a long and complex page, ":t n<ENTER>t" may still be simpler than searching visually. I refrained from making the tagging feature more complex and supporting stuff like "-O tag=Dv=n" vs. "-O tag=Fl=n", and i don't think that was a mistake. Such clashes are not *that* common, so KISS. > like > man -Otag=D ps > that doesn;t work either. Probably wouldn't hurt either to make that work, but seems neither urgent nor required to make Klemens' patch useful. >> Route flags that now produce an already existing tag don't conflict, i.e. >> ":tT" first shows >> -T rtable >> Select an alternate routing table to modify or query. The >> and then on second "t" >> T RTF_MPLS MPLS route. Oops, right, you found that too. >> OK? FWIW, i'm OK with this patch. >> Index: route.8 >> =================================================================== >> RCS file: /cvs/src/sbin/route/route.8,v >> retrieving revision 1.117 >> diff -u -p -r1.117 route.8 >> --- route.8 18 Mar 2023 11:44:53 -0000 1.117 >> +++ route.8 5 Apr 2023 12:56:12 -0000 >> @@ -401,27 +401,27 @@ Within the output of >> the "Flags" column indicates what flags are set on the route. >> The mapping between letters and flags is: >> .Bl -column "1" "RTF_BLACKHOLE" "Protocol specific routing flag #1." >> -.It 1 Ta Dv RTF_PROTO1 Ta "Protocol specific routing flag #1." >> -.It 2 Ta Dv RTF_PROTO2 Ta "Protocol specific routing flag #2." >> -.It 3 Ta Dv RTF_PROTO3 Ta "Protocol specific routing flag #3." >> -.It B Ta Dv RTF_BLACKHOLE Ta "Just discard packets." >> -.It b Ta Dv RTF_BROADCAST Ta "Correspond to a local broadcast address." >> -.It C Ta Dv RTF_CLONING Ta "Generate new routes on use." >> -.It c Ta Dv RTF_CLONED Ta "Cloned routes (generated from RTF_CLONING)." >> -.It D Ta Dv RTF_DYNAMIC Ta "Created dynamically (by redirect)." >> -.It G Ta Dv RTF_GATEWAY Ta "Dest requires forwarding by intermediary." >> -.It H Ta Dv RTF_HOST Ta "Host entry (net otherwise)." >> -.It h Ta Dv RTF_CACHED Ta "Referenced by gateway route." >> -.It L Ta Dv RTF_LLINFO Ta "Valid protocol to link address translation." >> -.It l Ta Dv RTF_LOCAL Ta "Correspond to a local address." >> -.It M Ta Dv RTF_MODIFIED Ta "Modified dynamically (by redirect)." >> -.It m Ta Dv RTF_MULTICAST Ta "Correspond to a multicast address." >> -.It n Ta Dv RTF_CONNECTED Ta "Interface route." >> -.It P Ta Dv RTF_MPATH Ta "Multipath route." >> -.It R Ta Dv RTF_REJECT Ta "Host or net unreachable." >> -.It S Ta Dv RTF_STATIC Ta "Manually added." >> -.It T Ta Dv RTF_MPLS Ta "MPLS route." >> -.It U Ta Dv RTF_UP Ta "Route usable." >> +.It Dv 1 Ta Dv RTF_PROTO1 Ta "Protocol specific routing flag #1." >> +.It Dv 2 Ta Dv RTF_PROTO2 Ta "Protocol specific routing flag #2." >> +.It Dv 3 Ta Dv RTF_PROTO3 Ta "Protocol specific routing flag #3." >> +.It Dv B Ta Dv RTF_BLACKHOLE Ta "Just discard packets." >> +.It Dv b Ta Dv RTF_BROADCAST Ta "Correspond to a local broadcast address." >> +.It Dv C Ta Dv RTF_CLONING Ta "Generate new routes on use." >> +.It Dv c Ta Dv RTF_CLONED Ta "Cloned routes (generated from RTF_CLONING)." >> +.It Dv D Ta Dv RTF_DYNAMIC Ta "Created dynamically (by redirect)." >> +.It Dv G Ta Dv RTF_GATEWAY Ta "Dest requires forwarding by intermediary." >> +.It Dv H Ta Dv RTF_HOST Ta "Host entry (net otherwise)." >> +.It Dv h Ta Dv RTF_CACHED Ta "Referenced by gateway route." >> +.It Dv L Ta Dv RTF_LLINFO Ta "Valid protocol to link address translation." >> +.It Dv l Ta Dv RTF_LOCAL Ta "Correspond to a local address." >> +.It Dv M Ta Dv RTF_MODIFIED Ta "Modified dynamically (by redirect)." >> +.It Dv m Ta Dv RTF_MULTICAST Ta "Correspond to a multicast address." >> +.It Dv n Ta Dv RTF_CONNECTED Ta "Interface route." >> +.It Dv P Ta Dv RTF_MPATH Ta "Multipath route." >> +.It Dv R Ta Dv RTF_REJECT Ta "Host or net unreachable." >> +.It Dv S Ta Dv RTF_STATIC Ta "Manually added." >> +.It Dv T Ta Dv RTF_MPLS Ta "MPLS route." >> +.It Dv U Ta Dv RTF_UP Ta "Route usable." >> .El >> .Pp >> .It Xo
