Re: (Getting rid of) man pages

Re: (Getting rid of) man pages

[Josh Stern]

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

Re: (Getting rid of) man pages

[Josh Stern]

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

Re: (Getting rid of) man pages

[Alexandre Oliva]

I'd rather have this message stored in the egcs ML archives than
accidentally removed forever from my mail box :-)

Re: (Getting rid of) man pages

[Alexandre Oliva]

I'd rather have this message stored in the egcs ML archives than
accidentally removed forever from my mail box :-)

Re: (Getting rid of) man pages

[Alexandre Oliva]

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

Re: (Getting rid of) man pages

[Joe Buck]

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

Re: (Getting rid of) man pages

[Alexandre Oliva]

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

Re: (Getting rid of) man pages

[CaT]

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

Re: (Getting rid of) man pages

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

Re: (Getting rid of) man pages

[Jeffrey A Law]

  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

Re: (Getting rid of) man pages

[Marc Espie]

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.

Re: (Getting rid of) man pages

[CaT]

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

Re: (Getting rid of) man pages

[Alexandre Oliva]

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

Re: (Getting rid of) man pages

[Joe Buck]

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

Re: (Getting rid of) man pages

[CaT]

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

(Getting rid of) man pages

[Gerald Pfeifer]

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/

Re: (Getting rid of) man pages

[Joe Buck]

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

Re: (Getting rid of) man pages

[CaT]

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

Re: (Getting rid of) man pages

[Andreas Schwab]

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

Re: (Getting rid of) man pages

[Gerald Pfeifer]

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/

Re: (Getting rid of) man pages

[rich-paul]

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      |  

Re: (Getting rid of) man pages

[Keith Duthie]

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-

Re: (Getting rid of) man pages

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

Re: (Getting rid of) man pages

[CaT]

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

Re: (Getting rid of) man pages

[rich-paul]

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      |  

Re: (Getting rid of) man pages

[Joe Buck]

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

Re: (Getting rid of) man pages

[Marc Espie]

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.

Re: (Getting rid of) man pages

[Joe Buck]

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

Re: (Getting rid of) man pages

[Andreas Schwab]

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

Re: (Getting rid of) man pages

[Jeffrey A Law]

  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

Re: (Getting rid of) man pages

[Joe Buck]

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

Re: (Getting rid of) man pages

[Gerald Pfeifer]

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/

Re: (Getting rid of) man pages

[Alexandre Oliva]

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

Re: (Getting rid of) man pages

[CaT]

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

Re: (Getting rid of) man pages

[Keith Duthie]

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-

Re: (Getting rid of) man pages

[CaT]

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

Re: (Getting rid of) man pages

[Alexandre Oliva]

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

Re: (Getting rid of) man pages

[CaT]

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

Re: (Getting rid of) man pages

[Alexandre Oliva]

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

(Getting rid of) man pages

[Gerald Pfeifer]

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/