* (Getting rid of) man pages @ 1999-04-22 9:23 Gerald Pfeifer 1999-04-22 9:35 ` Alexandre Oliva ` (3 more replies) 0 siblings, 4 replies; 40+ messages in thread From: Gerald Pfeifer @ 1999-04-22 9:23 UTC (permalink / raw) To: egcs As far as I understand, our man pages have not been maintained for a rather extensive period of time. Of course on the first page we have This man page is not kept up to date except when volunteers want to maintain it. but, at least according to `cvs log` there are virtually no such volunteers. I therefore propose to remove those man pages, at least those that are obsolete and virtually unmaintained, from the distribution, and solely refer to the info and HTML docs. Gerald, fetching his asbesto suit... -- Gerald "Jerry" pfeifer@dbai.tuwien.ac.at http://www.dbai.tuwien.ac.at/~pfeifer/ ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-22 9:23 (Getting rid of) man pages Gerald Pfeifer @ 1999-04-22 9:35 ` Alexandre Oliva 1999-04-30 23:15 ` Alexandre Oliva 1999-04-22 9:52 ` CaT ` (2 subsequent siblings) 3 siblings, 1 reply; 40+ messages in thread From: Alexandre Oliva @ 1999-04-22 9:35 UTC (permalink / raw) To: Gerald Pfeifer; +Cc: egcs On Apr 22, 1999, Gerald Pfeifer <pfeifer@dbai.tuwien.ac.at> wrote: > I therefore propose to remove those man pages, at least those that are > obsolete and virtually unmaintained, from the distribution, and solely > refer to the info and HTML docs. There's a help2man script somewhere on the net that we could use to automatically generate the man pages from the output of gcc --help [--verbose], for example. -- Alexandre Oliva http://www.dcc.unicamp.br/~oliva IC-Unicamp, Brasil {oliva,Alexandre.Oliva}@dcc.unicamp.br aoliva@{acm.org,computer.org} oliva@{gnu.org,kaffe.org,{egcs,sourceware}.cygnus.com,samba.org} *** E-mail about software projects will be forwarded to mailing lists ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-22 9:35 ` Alexandre Oliva @ 1999-04-30 23:15 ` Alexandre Oliva 0 siblings, 0 replies; 40+ messages in thread From: Alexandre Oliva @ 1999-04-30 23:15 UTC (permalink / raw) To: Gerald Pfeifer; +Cc: egcs On Apr 22, 1999, Gerald Pfeifer <pfeifer@dbai.tuwien.ac.at> wrote: > I therefore propose to remove those man pages, at least those that are > obsolete and virtually unmaintained, from the distribution, and solely > refer to the info and HTML docs. There's a help2man script somewhere on the net that we could use to automatically generate the man pages from the output of gcc --help [--verbose], for example. -- Alexandre Oliva http://www.dcc.unicamp.br/~oliva IC-Unicamp, Brasil {oliva,Alexandre.Oliva}@dcc.unicamp.br aoliva@{acm.org,computer.org} oliva@{gnu.org,kaffe.org,{egcs,sourceware}.cygnus.com,samba.org} *** E-mail about software projects will be forwarded to mailing lists ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-22 9:23 (Getting rid of) man pages Gerald Pfeifer 1999-04-22 9:35 ` Alexandre Oliva @ 1999-04-22 9:52 ` CaT 1999-04-22 10:08 ` Alexandre Oliva 1999-04-30 23:15 ` CaT 1999-04-30 23:15 ` Gerald Pfeifer 1999-06-25 6:25 ` Alexandre Oliva 3 siblings, 2 replies; 40+ messages in thread From: CaT @ 1999-04-22 9:52 UTC (permalink / raw) To: Gerald Pfeifer; +Cc: egcs Gerald Pfeifer wrote the following: > > As far as I understand, our man pages have not been maintained for a > rather extensive period of time. > > Of course on the first page we have > This man page is not kept up to date except when volunteers > want to maintain it. > but, at least according to `cvs log` there are virtually no such > volunteers. > > I therefore propose to remove those man pages, at least those that are > obsolete and virtually unmaintained, from the distribution, and solely > refer to the info and HTML docs. Nooooo!!!!!!!! I hate the info system! *sob* And html would be just as bad. :/ What IS ionvolved in maintaining the man pages btw? > Gerald, fetching his asbesto suit... *chucks nuke at you* Bad Gerald, bad. ;) -- CaT (cat@zip.net.au) URL: http://www.zip.com.au/dev/null For a bad joke read: http://www2.hunterlink.net.au/~ddhrg/censorship_legislation.html ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-22 9:52 ` CaT @ 1999-04-22 10:08 ` Alexandre Oliva 1999-04-22 10:22 ` CaT ` (2 more replies) 1999-04-30 23:15 ` CaT 1 sibling, 3 replies; 40+ messages in thread From: Alexandre Oliva @ 1999-04-22 10:08 UTC (permalink / raw) To: CaT; +Cc: Gerald Pfeifer, egcs On Apr 22, 1999, CaT <cat@zip.com.au> wrote: > Gerald Pfeifer wrote the following: >> I therefore propose to remove those man pages, at least those that are >> obsolete and virtually unmaintained, from the distribution, and solely >> refer to the info and HTML docs. > html would be just as bad. :/ What's wrong with lynx? :-) > What IS ionvolved in maintaining the man pages btw? Your sending legal papers to the FSF to become their official maintainer? :-D -- Alexandre Oliva http://www.dcc.unicamp.br/~oliva IC-Unicamp, Brasil {oliva,Alexandre.Oliva}@dcc.unicamp.br aoliva@{acm.org,computer.org} oliva@{gnu.org,kaffe.org,{egcs,sourceware}.cygnus.com,samba.org} *** E-mail about software projects will be forwarded to mailing lists ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-22 10:08 ` Alexandre Oliva @ 1999-04-22 10:22 ` CaT 1999-04-30 23:15 ` CaT 1999-04-22 10:23 ` Keith Duthie 1999-04-30 23:15 ` Alexandre Oliva 2 siblings, 1 reply; 40+ messages in thread From: CaT @ 1999-04-22 10:22 UTC (permalink / raw) To: Alexandre Oliva; +Cc: cat, pfeifer, egcs Alexandre Oliva wrote the following: > > On Apr 22, 1999, CaT <cat@zip.com.au> wrote: > > > Gerald Pfeifer wrote the following: > > >> I therefore propose to remove those man pages, at least those that are > >> obsolete and virtually unmaintained, from the distribution, and solely > >> refer to the info and HTML docs. > > > html would be just as bad. :/ > > What's wrong with lynx? :-) Absolutely nothing. Lynx quite frankly rocks my world. I've even adapted an SSL patch to work witht he development releases. I just have a problem with such a layout for manpages. it annoys me. > > What IS ionvolved in maintaining the man pages btw? > > Your sending legal papers to the FSF to become their official > maintainer? :-D That sounds, well, rather ominous. :) -- CaT (cat@zip.net.au) URL: http://www.zip.com.au/dev/null For a bad joke read: http://www2.hunterlink.net.au/~ddhrg/censorship_legislation.html ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-22 10:22 ` CaT @ 1999-04-30 23:15 ` CaT 0 siblings, 0 replies; 40+ messages in thread From: CaT @ 1999-04-30 23:15 UTC (permalink / raw) To: Alexandre Oliva; +Cc: cat, pfeifer, egcs Alexandre Oliva wrote the following: > > On Apr 22, 1999, CaT <cat@zip.com.au> wrote: > > > Gerald Pfeifer wrote the following: > > >> I therefore propose to remove those man pages, at least those that are > >> obsolete and virtually unmaintained, from the distribution, and solely > >> refer to the info and HTML docs. > > > html would be just as bad. :/ > > What's wrong with lynx? :-) Absolutely nothing. Lynx quite frankly rocks my world. I've even adapted an SSL patch to work witht he development releases. I just have a problem with such a layout for manpages. it annoys me. > > What IS ionvolved in maintaining the man pages btw? > > Your sending legal papers to the FSF to become their official > maintainer? :-D That sounds, well, rather ominous. :) -- CaT (cat@zip.net.au) URL: http://www.zip.com.au/dev/null For a bad joke read: http://www2.hunterlink.net.au/~ddhrg/censorship_legislation.html ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-22 10:08 ` Alexandre Oliva 1999-04-22 10:22 ` CaT @ 1999-04-22 10:23 ` Keith Duthie 1999-04-22 10:26 ` CaT ` (3 more replies) 1999-04-30 23:15 ` Alexandre Oliva 2 siblings, 4 replies; 40+ messages in thread From: Keith Duthie @ 1999-04-22 10:23 UTC (permalink / raw) To: Alexandre Oliva; +Cc: CaT, Gerald Pfeifer, egcs On 22 Apr 1999, Alexandre Oliva wrote: > On Apr 22, 1999, CaT <cat@zip.com.au> wrote: > > > html would be just as bad. :/ > > What's wrong with lynx? :-) The latest version seems to mess up the terminal fonts (I've probably misconfigured it). Other than that, nothing. > > What IS ionvolved in maintaining the man pages btw? > > Your sending legal papers to the FSF to become their official > maintainer? :-D Which is probably one of the main reasons why nobody has stepped forward. Perhaps someone could write a script to automagically convert the info files to man pages. I'm not entirely sure why the FSF wants to get rid of man pages in favour of info files, but I for one turn to info only as a last resort, whereas I turn to man as a first resort. -- .sig under deconstruction. Please watch out for falling stars. http://www.albatross.co.nz/~psycho/ O- ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-22 10:23 ` Keith Duthie @ 1999-04-22 10:26 ` CaT 1999-04-30 23:15 ` CaT 1999-04-22 10:31 ` Alexandre Oliva ` (2 subsequent siblings) 3 siblings, 1 reply; 40+ messages in thread From: CaT @ 1999-04-22 10:26 UTC (permalink / raw) To: Keith Duthie; +Cc: oliva, cat, pfeifer, egcs Keith Duthie wrote the following: > > On 22 Apr 1999, Alexandre Oliva wrote: > > > On Apr 22, 1999, CaT <cat@zip.com.au> wrote: > > > > > html would be just as bad. :/ > > > > What's wrong with lynx? :-) > The latest version seems to mess up the terminal fonts (I've probably > misconfigured it). Other than that, nothing. Hmm.. I've not had problems so could be. > > > What IS ionvolved in maintaining the man pages btw? > > > > Your sending legal papers to the FSF to become their official > > maintainer? :-D > Which is probably one of the main reasons why nobody has stepped forward. And has made me do a bit of a doubletake... > Perhaps someone could write a script to automagically convert the info > files to man pages. I've been pondering this. would be difficult in some respects. At least to keep the order of information sane automatically. > I'm not entirely sure why the FSF wants to get rid of man pages in favour > of info files, but I for one turn to info only as a last resort, whereas I > turn to man as a first resort. Ditto. It seems like a bizarr ething to do and I fail to understand it. I've had more problems with info then I ever have with man. I like man's simplicity. -- CaT (cat@zip.net.au) URL: http://www.zip.com.au/dev/null For a bad joke read: http://www2.hunterlink.net.au/~ddhrg/censorship_legislation.html ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-22 10:26 ` CaT @ 1999-04-30 23:15 ` CaT 0 siblings, 0 replies; 40+ messages in thread From: CaT @ 1999-04-30 23:15 UTC (permalink / raw) To: Keith Duthie; +Cc: oliva, cat, pfeifer, egcs Keith Duthie wrote the following: > > On 22 Apr 1999, Alexandre Oliva wrote: > > > On Apr 22, 1999, CaT <cat@zip.com.au> wrote: > > > > > html would be just as bad. :/ > > > > What's wrong with lynx? :-) > The latest version seems to mess up the terminal fonts (I've probably > misconfigured it). Other than that, nothing. Hmm.. I've not had problems so could be. > > > What IS ionvolved in maintaining the man pages btw? > > > > Your sending legal papers to the FSF to become their official > > maintainer? :-D > Which is probably one of the main reasons why nobody has stepped forward. And has made me do a bit of a doubletake... > Perhaps someone could write a script to automagically convert the info > files to man pages. I've been pondering this. would be difficult in some respects. At least to keep the order of information sane automatically. > I'm not entirely sure why the FSF wants to get rid of man pages in favour > of info files, but I for one turn to info only as a last resort, whereas I > turn to man as a first resort. Ditto. It seems like a bizarr ething to do and I fail to understand it. I've had more problems with info then I ever have with man. I like man's simplicity. -- CaT (cat@zip.net.au) URL: http://www.zip.com.au/dev/null For a bad joke read: http://www2.hunterlink.net.au/~ddhrg/censorship_legislation.html ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-22 10:23 ` Keith Duthie 1999-04-22 10:26 ` CaT @ 1999-04-22 10:31 ` Alexandre Oliva 1999-04-30 23:15 ` Alexandre Oliva 1999-04-22 16:10 ` Gerald Pfeifer 1999-04-30 23:15 ` Keith Duthie 3 siblings, 1 reply; 40+ messages in thread From: Alexandre Oliva @ 1999-04-22 10:31 UTC (permalink / raw) To: Keith Duthie; +Cc: CaT, Gerald Pfeifer, egcs On Apr 22, 1999, Keith Duthie <psycho@albatross.co.nz> wrote: > I'm not entirely sure why the FSF wants to get rid of man pages in favour > of info files, but I for one turn to info only as a last resort, whereas I > turn to man as a first resort. That's interesting... I usually run `info' to read man-pages :-) -- Alexandre Oliva http://www.dcc.unicamp.br/~oliva IC-Unicamp, Brasil {oliva,Alexandre.Oliva}@dcc.unicamp.br aoliva@{acm.org,computer.org} oliva@{gnu.org,kaffe.org,{egcs,sourceware}.cygnus.com,samba.org} *** E-mail about software projects will be forwarded to mailing lists ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-22 10:31 ` Alexandre Oliva @ 1999-04-30 23:15 ` Alexandre Oliva 0 siblings, 0 replies; 40+ messages in thread From: Alexandre Oliva @ 1999-04-30 23:15 UTC (permalink / raw) To: Keith Duthie; +Cc: CaT, Gerald Pfeifer, egcs On Apr 22, 1999, Keith Duthie <psycho@albatross.co.nz> wrote: > I'm not entirely sure why the FSF wants to get rid of man pages in favour > of info files, but I for one turn to info only as a last resort, whereas I > turn to man as a first resort. That's interesting... I usually run `info' to read man-pages :-) -- Alexandre Oliva http://www.dcc.unicamp.br/~oliva IC-Unicamp, Brasil {oliva,Alexandre.Oliva}@dcc.unicamp.br aoliva@{acm.org,computer.org} oliva@{gnu.org,kaffe.org,{egcs,sourceware}.cygnus.com,samba.org} *** E-mail about software projects will be forwarded to mailing lists ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-22 10:23 ` Keith Duthie 1999-04-22 10:26 ` CaT 1999-04-22 10:31 ` Alexandre Oliva @ 1999-04-22 16:10 ` Gerald Pfeifer 1999-04-22 16:44 ` Joe Buck 1999-04-30 23:15 ` Gerald Pfeifer 1999-04-30 23:15 ` Keith Duthie 3 siblings, 2 replies; 40+ messages in thread From: Gerald Pfeifer @ 1999-04-22 16:10 UTC (permalink / raw) To: Keith Duthie; +Cc: Alexandre Oliva, CaT, egcs On Fri, 23 Apr 1999, Keith Duthie wrote: > I'm not entirely sure why the FSF wants to get rid of man pages in favour > of info files, but I for one turn to info only as a last resort, whereas I > turn to man as a first resort. ...thus getting obsolete, incomplete and probably even incorrect information in the case of egcs. :-( That's exactly why I suggest removing these man pages from the egcs distribution. Gerald -- Gerald "Jerry" pfeifer@dbai.tuwien.ac.at http://www.dbai.tuwien.ac.at/~pfeifer/ ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-22 16:10 ` Gerald Pfeifer @ 1999-04-22 16:44 ` Joe Buck 1999-04-22 22:19 ` Jeffrey A Law ` (2 more replies) 1999-04-30 23:15 ` Gerald Pfeifer 1 sibling, 3 replies; 40+ messages in thread From: Joe Buck @ 1999-04-22 16:44 UTC (permalink / raw) To: Gerald Pfeifer; +Cc: psycho, oliva, cat, egcs > On Fri, 23 Apr 1999, Keith Duthie wrote: > > I'm not entirely sure why the FSF wants to get rid of man pages in favour > > of info files, but I for one turn to info only as a last resort, whereas I > > turn to man as a first resort. > > ...thus getting obsolete, incomplete and probably even incorrect > information in the case of egcs. :-( > > That's exactly why I suggest removing these man pages from the egcs > distribution. Sigh. man pages are necessary. For those of us who have used Unix for years, they are almost a way of life. The GNU project has attempted to get rid of them, but hasn't really succeeded. The key is to define the purpose of man pages. They are not complete documentation, the gcc manual is. Rather, they should be a quick reference, describing how to invoke gcc, giving the meaning of the flags, and pointing the user to the gcc manual for further details. With a proper scope it shouldn't be so hard to keep the manual in sync. The best way would be to obtain gcc.1 by conversion of invoke.texi, with possibly a small header and footer added. If no one else will do it, perhaps I can find some time, but probably not until mid-May. ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-22 16:44 ` Joe Buck @ 1999-04-22 22:19 ` Jeffrey A Law 1999-04-30 23:15 ` Jeffrey A Law 1999-04-23 1:52 ` Andreas Schwab 1999-04-30 23:15 ` Joe Buck 2 siblings, 1 reply; 40+ messages in thread From: Jeffrey A Law @ 1999-04-22 22:19 UTC (permalink / raw) To: Joe Buck; +Cc: Gerald Pfeifer, psycho, oliva, cat, egcs In message < 199904222341.QAA13973@atrus.synopsys.com >you write: > Sigh. man pages are necessary. For those of us who have used Unix for > years, they are almost a way of life. The GNU project has attempted to > get rid of them, but hasn't really succeeded. Unfortunately I have to agree. > The key is to define the purpose of man pages. They are not complete > documentation, the gcc manual is. Rather, they should be a quick > reference, describing how to invoke gcc, giving the meaning of the flags, > and pointing the user to the gcc manual for further details. With a > proper scope it shouldn't be so hard to keep the manual in sync. > The best way would be to obtain gcc.1 by conversion of invoke.texi, > with possibly a small header and footer added. Right. I think this is the only way to really deal with the man pages -- generate them from the texi code. jeff ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-22 22:19 ` Jeffrey A Law @ 1999-04-30 23:15 ` Jeffrey A Law 0 siblings, 0 replies; 40+ messages in thread From: Jeffrey A Law @ 1999-04-30 23:15 UTC (permalink / raw) To: Joe Buck; +Cc: pfeifer In message < 199904222341.QAA13973@atrus.synopsys.com >you write: > Sigh. man pages are necessary. For those of us who have used Unix for > years, they are almost a way of life. The GNU project has attempted to > get rid of them, but hasn't really succeeded. Unfortunately I have to agree. > The key is to define the purpose of man pages. They are not complete > documentation, the gcc manual is. Rather, they should be a quick > reference, describing how to invoke gcc, giving the meaning of the flags, > and pointing the user to the gcc manual for further details. With a > proper scope it shouldn't be so hard to keep the manual in sync. > The best way would be to obtain gcc.1 by conversion of invoke.texi, > with possibly a small header and footer added. Right. I think this is the only way to really deal with the man pages -- generate them from the texi code. jeff ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-22 16:44 ` Joe Buck 1999-04-22 22:19 ` Jeffrey A Law @ 1999-04-23 1:52 ` Andreas Schwab 1999-04-23 9:12 ` Joe Buck ` (2 more replies) 1999-04-30 23:15 ` Joe Buck 2 siblings, 3 replies; 40+ messages in thread From: Andreas Schwab @ 1999-04-23 1:52 UTC (permalink / raw) To: Joe Buck; +Cc: Gerald Pfeifer, psycho, oliva, cat, egcs Joe Buck <jbuck@Synopsys.COM> writes: |> The key is to define the purpose of man pages. They are not complete |> documentation, the gcc manual is. Rather, they should be a quick |> reference, describing how to invoke gcc, giving the meaning of the flags, |> and pointing the user to the gcc manual for further details. That's what info gcc 'invoking gcc' is for. With the current texinfo snapshot you can even say info --show-options gcc. -- Andreas Schwab "And now for something schwab@issan.cs.uni-dortmund.de completely different" schwab@gnu.org ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-23 1:52 ` Andreas Schwab @ 1999-04-23 9:12 ` Joe Buck 1999-04-24 0:31 ` rich-paul 1999-04-30 23:15 ` Joe Buck 1999-04-23 10:52 ` Marc Espie 1999-04-30 23:15 ` Andreas Schwab 2 siblings, 2 replies; 40+ messages in thread From: Joe Buck @ 1999-04-23 9:12 UTC (permalink / raw) To: Andreas Schwab; +Cc: jbuck, pfeifer, psycho, oliva, cat, egcs I wrote: > |> The key is to define the purpose of man pages. They are not complete > |> documentation, the gcc manual is. Rather, they should be a quick > |> reference, describing how to invoke gcc, giving the meaning of the flags, > |> and pointing the user to the gcc manual for further details. Andreas Schwab wrote: > That's what info gcc 'invoking gcc' is for. With the current texinfo > snapshot you can even say info --show-options gcc. This is why I think that the gcc man page should be obtained by coverting invoke.texi. The vast majority of software on any Unix, GNU/Linux, or BSD system has documentation in the form of man pages. Users expect to type "man". Now, of course we could make "null manpages" that tell the user to run info --show-options gcc. Or maybe we can have a version of the "man" program that can invoke "info --show-options". But we then have to fix the other places where "man" is used (the Emacs manual-entry command) and support the other behavior. There's also "man -t". ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-23 9:12 ` Joe Buck @ 1999-04-24 0:31 ` rich-paul 1999-04-24 0:50 ` CaT ` (2 more replies) 1999-04-30 23:15 ` Joe Buck 1 sibling, 3 replies; 40+ messages in thread From: rich-paul @ 1999-04-24 0:31 UTC (permalink / raw) To: Joe Buck; +Cc: Andreas Schwab, pfeifer, psycho, oliva, cat, egcs On Fri, 23 Apr 1999, Joe Buck wrote: > > That's what info gcc 'invoking gcc' is for. With the current texinfo > > snapshot you can even say info --show-options gcc. > > This is why I think that the gcc man page should be obtained by coverting > invoke.texi. > > The vast majority of software on any Unix, GNU/Linux, or BSD system has > documentation in the form of man pages. Users expect to type "man". Just to put in my two cents, 'invoking gcc' very nice for what it is, but it ain't no man page. One of the great things about man pages is that they have a very specific set of sections, normally in the same order. Near the top, they have a canonical list of flags, so that when you find some invocation you don't grok in some makefile somewhere, you have a hope of finding a clue. It won't tell you all the whys and wherefores, but it will give you just a QUICK idea of what the damn thing does. I'm not against, in principal, converting to man pages from texinfo, but I've never seen anything in a texinfo file anywhere as quick and useful as a man page. A better solution might be to use the perl pod format, since it's extremely simple, and converts to troff as well as sweetened and unsweetened ascii. It's easier to use ( read *MUCH* easier ) than troff, which is as ugly as postscript, and most importantly, the results will be paged through things that search with the / key, as they should. <G> Of course the man page maintainer would have to have perl, but who doesn't? ( We can make this two ... two ... two flamewars in one! ;) --- There is a party that | Libertarian Party | A victimless crime is supports the right to | http://www.lp.org | a contradiction in free speech and | The Party of | terms. encryption!! | Principle | ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-24 0:31 ` rich-paul @ 1999-04-24 0:50 ` CaT 1999-04-30 23:15 ` CaT 1999-04-24 5:50 ` craig 1999-04-30 23:15 ` rich-paul 2 siblings, 1 reply; 40+ messages in thread From: CaT @ 1999-04-24 0:50 UTC (permalink / raw) To: rich-paul; +Cc: jbuck, schwab, pfeifer, psycho, oliva, cat, egcs rich-paul@rich-paul.net wrote the following: > > On Fri, 23 Apr 1999, Joe Buck wrote: > > > > That's what info gcc 'invoking gcc' is for. With the current texinfo > > > snapshot you can even say info --show-options gcc. > > > > This is why I think that the gcc man page should be obtained by coverting > > invoke.texi. > > > > The vast majority of software on any Unix, GNU/Linux, or BSD system has > > documentation in the form of man pages. Users expect to type "man". > > Just to put in my two cents, 'invoking gcc' very nice for what it is, but > it ain't no man page. One of the great things about man pages is that > they have a very specific set of sections, normally in the same order. > > Near the top, they have a canonical list of flags, so that when you find > some invocation you don't grok in some makefile somewhere, you have a hope > of finding a clue. It won't tell you all the whys and wherefores, but it > will give you just a QUICK idea of what the damn thing does. > > I'm not against, in principal, converting to man pages from texinfo, but > I've never seen anything in a texinfo file anywhere as quick and useful > as a man page. I'm wondering. After the initial investment in converting the texinfo stuff to proper manpages, how hard can it be to maintain incrementally from say diffs? Initially this would suck SOOOO much butt but then it'd get easier as smaller changes are required, no? > A better solution might be to use the perl pod format, since it's extremely > simple, and converts to troff as well as sweetened and unsweetened ascii. > It's easier to use ( read *MUCH* easier ) than troff, which is as ugly > as postscript, and most importantly, the results will be paged through > things that search with the / key, as they should. <G> I don't like perldoc either. I'm a sucker for man. :) > Of course the man page maintainer would have to have perl, > but who doesn't? ( We can make this two ... two ... two flamewars in one! ;) 8) -- CaT (cat@zip.net.au) URL: http://www.zip.com.au/dev/null For a bad joke read: http://www2.hunterlink.net.au/~ddhrg/censorship_legislation.html ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-24 0:50 ` CaT @ 1999-04-30 23:15 ` CaT 0 siblings, 0 replies; 40+ messages in thread From: CaT @ 1999-04-30 23:15 UTC (permalink / raw) To: rich-paul; +Cc: jbuck, schwab, pfeifer, psycho, oliva, cat, egcs rich-paul@rich-paul.net wrote the following: > > On Fri, 23 Apr 1999, Joe Buck wrote: > > > > That's what info gcc 'invoking gcc' is for. With the current texinfo > > > snapshot you can even say info --show-options gcc. > > > > This is why I think that the gcc man page should be obtained by coverting > > invoke.texi. > > > > The vast majority of software on any Unix, GNU/Linux, or BSD system has > > documentation in the form of man pages. Users expect to type "man". > > Just to put in my two cents, 'invoking gcc' very nice for what it is, but > it ain't no man page. One of the great things about man pages is that > they have a very specific set of sections, normally in the same order. > > Near the top, they have a canonical list of flags, so that when you find > some invocation you don't grok in some makefile somewhere, you have a hope > of finding a clue. It won't tell you all the whys and wherefores, but it > will give you just a QUICK idea of what the damn thing does. > > I'm not against, in principal, converting to man pages from texinfo, but > I've never seen anything in a texinfo file anywhere as quick and useful > as a man page. I'm wondering. After the initial investment in converting the texinfo stuff to proper manpages, how hard can it be to maintain incrementally from say diffs? Initially this would suck SOOOO much butt but then it'd get easier as smaller changes are required, no? > A better solution might be to use the perl pod format, since it's extremely > simple, and converts to troff as well as sweetened and unsweetened ascii. > It's easier to use ( read *MUCH* easier ) than troff, which is as ugly > as postscript, and most importantly, the results will be paged through > things that search with the / key, as they should. <G> I don't like perldoc either. I'm a sucker for man. :) > Of course the man page maintainer would have to have perl, > but who doesn't? ( We can make this two ... two ... two flamewars in one! ;) 8) -- CaT (cat@zip.net.au) URL: http://www.zip.com.au/dev/null For a bad joke read: http://www2.hunterlink.net.au/~ddhrg/censorship_legislation.html ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-24 0:31 ` rich-paul 1999-04-24 0:50 ` CaT @ 1999-04-24 5:50 ` craig 1999-04-30 23:15 ` craig 1999-04-30 23:15 ` rich-paul 2 siblings, 1 reply; 40+ messages in thread From: craig @ 1999-04-24 5:50 UTC (permalink / raw) To: rich-paul; +Cc: craig >Just to put in my two cents, 'invoking gcc' very nice for what it is, but >it ain't no man page. One of the great things about man pages is that >they have a very specific set of sections, normally in the same order. > >Near the top, they have a canonical list of flags, so that when you find >some invocation you don't grok in some makefile somewhere, you have a hope >of finding a clue. It won't tell you all the whys and wherefores, but it >will give you just a QUICK idea of what the damn thing does. I've been seeing the same pro-man-page arguments for *years*, and have yet to see anyone, or any group, step forward and *volunteer* to maintain them for GNU to any serious extent. Without getting into a debate -- because, frankly, I've got too much expertise to be interested in having people here try to convince me why I should prefer maintaining, or even reading, man pages, especially given the inarticulate arguments I've seen in their favor to date -- let me say why *I* prefer to maintain docs in GNU Texinfo format over those in man format: - I've been reading computer documentation for 30 years now, and haven't seen many formats as annoying to read as typical man pages. They simply are *not* well-designed for on-line reading, though I gather they're better when printed out (they looked better when I've seen them printed in the distant past, though the printed forms of Texinfo I've seen most recently were superior in most respects). - When I've worked as a tech-writer, the more "man-like" (nroff) the input language I was dealing with, the more unmaintainable the documentation in its source form. *Period*. (Not that Texinfo, the makeinfo program, and so on can't be improved -- but they don't need *overhauls* to be usable.) I've had better experiences maintaining documentation in plain text (which is why I've gone from that directly to Texinfo in my g77 work, not even bothering with man pages for anything but a bare-bones one, copied from g++'s long ago to make it "easy"). - GNU Texinfo format is simply superior. It's higher-level, it's more device-independent, and it's got real hyperlinks, which work fine as static-form references. (That means I don't, as a reader *or* author, have to balance repeating information against doing *painful* cross-references.) - Every improvement I've heard of, or can *think* of, that could be made to typical Texinfo (I see them mostly as Info) documents to make them better meet peoples' man-page-based expectations could be *better* made to Texinfo and/or to Info or HTML readers (and there *has* been progress made here, over the years) than made by switching back to man pages. So, whenever I hear people say "I'd rather you maintain your docs as man pages than Texinfo/Info", it sounds pretty much the same to me as when they say: "That C language you're writing your code in is *so* hard to read. I'm used to reading assembler. Could you please maintain your code in assembler instead, or at least in parallel, so it would be easier for me to read?" Put simply, *I'm* going to say "no". *Always*. Even though, in both cases, I agree there are situations where the lower-level-language version *is* easier to read for certain kinds of uses, I'll always lean towards making a bigger investment in improving my C code, the C language, and C compilers, than would be needed to get some improvement in maintaining a *particular* version of my code in assembler -- because I'm (as always) looking at the *long-term* costs of maintenance. But, if a bunch of you want to get together and form the "GNU man-page project", to meet and prioritize which GNU man pages you think are most important to write (we've, e.g. the g77 man pages, have been calling for volunteers to do that for *years*), by all means, go to it. I'd suggest you figure out what *conceptual* information you really want, first; how to best architect that into the present *Texinfo* document (not just what new @-style markup you might need, but how typical GNU Texinfo docs could be better architected overall); then perhaps how to mark it up in a canonical way so automatic extraction tools can convert the Texinfo to man pages, at which point you can collaborate on providing such a tool. There's already @ifhtml/@end ifhtml, as well as @ifinfo, etc. A @ifman might be appropriate, but I'd hope that, if you did your homework properly, higher-level constructs would be more suitable. (If man pages were important to *me*, I'd have done the above as of about three years ago. If you want to hire me as a consultant to do some of the work, I'm *definitely* open to that, and have plenty of expertise across the spectrum, having architected, designed, and built documentation systems, including indexing tools for tech writers, in the past. That I don't see it as anywhere near important enough for me to spend my *volunteer* time doing it does not mean I'd give such a project short shrift!) But please, *please*, stop pestering any of the various GNU development lists with these discussions any further. Get your *own* list, invite people onto it, set up a web page (call it "The GNU Needs A Real Man Page" or something clever ;-), announce it on gnu.announce, whatever. Realize that any solution to this problem is, IMO, going to involve GNU developers like myself *only* to the extent that it constitutes high-level improvements to how we write *Texinfo* (and therefore our Info, HTML, DVI-printed, etc.) documentation. That's because most of us recognize that maintaining *two* forms of documentation is a *lose*, and that, at least for now, Texinfo is pretty much our #1 choice, when looking at all the factors, while man-page (nroff) format is probably not even in the top 5 or 10. And if you want to get an idea of how much better a use we could make of *Texinfo* format than we already do today, try compiling this line as file "foo.f" via g77 -- "99999 %invalid token" -- and "follow" the link given, using either "info -f", or Emacs Info mode's "m" command (first look for "M", then "LEX", as directed). Then ask yourself, how would that much documentation on a *diagnostic* be fit appropriately into the man-page system you love so much, how would it be dynamically hyperlinked-to, how well (vs. Texinfo) does it "scale up" to real end-user systems like the various windowing free-software GUIs people are designing (for Linux, for example), how well (vs. Texinfo) is it prepared for improvements for internationalization, etc.? I mean, I think *Texinfo*, and the GNU documentation written in it, has a long race to run, to be really great, and I haven't convinced myself (yet) that they'll even be able to *finish* -- that a whole new paradigm won't be needed down the road, one that is to Texinfo what Texinfo is to man pages. But, from what I've seen, man pages aren't even in the *race* -- they're sitting on the couch, watching it on TV, recalling their glory days. Give me a pointer to a web page to convince me (and the GNU people who make the high-level decisions about this) otherwise, if you like. In the meantime, stop pestering GNU development mailing-lists with this issue. It's just *so* annoying hearing the same tired old arguments over and over again, on a forum where we're supposed to be getting work done. tq vm, (burley) ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-24 5:50 ` craig @ 1999-04-30 23:15 ` craig 0 siblings, 0 replies; 40+ messages in thread From: craig @ 1999-04-30 23:15 UTC (permalink / raw) To: rich-paul; +Cc: craig >Just to put in my two cents, 'invoking gcc' very nice for what it is, but >it ain't no man page. One of the great things about man pages is that >they have a very specific set of sections, normally in the same order. > >Near the top, they have a canonical list of flags, so that when you find >some invocation you don't grok in some makefile somewhere, you have a hope >of finding a clue. It won't tell you all the whys and wherefores, but it >will give you just a QUICK idea of what the damn thing does. I've been seeing the same pro-man-page arguments for *years*, and have yet to see anyone, or any group, step forward and *volunteer* to maintain them for GNU to any serious extent. Without getting into a debate -- because, frankly, I've got too much expertise to be interested in having people here try to convince me why I should prefer maintaining, or even reading, man pages, especially given the inarticulate arguments I've seen in their favor to date -- let me say why *I* prefer to maintain docs in GNU Texinfo format over those in man format: - I've been reading computer documentation for 30 years now, and haven't seen many formats as annoying to read as typical man pages. They simply are *not* well-designed for on-line reading, though I gather they're better when printed out (they looked better when I've seen them printed in the distant past, though the printed forms of Texinfo I've seen most recently were superior in most respects). - When I've worked as a tech-writer, the more "man-like" (nroff) the input language I was dealing with, the more unmaintainable the documentation in its source form. *Period*. (Not that Texinfo, the makeinfo program, and so on can't be improved -- but they don't need *overhauls* to be usable.) I've had better experiences maintaining documentation in plain text (which is why I've gone from that directly to Texinfo in my g77 work, not even bothering with man pages for anything but a bare-bones one, copied from g++'s long ago to make it "easy"). - GNU Texinfo format is simply superior. It's higher-level, it's more device-independent, and it's got real hyperlinks, which work fine as static-form references. (That means I don't, as a reader *or* author, have to balance repeating information against doing *painful* cross-references.) - Every improvement I've heard of, or can *think* of, that could be made to typical Texinfo (I see them mostly as Info) documents to make them better meet peoples' man-page-based expectations could be *better* made to Texinfo and/or to Info or HTML readers (and there *has* been progress made here, over the years) than made by switching back to man pages. So, whenever I hear people say "I'd rather you maintain your docs as man pages than Texinfo/Info", it sounds pretty much the same to me as when they say: "That C language you're writing your code in is *so* hard to read. I'm used to reading assembler. Could you please maintain your code in assembler instead, or at least in parallel, so it would be easier for me to read?" Put simply, *I'm* going to say "no". *Always*. Even though, in both cases, I agree there are situations where the lower-level-language version *is* easier to read for certain kinds of uses, I'll always lean towards making a bigger investment in improving my C code, the C language, and C compilers, than would be needed to get some improvement in maintaining a *particular* version of my code in assembler -- because I'm (as always) looking at the *long-term* costs of maintenance. But, if a bunch of you want to get together and form the "GNU man-page project", to meet and prioritize which GNU man pages you think are most important to write (we've, e.g. the g77 man pages, have been calling for volunteers to do that for *years*), by all means, go to it. I'd suggest you figure out what *conceptual* information you really want, first; how to best architect that into the present *Texinfo* document (not just what new @-style markup you might need, but how typical GNU Texinfo docs could be better architected overall); then perhaps how to mark it up in a canonical way so automatic extraction tools can convert the Texinfo to man pages, at which point you can collaborate on providing such a tool. There's already @ifhtml/@end ifhtml, as well as @ifinfo, etc. A @ifman might be appropriate, but I'd hope that, if you did your homework properly, higher-level constructs would be more suitable. (If man pages were important to *me*, I'd have done the above as of about three years ago. If you want to hire me as a consultant to do some of the work, I'm *definitely* open to that, and have plenty of expertise across the spectrum, having architected, designed, and built documentation systems, including indexing tools for tech writers, in the past. That I don't see it as anywhere near important enough for me to spend my *volunteer* time doing it does not mean I'd give such a project short shrift!) But please, *please*, stop pestering any of the various GNU development lists with these discussions any further. Get your *own* list, invite people onto it, set up a web page (call it "The GNU Needs A Real Man Page" or something clever ;-), announce it on gnu.announce, whatever. Realize that any solution to this problem is, IMO, going to involve GNU developers like myself *only* to the extent that it constitutes high-level improvements to how we write *Texinfo* (and therefore our Info, HTML, DVI-printed, etc.) documentation. That's because most of us recognize that maintaining *two* forms of documentation is a *lose*, and that, at least for now, Texinfo is pretty much our #1 choice, when looking at all the factors, while man-page (nroff) format is probably not even in the top 5 or 10. And if you want to get an idea of how much better a use we could make of *Texinfo* format than we already do today, try compiling this line as file "foo.f" via g77 -- "99999 %invalid token" -- and "follow" the link given, using either "info -f", or Emacs Info mode's "m" command (first look for "M", then "LEX", as directed). Then ask yourself, how would that much documentation on a *diagnostic* be fit appropriately into the man-page system you love so much, how would it be dynamically hyperlinked-to, how well (vs. Texinfo) does it "scale up" to real end-user systems like the various windowing free-software GUIs people are designing (for Linux, for example), how well (vs. Texinfo) is it prepared for improvements for internationalization, etc.? I mean, I think *Texinfo*, and the GNU documentation written in it, has a long race to run, to be really great, and I haven't convinced myself (yet) that they'll even be able to *finish* -- that a whole new paradigm won't be needed down the road, one that is to Texinfo what Texinfo is to man pages. But, from what I've seen, man pages aren't even in the *race* -- they're sitting on the couch, watching it on TV, recalling their glory days. Give me a pointer to a web page to convince me (and the GNU people who make the high-level decisions about this) otherwise, if you like. In the meantime, stop pestering GNU development mailing-lists with this issue. It's just *so* annoying hearing the same tired old arguments over and over again, on a forum where we're supposed to be getting work done. tq vm, (burley) ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-24 0:31 ` rich-paul 1999-04-24 0:50 ` CaT 1999-04-24 5:50 ` craig @ 1999-04-30 23:15 ` rich-paul 2 siblings, 0 replies; 40+ messages in thread From: rich-paul @ 1999-04-30 23:15 UTC (permalink / raw) To: Joe Buck; +Cc: Andreas Schwab, pfeifer, psycho, oliva, cat, egcs On Fri, 23 Apr 1999, Joe Buck wrote: > > That's what info gcc 'invoking gcc' is for. With the current texinfo > > snapshot you can even say info --show-options gcc. > > This is why I think that the gcc man page should be obtained by coverting > invoke.texi. > > The vast majority of software on any Unix, GNU/Linux, or BSD system has > documentation in the form of man pages. Users expect to type "man". Just to put in my two cents, 'invoking gcc' very nice for what it is, but it ain't no man page. One of the great things about man pages is that they have a very specific set of sections, normally in the same order. Near the top, they have a canonical list of flags, so that when you find some invocation you don't grok in some makefile somewhere, you have a hope of finding a clue. It won't tell you all the whys and wherefores, but it will give you just a QUICK idea of what the damn thing does. I'm not against, in principal, converting to man pages from texinfo, but I've never seen anything in a texinfo file anywhere as quick and useful as a man page. A better solution might be to use the perl pod format, since it's extremely simple, and converts to troff as well as sweetened and unsweetened ascii. It's easier to use ( read *MUCH* easier ) than troff, which is as ugly as postscript, and most importantly, the results will be paged through things that search with the / key, as they should. <G> Of course the man page maintainer would have to have perl, but who doesn't? ( We can make this two ... two ... two flamewars in one! ;) --- There is a party that | Libertarian Party | A victimless crime is supports the right to | http://www.lp.org | a contradiction in free speech and | The Party of | terms. encryption!! | Principle | ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-23 9:12 ` Joe Buck 1999-04-24 0:31 ` rich-paul @ 1999-04-30 23:15 ` Joe Buck 1 sibling, 0 replies; 40+ messages in thread From: Joe Buck @ 1999-04-30 23:15 UTC (permalink / raw) To: Andreas Schwab; +Cc: jbuck, pfeifer, psycho, oliva, cat, egcs I wrote: > |> The key is to define the purpose of man pages. They are not complete > |> documentation, the gcc manual is. Rather, they should be a quick > |> reference, describing how to invoke gcc, giving the meaning of the flags, > |> and pointing the user to the gcc manual for further details. Andreas Schwab wrote: > That's what info gcc 'invoking gcc' is for. With the current texinfo > snapshot you can even say info --show-options gcc. This is why I think that the gcc man page should be obtained by coverting invoke.texi. The vast majority of software on any Unix, GNU/Linux, or BSD system has documentation in the form of man pages. Users expect to type "man". Now, of course we could make "null manpages" that tell the user to run info --show-options gcc. Or maybe we can have a version of the "man" program that can invoke "info --show-options". But we then have to fix the other places where "man" is used (the Emacs manual-entry command) and support the other behavior. There's also "man -t". ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-23 1:52 ` Andreas Schwab 1999-04-23 9:12 ` Joe Buck @ 1999-04-23 10:52 ` Marc Espie 1999-04-23 11:00 ` Joe Buck 1999-04-30 23:15 ` Marc Espie 1999-04-30 23:15 ` Andreas Schwab 2 siblings, 2 replies; 40+ messages in thread From: Marc Espie @ 1999-04-23 10:52 UTC (permalink / raw) To: egcs In article < vyzzp3zsoxd.fsf@issan.cs.uni-dortmund.de > you write: >Joe Buck <jbuck@Synopsys.COM> writes: > >|> The key is to define the purpose of man pages. They are not complete >|> documentation, the gcc manual is. Rather, they should be a quick >|> reference, describing how to invoke gcc, giving the meaning of the flags, >|> and pointing the user to the gcc manual for further details. > >That's what info gcc 'invoking gcc' is for. With the current texinfo >snapshot you can even say info --show-options gcc. If you want to get rid of manpages, first get out an info stand-alone reader that is easy to use, *merges seamlessly with existing manpages*, and is easy to use. I know, the reason info is ugly is so that you will use emacs instead. Some of us wouldn't touch emacs with a ten foot pole, though. Some of us don't like info because the resulting documentation is generally badly thought out and formatted (not so for gcc, though it's not perfect yet). Speaking for my own church, BSD manpages tend to get to the point: plain text tends to do wonders to one's crispness, and end with reference texts that go to the point. For an automatic conversion, I've found a tool in our ports tree that is called rman, and is supposed to convert formatted man pages back to unformatted nroff. (check ftp://ftp.cs.berkeley.edu/ucb/people/phelps/tcltk/rman-3.0.5.tar.Z that's what the port Makefile says) No, it's not a free tool, it has a restrictive licence, somewhat. But I don't particularly care. I'll try to give it a run on invoke.texi. ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-23 10:52 ` Marc Espie @ 1999-04-23 11:00 ` Joe Buck 1999-04-30 23:15 ` Joe Buck 1999-04-30 23:15 ` Marc Espie 1 sibling, 1 reply; 40+ messages in thread From: Joe Buck @ 1999-04-23 11:00 UTC (permalink / raw) To: Marc Espie; +Cc: egcs > If you want to get rid of manpages, first get out an info stand-alone reader > that is easy to use, *merges seamlessly with existing manpages*, and is > easy to use. Before we get into a war over info format again, remember that Texinfo, not info, is the source format, and texi2html, or TeX with texinfo.tex, gives pretty good output. > For an automatic conversion, I've found a tool in our ports tree that is > called rman, and is supposed to convert formatted man pages back to > unformatted nroff. That tool presumably tries to turn the kinds of files found in /usr/man/cat1/... into nroff man files. > I'll try to give it a run on invoke.texi. It's not going to work. We need something that translates things like @samp, @itemize, @section, etc into their nroff equivalents. rman will be more likely to work on the *output* -- the part of gcc.info that is generated from invoke.texi. ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-23 11:00 ` Joe Buck @ 1999-04-30 23:15 ` Joe Buck 0 siblings, 0 replies; 40+ messages in thread From: Joe Buck @ 1999-04-30 23:15 UTC (permalink / raw) To: Marc Espie; +Cc: egcs > If you want to get rid of manpages, first get out an info stand-alone reader > that is easy to use, *merges seamlessly with existing manpages*, and is > easy to use. Before we get into a war over info format again, remember that Texinfo, not info, is the source format, and texi2html, or TeX with texinfo.tex, gives pretty good output. > For an automatic conversion, I've found a tool in our ports tree that is > called rman, and is supposed to convert formatted man pages back to > unformatted nroff. That tool presumably tries to turn the kinds of files found in /usr/man/cat1/... into nroff man files. > I'll try to give it a run on invoke.texi. It's not going to work. We need something that translates things like @samp, @itemize, @section, etc into their nroff equivalents. rman will be more likely to work on the *output* -- the part of gcc.info that is generated from invoke.texi. ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-23 10:52 ` Marc Espie 1999-04-23 11:00 ` Joe Buck @ 1999-04-30 23:15 ` Marc Espie 1 sibling, 0 replies; 40+ messages in thread From: Marc Espie @ 1999-04-30 23:15 UTC (permalink / raw) To: egcs In article < vyzzp3zsoxd.fsf@issan.cs.uni-dortmund.de > you write: >Joe Buck <jbuck@Synopsys.COM> writes: > >|> The key is to define the purpose of man pages. They are not complete >|> documentation, the gcc manual is. Rather, they should be a quick >|> reference, describing how to invoke gcc, giving the meaning of the flags, >|> and pointing the user to the gcc manual for further details. > >That's what info gcc 'invoking gcc' is for. With the current texinfo >snapshot you can even say info --show-options gcc. If you want to get rid of manpages, first get out an info stand-alone reader that is easy to use, *merges seamlessly with existing manpages*, and is easy to use. I know, the reason info is ugly is so that you will use emacs instead. Some of us wouldn't touch emacs with a ten foot pole, though. Some of us don't like info because the resulting documentation is generally badly thought out and formatted (not so for gcc, though it's not perfect yet). Speaking for my own church, BSD manpages tend to get to the point: plain text tends to do wonders to one's crispness, and end with reference texts that go to the point. For an automatic conversion, I've found a tool in our ports tree that is called rman, and is supposed to convert formatted man pages back to unformatted nroff. (check ftp://ftp.cs.berkeley.edu/ucb/people/phelps/tcltk/rman-3.0.5.tar.Z that's what the port Makefile says) No, it's not a free tool, it has a restrictive licence, somewhat. But I don't particularly care. I'll try to give it a run on invoke.texi. ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-23 1:52 ` Andreas Schwab 1999-04-23 9:12 ` Joe Buck 1999-04-23 10:52 ` Marc Espie @ 1999-04-30 23:15 ` Andreas Schwab 2 siblings, 0 replies; 40+ messages in thread From: Andreas Schwab @ 1999-04-30 23:15 UTC (permalink / raw) To: Joe Buck; +Cc: pfeifer Joe Buck <jbuck@Synopsys.COM> writes: |> The key is to define the purpose of man pages. They are not complete |> documentation, the gcc manual is. Rather, they should be a quick |> reference, describing how to invoke gcc, giving the meaning of the flags, |> and pointing the user to the gcc manual for further details. That's what info gcc 'invoking gcc' is for. With the current texinfo snapshot you can even say info --show-options gcc. -- Andreas Schwab "And now for something schwab@issan.cs.uni-dortmund.de completely different" schwab@gnu.org ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-22 16:44 ` Joe Buck 1999-04-22 22:19 ` Jeffrey A Law 1999-04-23 1:52 ` Andreas Schwab @ 1999-04-30 23:15 ` Joe Buck 2 siblings, 0 replies; 40+ messages in thread From: Joe Buck @ 1999-04-30 23:15 UTC (permalink / raw) To: pfeifer; +Cc: psycho, oliva, cat, egcs > On Fri, 23 Apr 1999, Keith Duthie wrote: > > I'm not entirely sure why the FSF wants to get rid of man pages in favour > > of info files, but I for one turn to info only as a last resort, whereas I > > turn to man as a first resort. > > ...thus getting obsolete, incomplete and probably even incorrect > information in the case of egcs. :-( > > That's exactly why I suggest removing these man pages from the egcs > distribution. Sigh. man pages are necessary. For those of us who have used Unix for years, they are almost a way of life. The GNU project has attempted to get rid of them, but hasn't really succeeded. The key is to define the purpose of man pages. They are not complete documentation, the gcc manual is. Rather, they should be a quick reference, describing how to invoke gcc, giving the meaning of the flags, and pointing the user to the gcc manual for further details. With a proper scope it shouldn't be so hard to keep the manual in sync. The best way would be to obtain gcc.1 by conversion of invoke.texi, with possibly a small header and footer added. If no one else will do it, perhaps I can find some time, but probably not until mid-May. ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-22 16:10 ` Gerald Pfeifer 1999-04-22 16:44 ` Joe Buck @ 1999-04-30 23:15 ` Gerald Pfeifer 1 sibling, 0 replies; 40+ messages in thread From: Gerald Pfeifer @ 1999-04-30 23:15 UTC (permalink / raw) To: Keith Duthie; +Cc: Alexandre Oliva, CaT, egcs On Fri, 23 Apr 1999, Keith Duthie wrote: > I'm not entirely sure why the FSF wants to get rid of man pages in favour > of info files, but I for one turn to info only as a last resort, whereas I > turn to man as a first resort. ...thus getting obsolete, incomplete and probably even incorrect information in the case of egcs. :-( That's exactly why I suggest removing these man pages from the egcs distribution. Gerald -- Gerald "Jerry" pfeifer@dbai.tuwien.ac.at http://www.dbai.tuwien.ac.at/~pfeifer/ ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-22 10:23 ` Keith Duthie ` (2 preceding siblings ...) 1999-04-22 16:10 ` Gerald Pfeifer @ 1999-04-30 23:15 ` Keith Duthie 3 siblings, 0 replies; 40+ messages in thread From: Keith Duthie @ 1999-04-30 23:15 UTC (permalink / raw) To: Alexandre Oliva; +Cc: CaT, Gerald Pfeifer, egcs On 22 Apr 1999, Alexandre Oliva wrote: > On Apr 22, 1999, CaT <cat@zip.com.au> wrote: > > > html would be just as bad. :/ > > What's wrong with lynx? :-) The latest version seems to mess up the terminal fonts (I've probably misconfigured it). Other than that, nothing. > > What IS ionvolved in maintaining the man pages btw? > > Your sending legal papers to the FSF to become their official > maintainer? :-D Which is probably one of the main reasons why nobody has stepped forward. Perhaps someone could write a script to automagically convert the info files to man pages. I'm not entirely sure why the FSF wants to get rid of man pages in favour of info files, but I for one turn to info only as a last resort, whereas I turn to man as a first resort. -- .sig under deconstruction. Please watch out for falling stars. http://www.albatross.co.nz/~psycho/ O- ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-22 10:08 ` Alexandre Oliva 1999-04-22 10:22 ` CaT 1999-04-22 10:23 ` Keith Duthie @ 1999-04-30 23:15 ` Alexandre Oliva 2 siblings, 0 replies; 40+ messages in thread From: Alexandre Oliva @ 1999-04-30 23:15 UTC (permalink / raw) To: CaT; +Cc: pfeifer On Apr 22, 1999, CaT <cat@zip.com.au> wrote: > Gerald Pfeifer wrote the following: >> I therefore propose to remove those man pages, at least those that are >> obsolete and virtually unmaintained, from the distribution, and solely >> refer to the info and HTML docs. > html would be just as bad. :/ What's wrong with lynx? :-) > What IS ionvolved in maintaining the man pages btw? Your sending legal papers to the FSF to become their official maintainer? :-D -- Alexandre Oliva http://www.dcc.unicamp.br/~oliva IC-Unicamp, Brasil {oliva,Alexandre.Oliva}@dcc.unicamp.br aoliva@{acm.org,computer.org} oliva@{gnu.org,kaffe.org,{egcs,sourceware}.cygnus.com,samba.org} *** E-mail about software projects will be forwarded to mailing lists ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-22 9:52 ` CaT 1999-04-22 10:08 ` Alexandre Oliva @ 1999-04-30 23:15 ` CaT 1 sibling, 0 replies; 40+ messages in thread From: CaT @ 1999-04-30 23:15 UTC (permalink / raw) To: pfeifer; +Cc: egcs Gerald Pfeifer wrote the following: > > As far as I understand, our man pages have not been maintained for a > rather extensive period of time. > > Of course on the first page we have > This man page is not kept up to date except when volunteers > want to maintain it. > but, at least according to `cvs log` there are virtually no such > volunteers. > > I therefore propose to remove those man pages, at least those that are > obsolete and virtually unmaintained, from the distribution, and solely > refer to the info and HTML docs. Nooooo!!!!!!!! I hate the info system! *sob* And html would be just as bad. :/ What IS ionvolved in maintaining the man pages btw? > Gerald, fetching his asbesto suit... *chucks nuke at you* Bad Gerald, bad. ;) -- CaT (cat@zip.net.au) URL: http://www.zip.com.au/dev/null For a bad joke read: http://www2.hunterlink.net.au/~ddhrg/censorship_legislation.html ^ permalink raw reply [flat|nested] 40+ messages in thread
* (Getting rid of) man pages 1999-04-22 9:23 (Getting rid of) man pages Gerald Pfeifer 1999-04-22 9:35 ` Alexandre Oliva 1999-04-22 9:52 ` CaT @ 1999-04-30 23:15 ` Gerald Pfeifer 1999-06-25 6:25 ` Alexandre Oliva 3 siblings, 0 replies; 40+ messages in thread From: Gerald Pfeifer @ 1999-04-30 23:15 UTC (permalink / raw) To: egcs As far as I understand, our man pages have not been maintained for a rather extensive period of time. Of course on the first page we have This man page is not kept up to date except when volunteers want to maintain it. but, at least according to `cvs log` there are virtually no such volunteers. I therefore propose to remove those man pages, at least those that are obsolete and virtually unmaintained, from the distribution, and solely refer to the info and HTML docs. Gerald, fetching his asbesto suit... -- Gerald "Jerry" pfeifer@dbai.tuwien.ac.at http://www.dbai.tuwien.ac.at/~pfeifer/ ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-22 9:23 (Getting rid of) man pages Gerald Pfeifer ` (2 preceding siblings ...) 1999-04-30 23:15 ` Gerald Pfeifer @ 1999-06-25 6:25 ` Alexandre Oliva 1999-06-30 15:43 ` Alexandre Oliva 3 siblings, 1 reply; 40+ messages in thread From: Alexandre Oliva @ 1999-06-25 6:25 UTC (permalink / raw) To: egcs; +Cc: Brendan O'Dea I'd rather have this message stored in the egcs ML archives than accidentally removed forever from my mail box :-) ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-06-25 6:25 ` Alexandre Oliva @ 1999-06-30 15:43 ` Alexandre Oliva 0 siblings, 0 replies; 40+ messages in thread From: Alexandre Oliva @ 1999-06-30 15:43 UTC (permalink / raw) To: egcs; +Cc: Brendan O'Dea I'd rather have this message stored in the egcs ML archives than accidentally removed forever from my mail box :-) ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages @ 1999-04-23 11:10 Josh Stern 1999-04-30 23:15 ` Josh Stern 0 siblings, 1 reply; 40+ messages in thread From: Josh Stern @ 1999-04-23 11:10 UTC (permalink / raw) To: egcs, espie If anyone ever introduces a replacement format for manpages, it should be one that requires a sample of example usage (perhaps listed at the bottom of the page, or accessible through a hyperlink) for each of the major features of the utility in question (this isn't a problem for pages that document APIs). It would be an interesting thought experiment to try and estimate the amount, in dollars, of productivity that could have been saved by allowing people to quickly see examples of the major syntactic forms and usage of utilities that they are not familiar with - I think that a number described as "many billions" would be an appropriate guess. It shouldn't matter whether some originator thought of manpages as only a reminder for the already initiated - in practice they have come to serve as primary, and sometimes only documentation for the command line interface on many systems. - Josh ^ permalink raw reply [flat|nested] 40+ messages in thread
* Re: (Getting rid of) man pages 1999-04-23 11:10 Josh Stern @ 1999-04-30 23:15 ` Josh Stern 0 siblings, 0 replies; 40+ messages in thread From: Josh Stern @ 1999-04-30 23:15 UTC (permalink / raw) To: egcs, espie If anyone ever introduces a replacement format for manpages, it should be one that requires a sample of example usage (perhaps listed at the bottom of the page, or accessible through a hyperlink) for each of the major features of the utility in question (this isn't a problem for pages that document APIs). It would be an interesting thought experiment to try and estimate the amount, in dollars, of productivity that could have been saved by allowing people to quickly see examples of the major syntactic forms and usage of utilities that they are not familiar with - I think that a number described as "many billions" would be an appropriate guess. It shouldn't matter whether some originator thought of manpages as only a reminder for the already initiated - in practice they have come to serve as primary, and sometimes only documentation for the command line interface on many systems. - Josh ^ permalink raw reply [flat|nested] 40+ messages in thread
end of thread, other threads:[~1999-06-30 15:43 UTC | newest] Thread overview: 40+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 1999-04-22 9:23 (Getting rid of) man pages Gerald Pfeifer 1999-04-22 9:35 ` Alexandre Oliva 1999-04-30 23:15 ` Alexandre Oliva 1999-04-22 9:52 ` CaT 1999-04-22 10:08 ` Alexandre Oliva 1999-04-22 10:22 ` CaT 1999-04-30 23:15 ` CaT 1999-04-22 10:23 ` Keith Duthie 1999-04-22 10:26 ` CaT 1999-04-30 23:15 ` CaT 1999-04-22 10:31 ` Alexandre Oliva 1999-04-30 23:15 ` Alexandre Oliva 1999-04-22 16:10 ` Gerald Pfeifer 1999-04-22 16:44 ` Joe Buck 1999-04-22 22:19 ` Jeffrey A Law 1999-04-30 23:15 ` Jeffrey A Law 1999-04-23 1:52 ` Andreas Schwab 1999-04-23 9:12 ` Joe Buck 1999-04-24 0:31 ` rich-paul 1999-04-24 0:50 ` CaT 1999-04-30 23:15 ` CaT 1999-04-24 5:50 ` craig 1999-04-30 23:15 ` craig 1999-04-30 23:15 ` rich-paul 1999-04-30 23:15 ` Joe Buck 1999-04-23 10:52 ` Marc Espie 1999-04-23 11:00 ` Joe Buck 1999-04-30 23:15 ` Joe Buck 1999-04-30 23:15 ` Marc Espie 1999-04-30 23:15 ` Andreas Schwab 1999-04-30 23:15 ` Joe Buck 1999-04-30 23:15 ` Gerald Pfeifer 1999-04-30 23:15 ` Keith Duthie 1999-04-30 23:15 ` Alexandre Oliva 1999-04-30 23:15 ` CaT 1999-04-30 23:15 ` Gerald Pfeifer 1999-06-25 6:25 ` Alexandre Oliva 1999-06-30 15:43 ` Alexandre Oliva 1999-04-23 11:10 Josh Stern 1999-04-30 23:15 ` Josh Stern
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).