On Sat, Dec 04, 2021 at 07:11:01PM +0100, Richard Ulmer wrote:
> Hi Jason,
> Thanks for you response!
>
hi!
> > the actions do indeed match those in the command list. whether there are
> > any undocumented ones, i don;t know. i suppose you'd have to go poking
> > in the source.
>
> IMO users shouldn't have to go to the source code to compensate for
> lacking documentation.
>
right. but someone at some point has to do the work if there is an
issue. so by "you'd have to go poking" i really meant with a view to
improving the page, rather than "all users should read the source to find this out".
> Out of curiosity I did take a peek at the source and found this that
> there are indeed undocumented actions:
> - 'display-flag' is an undocumented alias for 'display-option'
> - 'end' is an undocumented alias for 'goto-end'
> - 'first-cmd' is an undocumented alias for 'firstcmd'
> - 'flush-repaint' is an undocumented alias for 'repaint-flush'
> - 'toggle-flag' is an undocumented alias for 'toggle-option'
> - 'debug' is an entirely undocumented action
> - 'forw-skip' is an entirely undocumented action
> - 'shell' appears in the lesskey(1) man page but does not work
>
right. so if someone writes it up, future readers will not have to go
poking. alternatively, there may a reason they are undocumented.
> > the actions will roughly match those described in the
> > less(1) COMMANDS section. so for example in less(1):
> >
> > d | ^D
> > Scroll forward n lines ...
> >
> > and in lesskey(1):
> >
> > d forw-scroll
> > ^D forw-scroll
>
> Doing this seems unnecessarily tedious to me. I'd much prefer to have
> the actions explained in the lesskey(1) man page. Doing this still
> doesn't explain everything; e.g. this still confuses me:
>
> s toggle-option o
>
> translates to
>
> s filename
> Save the input to a file. This only works if the input is a pipe,
> not an ordinary file.
>
it confuses me too! i have no idea why they have used "toggle-option".
but you can easily correlate "s" in lesskey with the documented "s" command
in less.
> > we could maybe make this clearer:
> >
> > #command
> > \r forw-line
> > ...
> >
> > to sth like this:
> >
> > #command action
> > \r forw-line
> > ...
>
> I'd prefer a separate list where each action is described with a little
> more detail, than just having the example.
>
> > however we still import less. i'd want to make sure that's not stepping
> > on anyone's toes to make local changes.
>
> I wanted to hear some second opinions first and make sure, that I didn't
> miss anything. If I still think the documentation is lacking after that,
> I could also suggest changes upstream.
well you can file a bug report i suppose. but you could also look at how
to improve things, write a diff, and submit it upstream. you will
probably have a better chance if you do some of the work.
jmc
No comments:
Post a Comment