[Tcsh] tcsh.man improvements style question

[Luke Mewburn]

Hi Kimmo,

Thanks for the feedback - it's useful.

I've got a bunch of changes on the branch:
	https://github.com/lukem/tcsh/tree/lukem/man-improvements
which include:
- fix mandoc(1) warnings.
- improve rendering to PDF and HTML.
- add tcsh.html target using mandoc.
- the proposals earlier in the thread.

I'll wait a day or so before submitting a pull request (maybe with a fresh
rebased branch without the merge syncs from master).


For the "History word designators" table, I experimented with
duplicating part of the table for the !^ (etc) abbreviation,
and instead decided that a third column in the existing table
worked:

     The basic word designators are, with columns for a leading ‘:’ and a
     leading ‘!’ (for the abbreviated word designators - see below):

           :0             The first (command) word.
           :n             The nth argument.
           :^      !^     The first argument, equivalent to ‘:1’.
           :$      !$     The last argument.


I also added more clarity to the history variations (e.g, different ways of
rewriting 'diff'), at the expense of a few more words and paragraphs,
This helps now that the history stuff is over multiple sub-sections.

Previous:
     Selected words are inserted into the command line separated by single
     blanks.  For example, the ‘diff’ command in the previous example might
     have been typed as ‘diff !!:1.old !!:1’ (using ‘:1’ to select the first
     argument from the previous event) or ‘diff !-2:2 !-2:1’ to select and
     swap the arguments from the ‘cp’ command.  If we didn't care about the
     order of the ‘diff’ we might have said ‘diff !-2:1-2’ or simply ‘diff
     !-2:*’.  The ‘cp’ command might have been written ‘cp wumpus.man
     !#:1.old’, using ‘#’ to refer to the current event.

New:
     Selected words are inserted into the command line separated by single
     blanks.

     For example, the ‘diff’ command (event 12) in the history list example in
     History event specification,
           diff wumpus.man.old wumpus.man
     might have been typed as
           diff !!:1.old !!:1
     (using ‘:1’ to select the first argument from the previous event) or
           diff !-2:2 !-2:1
     to select and swap the arguments from the ‘cp’ command (event 10).  If we
     didn't care about the order of the ‘diff’ we might have typed
           diff !-2:1-2
     or simply
           diff !-2:*


regards,
Luke.



On 22-12-05 13:51, Kimmo Suominen wrote:
  | Hi Luke,
  | 
  | A history reference may have a word designator but no event
  | specification. Thus the history word designators table entries can be
  | preceded by either a colon or an exclamation point. (With the possible
  | exception of !% not making sense... I'm not sure.) So users searching
  | for e.g. :$ would be happy, but those searching for !$ would not be.
  | 
  | The last two paragraphs of the "History word designators" section are
  | somewhat difficult to follow to begin with. Turning them into a table
  | might help, at the cost of replicating the existing table in that
  | section.
  | 
  | Or how about adding a column to the existing table to show e.g. both
  | :$ and !$ with an explanation for the columns?
  | 
  | In any case, I think it is a good improvement. Just trying to think
  | about how to fix one more use case. :)
  | 
  | Cheers,
  | + Kimmo
  | 
  | On Sat, 3 Dec 2022 at 11:34, Luke Mewburn <luke at mewburn.net> wrote:
  | >
  | > 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