Subject: Re: FVWM: 2 states for a doc

From: Elliot Sowadsky <[email-masked]>
Date: Sun, 27 Jan 2002 17:40:35 -0800 (PST)

<<
There are no silly question, only silly answers.  The fact that
people have trouble finding the necessary information indicates
that our documentation isn't good enough.

Putting a command summary up at the top will point users to which
command(s)  they should be looking at, rather than forcing them to scan
thru the entire doc.
--
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: Dominik Vogt <[email-masked]>
Date: Mon, 28 Jan 2002 23:01:07 +0100

> command(s)  they should be looking at, rather than forcing them to scan

Hm.  How would you structure this summary?  Just the command name
and a brief description?

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" in the body of a
message to [email-masked].
To report problems, send mail to [email-masked].

---

From: Uwe Pross <[email-masked]>
Date: Tue, 29 Jan 2002 09:12:41 +0100

> Hm.  How would you structure this summary?  Just the command name

I think a command summary in the man page would be not that helpful. The
problem is that the fvwm2 man page is just too big and the requirements
to the man page are too various. Sometimes one is looking for a special
command, an other time one looks for some certain behavior and next time
one is browsing through the man page just to get a new idea, without
actually knowing what to look for ;-)
Regarding this, one needs three (or even more) man pages for one
application or one really big man page containing a lot of redundancy.
And even then some people might not find what they are looking for.

Maybe a set of html-files could provide a more comfortable way the get
the required information. I like the html documentation for java
provided by the javadoc program. (javadoc produces a set of html pages.
I think actually there three frames one for chapters (java packages),
one for sections (class names) and for the text.) Maybe you guys could
do a similar documentation for fvwm2. 

Another way could be providing a setup/configuration tool which comes
with fvwm2. A tool which interacts with fvwm2 would provide much more
help as a good documentation can do. (But it cannot replace the doc.) I
know there are some people working on a config tool, but none of the
tools is supported by fvwm2 and none, which really works, does interact
with fvwm2. 

Uwe

---

From: Dominik Vogt <[email-masked]>
Date: Tue, 29 Jan 2002 09:26:54 +0100

> do a similar documentation for fvwm2. 

Actually, I recently thought about doing the documentation in SGML
like the Linux Documentation Project does.  Other that this, I
have no knowledge about SGML at all.

Bye

Dominik ^_^  ^_^

-- 
Dominik Vogt, email: [email-masked]
LifeBits Aktiengesellschaft, Albrechtstr. 9, D-72072 Tuebingen
fon: ++49 (0) 7071/7965-0, fax: ++49 (0) 7071/7965-20
--
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: Uwe Pross <[email-masked]>
Date: Tue, 29 Jan 2002 10:36:06 +0100

> have no knowledge about SGML at all.

I just had a look in the web about SGML and the LDP. It seems that it
might be not that complicated to translate the fvwm2 man pages to
DocBook SGML or DocBook XML, which are the languages used in the LDP. 
The LDP provides a documentation for authors at
http://www.linuxdoc.org/LDP/LDP-Author-Guide/index.html 
(There was also a good article in the german computer magazine c't
02/2002 about XML.) 

Uwe

---

From: szonyi calin <[email-masked]>
Date: Tue, 29 Jan 2002 11:28:45 +0100 (CET)

> to the man page are too various.  

I think fvwm2 has a very nice manual page. Very
 few programs have such good written manual pages.

A very good source of information is also New-features

fvwm configuration file. Other configs are also a good

source of information. 

> Uwe

Calin

___________________________________________________________
Do You Yahoo!? -- Une adresse @yahoo.fr gratuite et en français !
Yahoo! Mail : http://fr.mail.yahoo.fr
--
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: Uwe Pross <[email-masked]>
Date: Tue, 29 Jan 2002 12:20:03 +0100

>  few programs have such good written manual pages.

I did not say that I think the man page is not good nor something
similar. The problem was that sometimes it can be difficult to find the
required information in the page. But this does not mean that the man
page is not good enough. In fact I think the fvwm2 man page is one of
the best man pages I have ever seen. However, maybe you go with me
saying that finding something in a large document is most times more
difficult that finding something in a small document. 
Since the fvwm2 man page is quite big it might sometimes a problem
finding the required information in the time one expected. This was
actually the aim of my saying.

Uwe

---

From: szonyi calin <[email-masked]>
Date: Tue, 29 Jan 2002 13:35:00 +0100 (CET)

--- Uwe Pross <[email-masked]> a
> actually the aim of my saying.

Maybe generating a html page will be helpfull.
There is a program man2html but it generates
references 
at the end of the file not at the beginning.

Maybe the developers will consider generating a html
version from the manual page. 

Calin

---

From: Dan Espen <[email-masked]>
Date: Tue, 29 Jan 2002 07:58:58 -0500

> version from the manual page. 

http://fvwm.org/generated/manpages/

-- 
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" in the body of a
message to [email-masked].
To report problems, send mail to [email-masked].

---

From: hugo vanwoerkom <[email-masked]>
Date: Tue, 29 Jan 2002 07:48:10 -0800 (PST)

I would look at HyperLatex too. Problem now is finding
something in the documentation, which is large. It
begs for an index. Actually the program itself is a
perfect candidate for an expert system`s approach.
Hugo Van Woerkom.

__________________________________________________
Do You Yahoo!?
Great stuff seeking new owners in Yahoo! Auctions! 
http://auctions.yahoo.com
--
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: Dominik Vogt <[email-masked]>
Date: Tue, 29 Jan 2002 17:38:19 +0100

> version from the manual page. 

That's was what I was aiming at when I suggested using SGML.  From
the SGML source you can generate the documentation in virtually
any other format, including html, info and man page.

Bye

Dominik ^_^  ^_^

---

From: szonyi calin <[email-masked]>
Date: Tue, 29 Jan 2002 18:16:38 +0100 (CET)

--- Dominik Vogt <[email-masked]> a écrit : > On Tue,
Jan 29, 2002 at 01:35:00PM +0100, szonyi
> calin wrote:
> > > I did not say that I think the man page is not
> good
> > > nor something
> > > similar. The problem was that sometimes it can
> be
> > > difficult to find the
> > > required information in the page. But this does
> not
> > > mean that the man
> > > page is not good enough. In fact I think the
> fvwm2
> > > man page is one of
> > > the best man pages I have ever seen. However,
> maybe
> > > you go with me
> > > saying that finding something in a large
> document is
> > > most times more

Sorry for being missunderstood. The ideea was using 
html because it permits links in document and 
 easy navigation.(_if it's well done_). It's very 
easy to generate a html page from fvwm manual but it's
useless as long as it has ~250k and it doesn't have
a link to every command inside the page. I just
generated a fvwm2 documentation in html (using 
man2html) but the index is at the end of the page 
and is pretty weak (you cannot access individual 
configuration commands from it). 
Not the format is the problem but the speed of finding

the information you want (if it's one big html without
an index or links to fvwm configuration commands it's
like reading the manual page, only the viewer is
different).
I hope you underestand what i mean and i think uwe 
wanted something like this.

Sorry for bothering you. 
I don't mind reading the manual page but at some time 
in the future it could became a huge man page and 
serching through it will became something painfull.

Bye

Calin

---

From: hugo vanwoerkom <[email-masked]>
Date: Tue, 29 Jan 2002 09:57:28 -0800 (PST)

There are a slew of converters available. E.g man2html
allows you to put your systems man pages all in a
browser format with cgi-bin. rman does it individually
but from man to anything. I just tried fvwm -> latex
and html. Does a decent job given the weird characters
that are used. But I still like HyperLatex because it
doesnt just do an automated conversion.

---

From: Walter Dnes <[email-masked]>
Date: Wed, 30 Jan 2002 01:33:40 -0500

On Tue, Jan 29, 2002 at 09:12:41AM +0100, Uwe Pross wrote

> actually knowing what to look for ;-)

  One thing I'd like to see is maybe an appendix with nothing but style
settings.  Maybe group by menu styles, window styles, etc.  The problem
right now is that I have to hunt all over the place.  Menu styles are
part of menu docs, window styles are part of Window doc, etc.

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