On Sat, Jan 11, 2003 at 12:56:40AM -0700, Rob Park wrote:
> Alas! Olivier Chapuis spake thus:
> > - Improved HTML version of the documentation (better inter-link that
> > we have now with the man to html conversion).
> >
> > - Possibility to have a printable version of the documentation.
> > I.e., a ps and/or pdf FVWM book.
> >
> > I think that what we need is SGML+DocBook. The LDP and numerous open
> > source project use this now.
>
> Maybe I don't have all the facts, but using SGML seems like overkill to
> me. Were it up to me, I'd maintain the fvwm documentation as POD (perl's
> Plain Old Documentation). POD is a very simple format, and there already
> exists many scripts for converting POD to useful formats like man, html,
> etc. It's also rather trivial to write a perl script that will convert
> POD into some other useful language, if the script doesn't already
> exist.
>
> But, I'm just a big perl fan, so maybe I'm biased ;)
>
I think that POD is too weak. I will quote an old msg of Mikhael:
"We already use the pod documentation format in FVWM in perl tools:
* fvwm-menu-directory
* fvwm-menu-headlines
* fvwm-menu-xlock
* fvwm-perllib
* all perllib classes
* FvwmPerl
I would probably say more yes than no to use pod in all documentation,
but I don't see a lot of reasons for this.
Pod is pretty rich, but not as rich as the man page format.
As for me, both the man page format and pod are easy to write and read.
There are a lot of small things in pod (say, no center-justification in
man pages) that I don't like, it is just not configurable enough. I myself
even have somewhere a patched Pod::Man that fixes some annoyances, like
converting "run fvwm(1)" to "run the fvwm manpage", but it's not an option
for everyone to install it. Also fvwm-perllib fixes one bug in pod2man.
There is no easy way to define a plain-unformatted-lines text without
first padding it with at least one space, this looks ugly in SYNOPSYS and
other places. This padding feature is often misused, for example the pod
used in Pod::Parser class itself hardcodes the 12 spaces indentation,
which is bad if the output is html, not just man pages.
Of course if I would not be a pod fan, I would not create fvwm-perllib
that uses it in several interesting ways."
> I also don't have a problem with the current state of fvwm
> documentation... I just read through the manpage every now and then to
> make sure I'm getting the most out of my .fvwm2rc ;)
>
- With the html version you will have a page which contains all
fvwm commands with a small description: as doc/COMMANDS in
2.5.5. Then, to get the detailed description of a command you will
just have to click on the command name. (With the ps version you
will have the page of the detailed description).
- With a man page you have in FvwmIdent "See the Module Command section
of fvwm (1)". With the html version you will have a direct link.
- With the html/ps version you will have various complete table of
contents and an "concept" index (both automatically generated).
- We may add images for a better explanation of some cmd.
- You will have the man page in the current form!
Olivier
--
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 PROTECTED]
To report problems, send mail to [EMAIL PROTECTED]
