Subject: Re: [RFC] Documentation

From: "Dmitry Yu. Bolkhovityanov" <[email-masked]>
Date: Mon, 26 Feb 2001 19:55:09 +0600

On 26 Feb 01 at 13:56, [email-masked] wrote:

> Dominik Vogt wrote:
> > > Comments?
> >
> > I'm all for having a common source for various documentation
> > formats
>
> Yes, this is what I'm trying to do right now.
>
> >, but I'm absolutely against removing the man page and
> > replacing it with one of these "see elsewhere" pointers.  On a
> > UNIX system, "man ..." should give detailed information about the
> > program, not the statement that the authors do not like manual
> > pages :-)
>
> No, I didn't say I don't like manual pages. I _do_ like manpages. This
> is not the reason I wanted to replace it.
>
> The fvwm manpage is _most definitely not_ a standard UNIX manpage. (``Not
> standard'' doesn't necessarily mean ``bad'', though.) Consider the
> output below. The essential information it contains is IMO that
>
>     (1) The fvwm manpage is the largest on my entire system.
>     (2) The fourth-largest manpage has just (roughly) half the size
>     of fvwm's manpage.
> (There are 2314 manpages on my computer)
[snip]
> > However, the more important in my eyes is that we don't have a
> > nice introduction to fvwm which explains concepts in more detail.
>

    In fact, the Z shell (zsh) meta-man page zshall(1) is easily the biggest
-- it is 46K lines, while fvwm-2.3.28's is about 6K lines.

    Maybe we can use zsh's approach to man pages? (Well, Zsh is the same to
shells as Fvwm2 to window managers ;)

    They have a small "zsh" page (<100 lines), which tells what Zsh is,
describes the basic things and gives references to other man pages
(zshbuiltins, zshoptions, etc.), containing detailed info about specific
subjects.  And there is a big "zshall" manpage, which simply includes all
the other pages and is suitable for </> searching in more/less.

NB: zshall(1) on RedHat 6.2 is broken -- it \fI's wrong files (man1/zshTTT
    instead of just zshTTT).

       ___________________________________________________________________
       Dmitry Yu. Bolkhovityanov  |  Novosibirsk, RUSSIA
       phone (383-2)-39-49-56     |  The Budker Institute of Nuclear Physics
                                  |  Lab. 5-13
--
Visit the official FVWM web page at <URL:http://www.fvwm.org/>.
To unsubscribe from the list, send "unsubscribe fvwm-workers" in the
body of a message to [email-masked].
To report problems, send mail to [email-masked]

---

From: Lorenz Minder <[email-masked]>
Date: Mon, 26 Feb 2001 16:58:17 +0100

> -- it is 46K lines, while fvwm-2.3.28's is about 6K lines.

Yes, obviously the result of the tests depend on what is installed.
Fvwm2 being biggest on my system is clearly also due to the fact that I
tend not to have installed software I don't use.

What I forgot to take into account is that split up pages are counted,
so it is at least possible that there are other huge beasts around.

That doesn't change what I wanted to show with that demonstration.

And, btw, on Debian at least, zsh does have a seperate html
documentation as well.

> subjects.

I was also thinking about that. We could e.g. break it up into fvwm2(1) and
fvwm2rc(5), the second one describing the configuration language.
Similarily, the corresponding html manual would have different chapters
for those two things. (The preliminary version I posted actually has
this.)

Regards,
--Lorenz