Subject: [RFC] Documentation

From: Lorenz Minder <[email-masked]>
Date: Sun, 25 Feb 2001 02:41:49 +0100

Hello.

First, this is not for 2.4. I'm just posting this now, so I can get some
feedback.

I'd like to propose a changement in the fvwm Documentation. We have a
Manual Page which Documents just about every Feature and all the
commands fvwm has. Unfortunately (well, in this context), FVWM has grown
quite large over time, and therefore the manpage has become, IMO,
way too large. (In fact, printing it would give you a Manual of ~80
Pages). The problem is, that it is hard to find the thing you're looking
for. We don't have things such as Tables of Contents, Links to Sections,
etc.; This is a basic problem of manpages: They are mainly designed to
document small commands such as ls, etc.

I therefore think it's about time we consider changing our Documentation
structure. The things I propose is

	* Replace the manual page by a very small one, documenting just
	  the stuff, you have normally in the manpage, i.e. NAME,
	  SYNOPSIS, DESCRIPTION, OPTIONS, AUTHORS, SEE ALSO
	
	* In the SEE ALSO section we would refer to the real manual,
	  which we keep seperately. I propose to deliver some HTML file,
	  which we could put in /usr/local/doc/fvwm/html or whereever.

This Documentation could have a real table of contents, and all the
navigating facilities you actually need to efficiently find what you
want.

I started to convert the manpage to SGML (linuxdoc DTD), and put a very
preliminary version online. You can find it here:

	http://dmawww.epfl.ch/~minder/fvwm/manual.html

Comments?

Regards,
--Lorenz

--
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: Dan Espen <[email-masked]>
Date: Sat, 24 Feb 2001 21:49:37 -0500

Lorenz Minder <[email-masked]> writes:
> I'd like to propose a changement in the fvwm Documentation.
...
> 	  which we could put in /usr/local/doc/fvwm/html or whereever.
...
> 	http://dmawww.epfl.ch/~minder/fvwm/manual.html

I see this in the source code: SGML-Tools 1.0.9.
Did the SGML Tools do all of that conversion or did you do additonal
changes by hand?

I made essentially the same suggestion a few years back.  It wasn't
very popular.

One suggested alternative was to use a meta language that can generate
the man page and html.  That seemed like a good idea to me.

We currently convert our man pages to html with man2html.

I find  that  reading man pages with   emacs (M-x  manual-entry) makes
finding things in man pages pretty easy.

--
Dan Espen
444 Hoes Lane  Room RRC 1C-214           E-mail: [email-masked]
Piscataway, NJ 08854                     Phone: (732) 699-5570
--
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: Sun, 25 Feb 2001 04:06:37 +0100

> Did the SGML Tools do all of that conversion or did you do additonal

SGML-Tools just does the conversion sgml->html. I actually wrote a
couple of awk-scripts which decompose the man-page into sections,
convert groff to sgml and then reassemble them with a new structure. I
decided to use sgml as an intermediate step because it makes it possible
to also create texinfo documentation, if you prefer that, or a nice
print manual.

> the man page and html.  That seemed like a good idea to me.

You could essentially do this now, by just modifying the manpage and
recreating the sgml-file from that man-page, etc. I thought about
similar ideas too. I'm not too fond of it, however:

* We'd give up a lot of the gain of flexibility. For instance, having
  sgml we could decide to add some figures, if we wanted to.
* It doesn't solve some of the structural problems we have in the man
  page, e.g. that there is no quick pointer to a command reference (and
  that it is hard, at best, to find a good structure for a manpage of that
  size.)
* There are some deficiencies in my conversion scripts I can't
  solve. For instance, low-level formatting sometimes simply doesn't
  have an equivalent sgml-command. I hoped by migrating I could just
  edit the remaining problems by hand.
* I fear that keeping that manpage would actually hide the fact that
  there is some more convenient documentation around.
* It doesn't make the documentation any better and it is bug-prone. It's
  actually some kind of bloat.

I agree that some of these problems could be solved by switching to a
real meta-language, as you suggested, and I would also still prefer
this new situation to the way it is now, but I still think replacing the
manpage would be the better way to go.

> We currently convert our man pages to html with man2html.

I made some tries with 'man -T html', but the result was a bit
deceiving, therefore I finally decided to write my own conversion
scripts.

> finding things in man pages pretty easy.

Greetings,
--Lorenz

---

From: Lorenz Minder <[email-masked]>
Date: Sun, 25 Feb 2001 16:11:15 +0100

> manpage would be the better way to go.

Well, I can update this a bit. I figured that if I'd use DocBook DTD
instead of linuxdoc, I could automatically create a manpage from the
same source. Given a technically clean solution, having both wouldn't be
so bad, after all.

I'll check this option when I come around to.

Regards,
--Lorenz

---

From: Dominik Vogt <[email-masked]>
Date: Mon, 26 Feb 2001 11:49:36 +0100

> 	http://dmawww.epfl.ch/~minder/fvwm/manual.html

I'm all for having a common source for various documentation
formats, 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 :-)

However, the more important in my eyes is that we don't have a
nice introduction to fvwm which explains concepts in more detail.

Bye

Dominik ^_^  ^_^

--
Dominik Vogt, [email-masked]
Reply-To: [email-masked]
--
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 13:56:39 +0100

Dominik Vogt wrote:
> formats

Yes, this is what I'm trying to do right now.

>, but I'm absolutely against removing the man page and

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)

However, as I said before already, I'm looking for a way to have common
source for both manual pages and other help systems.

Up to now, it looks as though there is a rough consensus that this would
be useful.

Regards,
--Lorenz

lorinder$ cat findlargest 
#!/usr/bin/awk -f

BEGIN {
        if(keep==0)
                keep=10;
        smallestkeptsz=0;
        for(i=0; i<keep; i++)
                A["--FILLER"i"--"]=0;
}

{
        if($5 > smallestkeptsz) {
                for(k in A) {
                        if(A[k]==smallestkeptsz) {
                                delete A[k];
                                A[$9]=$5;
                                smallestkeptsz=$5;
                                break;
                        }
                }

                for(k in A) {
                        if(A[k]<smallestkeptsz) 
                                smallestkeptsz=A[k];
                }
        }
}

END {
        for(k in A)
                print A[k] ":  " k
}
lorinder$ ls -l /usr/share/man/man?/* /usr/local/man/man?/*.gz | ./findlargest | sort -r
67220:  /usr/local/man/man1/fvwm2.1.gz
61907:  /usr/share/man/man1/tcsh.1.gz
57626:  /usr/share/man/man1/bash.1.gz
33797:  /usr/share/man/man1/gcc.1.gz
32694:  /usr/share/man/man3/libpng.3.gz
31963:  /usr/share/man/man5/terminfo.5.gz
29160:  /usr/share/man/man1/fetchmail.1.gz
27803:  /usr/local/man/man1/xterm.1.gz
26233:  /usr/share/man/man5/muttrc.5.gz
22446:  /usr/share/man/man7/groff_mdoc.samples.7.gz

---

From: Mikhael Goikhman <[email-masked]>
Date: Tue, 27 Feb 2001 04:26:05 -0600

On 26 Feb 2001 13:56:39 +0100, Lorenz Minder wrote:
> 
> The fvwm manpage is _most definitely not_ a standard UNIX manpage.

I can agree with other points, but I don't agree this this one.

The size of tcsh man page is comparable with fvwm's. There are 164 (yes)
man pages included with perl-5.6, big and complete, just one perlfunc(1)
is bigger than fvwm's. I am currently fluent with perl, tcsh and fvwm by
learning their man pages. It is definitely a unix way. :-) Well, this is
why we with Olivier created 4 fvwm-menu-* and 5 fvwm-themes-* man pages.

Regards,
Mikhael.

---

From: Dominik Vogt <[email-masked]>
Date: Tue, 27 Feb 2001 14:43:57 +0100

> (There are 2314 manpages on my computer)

The zsh developers had the same problem and solved it by splitting
up the man page into several sections.

  man zsh

Just gives a list of the other pages,

  zshcompctl zshcontrib zshmodules zshzftpsys zshcompsys zshexpn
  zshoptions zshzle zshbuiltins zshcompwid zshmisc zshparam      

are the smaller pages, and

  zshall

Is the complete men page containing all information.  All man
pages are generated with yodl.

Bye

Dominik ^_^  ^_^

---

From: Lorenz Minder <[email-masked]>
Date: Wed, 28 Feb 2001 00:29:49 +0100

> are the smaller pages, and

Yes, Dmitry mentionned this as well. I personally think, just a
decomposition into two pages would be a good thing for fvwm's
documentation.

> pages are generated with yodl.

Thanks for the tip.

Short status update: I switched to DocBook, because it is also capable
to create manpages, and it looks like linuxdoc will become obsolete
soon. I have now managed to create SGML-Source of the FVWM-manpage which
in turn can be converted into a manpage again. (Wow! A Program that does
nothing! :-) Unfortunately up to now I didn't succeed in producing a
good HTML-Output of this file: I haven't figured out yet how to create a
ToC, and so on; so the HTML-File just looks like a converted manpage
(with the minor advantage that you have FVWM-Command names linked to
their Definition.)

In other words, nothing useful yet.

Regards,
--Lorenz

---

From: Lorenz Minder <[email-masked]>
Date: Wed, 28 Feb 2001 00:13:00 +0100

Mikhael Goikhman wrote:
> The size of tcsh man page is comparable with fvwm's.

Yes it's also on my list of The Big Ten.

> There are 164 (yes)
> is bigger than fvwm's.

Yes. I actually regret having sent this comment to the list. It's
obviously crap. I was just so excited that fvwm's page was not only the
second or third, but the BIGGEST. So I hit the submit button a bit too
quickly.... (Well, I actually don't have a submit button, but an enter
key.)

The examples I had quickly thought of were Octave, R, vim ... . Those
have moderate manpages and a big amount of other documentation.  But the
existence of other widely accepted ways to document complex packages
doesn't mean using mainly manpages is not standard.

Regards,
--Lorenz

---

From: Dan Espen <[email-masked]>
Date: Tue, 27 Feb 2001 20:55:17 -0500

...
> In other words, nothing useful yet.

Heres something that comes close to working, and just demonstrates the
idea of writing an fvwm specific solution. This uses cpp, which is not
very flexible.  Something in Perl would certainly do the job.

Is this a "good" idea?  I'm not sure...

#ifdef man
#define SS .SH
#define SE
#define BIL .BI
#define BS
#define BE
#define IS
#define IE
#else
#define SectStart <H1>
#define SectEnd </H1>
#define BIL
#define BS <b>
#define BE </b>
#define IS <i>
#define IE </i>
#endif

SS SYNOPSIS SE

BIL BS "fvwm2 [\-blackout] [\-clientId " BE
   IS id IE
   BS "] [\-cmd " BE
   IS config_command IE
   BS "] [\-d " BE
   IS displayname IE
   BS "] [\-debug] [\-f " BE
   IS config_file IE
   BS "] [\-h] [\-replace] [\-restore " BE
   IS state_file IE
   BS "] [\-s] [\-version] [\-visual " BE
   IS "visual class" IE
   BS "] [\-visualId " BE
   IS id IE
   BS "]" BE

SS DESCRIPTION SE

Fvwm is a window manager for X11.  ...