Re: A feasible method to add examples to man pages?
On 06/22/2021 02:21 AM, Curt wrote: On 2021-06-22, Greg Wooledge wrote: On Mon, Jun 21, 2021 at 11:50:22PM +0100, Brian wrote: On Mon 21 Jun 2021 at 15:25:53 -0500, Richard Owlett wrote: On 06/21/2021 02:36 PM, Curt wrote: curl https://cht.sh/:cht.sh > ~/bin/cht.sh chmod +x ~/bin/cht.sh cht.sh --standalone-install I don't understand what those 3 lines are attempting to do. What should I be reading? curl(1) bash(1) (Redirection) chmod(1) less ~/bin/cht.sh Just for the record, there should be a mkdir -p ~/bin in there as well. And one might need to log out and back in to get ~/bin into one's PATH, depending on how one's dot files are set up. (Manual modification of PATH is also acceptable.) That's what I get for blindly copying and pasting the "directions" from Github. I should've have just told Monnier that the whole shebang can be installed locally, which renders inoperative his nitpick about not having the Net when he needs to cheat the most (or most often). FYI It may be "operator error", but I get a "Could not install python dependencies into the virtual environment" ERROR when trying to install on Debian 10.7. The install.log is 6.6kB of messages I don't have the background to interpret. A side effect is destruction of the ability to consistently edit Profile Preferences. {perhaps also operator error}. I'll not pursue further.
Re: A feasible method to add examples to man pages?
On Tuesday, June 22, 2021 12:16:19 PM Stefan Monnier wrote: > > That's what I get for blindly copying and pasting the "directions" from > > Github. I should've have just told Monnier that the whole shebang > > can be installed locally, which renders inoperative his nitpick about > > not having the Net when he needs to cheat the most (or most often). > > The difference is that the manpages get installed automatically along > with the software, so they're always there, always uptodate, without me > having to think about it beforehand, without having to choose where to > install them, nor remember where I installed them. > > Don't get me wrong: all it means is that I think we want to keep *some* > examples in the manpages. IOW, I was just pointing out that the main > benefit of manpages is that they're local and work in almost all > situations. They don't need to contain all the info you'll ever want to > know, but I usually welcome a few examples in there ;-) Eventually those extra examples for the man pages could become a local, automatically installed thing, similiar to the man pages -- there might be a command analogous to man, but instead exam[ple] (or similar, or wiki), invoked like: exam ls exam tar etc.
Re: A feasible method to add examples to man pages?
> That's what I get for blindly copying and pasting the "directions" from > Github. I should've have just told Monnier that the whole shebang > can be installed locally, which renders inoperative his nitpick about > not having the Net when he needs to cheat the most (or most often). The difference is that the manpages get installed automatically along with the software, so they're always there, always uptodate, without me having to think about it beforehand, without having to choose where to install them, nor remember where I installed them. Don't get me wrong: all it means is that I think we want to keep *some* examples in the manpages. IOW, I was just pointing out that the main benefit of manpages is that they're local and work in almost all situations. They don't need to contain all the info you'll ever want to know, but I usually welcome a few examples in there ;-) Stefan
Re: A feasible method to add examples to man pages?
On Tue 22 Jun 2021 at 05:54:19 -0500, Richard Owlett wrote: > On 06/22/2021 02:21 AM, Curt wrote: > > On 2021-06-22, Greg Wooledge wrote: > > > On Mon, Jun 21, 2021 at 11:50:22PM +0100, Brian wrote: > > > > On Mon 21 Jun 2021 at 15:25:53 -0500, Richard Owlett wrote: > > > > > > > > > On 06/21/2021 02:36 PM, Curt wrote: > > > > > >curl https://cht.sh/:cht.sh > ~/bin/cht.sh > ^ > | > +-- I don't understand that use of : A search with "url with colon" is suggested. Conclusions are welcomed. It hasn't anything to do with curl. -- Brian.
Re: A feasible method to add examples to man pages?
On 2021-06-22, Richard Owlett wrote: > Unfortunately it outputs light gray text on white background which is > near impossible for me to read. I Can't figure out how to COERCE MATE > Terminal to render everything as black on white. That is a showstopper > for me. Yeah, maybe you're trying to coerce the wrong thingamajig. 'curl cht.sh/ls?style=bw' works for me. Then again 'curl cht.sh/ls\?T' works equally well. Other styles here: curl cht.sh/:styles
Re: A feasible method to add examples to man pages?
On Ma, 22 iun 21, 05:54:19, Richard Owlett wrote: > > If ~/bin needs to be created, will logging out then in _guarantee_ it gets > added to my path? That doesn't sound normal. There is no guarantee :) On buster /etc/skel/.profile includes the following snippets # set PATH so it includes user's private bin if it exists if [ -d "$HOME/bin" ] ; then PATH="$HOME/bin:$PATH" fi # set PATH so it includes user's private bin if it exists if [ -d "$HOME/.local/bin" ] ; then PATH="$HOME/.local/bin:$PATH" fi /etc/skel/.profile should be copied to the home directory of every new user (at least if created by the installer or with adduser). Whether your shell and/or login method actually leads to sourcing ~/.profile is a completely different question and depends on: 1. Login method (Linux console, ssh, display manager, etc.) 2. How you start your X session (if applicable and not taken care of by a display manager) 3. Terminal emulator (if in a graphical environment) 4. Shell in use and its configuration > Is there a Debian specific article on when to use which ...\bin directory in > $PATH and when/how to permanently add an additional directory. Not that I'm aware of. On the other hand the ~/.local/bin snippet was added recently (buster?) and makes sense for those who prefer the XDG directories over traditional dotfiles in $HOME. Kind regards, Andrei -- http://wiki.debian.org/FAQsFromDebianUser signature.asc Description: PGP signature
Re: A feasible method to add examples to man pages?
On 06/22/2021 07:59 AM, Curt wrote: On 2021-06-22, Richard Owlett wrote: I got multiple warning messages including a missing dependency and warning that my Python was too old. I'm in process of installing Debian 10.7 on another machine. I'll try again this afternoon or tomorrow. Thanks. Too old is surprising because it uses python 2 by default, but also will work with python 3 after a tiny, documented modification of the script ("curl cheat.sh/:cht.sh | less" told me all about it). I also read that 1G of local disk space is required. Good luck. The warning said that Python 3.5 was no longer being supported. I fortunately have lots of disk room and it apparently runs correctly. Unfortunately it outputs light gray text on white background which is near impossible for me to read. I Can't figure out how to COERCE MATE Terminal to render everything as black on white. That is a showstopper for me.
Re: A feasible method to add examples to man pages?
On 2021-06-22, Richard Owlett wrote: > > I got multiple warning messages including a missing dependency and > warning that my Python was too old. I'm in process of installing > Debian 10.7 on another machine. I'll try again this afternoon or tomorrow. > Thanks. Too old is surprising because it uses python 2 by default, but also will work with python 3 after a tiny, documented modification of the script ("curl cheat.sh/:cht.sh | less" told me all about it). I also read that 1G of local disk space is required. Good luck.
Re: A feasible method to add examples to man pages?
On 06/22/2021 06:43 AM, Curt wrote: On 2021-06-22, Richard Owlett wrote: On 06/22/2021 02:21 AM, Curt wrote: On 2021-06-22, Greg Wooledge wrote: On Mon, Jun 21, 2021 at 11:50:22PM +0100, Brian wrote: On Mon 21 Jun 2021 at 15:25:53 -0500, Richard Owlett wrote: On 06/21/2021 02:36 PM, Curt wrote: curl https://cht.sh/:cht.sh > ~/bin/cht.sh ^ | +-- I don't understand that use of : It's the syntax for "special pages." Regular usage: curl cheat.sh/TOPIC show cheat sheet on the TOPIC Special pages: :help help page :list list all cheat sheets :post how to post new cheat sheet :cht.sh shell client (cht.sh) etc. So curl cheat.sh/:help I have Debian 9.13 installed As root I did curl https://cht.sh/:cht.sh > /usr/bin/cht.sh chmod +x /usr/bin/cht.sh Then as normal user did cht.sh --standalone-install I got multiple warning messages including a missing dependency and warning that my Python was too old. I'm in process of installing Debian 10.7 on another machine. I'll try again this afternoon or tomorrow. Thanks.
Re: A feasible method to add examples to man pages?
On 2021-06-22, Richard Owlett wrote: > On 06/22/2021 02:21 AM, Curt wrote: >> On 2021-06-22, Greg Wooledge wrote: >>> On Mon, Jun 21, 2021 at 11:50:22PM +0100, Brian wrote: On Mon 21 Jun 2021 at 15:25:53 -0500, Richard Owlett wrote: > On 06/21/2021 02:36 PM, Curt wrote: >>curl https://cht.sh/:cht.sh > ~/bin/cht.sh > ^ > | > +-- I don't understand that use of : > It's the syntax for "special pages." Regular usage: curl cheat.sh/TOPIC show cheat sheet on the TOPIC Special pages: :help help page :list list all cheat sheets :post how to post new cheat sheet :cht.sh shell client (cht.sh) etc. So curl cheat.sh/:help
Re: A feasible method to add examples to man pages?
On 06/22/2021 02:21 AM, Curt wrote: On 2021-06-22, Greg Wooledge wrote: On Mon, Jun 21, 2021 at 11:50:22PM +0100, Brian wrote: On Mon 21 Jun 2021 at 15:25:53 -0500, Richard Owlett wrote: On 06/21/2021 02:36 PM, Curt wrote: curl https://cht.sh/:cht.sh > ~/bin/cht.sh ^ | +-- I don't understand that use of : chmod +x ~/bin/cht.sh cht.sh --standalone-install q.v. https://github.com/chubin/cheat.sh/blob/master/doc/standalone.md I don't understand what those 3 lines are attempting to do. What should I be reading? curl(1) bash(1) (Redirection) chmod(1) less ~/bin/cht.sh Just for the record, there should be a mkdir -p ~/bin in there as well. That was part of what threw me. I didn't think to check if ~/bin existed. And one might need to log out and back in to get ~/bin into one's PATH, depending on how one's dot files are set up. (Manual modification of PATH is also acceptable.) If ~/bin needs to be created, will logging out then in _guarantee_ it gets added to my path? That doesn't sound normal. Is there a Debian specific article on when to use which ...\bin directory in $PATH and when/how to permanently add an additional directory. That's what I get for blindly copying and pasting the "directions" from Github. I should've have just told Monnier that the whole shebang can be installed locally, which renders inoperative his nitpick about not having the Net when he needs to cheat the most (or most often).
Re: A feasible method to add examples to man pages?
On 2021-06-22, Greg Wooledge wrote: > On Mon, Jun 21, 2021 at 11:50:22PM +0100, Brian wrote: >> On Mon 21 Jun 2021 at 15:25:53 -0500, Richard Owlett wrote: >> >> > On 06/21/2021 02:36 PM, Curt wrote: >> > > curl https://cht.sh/:cht.sh > ~/bin/cht.sh >> > > chmod +x ~/bin/cht.sh >> > > cht.sh --standalone-install >> > >> > I don't understand what those 3 lines are attempting to do. >> > What should I be reading? >> >> curl(1) >> bash(1) (Redirection) >> chmod(1) >> less ~/bin/cht.sh > > Just for the record, there should be a mkdir -p ~/bin in there as > well. And one might need to log out and back in to get ~/bin into > one's PATH, depending on how one's dot files are set up. (Manual > modification of PATH is also acceptable.) That's what I get for blindly copying and pasting the "directions" from Github. I should've have just told Monnier that the whole shebang can be installed locally, which renders inoperative his nitpick about not having the Net when he needs to cheat the most (or most often).
Re: A feasible method to add examples to man pages?
On Mon, Jun 21, 2021 at 11:50:22PM +0100, Brian wrote: > On Mon 21 Jun 2021 at 15:25:53 -0500, Richard Owlett wrote: > > > On 06/21/2021 02:36 PM, Curt wrote: > > > curl https://cht.sh/:cht.sh > ~/bin/cht.sh > > > chmod +x ~/bin/cht.sh > > > cht.sh --standalone-install > > > > I don't understand what those 3 lines are attempting to do. > > What should I be reading? > > curl(1) > bash(1) (Redirection) > chmod(1) > less ~/bin/cht.sh Just for the record, there should be a mkdir -p ~/bin in there as well. And one might need to log out and back in to get ~/bin into one's PATH, depending on how one's dot files are set up. (Manual modification of PATH is also acceptable.)
Re: A feasible method to add examples to man pages?
On Mon 21 Jun 2021 at 15:25:53 -0500, Richard Owlett wrote: > On 06/21/2021 02:36 PM, Curt wrote: > > On 2021-06-21, Stefan Monnier wrote: > > > > Many see the need for examples to be associated with man pages. > > > [...] > > > > Would it be proper/reasonable/practical/??? to add an entry of the form > > > > https://cht.sh/XXX ? > > > > > > I think it can make sense for manpages to include a link to some further > > > doc in the form of a wiki or some other webpage, but I often enough find > > > myself using `man` while trying to fix a system's network or X11/Wayland > > > config, which makes it either impossible to access the Internet at that > > > moment, or painful to browse a webpage. > > > > curl https://cht.sh/:cht.sh > ~/bin/cht.sh > > chmod +x ~/bin/cht.sh > > cht.sh --standalone-install > > > > I don't understand what those 3 lines are attempting to do. > What should I be reading? curl(1) bash(1) (Redirection) chmod(1) less ~/bin/cht.sh -- Brian.
Re: A feasible method to add examples to man pages?
On 06/21/2021 02:36 PM, Curt wrote: On 2021-06-21, Stefan Monnier wrote: Many see the need for examples to be associated with man pages. [...] Would it be proper/reasonable/practical/??? to add an entry of the form https://cht.sh/XXX ? I think it can make sense for manpages to include a link to some further doc in the form of a wiki or some other webpage, but I often enough find myself using `man` while trying to fix a system's network or X11/Wayland config, which makes it either impossible to access the Internet at that moment, or painful to browse a webpage. curl https://cht.sh/:cht.sh > ~/bin/cht.sh chmod +x ~/bin/cht.sh cht.sh --standalone-install I don't understand what those 3 lines are attempting to do. What should I be reading? TIA
Re: A feasible method to add examples to man pages?
> Many see the need for examples to be associated with man pages. [...] > Would it be proper/reasonable/practical/??? to add an entry of the form > https://cht.sh/XXX ? I think it can make sense for manpages to include a link to some further doc in the form of a wiki or some other webpage, but I often enough find myself using `man` while trying to fix a system's network or X11/Wayland config, which makes it either impossible to access the Internet at that moment, or painful to browse a webpage. Stefan
Re: A feasible method to add examples to man pages?
On 2021-06-21, Stefan Monnier wrote: >> Many see the need for examples to be associated with man pages. > [...] >> Would it be proper/reasonable/practical/??? to add an entry of the form >> https://cht.sh/XXX ? > > I think it can make sense for manpages to include a link to some further > doc in the form of a wiki or some other webpage, but I often enough find > myself using `man` while trying to fix a system's network or X11/Wayland > config, which makes it either impossible to access the Internet at that > moment, or painful to browse a webpage. curl https://cht.sh/:cht.sh > ~/bin/cht.sh chmod +x ~/bin/cht.sh cht.sh --standalone-install > > Stefan
Re: A feasible method to add examples to man pages?
On 21.06.21 17:29, Richard Owlett wrote: Many see the need for examples to be associated with man pages. Sometime back a post mentioned a web page that could return examples for most(all??) Linux commands. I failed to bookmark it and have not rediscovered it since. In another forum I was pointed to https://cht.sh/ . Going to https://cht.sh/XXX will return a list of examples for XXX. Along the right side of each page of /manpages.debian.org/... there is a list of links to various topics. Would it be proper/reasonable/practical/??? to add an entry of the form https://cht.sh/XXX ? Comments? TIA For displaying examples I am using the tldr command provided by package "tldr". This client's web page is here: https://github.com/psibi/tldr-hs#readme The general tldr site is here: https://tldr.sh/ There are also several web pages which search and display the information from the tldr examples collection, like this one: https://tldr.ostera.io/ The project invites to participate by adding examples to its collection. Following for years the upcoming discussions about the wish to enhance man pages by adding examples to it but confronting the situation that man pages are usually maintained by the package maintainers and not all of them are in favor of adding examples to the man pages, I think that the normal users are best served by supporting as a community an examples collection like the above mentioned tldr project. Just my view as a user. Marco.
Re: A feasible method to add examples to man pages?
On 06/21/2021 11:49 AM, Nate Bargmann wrote: * On 2021 21 Jun 10:30 -0500, Richard Owlett wrote: Many see the need for examples to be associated with man pages. My name is among the authors of a few man pages found in the Debian archive with regard to some software used primarily by radio amateurs. Part of the issue is how many examples are enough and how many are too much. I landed at the point of providing enough for the curious to get a sense of the options and how to provide them for programs. Mostly this was aimed at those more familiar with GUI programs not programs that take command line options. Manual pages that focus on library API calls have yet another challenge for providing examples. The Linux Man Pages Project seems to do a good job in sections 2 (system calls) and 3 (C library calls) with concise and useful examples and should probably serve as an example for other authors to follow, IMO. Sometime back a post mentioned a web page that could return examples for most(all??) Linux commands. I failed to bookmark it and have not rediscovered it since. That may have been me. Here is an example: $ curl cheat.sh/curl The cheat.sh site is not mine and I have no relation to it. In another forum I was pointed to https://cht.sh/ . Going to https://cht.sh/XXX will return a list of examples for XXX. It is the same site only through the Web interface. IIRC the page I saw was neither chat.sh nor cht.sh . Right now both seem to have long response times. I may have local hardware issues as some purely local operations have strange delays. Along the right side of each page of /manpages.debian.org/... there is a list of links to various topics. Would it be proper/reasonable/practical/??? to add an entry of the form https://cht.sh/XXX ? That question would be better posed to the Debian Web site team than here. I asked here as the subject had been raised here and I wanted feed back from people had raised the issue. As to discussing its implementation I was leaning to raising it on debian-doc rather than debian-www.
Re: A feasible method to add examples to man pages?
* On 2021 21 Jun 10:30 -0500, Richard Owlett wrote: > Many see the need for examples to be associated with man pages. My name is among the authors of a few man pages found in the Debian archive with regard to some software used primarily by radio amateurs. Part of the issue is how many examples are enough and how many are too much. I landed at the point of providing enough for the curious to get a sense of the options and how to provide them for programs. Mostly this was aimed at those more familiar with GUI programs not programs that take command line options. Manual pages that focus on library API calls have yet another challenge for providing examples. The Linux Man Pages Project seems to do a good job in sections 2 (system calls) and 3 (C library calls) with concise and useful examples and should probably serve as an example for other authors to follow, IMO. > Sometime back a post mentioned a web page that could return examples for > most(all??) Linux commands. I failed to bookmark it and have not > rediscovered it since. That may have been me. Here is an example: $ curl cheat.sh/curl The cheat.sh site is not mine and I have no relation to it. > In another forum I was pointed to https://cht.sh/ . > Going to https://cht.sh/XXX will return a list of examples for XXX. It is the same site only through the Web interface. > Along the right side of each page of /manpages.debian.org/... there is a > list of links to various topics. > > Would it be proper/reasonable/practical/??? to add an entry of the form > https://cht.sh/XXX ? That question would be better posed to the Debian Web site team than here. - Nate -- "The optimist proclaims that we live in the best of all possible worlds. The pessimist fears this is true." Web: https://www.n0nb.us Projects: https://github.com/N0NB GPG fingerprint: 82D6 4F6B 0E67 CD41 F689 BBA6 FB2C 5130 D55A 8819 signature.asc Description: PGP signature
Re: A feasible method to add examples to man pages?
On 06/21/2021 10:29 AM, Richard Owlett wrote: Many see the need for examples to be associated with man pages. Sometime back a post mentioned a web page that could return examples for most(all??) Linux commands. I failed to bookmark it and have not rediscovered it since. In another forum I was pointed to https://cht.sh/ . Going to https://cht.sh/XXX will return a list of examples for XXX. Along the right side of each page of /manpages.debian.org/... there is a list of links to various topics. Would it be proper/reasonable/practical/??? to add an entry of the form https://cht.sh/XXX ? Comments? TIA I just checked. That page does not explicitly address Greg Wooledge's comment[1] in another thread about handling one command with conflicting implementations. [e.g. "parallel"] [1] https://lists.debian.org/debian-user/2021/06/msg00496.html