Subject: FVWM: Documentation

From: Laurent EVAIN <[email-masked]>
Date: Tue, 5 Mar 2002 22:09:18 +0100

Hi, 

I wrote a few months ago to say that, though
fvwm was a wonderful window manager, a introductive
documentation was missing. The current documentation
is very extensive and it is not so easy to read. 
I am volunteer to try to write such an introductory 
documentation. The goal would 
be:
-to help people to understand the philosophy of fvww 
so that they can decide whether they want to use it
-if they want to use it, to draw up a general picture 
of fvwm to prepare for the man pages 

The length would be 5 or 6 pages, and 
definitly at most 10 pages. 

However, before starting, I would like to make  sure 
that people find this work useful and 
that no one has already started such a work. 

Laurent. 

--
Visit the official FVWM web page at <URL: http://www.fvwm.org/>.
To unsubscribe from the list, send "unsubscribe fvwm" in the body of a
message to [email-masked].
To report problems, send mail to [email-masked].

---

From: Mikhael Goikhman <[email-masked]>
Date: Wed, 6 Mar 2002 01:02:09 +0000

> definitly at most 10 pages. 

Here is my humble opinion.

It is impossible to compress the man page from, say, 5000 lines to 10.

Such summary may be useful to get some initial information about FVWM, but
it will not answer any non trivial question, so in the end the user should
read 10+5000 lines. :)

But, maybe you may write these 10 pages so they open eyes, I don't know.

> that no one has already started such a work. 

Even if there is a similar work, I don't think yours will be a repetition.
Think about this as two independent journalists wrote about FVWM.

Regards,
Mikhael.

---

From: Dan Espen <[email-masked]>
Date: Tue, 05 Mar 2002 20:24:37 -0500

> that no one has already started such a work. 

As you observed, we have a lot of documentation.

I don't think we want more things we have to change as features
are added.

If you think you have 5 pages that will ease a new user into
Fvwm, that would be great, but I think you should try to find
a place to fit it into the existing Fvwm documenation hierarchy.

That is, submit it as a man page patch, or a web page patch.

-- 
Dan Espen                           E-mail: [email-masked]
444 Hoes Lane  Room RRC 1C-214      Phone: (732) 699-5570
Piscataway, NJ 08854
--
Visit the official FVWM web page at <URL: http://www.fvwm.org/>.
To unsubscribe from the list, send "unsubscribe fvwm" in the body of a
message to [email-masked].
To report problems, send mail to [email-masked].

---

From: Walter Dnes <[email-masked]>
Date: Wed, 6 Mar 2002 01:53:07 -0500

On Tue, Mar 05, 2002 at 10:09:18PM +0100, Laurent EVAIN wrote
> Hi, 
> 
> I wrote a few months ago to say that, though fvwm was a wonderful
> window manager, a introductive documentation was missing. The
> current documentation is very extensive and it is not so easy
> to read.  I am volunteer to try to write such an introductory
> documentation. The goal would be:
> The length would be 5 or 6 pages, and definitly at most 10 pages.
> 
> 
> However, before starting, I would like to make  sure that people
> find this work useful and that no one has already started such
> a work.

  I gave a talk at a local linux users group, where people were talking
about their favourite interfaces, etc.  I've put some notes together
that come in at 9 screens (I'm running 80X43 textmode); I don't see how
I can reduce it any further.  I've also included a basic config based on
my setup.  The last few pages are a tutorial on things like
sloppy-focus, raising, X Window geometry, etc.  I've also included basic
install instructions.

  My ISP has a low-traffic webpage, so I'd prefer to have the files
posted elsewhere.  The zipfile, including a screenshot, is 52 kbytes; 10
kbytes without the screenshot.  I don't think people would appreciate
even the small file as an attachment to this list.

  Anybody who has a website, or wants a copy, let me know.  This
document is a first draft and could probably use some polishing.

-- 
Walter Dnes <[email-masked]>
If you had purchased $1000 of @home stock in 1999, today you would
have $1.30.  If you had purchased $1000 of beer in 1999, today you
would still have $59 in empty cans.
--
Visit the official FVWM web page at <URL: http://www.fvwm.org/>.
To unsubscribe from the list, send "unsubscribe fvwm" in the body of a
message to [email-masked].
To report problems, send mail to [email-masked].

---

From: José Romildo Malaquias <[email-masked]>
Date: Wed, 6 Mar 2002 07:17:17 -0300

> > find this work useful and that no one has already started such

I am a newbie to fvwm. I have recently installed it and I am
in the process of configuring it to my willings. But I really
think the manual is too long and to detailed for a first grap
of how things are configured, even after printing it and
reading almost of it. So for newbie users like me, such
introductory documentation would be welcome. Please, write it
and make it available.

> document is a first draft and could probably use some polishing.

Please, sent me a copy of it.

Romildo
-- 
Prof. José Romildo Malaquias               Departamento de Computação
http://iceb.ufop.br/~romildo       Universidade Federal de Ouro Preto
[email-masked]                                           Brasil
[email-masked]
--
Visit the official FVWM web page at <URL: http://www.fvwm.org/>.
To unsubscribe from the list, send "unsubscribe fvwm" in the body of a
message to [email-masked].
To report problems, send mail to [email-masked].

---

From: Laurent EVAIN <[email-masked]>
Date: Wed, 6 Mar 2002 20:43:41 +0100

> it will not answer any non trivial question, so in the end the user should

You're completely right. Nothing magic can be done. I do not claim 
that programs can be powerful and user-friendly without any documentation.
The extensive documentation of fvwm is a very good point :) 

Let me however explain my point of view a bit more. 
When I decided to choose a window manager 2 years ago, 
I wanted an overview. When I tried to read the documentation,
I had to read at the very beginning technical things like M4 
preprocessing, ICCM compliance ... whereas I was just 
an end user without any knowledge on the difference 
between X, a window manager or a Desktop.
Even for simple things like the size of the window, 
I found rather difficult to 
read technical details _before_ having a general 
picture of fvwm: there are 
-commands for graphical appearance, 
-menus, functions and modules to add functionalities,
-and key bindings for ergonomics. 

Whereas I was in difficulty because of my 
poor knowledge to read the documentation,
my needs were very basic. 
To be concrete, I had 2 basic needs:

I wanted to know if 
if fvwm had the qualities I was looking for:
light, configurable, open source.
I didn't wan't any ``automatic feature''
since I wanted to keep exactly my environment
from one version of the wm to the following. 
To sum up, my first need was a ``philosophical 
presentation of fvwm'' to understand if it 
was the good choice. 

My second need was a quick technical introduction
so that I could set up a poor configuration easily,
which could be enriched by reading the documentation
later on. 

I think the current documentation is more or less written 
for developpers or at least very advanced end-users. 
I think however that fvwm has so many qualities that
it can be of use to average end-users. 
The goal of an introductive documentation
would be to help these guys. It wouldn't compete with 
the current documentation. 

Laurent.

---

From: Laurent EVAIN <[email-masked]>
Date: Wed, 6 Mar 2002 20:44:05 +0100

> I don't think we want more things we have to change as features

As I told in the previous message, specific features wouldn't
be discussed. It would only draw up a general picture, which
is independent of the version at 95%. 

Laurent.

---

From: David Koo <[email-masked]>
Date: Thu, 7 Mar 2002 09:15:53 +0530

Hi All,

    After lurking and eavesdropping on this thread, I seem to gather
that people want a "gentle introduction to Fvwm" type of a document.
While you can't get more concise than the manual if you want to
document everything in a as-small-as-possible space, perhaps the
length is not the question!! I don't know how many users would really
mind reading a document twice as large, _provided_ the effort to
understand is less! Everybody seems to agree that we can do with a
document that'll introduce fvwm in a gentle way!

    Soooo ... how about an Fvwm cookbook? I don't know of any such
project, but perhaps a cookbook can meet the requirements laid down.
It'll give examples of how things are done - how to have gradient in
title bars, how to define titlebar buttons, blah, blah, with
sufficiently detailed examples, pictures, etc. Different sections can
cater to different levels of expertise/familiarity.

    Is there any such existing project? Can the proposed documentation
project go on such lines? Other comments?

--
Koo