Re: Missing action list in lesskey man page
On Tue, Dec 07, 2021 at 07:51:31PM +0100, Richard Ulmer wrote: > Hi Ingo and Theo, > thanks for sharing your opinions and thanks for the very thorough > response, Ingo! I learned a few things while reading it and appreciate > your suggested patch. I especially like the introduced bullet points and > find they make the man page easier to read. > > "Theo de Raadt" wrote: > > Ingo Schwarze wrote: > > > > > >> I'd much prefer to have > > > >> the actions explained in the lesskey(1) man page. > > > > > > No way. Copying half of the less(1) manual to the lesskey(1) manual > > > would result in a maintenance nightmare. > > > > I agree. This is not the first time one has to read two related pages > > to gain understanding, rather than reading one monster combined or > > duplicated page -- which can muddle up other learning patterns. > > I understand your concerns and think I might had made up my mind a > little to quickly. Let me take one step back: I thought something was > missing from the man page, because I initially thought, that lesskey was > meant to provide ways to extend less. I thought, that it would allow > me to bind shell scripts to keys or something similar. Now that I'm a > little more familiar with lesskey, I can see that this assumption was > wrong. > > lesskey is only meant to change the default key bindings. If I > understood this earlier on, it would probably have saved me the > confusion. Maybe the purpose of lesskey could be clarified a bit more in > the man page. What do you think? > > Greetings, > Richard Ulmer > > Index: lesskey.1 > === > RCS file: /cvs/src/usr.bin/less/lesskey.1,v > retrieving revision 1.17 > diff -u -p -u -r1.17 lesskey.1 > --- lesskey.1 7 Dec 2021 13:26:49 - 1.17 > +++ lesskey.1 7 Dec 2021 18:49:26 - > @@ -27,7 +27,7 @@ > .Os > .Sh NAME > .Nm lesskey > -.Nd specify key bindings for less > +.Nd customize key bindings for less > .Sh SYNOPSIS > .Nm lesskey > .Oo Fl o Ar output > @@ -37,8 +37,8 @@ > .Fl V | -version > .Sh DESCRIPTION > .Nm > -is used to specify a set of key bindings to be used by > -.Xr less 1 . > +is used to change the default key bindings of > +.Xr less 1 to match personal preference. > The input file is a text file which describes the key bindings. > If the input file is > .Sq - , > hi. i committed your diff, with one adjustment: i omitted the "to match personal preference" text since i didn;t like how it sounded, nor felt that it added anything. thanks for the diff, jmc
Re: Missing action list in lesskey man page
Ingo Schwarze wrote: > >> I'd much prefer to have > >> the actions explained in the lesskey(1) man page. > > No way. Copying half of the less(1) manual to the lesskey(1) manual > would result in a maintenance nightmare. I agree. This is not the first time one has to read two related pages to gain understanding, rather than reading one monster combined or duplicated page -- which can muddle up other learning patterns. > >>> however we still import less. i'd want to make sure that's > >>> not stepping on anyone's toes to make local changes. > > We forked the "less" program and made many extensive changes. > I think we are free to improve the documentation as we see fit. The main reason there was little pushback against forking less is because upstream releases were changing features regularily and we wanted to get off that train. We want a simpler program that does what it is supposed to do, doesn't adopt new features every 3 months, with a couple keystrokes changing behaviours and messing with people's heads. > >> I could also suggest changes upstream. > > If people want, they can forward relevant patches to Illumos, > which has a code base somewhat similar to ours. Forwarding patches > to Mark Nudelman is harder; i would expect many merge conflicts. > Then again, if anybody wants to spend time helping Mark, there is > certainly nothing wrong with that. I think this latter sentence is where the problem comes from -- it is a piece of software gathering features like a rolling stone. Here let me throw a turd in front of it's path
Re: Missing action list in lesskey man page
Hi Jason and Richard, Jason McIntyre wrote on Sat, Dec 04, 2021 at 09:18:56PM +: > On Sat, Dec 04, 2021 at 07:11:01PM +0100, Richard Ulmer wrote: >> jmc@ wrote: >>> 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. >> 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' I don't think those should be documented. The only purpose action names can be used for is for lesskey(1). So having aliases helps noone. Besides, this stuff is already overcomplicated, overengineered, and full of feature creep without aliases, so documenting aliases would only exacerbate the mess. >> - 'debug' is an entirely undocumented action I grepped the usr.bin/less source directory for A_DEBUG and it appears to be unused. So i conclude "debug" does nothing and should not be documented. >> - 'forw-skip' is an entirely undocumented action That's apparently used if and only if less_is_more. The 's' key behaves differently in more(1) than in less(1). According to command.c, in more(1), it does this: /* * Skip ahead one screen, and then number lines. */ That's madness because the point of more(1) is compatibility, not featurism. Probably, the 's' key ought to be deleted from more(1), it is undocumented in the more(1) manual page anyway. Documenting it in lesskey(1) would seem wrong to me. >> - 'shell' appears in the lesskey(1) man page but does not work Good catch, deleting that was forgotten when deleting the '!' command from less(1) - which was done for security reasons. >> I'd much prefer to have >> the actions explained in the lesskey(1) man page. No way. Copying half of the less(1) manual to the lesskey(1) manual would result in a maintenance nightmare. What matters most is that the less(1) manual is correct, complete, and as readable as possible - even though the latter is hard to achieve given all the feature creep. The lesskey(1) manual page is secondary to that, documenting something that is almost entirely feature creep and not very well-designed on top of that. We can try to make it correct, complete, and readable to as far as possible, but the following two mistakes must be avoided: 1. Let's not make less(1) harder to read by refering to lesskey(1). 2. Let's not make lesskey(1) harder to maintain by usurping part of the purpose of the less(1) manual. >> Doing this still >> doesn't explain everything; e.g. this still confuses me: On the one hand, that's a consequence of less(1) being so overcomplicated; it's unavoidably hard to understand. On the other hand, wording of the manual could be improved in many places for precision and clarity. >> 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". Because the 's' action does the same as the less(1) -o command line option. After pressing the 's' key in less(1), you get a prompt where you can type the name of the log file you want to create. That file name you type is used in the same way as the .Fl o Ar logfile option argument which you could have provided on the command line when you started less(1). >>> we could maybe make this clearer: >>> >>> #command >>> \r forw-line >>> ... >>> >>> to sth like this: >>> >>> #command action >>> \r forw-line >>> ... I don't like that too much. From code inspection, it appears that control lines like "#command" ignore trailing garbage, and that implementation detail could maybe be exploited to sneak in comments. But that is undocumented, so relying on it in the documentation feels confusing. >> I'd prefer a separate list where each action is described with a little >> more detail, than just having the example. It's not an example; it documents the default key bindings and the action names. What the actions do is subject matter for less(1), not for lesskey(1). >>> however we still import less. i'd want to make sure that's >>> not stepping on anyone's toes to make local changes. We forked the "less" program and made many extensive changes. I think we are free to improve the documentation as we see fit. >> 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, No doubt less(1) documentation can be improved regarding man
Re: Missing action list in lesskey man page
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
Re: Missing action list in lesskey man page
On 2021-12-04 12:39:41+, Jason McIntyre wrote: > On Sat, Dec 04, 2021 at 12:19:34PM +0100, Richard Ulmer wrote: > > Hi all, > > I've been reading up on "advanced" less(1) features and came across the > > lesskey(1) man page. In the COMMAND SECTION of the page I read this: > > > > > The action is the name of the less action, from the list below. > > > > However I cannot see this list of available actions. The only thing > > similar I can find is the list of default commands with their actions. > > From this I can deduce some available actions, but I'm not sure if those > > are all the available actions. Maybe there are some actions that are not > > bound by default. I'm also missing a description of what the actions do > > (I don't know all the default less(1) commands off the cuff). > > > > Is the action list missing from the lesskey(1) man page, or am I > > misunderstanding something? > 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. the actions will roughly match those described in the > less(1) COMMANDS section. so for example in less(1): > [] > > however we still import less. i'd want to make sure that's not stepping > on anyone's toes to make local changes. Pls forgive if I'm missing the important points, but in a way, maybe it is implied by man lesskey that the actions are connected with the command list shown. On ~ line 56-57 (under COMMAND SECTION) it says "The string is the command key(s) which invoke the action", which is easy to miss. Then there follows a list of commands, and one can search the man pages (with /) for everything that mentions "command", type "h" within less, etc. I find I have to do kind of thing that often to get a better idea of things, if one idea is mentioned in one part (or man page) then I need to go read other parts (or pages) that discuss the same thing; I even made a couple of scripts or aliases that quicken the process for me.
Re: Missing action list in lesskey man page
On Sat, Dec 04, 2021 at 12:19:34PM +0100, Richard Ulmer wrote: > Hi all, > I've been reading up on "advanced" less(1) features and came across the > lesskey(1) man page. In the COMMAND SECTION of the page I read this: > > > The action is the name of the less action, from the list below. > > However I cannot see this list of available actions. The only thing > similar I can find is the list of default commands with their actions. > From this I can deduce some available actions, but I'm not sure if those > are all the available actions. Maybe there are some actions that are not > bound by default. I'm also missing a description of what the actions do > (I don't know all the default less(1) commands off the cuff). > > Is the action list missing from the lesskey(1) man page, or am I > misunderstanding something? > > Greetings, > Richard Ulmer > 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. 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 so leskey gives you the action names (if you want to change them), and less describes what these actions do. we could maybe make this clearer: #command \r forw-line ... to sth like this: #command action \r forw-line ... however we still import less. i'd want to make sure that's not stepping on anyone's toes to make local changes. jmc
