Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.debian.user > #236241 > unrolled thread

A feasible method to add examples to man pages?

Back to article view | Back to linux.debian.user

Contents

  A feasible method to add examples to man pages? Richard Owlett <rowlett@cloud85.net> - 2021-06-21 17:30 +0200
    Re: A feasible method to add examples to man pages? Richard Owlett <rowlett@cloud85.net> - 2021-06-21 17:50 +0200
    Re: A feasible method to add examples to man pages? Stefan Monnier <monnier@iro.umontreal.ca> - 2021-06-21 18:20 +0200
      Re: A feasible method to add examples to man pages? Curt <curty@free.fr> - 2021-06-21 22:00 +0200
        Re: A feasible method to add examples to man pages? Richard Owlett <rowlett@cloud85.net> - 2021-06-21 22:30 +0200
          Re: A feasible method to add examples to man pages? Brian <ad44@cityscape.co.uk> - 2021-06-22 01:00 +0200
            Re: A feasible method to add examples to man pages? Greg Wooledge <greg@wooledge.org> - 2021-06-22 03:10 +0200
              Re: A feasible method to add examples to man pages? Curt <curty@free.fr> - 2021-06-22 09:50 +0200
                Re: A feasible method to add examples to man pages? Richard Owlett <rowlett@cloud85.net> - 2021-06-22 13:00 +0200
                  Re: A feasible method to add examples to man pages? Curt <curty@free.fr> - 2021-06-22 14:10 +0200
                    Re: A feasible method to add examples to man pages? Richard Owlett <rowlett@cloud85.net> - 2021-06-22 14:40 +0200
                      Re: A feasible method to add examples to man pages? Curt <curty@free.fr> - 2021-06-22 15:20 +0200
                        Re: A feasible method to add examples to man pages? Richard Owlett <rowlett@cloud85.net> - 2021-06-22 15:50 +0200
                          Re: A feasible method to add examples to man pages? Curt <curty@free.fr> - 2021-06-22 16:40 +0200
                  Re: A feasible method to add examples to man pages? Andrei POPESCU <andreimpopescu@gmail.com> - 2021-06-22 16:30 +0200
                  Re: A feasible method to add examples to man pages? Brian <ad44@cityscape.co.uk> - 2021-06-22 18:20 +0200
                Re: A feasible method to add examples to man pages? Stefan Monnier <monnier@iro.umontreal.ca> - 2021-06-22 18:20 +0200
                  Re: A feasible method to add examples to man pages? rhkramer@gmail.com - 2021-06-23 13:20 +0200
                Re: A feasible method to add examples to man pages? Richard Owlett <rowlett@cloud85.net> - 2021-06-23 21:40 +0200
    Re: A feasible method to add examples to man pages? Nate Bargmann <n0nb@n0nb.us> - 2021-06-21 19:00 +0200
      Re: A feasible method to add examples to man pages? Richard Owlett <rowlett@cloud85.net> - 2021-06-21 20:30 +0200
    Re: A feasible method to add examples to man pages? Marco Möller <talby@debianlists.mobilxpress.net> - 2021-06-21 20:50 +0200

Page 1 of 2  [1] 2  Next page →

#236241 — A feasible method to add examples to man pages?

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

[toc] | [next] | [standalone]

#236242

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

[toc] | [prev] | [next] | [standalone]

#236243

> 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

[toc] | [prev] | [next] | [standalone]

#236250

On 2021-06-21, Stefan Monnier <monnier@iro.umontreal.ca> 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

[toc] | [prev] | [next] | [standalone]

#236251

On 06/21/2021 02:36 PM, Curt wrote:
> On 2021-06-21, Stefan Monnier <monnier@iro.umontreal.ca> 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

[toc] | [prev] | [next] | [standalone]

#236254

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 <monnier@iro.umontreal.ca> 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.

[toc] | [prev] | [next] | [standalone]

#236256

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.)

[toc] | [prev] | [next] | [standalone]

#236260

On 2021-06-22, Greg Wooledge <greg@wooledge.org> 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). 

[toc] | [prev] | [next] | [standalone]

#236268

On 06/22/2021 02:21 AM, Curt wrote:
> On 2021-06-22, Greg Wooledge <greg@wooledge.org> 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).
> 

[toc] | [prev] | [next] | [standalone]

#236274

On 2021-06-22, Richard Owlett <rowlett@cloud85.net> wrote:
> On 06/22/2021 02:21 AM, Curt wrote:
>> On 2021-06-22, Greg Wooledge <greg@wooledge.org> 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

[toc] | [prev] | [next] | [standalone]

#236275

On 06/22/2021 06:43 AM, Curt wrote:
> On 2021-06-22, Richard Owlett <rowlett@cloud85.net> wrote:
>> On 06/22/2021 02:21 AM, Curt wrote:
>>> On 2021-06-22, Greg Wooledge <greg@wooledge.org> 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.

[toc] | [prev] | [next] | [standalone]

#236277

On 2021-06-22, Richard Owlett <rowlett@cloud85.net> 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.

[toc] | [prev] | [next] | [standalone]

#236284

On 06/22/2021 07:59 AM, Curt wrote:
> On 2021-06-22, Richard Owlett <rowlett@cloud85.net> 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.

[toc] | [prev] | [next] | [standalone]

#236295

On 2021-06-22, Richard Owlett <rowlett@cloud85.net> 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

[toc] | [prev] | [next] | [standalone]

#236289

[Multipart message — attachments visible in raw view] — view raw

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

[toc] | [prev] | [next] | [standalone]

#236307

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 <greg@wooledge.org> 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.

[toc] | [prev] | [next] | [standalone]

#236308

> 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

[toc] | [prev] | [next] | [standalone]

#236348

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.

[toc] | [prev] | [next] | [standalone]

#236386

On 06/22/2021 02:21 AM, Curt wrote:
> On 2021-06-22, Greg Wooledge <greg@wooledge.org> 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.

[toc] | [prev] | [next] | [standalone]

#236245

[Multipart message — attachments visible in raw view] — view raw

* 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

[toc] | [prev] | [next] | [standalone]

Page 1 of 2  [1] 2  Next page →

Back to top | Article view | linux.debian.user

csiph-web