Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]
Groups > linux.debian.user > #174795 > unrolled thread
| Started by | Richard Owlett <rowlett@cloud85.net> |
|---|---|
| First post | 2016-11-16 15:20 +0100 |
| Last post | 2016-11-22 13:30 +0100 |
| Articles | 20 on this page of 117 — 32 participants |
Back to article view | Back to linux.debian.user
Why? -- "A Modest Proposal" Richard Owlett <rowlett@cloud85.net> - 2016-11-16 15:20 +0100
Re: Why? -- "A Modest Proposal" Lisi Reisz <lisi.reisz@gmail.com> - 2016-11-16 16:00 +0100
Re: Why? -- "A Modest Proposal" Jonathan Dowland <jmtd@debian.org> - 2016-11-16 16:20 +0100
Re: Why? -- "A Modest Proposal" Lisi Reisz <lisi.reisz@gmail.com> - 2016-11-16 19:40 +0100
Re: Why? -- "A Modest Proposal" Jonathan Dowland <jmtd@debian.org> - 2016-11-17 13:20 +0100
Re: Why? -- "A Modest Proposal" Lisi Reisz <lisi.reisz@gmail.com> - 2016-11-17 15:30 +0100
Re: Why? -- "A Modest Proposal" Jonathan Dowland <jmtd@debian.org> - 2016-11-17 15:50 +0100
Re: Why? -- "A Modest Proposal" Richard Owlett <rowlett@cloud85.net> - 2016-11-17 15:50 +0100
Re: Why? -- "A Modest Proposal" Lisi Reisz <lisi.reisz@gmail.com> - 2016-11-17 17:40 +0100
Re: Why? -- "A Modest Proposal" Curt <curty@free.fr> - 2016-11-17 18:10 +0100
Re: Why? -- "A Modest Proposal" kamaraju kusumanchi <raju.mailinglists@gmail.com> - 2016-11-22 06:40 +0100
Re: Why? -- "A Modest Proposal" <tomas@tuxteam.de> - 2016-11-16 16:40 +0100
Re: Why? -- "A Modest Proposal" Richard Owlett <rowlett@cloud85.net> - 2016-11-17 16:00 +0100
Re: Why? -- "A Modest Proposal" "John L. Ries" <jries@salford-systems.com> - 2016-11-17 19:00 +0100
Re: Why? -- "A Modest Proposal" Greg Wooledge <wooledg@eeg.ccf.org> - 2016-11-17 22:40 +0100
Re: Why? -- "A Modest Proposal" <tomas@tuxteam.de> - 2016-11-17 22:40 +0100
Re: Why? -- "A Modest Proposal" rhkramer@gmail.com - 2016-11-18 00:10 +0100
Re: Why? -- "A Modest Proposal" <tomas@tuxteam.de> - 2016-11-17 22:30 +0100
Re: Why? -- "A Modest Proposal" Greg Wooledge <wooledg@eeg.ccf.org> - 2016-11-17 22:40 +0100
Re: Why? -- "A Modest Proposal" <tomas@tuxteam.de> - 2016-11-17 22:40 +0100
Re: Why? -- "A Modest Proposal" Greg Wooledge <wooledg@eeg.ccf.org> - 2016-11-17 23:00 +0100
Re: Why? -- "A Modest Proposal" Reco <recoverym4n@gmail.com> - 2016-11-18 09:20 +0100
Re: Why? -- "A Modest Proposal" rhkramer@gmail.com - 2016-11-18 00:10 +0100
Re: Why? -- "A Modest Proposal" emetib <chadbrabec@gmail.com> - 2016-11-18 09:50 +0100
Re: Why? -- "A Modest Proposal" <tomas@tuxteam.de> - 2016-11-18 10:40 +0100
Re: Why? -- "A Modest Proposal" "Thomas Schmitt" <scdbackup@gmx.net> - 2016-11-18 11:10 +0100
Re: Why? -- "A Modest Proposal" emetib <chadbrabec@gmail.com> - 2016-11-18 20:30 +0100
Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") cbannister@slingshot.co.nz - 2016-12-29 15:10 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2016-12-29 19:10 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2016-12-29 19:10 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Catherine Gramze <rhiamom@gmail.com> - 2016-12-29 19:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2016-12-29 19:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2016-12-29 19:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Catherine Gramze <rhiamom@gmail.com> - 2016-12-29 19:50 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2016-12-30 02:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") rhkramer@gmail.com - 2016-12-30 03:30 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Lisi Reisz <lisi.reisz@gmail.com> - 2016-12-30 03:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Greg Wooledge <wooledg@eeg.ccf.org> - 2016-12-30 15:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Dan Purgert <dan@djph.net> - 2016-12-30 18:00 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Dan Purgert <dan@djph.net> - 2016-12-30 15:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") rhkramer@gmail.com - 2016-12-30 15:50 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") rhkramer@gmail.com - 2016-12-30 15:50 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Lisi Reisz <lisi.reisz@gmail.com> - 2016-12-30 16:00 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") John Hasler <jhasler@newsguy.com> - 2016-12-30 17:20 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2016-12-31 08:30 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2016-12-31 09:50 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Lisi Reisz <lisi.reisz@gmail.com> - 2016-12-31 10:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Catherine Gramze <rhiamom@gmail.com> - 2016-12-31 17:20 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2017-01-01 13:00 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2017-01-01 13:20 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2017-01-01 14:00 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Nemeth Gyorgy <friczy@freemail.hu> - 2016-12-31 10:40 +0100
Re: Do have programs have poor documentation? "Thomas Schmitt" <scdbackup@gmx.net> - 2016-12-31 12:00 +0100
Re: Do have programs have poor documentation? Xen <list@xenhideout.nl> - 2017-01-01 12:40 +0100
Re: Do have programs have poor documentation? "Thomas Schmitt" <scdbackup@gmx.net> - 2017-01-01 14:10 +0100
Re: Do have programs have poor documentation? Xen <list@xenhideout.nl> - 2017-01-01 19:10 +0100
Re: Do have programs have poor documentation? "Thomas Schmitt" <scdbackup@gmx.net> - 2017-01-01 20:50 +0100
Re: Do have programs have poor documentation? Gene Heskett <gheskett@shentel.net> - 2017-01-01 15:10 +0100
Re: Do have programs have poor documentation? "Thomas Schmitt" <scdbackup@gmx.net> - 2017-01-01 20:50 +0100
Re: Do have programs have poor documentation? Gene Heskett <gheskett@shentel.net> - 2017-01-02 02:10 +0100
Re: Do have programs have poor documentation? Lisi Reisz <lisi.reisz@gmail.com> - 2017-01-02 02:30 +0100
Re: Do have programs have poor documentation? David Wright <deblis@lionunicorn.co.uk> - 2017-01-02 16:00 +0100
Re: Do have programs have poor documentation? rhkramer@gmail.com - 2017-01-02 17:30 +0100
Re: Do have programs have poor documentation? David Wright <deblis@lionunicorn.co.uk> - 2017-01-02 18:20 +0100
Re: Do have programs have poor documentation? rhkramer@gmail.com - 2017-01-02 18:50 +0100
Re: Do have programs have poor documentation? Eike Lantzsch <zp6cge@gmx.net> - 2017-01-01 18:00 +0100
Re: Do have programs have poor documentation? Xen <list@xenhideout.nl> - 2017-01-01 19:30 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") rhkramer@gmail.com - 2016-12-31 15:20 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2017-01-01 12:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") David Wright <deblis@lionunicorn.co.uk> - 2017-01-02 15:50 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") rhkramer@gmail.com - 2017-01-02 17:20 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") David Wright <deblis@lionunicorn.co.uk> - 2017-01-02 18:10 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") rhkramer@gmail.com - 2017-01-02 18:50 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Jörg-Volker Peetz <jvpeetz@web.de> - 2017-01-02 19:10 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2016-12-30 02:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Lisi Reisz <lisi.reisz@gmail.com> - 2016-12-30 03:30 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") deloptes <deloptes@gmail.com> - 2016-12-30 18:30 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Dan Purgert <dan@djph.net> - 2017-01-01 12:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Nicolas George <george@nsup.org> - 2017-01-01 12:50 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") deloptes <deloptes@gmail.com> - 2017-01-01 14:10 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Nicolas George <george@nsup.org> - 2017-01-01 15:10 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") deloptes <deloptes@gmail.com> - 2017-01-01 16:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Nicolas George <george@nsup.org> - 2017-01-01 17:20 +0100
[OT] on education [was]: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") deloptes <deloptes@gmail.com> - 2017-01-01 20:40 +0100
Re: [OT] on education [was]: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Nicolas George <george@nsup.org> - 2017-01-01 23:50 +0100
Re: [OT] on education [was]: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Joel Rees <joel.rees@gmail.com> - 2017-01-02 01:30 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Rob van der Putten <rob@sput.nl> - 2017-03-12 17:50 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2016-12-31 08:30 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Lisi Reisz <lisi.reisz@gmail.com> - 2016-12-31 10:30 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2017-01-01 13:00 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Lisi Reisz <lisi.reisz@gmail.com> - 2017-01-01 13:00 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2017-01-01 13:30 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") deloptes <deloptes@gmail.com> - 2017-01-01 14:20 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2017-01-01 18:00 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <xen@dds.nl> - 2017-01-01 20:10 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Bob Holtzman <holtzm@cox.net> - 2017-01-02 20:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") cbannister@slingshot.co.nz - 2017-03-11 10:00 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Martin Read <zen75502@zen.co.uk> - 2017-03-11 12:50 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") deloptes <deloptes@gmail.com> - 2017-03-11 14:30 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Doug <dmcgarrett@optonline.net> - 2017-03-11 19:30 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Dan Purgert <dan@djph.net> - 2017-03-13 13:10 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Catherine Gramze <rhiamom@gmail.com> - 2016-12-30 04:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Xen <list@xenhideout.nl> - 2016-12-31 08:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Lisi Reisz <lisi.reisz@gmail.com> - 2016-12-30 12:40 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Richard Owlett <rowlett@cloud85.net> - 2016-12-30 13:30 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Dan Purgert <dan@djph.net> - 2016-12-30 15:50 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") rhkramer@gmail.com - 2016-12-30 15:50 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") deloptes <deloptes@gmail.com> - 2016-12-30 20:50 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Lisi Reisz <lisi.reisz@gmail.com> - 2016-12-31 00:20 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") deloptes <deloptes@gmail.com> - 2016-12-31 01:10 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Lisi Reisz <lisi.reisz@gmail.com> - 2016-12-31 01:50 +0100
[OT] Antikythera mechanism [was Re: Do have programs have poor documentation?] Miles Fidelman <mfidelman@meetinghouse.net> - 2016-12-31 03:20 +0100
Re: [OT] Antikythera mechanism [was Re: Do have programs have poor documentation?] deloptes <deloptes@gmail.com> - 2016-12-31 10:20 +0100
Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") Rob van der Putten <rob@sput.nl> - 2017-03-11 22:50 +0100
Re: Why? -- "A Modest Proposal" kamaraju kusumanchi <raju.mailinglists@gmail.com> - 2016-11-22 07:10 +0100
Re: Why? -- "A Modest Proposal" Darac Marjal <mailinglist@darac.org.uk> - 2016-11-22 13:00 +0100
Re: Why? -- "A Modest Proposal" Richard Owlett <rowlett@cloud85.net> - 2016-11-22 13:30 +0100
Page 2 of 6 — ← Prev page 1 [2] 3 4 5 6 Next page →
| From | Greg Wooledge <wooledg@eeg.ccf.org> |
|---|---|
| Date | 2016-11-17 23:00 +0100 |
| Message-ID | <sECSS-6iy-7@gated-at.bofh.it> |
| In reply to | #174836 |
On Thu, Nov 17, 2016 at 10:37:41PM +0100, tomas@tuxteam.de wrote:
> While Gnu does prefer info format to man page format (and they have
> their reasons, e.g. info allows links), the man pages (usually derived
> from the texinfo source) are well-structured, complete and have a
> solid language. I can't agree with you in that they are "atrocious",
> barring some exceptions. De gustibus... obviously.
I concede that they have a point about how texinfo is superior to the
*roff format, for several reasons, not least of which being that *roff
is a proprietary format whose documentation is non-free. However....
tar(1) on Debian 8:
BUGS
The GNU folks, in general, abhor man pages, and create info documents
instead. Unfortunately, the info document describing tar is licensed
under the GFDL with invariant cover texts, which makes it impossible to
include any text from that document in this man page. Most of the text
in this document was automatically extracted from the usage text in the
source. It may not completely describe all features of the program.
sort(1) on Debian 8:
SEE ALSO
uniq(1)
Full documentation at: <http://www.gnu.org/software/coreutils/sort>
or available locally via: info '(coreutils) sort invocation'
ls(1) on Debian 8:
SEE ALSO
Full documentation at: <http://www.gnu.org/software/coreutils/ls>
or available locally via: info '(coreutils) ls invocation'
I could continue for some time. Each of these man pages is missing
information that appears only in the info page. The only GNU project
man page that is a complete reference document is bash(1), which is
very, very different from the other GNU man pages.
[toc] | [prev] | [next] | [standalone]
| From | Reco <recoverym4n@gmail.com> |
|---|---|
| Date | 2016-11-18 09:20 +0100 |
| Message-ID | <sEMyS-4Aj-7@gated-at.bofh.it> |
| In reply to | #174837 |
Hi. On Thu, Nov 17, 2016 at 04:50:21PM -0500, Greg Wooledge wrote: > On Thu, Nov 17, 2016 at 10:37:41PM +0100, tomas@tuxteam.de wrote: > > While Gnu does prefer info format to man page format (and they have > > their reasons, e.g. info allows links), the man pages (usually derived > > from the texinfo source) are well-structured, complete and have a > > solid language. I can't agree with you in that they are "atrocious", > > barring some exceptions. De gustibus... obviously. > > I concede that they have a point about how texinfo is superior to the > *roff format, for several reasons, not least of which being that *roff > is a proprietary format whose documentation is non-free. However.... > > tar(1) on Debian 8: > > BUGS > The GNU folks, in general, abhor man pages, and create info documents > instead. Unfortunately, the info document describing tar is licensed > under the GFDL with invariant cover texts, which makes it impossible to > include any text from that document in this man page. Most of the text > in this document was automatically extracted from the usage text in the > source. It may not completely describe all features of the program. Please don't blame GNU for Debian tar(1). The part you quoted states clearly that this particular manpage was autogenerated from tar's help and did not come from GNU. I agree with your other examples though. Reco
[toc] | [prev] | [next] | [standalone]
| From | rhkramer@gmail.com |
|---|---|
| Date | 2016-11-18 00:10 +0100 |
| Message-ID | <sEDYB-7hJ-5@gated-at.bofh.it> |
| In reply to | #174834 |
On Thursday, November 17, 2016 04:27:54 PM Greg Wooledge wrote: > The Linux man pages are good, usually. The GNU man pages are atrocious. > They even admit it, right in their man pages. They (as a project, as a > whole) *hate* man pages and only write a stub that doesn't even cover > all of the basics. Then they tell you that the real documentation is > their GNU-specific "info" page, and you have to go learn an entirely > new program for reading GNU documentation vs. every other program's > documentation. And, with some frequency, the info pages contain the exact same information as the man pages.
[toc] | [prev] | [next] | [standalone]
| From | emetib <chadbrabec@gmail.com> |
|---|---|
| Date | 2016-11-18 09:50 +0100 |
| Message-ID | <sEN1U-4K5-3@gated-at.bofh.it> |
| In reply to | #174795 |
flame war- man pages vs info pages? open source documentation vs closed source documentation? .... yes some of them need to be updated. yes there are wiki's that you can contribute to. yet as someone said, 'someone else can do it'. heard that too many times from too many people. why isn't it 'i will take an hour to update this little piece of documentation'. is it that the one's in charge of keeping the docs think that they know best and the docs are fine how they are? personally when i release code to the public, i have notes threw out to tell others what is supposed to be happening. this also helps me three years later when i look at updating it. lets me know what i was thinking at the time. how about this old one- RTFM just my two cents. (just glad that i can say that still)
[toc] | [prev] | [next] | [standalone]
| From | <tomas@tuxteam.de> |
|---|---|
| Date | 2016-11-18 10:40 +0100 |
| Message-ID | <sENOi-5fG-31@gated-at.bofh.it> |
| In reply to | #174846 |
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On Fri, Nov 18, 2016 at 12:21:56AM -0800, emetib wrote: > flame war- > man pages vs info pages? > open source documentation vs closed source documentation? Luckily, discussion seems to be pretty civilized. Far from a flame war. There are sure different opinions, but we seem to be politely listening to each other, so everyone's a chance to learn (I am). And remember: if nobody is dissatisfied, nothing will change. So no flames (or only as much as needed to keep us comfortably warm: winter's starting in the North Hemisphere, pity us ;-) thanks+regards - -- tomás -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.12 (GNU/Linux) iEYEARECAAYFAlguytEACgkQBcgs9XrR2kZSTACcCyxEqKNhNIFEKsXM3sy5ajBS hSkAmQEAQk7FRGZASZt7GJzHQXWpfv2k =uHqo -----END PGP SIGNATURE-----
[toc] | [prev] | [next] | [standalone]
| From | "Thomas Schmitt" <scdbackup@gmx.net> |
|---|---|
| Date | 2016-11-18 11:10 +0100 |
| Message-ID | <sEOhk-5Ju-13@gated-at.bofh.it> |
| In reply to | #174846 |
Hi, Greg Wooledge wrote: > The only GNU project > man page that is a complete reference document is bash(1), which is > very, very different from the other GNU man pages. There is at least one more. :)) GNU xorriso offers three man pages which have identical content as the .info documents because they stem from the same .texi files. (.texi to man is done by help of a special converter which relies on special comments in the .texi file.) ---------------------------------------------------------------------- It is not easy to describe a program with many use cases and even more particular settings and actions. What lacks to my experience as confused reader and as best effort writer is the user's view on the programs. man pages should document the details and often do sufficiently. But the user looks for solutions, not opportunities. I can give some examples, not more. Users often surprise me with unexpected views on their use case or with combinations which i never had imagined on my own. But ... emetib wrote: > why isn't it 'i will take an hour to update this little piece of > documentation'. [man page or wiki] >From the view of the developer it is not that easy. It is very demanding to document a program which one does not know on source level. Every other year i get some proposal of overhauling the man pages. But the technical knowledge behind those proposals normally does not suffice for making a correct change in there. Especially when submitters tried to get my phrasing more compliant to the usual english language they submitted statements which were flatly wrong. That's why i rather hope for a separate tutorial, which relies on the man pages for technical info, has only tested statements and examples, and is open to technical corrections by me. (No wonder nobody feels motivated to do it.) Until then i can only invite users to ask for clarifications at bug-xorriso@gnu.org. Have a nice day :) Thomas
[toc] | [prev] | [next] | [standalone]
| From | emetib <chadbrabec@gmail.com> |
|---|---|
| Date | 2016-11-18 20:30 +0100 |
| Message-ID | <sEX1g-2SU-23@gated-at.bofh.it> |
| In reply to | #174848 |
Thomas Schmitt wrote: > [man page or wiki] either, both, all documentation. yes i know that these, updating documentation, can take a considerable amount of time, especially with the amount of programs/packages that there are available to, especially debian, linux. just looking at my system, ls /bin/, /usr/bin, /usr/local/bin, /sbin/, /usr/sbin/ | wc -l equals 2680. huge undertaking for just a static system. now update for different versions of the program/package, stable, testing, unstable, fedora, centos, opensuse, ... = really big number. >From the view of the developer it is not that easy. >It is very demanding to document a program which one does not know on >source level. understandable. yet, couldn't a review of the docs be achieved with each security update? maybe this thread show be forwarded to the FSF so they can think about putting things on the so-called 'same page'.
[toc] | [prev] | [next] | [standalone]
| From | cbannister@slingshot.co.nz |
|---|---|
| Date | 2016-12-29 15:10 +0100 |
| Subject | Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") |
| Message-ID | <sTJz3-7AW-7@gated-at.bofh.it> |
| In reply to | #174848 |
[sorry for the late response.] On Fri, Nov 18, 2016 at 11:05:48AM +0100, Thomas Schmitt wrote: > It is not easy to describe a program with many use cases and even > more particular settings and actions. > > What lacks to my experience as confused reader and as best effort writer > is the user's view on the programs. man pages should document the details > and often do sufficiently. > But the user looks for solutions, not opportunities. An interesting thing to ponder is whether a tractor manual should explain how to prepare a field to plant carrots. Also, think of man pages as a reference (what does that switch do again?) not as a "first introduction" or tutorial. e.g. I'd be annoyed if a chess database program's documentation consisted of how to play the game, rules of the game, etc. -- The media's the most powerful entity on earth. They have the power to make the innocent guilty and to make the guilty innocent, and that's power. -- Malcolm X
[toc] | [prev] | [next] | [standalone]
| From | Xen <list@xenhideout.nl> |
|---|---|
| Date | 2016-12-29 19:10 +0100 |
| Subject | Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") |
| Message-ID | <sTNjk-1y0-15@gated-at.bofh.it> |
| In reply to | #176061 |
> On Fri, Nov 18, 2016 at 11:05:48AM +0100, Thomas Schmitt wrote: >> What lacks to my experience as confused reader and as best effort >> writer >> is the user's view on the programs. man pages should document the >> details >> and often do sufficiently. >> But the user looks for solutions, not opportunities. I once spoke to the autofs developer about the difficulty of understanding how to use the system. There were two elements to the confusion: a) The developer admitted that he had no clue how a user would look at his system because he had been ingrained into and embedded into it for so long. He did not know how an outsider would look at it or would or would not understand. b) Not everyone is so keen on the numeric sections (5, 8, etc.) and it can quickly elude you if you are not trained to take note of it. An important man page, quite an essential man page, eluded me for quite some time because it was named the same as an other man page with the same name in a different section, that superseded the other one. So at least two lessons to learn from this you know: - give all your man pages a different name (not just different section number) - you must approach your man page as a new user. Someone who doesn't know anything. And also: developers can lose track of what they program looks like to the outside. I think by "solutions" Thomas means that the program provides a certain base functionality. This will agree with several succinct use cases. Those use cases can be taken as the starting point on how to detail the functionality. This means "I want to do this, that and that" becomes the organisation of the man page. The man page will tell you how to do this, that and that. It is oriented around tasks, not a dispersed list of options and patterns. For example the "apt" man page (on Debian Jessie) is oriented precisely around tasks. It is too short to really be useful and doesn't even list all the options it has, but it is an example of a task-oriented layout. Apt-get does the same and is probably a very good man-page. So it is not even out of the ordinary here. Some people just don't "get" it.
[toc] | [prev] | [next] | [standalone]
| From | Xen <list@xenhideout.nl> |
|---|---|
| Date | 2016-12-29 19:10 +0100 |
| Subject | Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") |
| Message-ID | <sTNjk-1y0-25@gated-at.bofh.it> |
| In reply to | #176061 |
cbannister@slingshot.co.nz schreef op 29-12-2016 14:44: > [sorry for the late response.] > > On Fri, Nov 18, 2016 at 11:05:48AM +0100, Thomas Schmitt wrote: >> It is not easy to describe a program with many use cases and even >> more particular settings and actions. >> >> What lacks to my experience as confused reader and as best effort >> writer >> is the user's view on the programs. man pages should document the >> details >> and often do sufficiently. >> But the user looks for solutions, not opportunities. > > An interesting thing to ponder is whether a tractor manual should > explain > how to prepare a field to plant carrots. > > Also, think of man pages as a reference (what does that switch do > again?) > not as a "first introduction" or tutorial. > > e.g. I'd be annoyed if a chess database program's documentation > consisted of > how to play the game, rules of the game, etc. I have heard that analogy before but it's really off. That's not what people are asking for. I was arguing with an OpenSUSE person about the completness of the sendmail (from exim?) manual page. The man page was actually ripped from their complete manual. Yet he called it complete. I should say that the other way. He considered it "complete". Yet it was actually just a fragment actually "ripped" from the entire manual, that just described the command line syntax / parameters. By its very definition, that could not be a complete man- page. Well it could be a complete man /page/ I guess, just not a complete manual... The "man" system is supposed to resemble a book.... with sections, and pages for every command... But when you take a real manual and rip a small part out of that, .... it can never be considered complete unto itself. Anyway. The problem is that the info system and /usr/share/doc are not accessible in the same way that the man system is accessible. I would consider both info and /usr/share/doc to be so inaccessible it does not even come near the man system. So the man system is really the only functional element the system has. After man comes not info or /usr/share/doc but... searching the web for the complete manual or documentation. THAT is the systems we have. I just want to say I agree completely here with Thomas Schmitt but I just subscribed to the list and don't have those messages, so can't reply to those individual ones. Some man pages do reasonably well but others do very bad indeed often even lacking good examples of usage. Man is often the first step in learning about a program. It is not really a reference guide, although it has to be concise and quick to read. If you think "man" is just reference guide, you misunderstand the position it has in the system. It particularly has to come down to business real quick. Get down to business I mean. But that means providing a user with the most common use case quickly and more pheripheral options can wait. It also means giving quick examples. Man is all about speed. If I don't want speed I will search the web for a manual of sorts. The absolute poorest man page I have ever seen is that of "aufs". The best... there are many good ones? "grep" is good. Many of the most common utilities have pretty good man pages. But if you are going to say the purpose of a man page is to be a complete reference guide unto its options, then you will write dirt poor man pages. That is all I can say here.
[toc] | [prev] | [next] | [standalone]
| From | Catherine Gramze <rhiamom@gmail.com> |
|---|---|
| Date | 2016-12-29 19:40 +0100 |
| Subject | Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") |
| Message-ID | <sTNMl-1J3-9@gated-at.bofh.it> |
| In reply to | #176072 |
[Multipart message — attachments visible in raw view] — view raw
On Thu, Dec 29, 2016 at 12:59 PM, Xen <list@xenhideout.nl> wrote: > But if you are going to say the purpose of a man page is to be a complete > reference guide unto its options, then you will write dirt poor man pages. > That is all I can say here > . > But that is precisely the original function of the man pages, to serve as a complete reference, not as any sort of tutorial. That is what those other /usr/share/doc documents were supposed to be, for people who found the man pages too difficult to use. Trying to wish the man pages into something they were never designed to be is likely to be unsuccessful.
[toc] | [prev] | [next] | [standalone]
| From | Xen <list@xenhideout.nl> |
|---|---|
| Date | 2016-12-29 19:40 +0100 |
| Subject | Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") |
| Message-ID | <sTNMl-1J3-17@gated-at.bofh.it> |
| In reply to | #176074 |
Catherine Gramze schreef op 29-12-2016 19:31: > On Thu, Dec 29, 2016 at 12:59 PM, Xen <list@xenhideout.nl> wrote: > >> But if you are going to say the purpose of a man page is to be a >> complete reference guide unto its options, then you will write dirt >> poor man pages. That is all I can say here >> . > > But that is precisely the original function of the man pages, to > serve as a complete reference, not as any sort of tutorial. That is > what those other /usr/share/doc documents were supposed to be, for > people who found the man pages too difficult to use. Trying to wish > the man pages into something they were never designed to be is likely > to be unsuccessful. It is very successful. You can see it all around, there are very many such successful man pages. Trying to turn /usr/share/doc into something useful when it is not, is not going to work however.
[toc] | [prev] | [next] | [standalone]
| From | Xen <list@xenhideout.nl> |
|---|---|
| Date | 2016-12-29 19:40 +0100 |
| Subject | Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") |
| Message-ID | <sTNMl-1J3-19@gated-at.bofh.it> |
| In reply to | #176074 |
Catherine Gramze schreef op 29-12-2016 19:31: > On Thu, Dec 29, 2016 at 12:59 PM, Xen <list@xenhideout.nl> wrote: > >> But if you are going to say the purpose of a man page is to be a >> complete reference guide unto its options, then you will write dirt >> poor man pages. That is all I can say here >> . > > But that is precisely the original function of the man pages, to > serve as a complete reference, not as any sort of tutorial. That is > what those other /usr/share/doc documents were supposed to be, for > people who found the man pages too difficult to use. Trying to wish > the man pages into something they were never designed to be is likely > to be unsuccessful. More importantly the man system or man format does not preclude such documents being written as tutorials so basically it is being done all around. So your assertion here does not really have a basis in reality I must say: the system does not preclude this from being done. People can do it all they want, and they do it. It is the people that insist on not doing it, that write poor man pages.
[toc] | [prev] | [next] | [standalone]
| From | Catherine Gramze <rhiamom@gmail.com> |
|---|---|
| Date | 2016-12-29 19:50 +0100 |
| Subject | Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") |
| Message-ID | <sTNW1-1Mm-7@gated-at.bofh.it> |
| In reply to | #176076 |
[Multipart message — attachments visible in raw view] — view raw
On Thu, Dec 29, 2016 at 1:36 PM, Xen <list@xenhideout.nl> wrote: > > More importantly the man system or man format does not preclude such > documents being written as tutorials so basically it is being done all > around. > > So your assertion here does not really have a basis in reality I must say: > the system does not preclude this from being done. People can do it all > they want, and they do it. > > It is the people that insist on not doing it, that write poor man pages. > > I did not say the man page system precluded it, nor that no man page was written in such a manner. I stated the original purpose and design of the man page as a complete reference, and only a reference, and the futility of wishing that all man pages would be re-written to conform to your personal preferences. What you apparently consider to be a "poorly written" man page I find to be highly accessible and useful. Give me the command and the list of options, with a sentence or so explaining the function of each option. Done. I can figure out which options I need better than somebody not in my situation. Examples muddy up the page and make it harder to scan the options for what I need without adding any clarity to the function..
[toc] | [prev] | [next] | [standalone]
| From | Xen <list@xenhideout.nl> |
|---|---|
| Date | 2016-12-30 02:40 +0100 |
| Subject | Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") |
| Message-ID | <sTUkO-66g-9@gated-at.bofh.it> |
| In reply to | #176077 |
Catherine Gramze schreef op 29-12-2016 19:47: > On Thu, Dec 29, 2016 at 1:36 PM, Xen <list@xenhideout.nl> wrote: > >> More importantly the man system or man format does not preclude such >> documents being written as tutorials so basically it is being done >> all around. >> >> So your assertion here does not really have a basis in reality I >> must say: the system does not preclude this from being done. People >> can do it all they want, and they do it. >> >> It is the people that insist on not doing it, that write poor man >> pages. > > I did not say the man page system precluded it, nor that no man > page was written in such a manner. I stated the original purpose and > design of the man page as a complete reference, and only a reference, > and the futility of wishing that all man pages would be re-written to > conform to your personal preferences. What you apparently consider > to be a "poorly written" man page I find to be highly accessible and > useful. Give me the command and the list of options, with a sentence > or so explaining the function of each option. Done. I can figure out > which options I need better than somebody not in my situation. > Examples muddy up the page and make it harder to scan the options for > what I need without adding any clarity to the function.. That's not what you said, dear sir. What you said was: "Trying to wish the man pages into something they were never designed to be is likely to be unsuccessful.". Basically, you imply or directly state that their stated design goals would interfere with becoming more introductory-text-oriented material (more explanative, rather than just poorly descriptive). I think it is clearly evident that the man page is clearly freeform as much as people want it to be. So it is rather evident that the design goals do not interfere with anything. Now again you state "the original purpose and design of the man page" in conjunction with "the futility of thinking (wishing) that all man pages would be re-written to conform to your "personal preferences"" (my quote). Any "original purpose and design" of the man page would only have any bearing if through historical reasons the majority of man pages were thus poorly constructed. I say that this is not even the case. Barring that, those "original purposes and design goals" have no bearing whatsoever on saying what can, and cannot be done. Moroever, this design goal could very well change, or by evolution people could decide that this design goal IS changing. You go on by stating your personal preferences. So I think we can conclude at least three things: - you *are* implying that somehow the descriptive option-oriented format is technically or at least principally (if, at the last instance, historically) being favoured by some "design goals" that people once had for the system. (That could also have been poor, as it is now). - you are the one who is using personal preferences as a reason for stuff to remain this way, not me. I am saying (and others are) that many users, in fact, users or new users in general, cannot use the man system to full extent because of these attitudes and opinions and styles of writing these documents. So that is not personal preference at all but rather the truth of how many experience this system. I have said nothing about what I like or don't like. So you are the one who is using what you like and don't like (or what works for you and doesn't work for you) (I have not implicated my own person at all, thus far) -- I have merely described how the system works and what descriptive is and what task-oriented is. So actually I think you are just projecting stuff onto me that really is something you are doing, not me. And - NO where have I stated any "wish" for "all man pages" to be rewritten according to those what you call "personal preferences" (actually they are what would work for the majority of new users to any program) (and what does work, and what many man page authors actually naturally and intuitively do) -- but you call it futile. You misinterpret my intent here little lady. I am not asking anyone to do any work. I am simply saying there is no reason to keep man pages poor based on some pre-existing notion of what they were initially intended to be. Basically, you can judge formats on their own merit also considering, or perhaps, predominantly also considering the position the man pages today have in the system, in which the "alternatives" are unusable, so "that's what /usr/share/doc is for" does not count. It doesn't work. No one goes there. It's too much trouble. The man system is automated and organized. The /usr/share/doc system is manual labour. As far as I know at least? I have certainly not ever seen any reference to this thing being automated, other than the dysfunctional "info" system. There are no other good reference materials other than the man system. Certainly not for users wanting to have a quick hands on introduction or guide into how to use the thing. So saying "there are alternatives that do that thing" is just lies and fallacy. It's not true. It doesn't work. That is wishful thinking indeed. It will never work the way it is, and it has never worked the way it is. Only the man system works. You must accept first that the man system is pretty much the only viable "info" system we have in Linux in the console world. And you will know that they are indeed used by all users as introductory texts. Here is Grep: "grep searches the named input FILEs (or standard input if no files are named, or if a single hyphen-minus (-) is given as file name) for lines containing a match to the given PATTERN. By default, grep prints the matching lines." Well, that is pretty introductory isn't it? It tells you exactly how to use it. This is exactly what I mean, and exactly what is good writing. What comes next is rather confusing, because it is so immaterial or irrelevant as to the main program at that point: "In addition, three variant programs egrep, fgrep and rgrep are available. egrep is the same as grep -E. fgrep is the same as grep -F. rgrep is the same as grep -r. Direct invocation as either egrep or fgrep is deprecated, but is provided to allow historical applications that rely on them to run unmodified." Not something that makes all that much sense, especially given that no one actually uses that (and it is deprecated, probably, because of it). But still, that can be forgiven, the beginning is excellent. The option descriptions are also just fine and the length of the document is just about right, not too long, not too short. No issue with this man page except for that paragraph. Now aufs: "Aufs is a stackable unification filesystem such as Unionfs, which uni‐ fies several directories and provides a merged single directory. In the early days, aufs was entirely re-designed and re-implemented Unionfs Version 1.x series. After many original ideas, approaches and improvements, it becomes totally different from Unionfs while keeping the basic features. See Unionfs Version 1.x series for the basic fea‐ tures. Recently, Unionfs Version 2.x series begin taking some of same approaches to aufs's." That's not a very concise intro. More historical than functional. "At mount-time, the order of interpreting options is, · simple flags, except xino/noxino and udba=notify · branches · xino/noxino · udba=notify" That's just incomprehensible. It doesn't start with the most common options, when it should. That's no quick introductory text, that is a complete manual written in a weird way. OpenSUSE does the same with some of their man-pages, which are like books. (Try "man zipper"). There is no point in starting out with ORDER of things if you haven't even explained what those things ARE. Then the syntax is just incomprehensible to begin with, and the description of it also. That's just completely unusable until you see some examples. So you skip down to the end of this very long page. And then it is still hard to comprehend to see what it does and how it is used, because the example aren't explained. So you go on the web and find your answers instead. Dirt-poor man page. Much too long but that is not the worst part. Poorly organized, doesn't explain that the system functions around "branches" (directories) and that you can create mount points based on 2 or more branches, but that you can also add and delete those branches from a running system (running mount). If it explained that _first_ then all of the other options would make *more sense*. So it's just poor writing from my perspective. Doesn't give examples soon enough, and when it does give them they are too complicated. When most users just want to do this: mount -t aufs -o br:upper-dir=rw:lower-dir=ro none target-dir Aufs has only two ordinary use cases: - upper dir and lower dir - both dirs are writeable and will see writes going to their respective directories (on each "upper" directory) If it would just explain those two use cases, people would get a clue. Now they have to hunt the internet for that same information. Because there is no lead-in explanatory text, users are now basically forced to read the entirety of the man page before they start getting a clue, or hunt around bits of information. So the speed of reading this man page is now gone. So miss Catherine you say you don't want examples and that you want a man page to be a clean and concise list of options. The aufs man page is clearly the opposite of that and it still fails to tutor people. It lists all of the options, but it is a complex program and needs more explanation. However it does this in reverse order, first starting with something you cannot comprehend until you have read the remaining parts, and all of the options are basically incomprehensible until you get the full picture, which would not take more than 5 lines to address. So precisely because it fails to answer a user's questions when they arise, this is a poorly written man page. For simple programs, like Grep, fine, that format is excellent. There is no need to explain much and it is such a basic tool that the "quick and easy list of options" format is enough. But aufs or something like autofs needs much more explanation. And it needs to do this in a "chronological" order starting with the stuff the user first needs to understand, and then going on with the next. If you display options for a program that hasn't been explained, it doesn't work. You'll first have to say what the program does you know. Even the Grep example does that.
[toc] | [prev] | [next] | [standalone]
| From | rhkramer@gmail.com |
|---|---|
| Date | 2016-12-30 03:30 +0100 |
| Subject | Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") |
| Message-ID | <sTV7b-6Di-3@gated-at.bofh.it> |
| In reply to | #176085 |
There is noting magic about man pages--what I'm trying to say is that, someone could start writing something similar to man pages, with all the detail or introductory / explanatory material you (they) might want. Maybe call them bman (for beginner man) pages? Then a little effort by a programmer / developer to let the man page infrastructure work also for the bman pages. My suggestion is you spend less time discussing it, and get started on writing a few bman pages... On Thursday, December 29, 2016 08:38:28 PM Xen wrote: > Catherine Gramze schreef op 29-12-2016 19:47: > > On Thu, Dec 29, 2016 at 1:36 PM, Xen <list@xenhideout.nl> wrote: ... > That's not what you said, dear sir. What you said was: "Trying to wish > the man pages into something they were never designed to be is likely to > be unsuccessful.".
[toc] | [prev] | [next] | [standalone]
| From | Lisi Reisz <lisi.reisz@gmail.com> |
|---|---|
| Date | 2016-12-30 03:40 +0100 |
| Subject | Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") |
| Message-ID | <sTVgR-6Gr-9@gated-at.bofh.it> |
| In reply to | #176087 |
On Friday 30 December 2016 02:23:15 rhkramer@gmail.com wrote: > My suggestion is you spend less time discussing it, and get started on > writing a few bman pages... :-)) +1! Lisi
[toc] | [prev] | [next] | [standalone]
| From | Greg Wooledge <wooledg@eeg.ccf.org> |
|---|---|
| Date | 2016-12-30 15:40 +0100 |
| Subject | Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") |
| Message-ID | <sU6vE-5zf-21@gated-at.bofh.it> |
| In reply to | #176087 |
On Fri, Dec 30, 2016 at 02:24:28PM -0000, Dan Purgert wrote: > Anyway, isn't this where the differences between say "man something" and > "man 5 something" come into play? Or rather, the implication that > section 1 (or whatever) may only hold a basic overview, and then section > 5 (or whatever) will hold the full documentation. Section 1: user commands. Section 5: file formats. man 1 intro man 5 intro What you want is actually section 7: overviews, conventions, protocols, etc. That's where tutorials should go. man 7 intro
[toc] | [prev] | [next] | [standalone]
| From | Dan Purgert <dan@djph.net> |
|---|---|
| Date | 2016-12-30 18:00 +0100 |
| Subject | Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") |
| Message-ID | <sU8H7-6U5-11@gated-at.bofh.it> |
| In reply to | #176100 |
Greg Wooledge wrote: > On Fri, Dec 30, 2016 at 02:24:28PM -0000, Dan Purgert wrote: >> Anyway, isn't this where the differences between say "man something" and >> "man 5 something" come into play? Or rather, the implication that >> section 1 (or whatever) may only hold a basic overview, and then section >> 5 (or whatever) will hold the full documentation. > > Section 1: user commands. > Section 5: file formats. > > man 1 intro > man 5 intro > > What you want is actually section 7: overviews, conventions, protocols, > etc. That's where tutorials should go. > > man 7 intro yeah, I really need to remember to not pretend to be a functioning human til at least my second cuppa coffee :) -- |_|O|_| Registered Linux user #585947 |_|_|O| Github: https://github.com/dpurgert |O|O|O| PGP: 05CA 9A50 3F2E 1335 4DC5 4AEE 8E11 DDF3 1279 A281
[toc] | [prev] | [next] | [standalone]
| From | Dan Purgert <dan@djph.net> |
|---|---|
| Date | 2016-12-30 15:40 +0100 |
| Subject | Re: Do have programs have poor documentation? (was ... Re: Why? -- "A Modest Proposal") |
| Message-ID | <sU6vE-5zf-23@gated-at.bofh.it> |
| In reply to | #176087 |
rhkramer@gmail.com wrote:
> My suggestion is you spend less time discussing it, and get started on
> writing a few bman pages...
Probably should be 'manng' (for 'next generation'), or perhaps mand (to
fit in with systemd) ;)
Anyway, isn't this where the differences between say "man something" and
"man 5 something" come into play? Or rather, the implication that
section 1 (or whatever) may only hold a basic overview, and then section
5 (or whatever) will hold the full documentation.
TBH though, I kind of follow what everyone else has been saying -- the
manpages are more quick-reference type things ("how do I make tar use
bzip again?") rather than a 200-page treatise on how to set things up
from scratch.
--
|_|O|_| Registered Linux user #585947
|_|_|O| Github: https://github.com/dpurgert
|O|O|O| PGP: 05CA 9A50 3F2E 1335 4DC5 4AEE 8E11 DDF3 1279 A281
[toc] | [prev] | [next] | [standalone]
Page 2 of 6 — ← Prev page 1 [2] 3 4 5 6 Next page →
Back to top | Article view | linux.debian.user
csiph-web