[Tcsh] tcsh.man improvements style question

[Vlad Meșco]

Le 3 décembre 2022 11:34:33 GMT+02:00, Luke Mewburn <luke at mewburn.net> a écrit :
>Hi tcsh list,
>
>I've made various improvements to tcsh.man over the last couple of
>weeks, including finishing the mandoc / mdoc conversion, and improving
>the overall markup when rendered as ASCII, UTF-8 or postscript/PDF.
>
>Recently I made some more improvements including adding more subsection
>headers to (hopefully) make it easier to find documentation:
>	History event specification
>	History word designators
>	History word modifiers
>	History abbreviation
>	History editor commands
>	Variable substitution metasequences
>	Variable substitution without modifiers
>
>These are in commit 06dab61 in pull request https://github.com/tcsh-org/tcsh/pull/62
>
>
>As a followup to that, I was considering some more changes which I think
>may make searching for certain items easier (IMHO), but may be
>controversial so I wanted to solicit input from Christos, Kimmo, and the
>tcsh community.
>
>Currently, there are various lists of items, and I would like to explicitly
>prefix the item with the selector, so it's easier to search.
>
>E.g, prefix all the history word modifiers with ':' so you can search for ':h'
>instead of the more generic 'h'.
>
>
>History event specification
>
>   existing:
>           n      A number, referring to a particular event.
>           -n     An offset, referring to the event n before the current
>                  event.
>           #      The current event.  This should be used carefully in csh(1),
>                  where there is no check for recursion.  tcsh allows 10 lev‐
>                  els of recursion. (+)
>
>
>   proposal - prefix with !:
>           !n     A number, referring to a particular event.
>           !-n    An offset, referring to the event n before the current
>                  event.
>           !#     The current event.  This should be used carefully in csh(1),
>                  where there is no check for recursion.  tcsh allows 10 lev‐
>                  els of recursion. (+)
>
>
>History word designators
>
>   existing:
>           0     The first (command) word.
>           n     The nth argument.
>           ^     The first argument, equivalent to ‘1’.
>
>   proposal - prefix with :
>           :0    The first (command) word.
>           :n    The nth argument.
>           :^    The first argument, equivalent to ‘1’.
>
>
>History word modifiers
>
>   existing:
>           h       Remove a trailing pathname component, leaving the head.
>           t       Remove all leading pathname components, leaving the tail.
>           r       Remove a filename extension ‘.xxx’, leaving the root name.
>
>   proposal - prefix with : (and probably sort)
>           :h      Remove a trailing pathname component, leaving the head.
>           :t      Remove all leading pathname components, leaving the tail.
>           :r      Remove a filename extension ‘.xxx’, leaving the root name.
>
>
>File inquiry operators
>
>   existing:
>           r    Read access.
>           w    Write access.
>           x    Execute access.
>
>   proposal - prefix with - and probably sort:
>           -r   Read access.
>           -w   Write access.
>           -x   Execute access.
>
>
>
>thoughts?
>
>
>Luke.
>-- 
>Tcsh mailing list
>Tcsh at astron.com
>https://mailman.astron.com/mailman/listinfo/tcsh

My two cents: I like the idea. 10 years ago I extracted those sections into a cheat sheet, or searched for /^\s*g\>/. But that was only to find the relevant section.

The question is how often are you looking for an explanation of :h rather than "what are all the modifiers again?" Someone could -like me- search for :q or !! to find the modifiers or history subtitution sections, or they could search for headings or they could scroll through the man page (in which case shorter=better) or something else. It's more a problem of discoverability than of anchors. 

On the other hand, you'd search for :x if you found a snippet on the internet/build system at work and you want to know what that does (in which case /:x/ getting you to the relevant section helps a lot).

FWIW bash's and zsh's pages don't have them prefixed; and both of them are so long it's hard to even find the lists.

Cheers,
Vlad