Hello, I have a concrete proposition for improving FVWM documentation. This has been discussed a number of time and I think that action is needed. I am really agree with the last mail of Dominik on the subject. I've just this mail in my brain but roughly speaking we need:
- The current man pages
- 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.
So, let us be concrete. Attached to this message a tar.gz ball which
contains an experimentation: the conversion of a very small part of
the FVWM doc into SGML. The source are sgml files and utilities:
fvwmdoc.sgml - a file to centralize all the doc
fvwm.sgml - A SGML version of a very small part of the fvwm man page
FvwmIdent.sgml - Full SGML version of the Fvwm Indent man page
FvwmTaskBar.sgml - just the title for a SGML TaskBar doc
CommandList.sgml - A SGML reduced version of doc/COMMANDS (can be
autogenerated in an artificial way).
docbook2man - a dramatic perl script that can convert the sgml file
that I've written to manual pages. This need some works
fvwm_print.dsl - Config file for building the ps/dvi/rtf version of the
doc
fvwm_html.dsl - Config file for building the html version of the doc
doit.sh - A personal shell script to build the html and ps/dvi/rtf
doc
README - Some useful www link
All the remaining stuff is auto-generated (but collateindex.pl which
comes from docbook-dsssl-1.77.tar.gz). Man page are under man/,
*nothing* is needed to build these man page but the ridiculous script
I wrote docbook2man. The html version is under html/; you found the
dvi and ps version under tex/ and the rtf version under rtf/ (all
these need DocBook-4.2, docbook-dsssl-1.77, jade or openjade and tex
for the dvi/ps version).
So try it! BUUUUUTTT please do not take to much attention to the
abstract and the 2nd paragraph of the Description section of the fvwm
Chapter. This is an other subject (What is FVWM?). I would like to
comment on this but later (at least an other thread should be started
on this).
I think that we can see with this small example that we can really
improve FVWM documentation by switching from man page to sgml. In
practice we should write the man pages using SGML+DocBook. Then, the
real man page should be auto-generated (as the man page for our perl
scripts are generated) using an improved version of docbook2man.
So from the point of view of the distribution nothing is changed:
the installed doc are the man pages.
The other versions of the doc will be build by a fvwm worker and put
for use (html) and download (html.tar.gz and ps.gz) on the web site.
Maybe, in the future, we can release an fvwm-doc-x.x.x ball together
with a fvwm-x.x.x release.
I need some comment before I do (or not) the full translation to the
new format.
Regards, Olivier
docbook.tar.bz2
Description: Binary data
