Re: Man pages missing

Re: Man pages missing

[Karl E. Vogel]

>> On Fri, 31 Jan 1997 12:51:15 +0000 (GMT), 
>> Zefram <zefram@dcs.warwick.ac.uk> said:

Z> For me, it's much more effective to have all the documentation in one place,
Z> and browse it with my preferred pager.  Hypertext just gets in the way of
Z> the information, and there still isn't a hypertext system that formats to
Z> look as good as man pages.

   Exactly.  Hypertext is fine when you're already familiar with most of what
   you're looking at, and all you need is to zoom in on a topic when more
   details are needed.

Z> And have you ever tried to read `all the documentation' on some subject,
Z> when said documentation is arranged as an arbitrary directed graph of fifty
Z> nodes of two pages each?

   Yes, and it drives me nuts.  That's when I either look for or create a
   PostScript version of the entire document.  It's generally easy to print
   them double-sided on HP LaserJets without fiddling with the printer console,
   and if I don't need to keep it, there's always a recycle bin around.

   I've never seen any hypertext system which lets me flip around as quickly or
   as easily as a 3-ring binder.  However, without a good keyword or concept
   index, it doesn't matter if the documentation is printed or not; I probably
   won't be able to find what I want either way.

-- 
Karl Vogel                                          vogelke@c17.wpafb.af.mil
ASC/YCOA, Wright-Patterson AFB, OH 45433	                937-255-3688

Man pages missing

[Vidiot]

The following was sent out regarding the 3.1.1 release:

    The other big change is the new documentation format.  Thanks to Andrew
    Main the complete zsh documentation is now written in yodl.  Yodl is a
    document language somewhat similar SGML which can generate the nroff
    manpages and the texinfo manual from the same source.  The precompiled
    nroff and texinfo manuals are included in the distribution but if you would
    like to add something, you need to get yodl-1.14 (earlier versions had some
    serious bugs).  Yodl is available from ftp://ftp.icce.rug.nl/pub/unix/ and
    from the sinsite Linux arcives.

I'm sorry, but I can't find the *.man pages in the 3.1.1 release or the
zsh-doc release.  For those of use who do not have, or don't want, yodl,
it would be nice if the *.man pages were really in the Doc directory.  If
it was just a mistake for this release, I can survive until the next release
for these pages.

Is it me, or has the documentation become a rat's nest, i.e., g/n/troff,
TeX, texinfo and now yodl?  Just what we need, another text formatting
package to learn. :-)  Sorry to sound negative, but when is the progression
of manual preparation going to stick with one package?  If I run across
something in the manual that needs clarification, all I can do is send a
message to the mail list indicating what needs to be changed, instead of
including a diff file with the changes.  It means more work for someone
else, but to me the zsh manual is a bit much.  A manual that has nroff,
TeX and texinfo commands all wrapped within yodl commands.  What a nightmare,
at least for me.  I've never heard of yodl before.

I'll climb off my soapbox now and go into my corner.

MB
-- 
System Administrator - Finnigan FT/MS - Madison WI. <URL:http://www.ftms.com/>
e-mail: brown@ftms.com
phone: (608) 273-8262 ext: 612  fax: (608) 273-8719
Visit - <URL:http://www.cdsnet.net/vidiot/>  (Your link to Star Trek and UPN)

Re: Man pages missing

[Richard Coleman]

> Is it me, or has the documentation become a rat's nest, i.e., g/n/troff,
> TeX, texinfo and now yodl?  Just what we need, another text formatting
> package to learn. :-)  Sorry to sound negative, but when is the progression
> of manual preparation going to stick with one package?  If I run across
> something in the manual that needs clarification, all I can do is send a
> message to the mail list indicating what needs to be changed, instead of
> including a diff file with the changes.  It means more work for someone
> else, but to me the zsh manual is a bit much.  A manual that has nroff,
> TeX and texinfo commands all wrapped within yodl commands.  What a nightmare,
> at least for me.  I've never heard of yodl before.

But yodl is an attempt to bring order to this mess.  We've been
searching for some time for a set of tools and meta-document format
that would allow us to generate all the formats necessary, while
maintaining only one document base.  I researched the problem
when I was maintainer of zsh, but I couldn't find a solid (and
free) solution.  Yodl is fairly new, but appears to be the best
solution so far.

rc

Re: Man pages missing

[Zefram]

Vidiot wrote:
>I'm sorry, but I can't find the *.man pages in the 3.1.1 release or the
>zsh-doc release.  For those of use who do not have, or don't want, yodl,
>it would be nice if the *.man pages were really in the Doc directory.

They are there, they're just called *.1 now.

>Is it me, or has the documentation become a rat's nest, i.e., g/n/troff,
>TeX, texinfo and now yodl?

It has been a rat's nest for quite a while.  Immediately prior to the
introduction of yodl, we were distributing both nroff and TeXinfo
forms, with the Makefile having rules to make info, HTML, DVI and
PostScript forms (from the TeXinfo).

>                            Just what we need, another text formatting
>package to learn. :-)  Sorry to sound negative, but when is the progression
>of manual preparation going to stick with one package?  If I run across
>something in the manual that needs clarification, all I can do is send a
>message to the mail list indicating what needs to be changed, instead of
>including a diff file with the changes.

The point of using yodl is that we only need to maintain *one* form of
the manual.  You now don't need to understand both nroff and TeXinfo to
patch the man page.  And the yodl is, I think, easier to maintain than
either nroff or TeXinfo was.

-zefram

Re: Man pages missing

[Vidiot]

<>I'm sorry, but I can't find the *.man pages in the 3.1.1 release or the
<>zsh-doc release.  For those of use who do not have, or don't want, yodl,
<>it would be nice if the *.man pages were really in the Doc directory.
<
<They are there, they're just called *.1 now.

There are no *.1 files in zsh-3.1.1. I did a find search and zippo files
that end in .1.

<The point of using yodl is that we only need to maintain *one* form of
<the manual.  You now don't need to understand both nroff and TeXinfo to
<patch the man page.  And the yodl is, I think, easier to maintain than
<either nroff or TeXinfo was.

Then I must be seeing things.  The few .yo files that I sampled sure looked
like they had flavors of nroff and TeXinfo in them.  It looks like this:

COMMENT(--- man page headers ---)
 
def(manpage)(4)(\
  NOTRANS(.TH ")ARG1" "ARG2" "ARG3" "ARG4"\
)
def(manpagename)(2)(\
  sect(NAME)NL()\
  ARG1 - ARG2\
)
 
COMMENT(--- TeXinfo headers and conditionals ---)
 
def(texinfo)(2)(CMT())
 
def(texiifinfo)(1)()
def(texiiftex)(1)()
 
def(texititlepage)(0)(CMT())
def(texiendtitlepage)(0)(CMT())
def(texititle)(1)(CMT())
def(texisubtitle)(1)(CMT())
def(texiauthor)(1)(CMT())
 
def(texinode)(4)(CMT())
def(texitop)(1)(CMT())
 
COMMENT(--- section divisions ---)
 
def(chapter)(1)(CMT())
 
def(sect)(1)(\
  USECHARTABLE(toupper)\
  NOTRANS(.SH ")ARG1"NL()\
  USECHARTABLE(standard)\
  STDPAR()\
  CMT()\
)
 
def(subsect)(1)(\
  NOTRANS(.SS ")ARG1"NL()\
  CMT()\
)
 
COMMENT(--- comment output ---)
 
DEFINECHARTABLE(roffcomment)(
  '\n' = "\n.\\\" "
)
def(comment)(1)(\
  USECHARTABLE(roffcomment)\
  NOTRANS(.\" )ARG1\
  USECHARTABLE(standard)\
)
 

To me this means one has to program yodl macros to handle nroff and texi
stuff (if something wasn't already defined).

In any event, I know n/t/groff and can muddle through TeX stuff.  I'll
be damned if I am going to learn yodl.  To learn yet another text processor
is just too much.  So forgive me if I only send in changes to documentation
via quoting the current text and suggesting changes.  If a format change
is needed, I will just have to indicate what needs to be done.

I can just hear it now... what a wimp.  So be it.  I have so many things I
have to know for my job, this is just one thing that breaks the camel's back.

MB
-- 
System Administrator - Finnigan FT/MS - Madison WI. <URL:http://www.ftms.com/>
e-mail: brown@ftms.com
phone: (608) 273-8262 ext: 612  fax: (608) 273-8719
Visit - <URL:http://www.cdsnet.net/vidiot/>  (Your link to Star Trek and UPN)

Re: Man pages missing

[Hrvoje Niksic]

 (brown@ftms.com) wrote:
> Then I must be seeing things.  The few .yo files that I sampled sure looked
> like they had flavors of nroff and TeXinfo in them.  It looks like this:
> 
> COMMENT(--- man page headers ---)
[...]

But these are the headers definition, I believe.  The text of the
manual is quite independent of the output format (nroff/texinfo).

> In any event, I know n/t/groff and can muddle through TeX stuff.
> I'll be damned if I am going to learn yodl.  To learn yet another
> text processor is just too much.

No, it's not too much.  What's too much is to have to handle too
different documentation format, and sync them all the time.

> So forgive me if I only send in changes to documentation
> via quoting the current text and suggesting changes.  If a format change
> is needed, I will just have to indicate what needs to be done.

As always, that's your choice; noone forces you to send documentation
patches.

-- 
Hrvoje Niksic <hniksic@srce.hr> | Student at FER Zagreb, Croatia
--------------------------------+--------------------------------
A: Vi is the God of editors.
B: Emacs is the editor of Gods.

Re: Man pages missing

[Vidiot]

<> In any event, I know n/t/groff and can muddle through TeX stuff.
<> I'll be damned if I am going to learn yodl.  To learn yet another
<> text processor is just too much.
<
<No, it's not too much.  What's too much is to have to handle too
<different documentation format, and sync them all the time.

I commented to RC separately about the documentation.  Personally I think
the man pages and the manual should be separated.  The man pages should be
very brief, to the point that the zsh man page could be only a couple of
pages long.

The manual should be vastly expanded, adding lots of examples of how all
of the various functions work.  Te current documentation discusses all
of the little pieces, but the big picture is easily lost.

The main manual should be done using a package like Framemaker, which would
allow for easier WYSIWYG editing and formatting.  Lots of examples could
be added to the document.  Zsh needs a decent manual.  What we have now
are the man pages without the nroff/man-page-looking-format.

Yes it would be a big project, something that I think Zsh deserves.

Using FrameMaker would also allow for the document to be turned into a PDF
file for on-line help.  Frankly, the current help files are old fashioned.
A state-of-the-art shell needs state-of-the-art manuals.

Those are my thoughts.

MB
-- 
System Administrator - Finnigan FT/MS - Madison WI. <URL:http://www.ftms.com/>
e-mail: brown@ftms.com
phone: (608) 273-8262 ext: 612  fax: (608) 273-8719
Visit - <URL:http://www.cdsnet.net/vidiot/>  (Your link to Star Trek and UPN)

Re: Man pages missing

[Hrvoje Niksic]

 (brown@ftms.com) wrote:
> <No, it's not too much.  What's too much is to have to handle too
> <different documentation format, and sync them all the time.
> 
> I commented to RC separately about the documentation.  Personally I think
> the man pages and the manual should be separated.  The man pages should be
> very brief, to the point that the zsh man page could be only a couple of
> pages long.

This is the approach some programs use (e.g. elm), and some not
(Perl, Emacs[1]).  It is simply a matter of choice; I like the choice
zsh developers made.

> Using FrameMaker would also allow for the document to be turned into a PDF
> file for on-line help.  Frankly, the current help files are old fashioned.
> A state-of-the-art shell needs state-of-the-art manuals.

I don't see anything wrong with the "old-fashioned" help currently
used.  Before thinking about converting to something different, one
should think about all the advantages of PDF over TexInfo?  Is there a
freely available viewer for PDF files?  Can they be viewed on a text
terminal?

-- 
Hrvoje Niksic <hniksic@srce.hr> | Student at FER Zagreb, Croatia
--------------------------------+--------------------------------
Good pings come in small packets.

Re: Man pages missing

[Vidiot]

<> I commented to RC separately about the documentation.  Personally I think
<> the man pages and the manual should be separated.  The man pages should be
<> very brief, to the point that the zsh man page could be only a couple of
<> pages long.
<
<This is the approach some programs use (e.g. elm), and some not
<(Perl, Emacs[1]).  It is simply a matter of choice; I like the choice
<zsh developers made.

Perl is a bad example, since there are books available in your local book
store.  Zsh has no such book and really needs one.

<> Using FrameMaker would also allow for the document to be turned into a PDF
<> file for on-line help.  Frankly, the current help files are old fashioned.
<> A state-of-the-art shell needs state-of-the-art manuals.
<
<I don't see anything wrong with the "old-fashioned" help currently
<used.  Before thinking about converting to something different, one
<should think about all the advantages of PDF over TexInfo?  Is there a
<freely available viewer for PDF files?  Can they be viewed on a text
<terminal?

Advantages: graphical, can included visual examples (though I admit that there
     isn't much in the way of graphics :-); the user can scale the size of
     the help pages to suite the needs of the user; hypertext TOC and index;
     just to name a few.

Disadvantages: doesn't work on text-only systems (how many of these are
     still around (one shouldn't cripple the on-line help because of a lack of
     X-windows); paging thru the pages and lines is not obvious

I've used texinfo a few times and do not like the interface.  One tends to
hit the return key to move down lines.  Well, that can't be done in texinfo
help files (at least that is the way it used to be, is it still that way?).

In any event one can argue about the best way for both systems.  I personally
prefer a physical copy of a manual.  With PDF the user has the choice of
using it on-line or printing it and making a copy that looks just like
the on-line version, graphics and all.  A pure text manual from texinfo
can't do that.  Of course, the source files for the text processor would
be available and FrameMaker allows for the documentation to be used on all
three major platforms; Unix, PC, Mac.

Again, these are my thoughts.

MB
-- 
System Administrator - Finnigan FT/MS - Madison WI. <URL:http://www.ftms.com/>
e-mail: brown@ftms.com
phone: (608) 273-8262 ext: 612  fax: (608) 273-8719
Visit - <URL:http://www.cdsnet.net/vidiot/>  (Your link to Star Trek and UPN)

Re: Man pages missing

[James B. Crigler]

>>>>>>> Vidiot == <brown@ftms.com> writes:

 Vidiot> Perl is a bad example, since there are books available in
 Vidiot> your local book store.  Zsh has no such book and really needs
 Vidiot> one.

Sorry, but I have to disagree.  I just started learning perl, and
while I'm sure there are nuances I'll miss, the layout of the perl man
pages is very helpful in learning the basic metaphors and many of the
specifics.  And using the perl man pages in emacs is a breeze: Just go
to the main page, and use some keystrokes as a quick navigation tool.
Emacs will also follow references to other man pages (though, like
info, it won't position you to the specific referenced thing on a
longish page).

HTML would be okay as long as there are indexes and tables of contents.

-- 
Jim Crigler <crigler@seo.com>
Schwartz Electro-Optics, Inc.   Voice:  (407)298-1802 x200
3404 N. Orange Blossom Tr.        Fax:  (407)290-9666
Orlando FL 32804-3498 USA

Re: Man pages missing

[Bruce Stephens]

> Perl is a bad example, since there are books available in your local book
> store.  Zsh has no such book and really needs one.

I'd agree here.  When the dynamic loading and programmable zle stuff is
in, I'd have thought a book would be worthwhile.  Has anybody who
actually understands all of zsh looked into publisher interest in such
a thing?  The manual is pretty good, but it's still a bit referency.
The intro was pretty good, the last time I looked at it, but I'd pay
money for a full-length book covering the whole thing (especially once
the important new features have settled down a bit---if the dynamic
loading could be made compatible with ksh93's, and if it could drag in
Tk (perhaps not just yet, but when some future version of Tk is more
language independent), then surely that would sell).

> Advantages: graphical, can included visual examples (though I admit that there
>      isn't much in the way of graphics :-); the user can scale the size of
>      the help pages to suite the needs of the user; hypertext TOC and index;
>      just to name a few.

(On PDF.)  I don't see that much need for pictures.  If they're needed,
Texinfo can do them (you can put arbitrary TeX into the printed
version, and give other text (perhaps a character version of the
picture) for the online version.  Presumably the texinfo2html converter
can do pictures, or could easily be hacked to do them.  Presumably yodl
can also do something that allows access to these features, or could
easily be extended to do so.

> I've used texinfo a few times and do not like the interface.  One tends to
> hit the return key to move down lines.

Really?  I've never found myself doing that.  If it's such a big thing,
you could customize emacs to do that, assuming you're using emacs.  I
couldn't really recommend the standalone info reader---there's
something of a need for a nice up to date X-based reader.

> In any event one can argue about the best way for both systems.  I personally
> prefer a physical copy of a manual.  With PDF the user has the choice of
> using it on-line or printing it and making a copy that looks just like
> the on-line version, graphics and all.  A pure text manual from texinfo
> can't do that.

That's true, but it's deliberate.  I don't need menus in my printed
manual, but they're very useful when reading online.  Pictures are a
bit of a problem, but presumably not for zsh?  Personally, I'd hate
PDF-only manuals: Adobe's Acrobat reader is slow, pretty unreadable,
and generally clunky, especially compared with info in Emacs.  And I've
never found printing with it to be particularly successful
either---horribly slow, horribly big PostScript files.

> Of course, the source files for the text processor would
> be available and FrameMaker allows for the documentation to be used on all
> three major platforms; Unix, PC, Mac.

What's "FrameMaker"?  Should I have heard of it?   If it's commercial,
then I think zsh should avoid requiring it, including for development,
but certainly for use.

Re: Man pages missing

[Hrvoje Niksic]

 (brown@ftms.com) wrote:
> <This is the approach some programs use (e.g. elm), and some not
> <(Perl, Emacs[1]).  It is simply a matter of choice; I like the choice
> <zsh developers made.
> 
> Perl is a bad example, since there are books available in your local book
> store.  Zsh has no such book and really needs one.

No, it's not a bad example.  When I say online documentation, I mean
it.  I know I can always buy the book from the bookstore.

> <I don't see anything wrong with the "old-fashioned" help currently
> <used.  Before thinking about converting to something different, one
> <should think about all the advantages of PDF over TexInfo?  Is there a
> <freely available viewer for PDF files?  Can they be viewed on a text
> <terminal?
> 
> Advantages: graphical, can included visual examples (though I admit that there
>      isn't much in the way of graphics :-); the user can scale the size of
>      the help pages to suite the needs of the user; hypertext TOC and index;
>      just to name a few.

Texinfo has almost all of this.

> Disadvantages: doesn't work on text-only systems (how many of these are
>      still around

Then forget it.  Yes, there are many text-only systems around, believe
it or not.

> (one shouldn't cripple the on-line help because of a lack of
>      X-windows);

Remember; we're talking about the documentation of a Unix shell.

> I've used texinfo a few times and do not like the interface.  One tends to
> hit the return key to move down lines.  Well, that can't be done in texinfo
> help files (at least that is the way it used to be, is it still that way?).

You can always press `1 C-v', if you use Emacs.  RET is used to follow
nodes.

> In any event one can argue about the best way for both systems.  I personally
> prefer a physical copy of a manual.

It's quite easy to print out the Texinfo manuals.  Thus we can have it
both ways -- you will have a nice, printed copy, and we'll be able to
browse it online.

-- 
Hrvoje Niksic <hniksic@srce.hr> | Student at FER Zagreb, Croatia
--------------------------------+--------------------------------
Ask not for whom the <CONTROL-G> tolls.

Re: Man pages missing

[Juergen Erhard]

>>>>> "Vidiot" == Vidiot  <brown@ftms.COM> writes:
    > 
    > Perl is a bad example, since there are books available in your local book
    > store.  Zsh has no such book and really needs one.

Wouldn't hurt zsh's rep...

    > <> Using FrameMaker would also allow for the document to be turned into a PDF
    > <> file for on-line help.  Frankly, the current help files are old fashioned.
    > <> A state-of-the-art shell needs state-of-the-art manuals.

Not all that's 'old-fashioned' is bad... and not all that's new is
good, either.

Now for some major snippage:

[SNIIIIIIIIIIIIIIIIIIIIIIIIP]

    > Advantages: graphical, can included visual examples (though I admit that there
    >      isn't much in the way of graphics :-); the user can scale the size of
    >      the help pages to suite the needs of the user; hypertext TOC and index;
    >      just to name a few.

Yeah, sure whatever... not that I mind a guey... but, and there's a
big BUT coming up...

    > Disadvantages: doesn't work on text-only systems (how many of these are
    >      still around (one shouldn't cripple the on-line help because of a lack of
    >      X-windows); paging thru the pages and lines is not obvious

Forgot one majorly major disadvantage: no free preparator...

Yeah and this here is one point that REEEEEEEALLY got me majorly
wondering... you just a post or two away said you don't like not
having access to the source of the zsh man-pages (in a format you're
familiar with)...

AND NOW YOU GO AND PROPOSE FRAMEMAKER!!!!!! Excuse me for using the
megaphone, but...

FrameMaker is a proprietary (read: non-free) and rather expensive (in
my view) application that certainly not very many people on this list
(or, if we limit the scope of this discussion to the developers) have
access too...

I mean, what I can't reconcile is that first you complain not being
able to send in source patches for the manual, and then you propose
using a system for said manual that'd make it impossible (instead of
just uncomfortable... for the maintainer(s)) for a whole lot of people
to work with the manual source.

Riddle me this... I don't get it.

[another couple lines fell victim a pair 'o scissors]

    > I personally
    > prefer a physical copy of a manual.

Hey, I don't want to keep you from gettin a lot of paper...

    > With PDF the user has the choice of
    > using it on-line or printing it and making a copy that looks just like
    > the on-line version, graphics and all.

Texinfo... no prob. Only the appearance on screen and on paper is not
identical.

    > A pure text manual from texinfo
    > can't do that.

No, not if I don#t have the source... and I hate it if I don't have
the .texi source!

    > Of course, the source files for the text processor would
    > be available and FrameMaker allows for the documentation to be used on all
    > three major platforms; Unix, PC, Mac.

Yeah, until FrameMaker (the company...) decides that Unix is not
economically viable anymore (according to Bob Fences (obscure L&C
ref), Unix has less than 1% market share)...

    > 
    > Again, these are my thoughts.

And these were mine...

Oh, and sorry if I've gotten a little loud there... *I* am not your
enemy (M$, on the other hand...)

    > Visit - <URL:http://www.cdsnet.net/vidiot/>  (Your link to Star Trek and UPN)

I'll do that ;-)

-- 
.sig *still* in the repair shop...

Re: Man pages missing

[Uli Zappe]

Hi,

sorry for intervening in this thread - I just got to read one mail  
from it - but where is the problem with zsh's manpages "not  
available in a graphic capable, platform independet format" to print  
out your own manual as a book?

I got me the zsh manual in postscript, a graphic capable, platform  
independet format, printed it out, and it looks great!

So what's this thread about?


                Bye
                        Uli

______________________________________________________________________

Uli Zappe               E-Mail: uli@tallowcross.uni-frankfurt.de
                                (NeXTMail,Mime,ASCII) PGP on request
Lorscher Strasse 5      WWW:    -
D-60489 Frankfurt       Fon:    +49 (69) 9784 0007
Germany                 Fax:    +49 (69) 9784 0042

staff member of NEXTTOYOU - the German NEXTSTEP/OPENSTEP magazine
______________________________________________________________________

Re: man pages missing

[Duncan Sargeant]

jae (Juergen Erhard) claimed on Wed, Feb 26, 1997 at 07:51:53PM +0100 Feb 26:

> >>>>> "Vidiot" == Vidiot  <brown@ftms.COM> writes:
> 
>     > Disadvantages: doesn't work on text-only systems (how many of these are
>     >      still around (one shouldn't cripple the on-line help because of a lack of
>     >      X-windows); paging thru the pages and lines is not obvious
 
*I* still use a "text-only" system.  Almost everyday I use the
a DEC vt220.  A bit slow because it only does 9600bps reliably, but
still useful.  At the University Computer Club, UWA, we've got about
seven in the clubroom.  Do they get used?  its often tough to find
one free...

someone's donating a couple of DEC vt320's to us in the next couple
of days.  I'm hoping they handle 19200 acceptably. (vt220's handle
it, but every n'th character gets corrupted.)

anyway, I'm sure there are millions of people just like us living
off the donated equipment of the more fortunate.

BTW, if anyone wants to donate an old SMD controller, we have a 
Sun 3/280 in need :)

,dunc

-- 
Duncan Sargeant, keraunothnetophobic.   WWW: http://www.ucc.gu.uwa.edu.au/~dunc/
Orr would be crazy to fly more missions and sane if he didnt, but if he was sane
he had to fly them.  If he flew then he was crazy and didn't have to; but if he
didn't want to he was sane and had to.  Yossarian was moved deeply and let out a
respectful whistle at the absolute simplicity of this clause of Catch-22. --jh

Re: Man pages missing

[Zefram]

Vidiot wrote:
>I commented to RC separately about the documentation.  Personally I think
>the man pages and the manual should be separated.  The man pages should be
>very brief, to the point that the zsh man page could be only a couple of
>pages long.

No!  man pages are the primary form of online documentation for Unix
programs; they *must* have complete information.  I regularly look
things up in the man page, and would be severely inconvenienced if I
had to log in to a graphical terminal and fire up ghostview (or
whatever) to get authoritative information.

(Nor would I want to print out the manual.  That would cost me money,
and waste paper, and be less convenient than online documentation, and
it would be difficult to keep up with each new release.)

>The main manual should be done using a package like Framemaker, which would
>allow for easier WYSIWYG editing and formatting.

Ease of editing is not really a significant consideration for most of
us, I suspect.  I've never yet seen a WYSIWYG system that was as good
as the WYGIWYG systems running on the same computers.

>                           Zsh needs a decent manual.  What we have now
>are the man pages without the nroff/man-page-looking-format.

And what do you have against man pages?

-zefram

Re: Man pages missing

[Juergen Christoffel]

   From: Zefram <zefram@dcs.warwick.ac.uk>
   Date: Fri, 31 Jan 1997 11:53:27 +0000 (GMT)

   Vidiot wrote:
   >I commented to RC separately about the documentation.  Personally I think
   >the man pages and the manual should be separated.  The man pages should be
   >very brief, to the point that the zsh man page could be only a couple of
   >pages long.

   No!  man pages are the primary form of online documentation for Unix
   programs; they *must* have complete information.  I regularly look
   things up in the man page, and would be severely inconvenienced if I
   had to log in to a graphical terminal and fire up ghostview (or
   whatever) to get authoritative information.

Man pages *must* have the complete documentation? I don't think so.
With today's complex commands (which somehow violate the Unix toolbox
philosophy of small tools put together to get work done anyway ;-)
man pages get so big that they tend to be much less useful. They
worked well for the small tools and work less well for the more
complex ones like perl or zsh.

It started with tools like perl; I'm a regular perl user and would not
want to miss it; but I remember the feeling I had when I first saw the
30 or so pages of perl in the early days. And as the man pages grow
larger it gets more difficult to locate a specific section because I
can't browse the whole stuff anymore and to find it with a regexp I
sometimes need two or three approaches to find stuff if I don't
remember the exact wording I'm looking for.

   (Nor would I want to print out the manual.  That would cost me money,
   and waste paper, and be less convenient than online documentation, and
   it would be difficult to keep up with each new release.)

There's no need to print out a manual if you don't want to. Today a
hypertext approach would work for me due to tools like lynx (the vt100
based web browser, so you wouldn't need Netscape or its ilk) or Emacs'
info mode. For me it's much more effective to browse through a well
organized manual with lynx or emacs than it is to page through 60+
pages of man pages with less.

I second Vidiot's suggestion to separate (a set of) terse man page(s)
and a much larger/better manual. I'd even be willing to help in
putting the latter together.

	--jc

Re: Man pages missing

[Zefram]

Juergen Christoffel wrote:
>It started with tools like perl; I'm a regular perl user and would not
>want to miss it; but I remember the feeling I had when I first saw the
>30 or so pages of perl in the early days. And as the man pages grow
>larger it gets more difficult to locate a specific section because I
>can't browse the whole stuff anymore and to find it with a regexp I
>sometimes need two or three approaches to find stuff if I don't
>remember the exact wording I'm looking for.

perl's OK.  A quick look at perl(1) will generally indicate which man
page actually contains the desired information, which one can the drag
a regexp over.  It's the same with zsh, except that zshall(1) can be
used to skip the first step (provided, of course, you have a caching
(or exceptionally fast) man pager).

>There's no need to print out a manual if you don't want to. Today a
>hypertext approach would work for me due to tools like lynx (the vt100

Actually lynx uses curses; it's not limited to vt100s.

>based web browser, so you wouldn't need Netscape or its ilk) or Emacs'
>info mode. For me it's much more effective to browse through a well
>organized manual with lynx or emacs than it is to page through 60+
>pages of man pages with less.

For me, it's much more effective to have all the documentation in one
place, and browse it with my preferred pager.  Hypertext just gets in
the way of the information, and there still isn't a hypertext system
that formats to look as good as man pages.  (And have you ever tried to
read `all the documentation' on some subject, when said documentation
is arranged as an arbitrary directed graph of fifty nodes of two pages
each?)

-zefram

Re: Man pages missing

[Bruce Stephens]

Zefram writes:

> For me, it's much more effective to have all the documentation in one
> place, and browse it with my preferred pager.  Hypertext just gets in
> the way of the information, and there still isn't a hypertext system
> that formats to look as good as man pages.  (And have you ever tried to
> read `all the documentation' on some subject, when said documentation
> is arranged as an arbitrary directed graph of fifty nodes of two pages
> each?)

I find Texinfo to be OK.  Using Emacs, it's easier to read than
manpages (although TkMan is wonderful, so I don't mind reading
manpages).  It also prints out nicely (it's annoying that it's awkward
to get PostScript fonts, but presumably they'll fix that one day), and
(and here I agree entirely with Zefram) it's easy to get the whole
manual, and easy to read the whole thing from beginning to end.  (It's
possible for sadists to produce manuals where you can't do this, but it
requires deliberate malice.)

If I had to pick *one* format, I'd choose Texinfo, but using yodl (so
we can get multiple formats) seems to work fine.

Re: Man pages missing

[Juergen Christoffel]

   From: Zefram <zefram@dcs.warwick.ac.uk>
   Date: Fri, 31 Jan 1997 12:51:15 +0000 (GMT)

   >There's no need to print out a manual if you don't want to. Today a
   >hypertext approach would work for me due to tools like lynx (the vt100

   Actually lynx uses curses; it's not limited to vt100s.

Usually I use "vt100" as a synonym when I mean character-based
displays; I should have been more careful here. And I use curses too
sometimes, but they don't work as good today as they did in the dark
ages ;-)

   >based web browser, so you wouldn't need Netscape or its ilk) or Emacs'
   >info mode. For me it's much more effective to browse through a well
   >organized manual with lynx or emacs than it is to page through 60+
   >pages of man pages with less.

   For me, it's much more effective to have all the documentation in one
   place, and browse it with my preferred pager.  Hypertext just gets in
   the way of the information, and there still isn't a hypertext system
   that formats to look as good as man pages.  

Hmm, I don't see such a great difference between lynx output and man
output. 

					       (And have you ever tried to
   read `all the documentation' on some subject, when said documentation
   is arranged as an arbitrary directed graph of fifty nodes of two pages
   each?)

It's easy to run down a concept by giving worst case scenarios. But if
you re-read my message, you'll note that I said "well organized
manual" and it is possible to create a document which follows a rather
linear structure _and_ offers links for fast cross-references to other
parts of the documentation and a good index with links.

If you have a chance to take a look at a Macintosh where MacPerl is
installed, you might want to take a look at the fine integration
Matthias Neeracher did between MacPerl, the perl man pages and
browsers like Netscape or Matthias' own lightweight pod viewer Shuck.

Cheers, JC

-- 
   E-Mail: christoffel@gmd.de or one of {ftp,news,web}master@gmd.de
   GMD - German National Research Center for Information Technology

GMD pays for my technical expertise. My opinions probably scare them...

Re: Man pages missing

[Hrvoje Niksic]

 (zefram@dcs.warwick.ac.uk) wrote:
> place, and browse it with my preferred pager.  Hypertext just gets in
> the way of the information, and there still isn't a hypertext system
> that formats to look as good as man pages.  (And have you ever tried to

Emacs Info is good in this respect; `s' in Info will let you search
for a regexp in all the info files (e.g. zsh.info*), which IMHO has
all the advantages of `man zshall(1)' and `info zsh'.

-- 
Hrvoje Niksic <hniksic@srce.hr> | Student at FER Zagreb, Croatia
--------------------------------+--------------------------------
Ask not for whom the <CONTROL-G> tolls.

Re: Man pages missing

[Vidiot]

<>I commented to RC separately about the documentation.  Personally I think
<>the man pages and the manual should be separated.  The man pages should be
<>very brief, to the point that the zsh man page could be only a couple of
<>pages long.
<
<No!  man pages are the primary form of online documentation for Unix
<programs; they *must* have complete information.  I regularly look
<things up in the man page, and would be severely inconvenienced if I
<had to log in to a graphical terminal and fire up ghostview (or
<whatever) to get authoritative information.

This is not true.  There are many man pages that are not authoritative,
sh and csh being examples.  For detailed information, one has to consult
the separate sections about sh or csh.  The man page only needs to be
authoritative iff there is not a separate document that expands the man page.

<(Nor would I want to print out the manual.  That would cost me money,
<and waste paper, and be less convenient than online documentation, and
<it would be difficult to keep up with each new release.)

That is definately your choice and PDF gives you the ability to do both,
or just one.

<>The main manual should be done using a package like Framemaker, which would
<>allow for easier WYSIWYG editing and formatting.
<
<I've never yet seen a WYSIWYG system that was as good
<as the WYGIWYG systems running on the same computers.

Huh?

<>                           Zsh needs a decent manual.  What we have now
<>are the man pages without the nroff/man-page-looking-format.
<
<And what do you have against man pages?

They are meant to be a quick reference to the syntax of a command or an
option.  For details and/or examples, expanded manuals are used.  Complicated
programs like Zsh require greatly expanded manuals, which is not the purpose
of man pages.

MB
-- 
System Administrator - Finnigan FT/MS - Madison WI. <URL:http://www.ftms.com/>
e-mail: brown@ftms.com
phone: (608) 273-8262 ext: 612  fax: (608) 273-8719
Visit - <URL:http://www.cdsnet.net/vidiot/>  (Your link to Star Trek and UPN)

Re: Man pages missing

[Zefram]

Vidiot wrote:
>This is not true.  There are many man pages that are not authoritative,
>sh and csh being examples.

The sh and csh man pages that I've seen are pretty complete.

>                                        The man page only needs to be
>authoritative iff there is not a separate document that expands the man page.

Ah, but the man page SHOULD be authoritative anyway.

><And what do you have against man pages?
>
>They are meant to be a quick reference to the syntax of a command or an
>option.  For details and/or examples, expanded manuals are used.

In the case of zsh, the man page is a quick referenece to all the
details too.  This is ideal.

-zefram

Re: Man pages missing

[Zefram]

Vidiot wrote:
>There are no *.1 files in zsh-3.1.1. I did a find search and zippo files
>that end in .1.

Are we looking at the same file?

% tar tvzf zsh-3.1.1-beta.tar.gz | grep '\.1$'
-rw-r--r-- hzoli/operator   910 Dec 21 02:35 1996 zsh-3.1.1/Doc/ansi2knr.1
-rw-r--r-- hzoli/operator  7453 Jan 27 23:38 1997 zsh-3.1.1/Doc/zsh.1
-rw-r--r-- hzoli/operator   7444 Jan 27 23:38 1997 zsh-3.1.1/Doc/zshall.1
-rw-r--r-- hzoli/operator  50450 Jan 27 23:38 1997 zsh-3.1.1/Doc/zshbuiltins.1
-rw-r--r-- hzoli/operator  18455 Jan 27 23:38 1997 zsh-3.1.1/Doc/zshcompctl.1
-rw-r--r-- hzoli/operator  34714 Jan 27 23:38 1997 zsh-3.1.1/Doc/zshexpn.1
-rw-r--r-- hzoli/operator  41583 Jan 27 23:38 1997 zsh-3.1.1/Doc/zshmisc.1
-rw-r--r-- hzoli/operator  26969 Jan 27 23:38 1997 zsh-3.1.1/Doc/zshoptions.1
-rw-r--r-- hzoli/operator  25029 Jan 27 23:38 1997 zsh-3.1.1/Doc/zshparam.1
-rw-r--r-- hzoli/operator  32860 Jan 27 23:38 1997 zsh-3.1.1/Doc/zshzle.1
% md5 zsh-3.1.1-beta.tar.gz
MD5 (zsh-3.1.1-beta.tar.gz) = f16415642314fe17d8c9c0c6823f56f4

>Then I must be seeing things.  The few .yo files that I sampled sure looked
>like they had flavors of nroff and TeXinfo in them.  It looks like this:
>
>COMMENT(--- man page headers ---)
> 
>def(manpage)(4)(\
>  NOTRANS(.TH ")ARG1" "ARG2" "ARG3" "ARG4"\
...

Bad choice of sample.  Look in the Zsh/ subdirectory, where the real
documentation is.

-zefram

Re: Man pages missing

[Vidiot]

<>There are no *.1 files in zsh-3.1.1. I did a find search and zippo files
<>that end in .1.
<
<Are we looking at the same file?
<
<% tar tvzf zsh-3.1.1-beta.tar.gz | grep '\.1$'
<-rw-r--r-- hzoli/operator   910 Dec 21 02:35 1996 zsh-3.1.1/Doc/ansi2knr.1
<-rw-r--r-- hzoli/operator  7453 Jan 27 23:38 1997 zsh-3.1.1/Doc/zsh.1
<-rw-r--r-- hzoli/operator   7444 Jan 27 23:38 1997 zsh-3.1.1/Doc/zshall.1
<-rw-r--r-- hzoli/operator  50450 Jan 27 23:38 1997 zsh-3.1.1/Doc/zshbuiltins.1
<-rw-r--r-- hzoli/operator  18455 Jan 27 23:38 1997 zsh-3.1.1/Doc/zshcompctl.1
<-rw-r--r-- hzoli/operator  34714 Jan 27 23:38 1997 zsh-3.1.1/Doc/zshexpn.1
<-rw-r--r-- hzoli/operator  41583 Jan 27 23:38 1997 zsh-3.1.1/Doc/zshmisc.1
<-rw-r--r-- hzoli/operator  26969 Jan 27 23:38 1997 zsh-3.1.1/Doc/zshoptions.1
<-rw-r--r-- hzoli/operator  25029 Jan 27 23:38 1997 zsh-3.1.1/Doc/zshparam.1
<-rw-r--r-- hzoli/operator  32860 Jan 27 23:38 1997 zsh-3.1.1/Doc/zshzle.1
<% md5 zsh-3.1.1-beta.tar.gz
<MD5 (zsh-3.1.1-beta.tar.gz) = f16415642314fe17d8c9c0c6823f56f4

Interesting.  The tar file that I have does indeed have the files there,
but they are gone from my directory.  Did make somewhere along the line
remove them?  To answer that I went looking at the Doc/Makefile and found:

clean: mostlyclean
        rm -f *.$(manext)
        rm -f *.y$(manext) *.ytexi paths.yo

I've done a "make clean" from the top level because I recompiled with a
different CFLAGS.

So, I'm not seeing things.  This is an error.  Configure should not erase
the .1 man pages if the user doesn't have yodl to rebuild them.

Now I have to pull them from the tar file.

<>Then I must be seeing things.  The few .yo files that I sampled sure looked
<>like they had flavors of nroff and TeXinfo in them.  It looks like this:
<>
<>COMMENT(--- man page headers ---)
<> 
<>def(manpage)(4)(\
<>  NOTRANS(.TH ")ARG1" "ARG2" "ARG3" "ARG4"\
<...
<
<Bad choice of sample.  Look in the Zsh/ subdirectory, where the real
<documentation is.

Yes and no.  As I mentioned in my posting, if one needs to add a new nroff
or TeX function, one has to edit these yodl macros (I assume they are macros)
to add the new functions.  This means one has to know nroff/TeX/texinfo and
now yodl.  It is true that this should habe to happen very often, but it
could still happen.

All we are going to agree on is that we disagree.

MB
-- 
System Administrator - Finnigan FT/MS - Madison WI. <URL:http://www.ftms.com/>
e-mail: brown@ftms.com
phone: (608) 273-8262 ext: 612  fax: (608) 273-8719
Visit - <URL:http://www.cdsnet.net/vidiot/>  (Your link to Star Trek and UPN)

Re: Man pages missing

[Lee Eakin]

In a way, he may be right.  I built this yesterday also (I love z-shell).
I built it for Slowaris and Sun-OS.  Preparing for the second build I ran 
'make distclean'.  When I did, the makefile removed *.1 from the Doc dir.
This would be OK if I had yodl built, but I didn't, so I had to restore
them from the tar-file.  I'm not sure how/if you want to address this as
a problem.  If it IS a problem it is a minor one, it just may cause a
little confusion.
  -Lee

Zefram Wrote: 
> Vidiot wrote:
> >There are no *.1 files in zsh-3.1.1. I did a find search and zippo files
> >that end in .1.
> 
> Are we looking at the same file?
> 
> % tar tvzf zsh-3.1.1-beta.tar.gz | grep '\.1$'
> -rw-r--r-- hzoli/operator   910 Dec 21 02:35 1996 zsh-3.1.1/Doc/ansi2knr.1
> -rw-r--r-- hzoli/operator  7453 Jan 27 23:38 1997 zsh-3.1.1/Doc/zsh.1
> -rw-r--r-- hzoli/operator   7444 Jan 27 23:38 1997 zsh-3.1.1/Doc/zshall.1
> -rw-r--r-- hzoli/operator  50450 Jan 27 23:38 1997 zsh-3.1.1/Doc/zshbuiltins.
1
> -rw-r--r-- hzoli/operator  18455 Jan 27 23:38 1997 zsh-3.1.1/Doc/zshcompctl.1
> -rw-r--r-- hzoli/operator  34714 Jan 27 23:38 1997 zsh-3.1.1/Doc/zshexpn.1
> -rw-r--r-- hzoli/operator  41583 Jan 27 23:38 1997 zsh-3.1.1/Doc/zshmisc.1
> -rw-r--r-- hzoli/operator  26969 Jan 27 23:38 1997 zsh-3.1.1/Doc/zshoptions.1
> -rw-r--r-- hzoli/operator  25029 Jan 27 23:38 1997 zsh-3.1.1/Doc/zshparam.1
> -rw-r--r-- hzoli/operator  32860 Jan 27 23:38 1997 zsh-3.1.1/Doc/zshzle.1
> % md5 zsh-3.1.1-beta.tar.gz
> MD5 (zsh-3.1.1-beta.tar.gz) = f16415642314fe17d8c9c0c6823f56f4
> 
> >Then I must be seeing things.  The few .yo files that I sampled sure looked
> >like they had flavors of nroff and TeXinfo in them.  It looks like this:
> >
> >COMMENT(--- man page headers ---)
> > 
> >def(manpage)(4)(\
> >  NOTRANS(.TH ")ARG1" "ARG2" "ARG3" "ARG4"\
> ...
> 
> Bad choice of sample.  Look in the Zsh/ subdirectory, where the real
> documentation is.
> 
> -zefram

--
 Lee E. Eakin, Paranet 14651 Dallas Pkwy., Suite 405 Dallas, Tx 75240 
 Email: Lee.Eakin@Paranet.COM (on loan to: Lee.Eakin@TI.COM (TI,PAC))

 ...You are in a maze of twisted little UNIX versions, all different.