Answer attached as I think it is rejected by the SPAM filter.
Olivier
On Sat, Jan 11, 2003 at 10:32:32PM -0500, Dan Espen wrote:
> Olivier Chapuis <[EMAIL PROTECTED]> writes:
> > 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'm sorry, what did Dominik say?
>
Take a look at the thread which start with:
8 Aug 2002 Len Philpot Documentation (was: Re: FVWM: How do I start modules
automatically?)
For example Dominik wrote:
"*Sigh* Yes, the documentation is one of the biggest open issues
with fvwm, but we don't have the people and/or the infrastructure to
do it right. We'd need somebody who is able and willing to set up
en environment in which the man page and other doc formats can be
generated from a single source."
And:
"I'm a complete newbie inrespect to documentation formats. Some
basic requirements are:
- Must be convertible to various other formats (man page, ps,
html and possible GNU Texinfo) and must look good in these
formats.
- The tools must works on any system and should run out of the
box. Everybody must be able to edit the documentation.
- The format should be reasonably easy to edit without any tools
other than a text editor.
> > 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).
>
> Right now we have links to external places, for example, for
> the libstroke package, and links to our other man pages, for
> example the modules like FvwmPager.
>
> I guess you mean you'd like to see links to other parts of
> the man page, for example when it mentions colorsets, you'd like
> a link to the colorset section.
>
Yes link to other parts of any man page (and also to the FAQ).
> > - Possibility to have a printable version of the documentation.
> > I.e., a ps and/or pdf FVWM book.
>
> I'd add, the ability to include images.
> Some of the documentation talks about visual effects,
> but there are no illustrations in our documentation.
>
> A while back I suggested junking the man pages and
> going to straight html. There were objections so it never
> happened, but I'm still not convinced that man pages are
> necessary.
>
I'm not convinced too that man page are necessary. But, I am afraid
that a lot of people will be very disappointed if we remove the man
page. Any way with my proposal you will have the fvwm doc with the
format you want (texinfo is an issue but there are tools which convert
DocBook to info; I just fail to setup these tools).
Note that "XML" is basically a subset of "SGML" and that both
look likes HTML.
> > 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:
> ...
> > I need some comment before I do (or not) the full translation to the
> > new format.
>
> The generated man pages and html look pretty good.
>
> However the .sgml is really hard to read.
> The markup gets in the way.
> I don't know if I'd like trying to edit the sgml with emacs or vi.
>
I do not understand. Really, SGML, XML and HTML is very very similar
at the edition level and you say that you would like to use HTML.
let us take an example the ChangeMenuStyle command
Man page:
.TP
.BI "ChangeMenuStyle " "menustyle menu ..."
Changes the menu style of
.IR menu " to " menustyle .
You may specified more than one menu in each call of
.BR ChangeMenuStyle .
.EX
ChangeMenuStyle pixmap1 \\
ScreenSaverMenu ScreenLockMenu
.EE
DocBook (you may add more space in between lines):
<!-- next line has no analog for man page -->
<anchor id="MenuStyle">
<para>
<synopsis>
<command>ChangeMenuStyle</command> <parameter>menustyle</parameter>
<parameter>menu</parameter>
</synopsis>
Changes the menu style of <parameter>menu</parameter> to
<parameter>menustyle</parameter>. You may specified more than one menu
in each call of <command>ChangeMenuStyle</command>.
<screen>
ChangeMenuStyle pixmap1 \\
ScreenSaverMenu ScreenLockMenu
</screen>
</para>
HTML (to get an hilighted synopsis command line):
<!-- next line has no analog for man page -->
<A NAME="MenuStyle">
<P>
<TABLE BORDER="0" BGCOLOR="#D7C79A" WIDTH="100%">
<TR>
<TD>
<B>ChangeMenuStyle</B> <I>menustyle</I> <I>menu</I>
</TD>
</TR>
</TABLE>
Changes the menu style of <I>menu</I> to <I>menustyle</I>. You may
specified more than one menu in each call of <B>ChangeMenuStyle</B>.
<PRE>
ChangeMenuStyle pixmap1 \\
ScreenSaverMenu ScreenLockMenu
</PRE>
</P>
So DocBook and HTML look similar:
<para> --> <P>
<command> --> <B>
<parameter> --> <I>
<screen> --> <pre>
<synopsis> --> hilight the bg of the synopsis of MenuStyle
The advantage of DocBook is that the MarkUp's are "concepts" and not
direct formating instruction. So for example if you want to redefine
the way you hilight an fvwm cmd synopsis, then with DocBook you modify
a few line in the style-sheet file, as with HTML you should "rewrite"
all the cmd synopsis.
There is a big difference between man page and DocBook/HTML. I will
just say that I do not like so much the lines of the form:
.IR menu " to " menustyle .
for me HTML/DocBook is better for this.
>
> The little POD that I've seen looked better. But I don't think
> POD allows for images either.
>
I am afraid that POD is too weak. I will try to answer to Rob Park on
this subject.
Olivier
