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

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

A Proposal: Each of Debian Man pages could have a wiki (Main page / Talk Page, etc.) at its bottom, with only Example Code Lines ...

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

Contents

  A Proposal: Each of Debian Man pages could have a wiki (Main page /  Talk Page, etc.) at its bottom, with only Example Code Lines ... "Susmita/Rajib" <bkpsusmitaa@gmail.com> - 2021-06-17 08:30 +0200
    Re: A Proposal: Each of Debian Man pages could have a wiki (Main  page / Talk Page, etc.) at its bottom, with only Example Code Lines ... Jonathan Dowland <jon+debian-user@dow.land> - 2021-06-17 11:40 +0200
    Re: A Proposal: Each of Debian Man pages could have a wiki (Main page  / Talk Page, etc.) at its bottom, with only Example Code Lines ... "Susmita/Rajib" <bkpsusmitaa@gmail.com> - 2021-06-17 14:50 +0200
      Re: A Proposal: Each of Debian Man pages could have a wiki (Main  page / Talk Page, etc.) at its bottom, with only Example Code Lines ... David Wright <deblis@lionunicorn.co.uk> - 2021-06-18 06:30 +0200

#236174 — A Proposal: Each of Debian Man pages could have a wiki (Main page / Talk Page, etc.) at its bottom, with only Example Code Lines ...

 ... for most complex combinations of codes, with a single line or two of
explanations, if at all necessary.

A talk page requesting explanations, or for recording innovative code lines.

Infrastructure and resource already exist. Just minor alterations
required. Community work could help.

A follow up on the earlier Thread:
Whether Man pages could visually be structured in an abstract form to
be understood easier
https://lists.debian.org/debian-user/2021/04/msg00552.html

The illustrative, but incomplete Mind Map:
bit.ly/Apt_readingManPages

Debian Online Man Pages available at: https://manpages.debian.org/

Best
Rajib
Etc.

[toc] | [next] | [standalone]

#236177 — Re: A Proposal: Each of Debian Man pages could have a wiki (Main page / Talk Page, etc.) at its bottom, with only Example Code Lines ...

On Thu, Jun 17, 2021 at 11:37:07AM +0530, Susmita/Rajib wrote:
> ... for most complex combinations of codes, with a single line or two of
>explanations, if at all necessary.

I think there's a lot of potential for tying together documentation
shipped inside Debian (including manpages) better with documentation
outside (including the wiki).

However, as with all things in Debian, things are best achieved by doing
them yourself; or at least, beginning to, so that there's a concrete
example to explore.

In this case, there are at least two hurdles to overcome, neither of
which should be insurmountable:

1) The source of most man pages in Debian is the upstream packages
    themselves. Therefore, to include a Debian-specific addition in
    every manpage, Debian package maintainers will need to carry
    patches for every man page. For some packages, especially those
    which don't already apply any patches, this is some overhead that
    a busy maintainer may not wish for.

2) The Debian Wiki has an unclear copyright situation. The content of
    wiki pages is not necessarily compatible with the Debian Free
    Software Guidelines (DFSG), and so Wiki content cannot be included
    in Debian packages without further checks. (This is something I've
    been trying to resolve for literally a decade or more, on and off.
    Mostly off.)

A good place to start would be finding a single package/program/manpage
that would benefit from linking out to a wiki page, and doing so, in
order to demonstrate the concept clearly.


-- 
Please do not CC me for listmail.

👱🏻	Jonathan Dowland
✎	 jmtd@debian.org
🔗	https://jmtd.net

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

#236180 — Re: A Proposal: Each of Debian Man pages could have a wiki (Main page / Talk Page, etc.) at its bottom, with only Example Code Lines ...

On Thu, 17 Jun 2021 10:37:43 +0100, Jonathan Dowland
<jon+debian-user@dow.land> wrote:
[...]
>     Message-id: <[🔎] 20210617093743.v3t2nyw2si2luoif@coil>
>     In-reply-to: <[🔎]
> CAEG4cZW1-rWJvF2hMACwigqU4JuQfm66R5XWKKz7FTMrfZhHew@mail.gmail.com>
>     References: <[🔎]
> CAEG4cZW1-rWJvF2hMACwigqU4JuQfm66R5XWKKz7FTMrfZhHew@mail.gmail.com>
>
[...]
Ref. https://lists.debian.org/debian-user/2021/06/msg00435.html
[...]
> However, as with all things in Debian, things are best achieved by doing
> them yourself; or at least, beginning to, so that there's a concrete
> example to explore.
>
> In this case, there are at least two hurdles to overcome, neither of
> which should be insurmountable:
>
> 1) The source ... upstream packages
>    themselves. Therefore, ... package maintainers will need to carry
>    patches for every man page...
>
> 2) The Debian Wiki has an unclear copyright ... Wiki content cannot be included...
>
> A good place to start would be finding a single package/program/manpage
> that would benefit from linking out to a wiki page, and doing so, in
> order to demonstrate the concept clearly.
[...]


Thank you for posting to this thread, Mr. Dowland. As a member of the
team Debian, you must really be hard-pressed for time.

So in brief, fully self-illustrative:
https://lists.debian.org/debian-user/2021/03/msg01358.html

In the end, the illustrative, but incomplete Mind Map:
bit.ly/Apt_readingManPages

Best,
Rajib
Etc.

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

#236189 — Re: A Proposal: Each of Debian Man pages could have a wiki (Main page / Talk Page, etc.) at its bottom, with only Example Code Lines ...

On Thu 17 Jun 2021 at 18:01:55 (+0530), Susmita/Rajib wrote:
> On Thu, 17 Jun 2021 10:37:43 +0100, Jonathan Dowland

> > However, as with all things in Debian, things are best achieved by doing
> > them yourself; or at least, beginning to, so that there's a concrete
> > example to explore.
> >
> > In this case, there are at least two hurdles to overcome, neither of
> > which should be insurmountable:
> >
> > 1) The source ... upstream packages
> >    themselves. Therefore, ... package maintainers will need to carry
> >    patches for every man page...
> >
> > 2) The Debian Wiki has an unclear copyright ... Wiki content cannot be included...
> >
> > A good place to start would be finding a single package/program/manpage
> > that would benefit from linking out to a wiki page, and doing so, in
> > order to demonstrate the concept clearly.
> [...]
> 
> So in brief, fully self-illustrative:
> https://lists.debian.org/debian-user/2021/03/msg01358.html
> 
> In the end, the illustrative, but incomplete Mind Map:
> bit.ly/Apt_readingManPages

I looked back at that post, which I have already replied to
in general terms (msg01366.html); this reply is more specific
on just one point.

You used as an example a comparison between   man ls
and several texts:

https://medium.com/@isaac_70614/the-ls-command-and-wildcard-7fff5a4f7f24
https://www.oreilly.com/library/view/learning-the-unix/1565923901/ch04s03.html
https://www.tecmint.com/use-wildcards-to-match-filenames-in-linux/
https://www.cyberciti.biz/faq/grep-regular-expressions/

Leaving aside the fourth¹ of these, you seem to have missed the point
that the texts are *teaching* wildcards, and the reason that all
three texts chose to use the ls command to illustrate the results is
that ls conveniently displays the matching filenames on the console.

The expansion of the wildcards is being done by the shell, not ls.
The shell would perform the same expansion for whatever command
were used, but most commands would operate on those files *without*
printing their names, which would not be very useful for teaching.

So comparing the texts with   man ls   is meaningless: the latter
deals with the options and exit codes provided by ls.

Where you should look for a meaningful comparison is   man bash, and
in particular, the section EXPANSION, subsection Pathname Expansion,
subsubsection Pattern Matching. In making your comparison, bear in
mind that the texts are didactic, whereas   man bash   is only an
aide-memoire. For example, someone might use ls for years and not
remember how to sort the output by extension (-X), but you wouldn't
read through a book just for that. You'd consult the man page.

¹ The fourth text looks as though the reference just slipped in
  accidentally from your next example. The patterns used by grep
  are very different.

Cheers,
David.

[toc] | [prev] | [standalone]

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

csiph-web