Subject: FVWM Documentation

From: Olivier Chapuis <[email-masked]>
Date: Fri, 10 Jan 2003 23:26:41 +0100

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

---

From: Eric Gillespie <[email-masked]>
Date: Sat, 11 Jan 2003 01:16:57 -0500

> source project use this now.

Everyone else has moved on to XML, using Norm Walsh's very nice
docbook-xsl stylesheets.

>                    that I've written to manual pages. This need some works

XSLT is a much better solution for this type of problem, and as a
matter of fact the docbook-xsl package already includes a man
page stylesheet.

--  
Eric Gillespie <*> [email-masked]

Build a fire for a man, and he'll be warm for a day.  Set a man on
fire, and he'll be warm for the rest of his life. -Terry Pratchett
--
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-masked].
To report problems, send mail to [email-masked]

---

From: Rob Park <[email-masked]>
Date: Sat, 11 Jan 2003 00:56:40 -0700

> 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 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 ;)

-- 
Rob Park
http://www.ualberta.ca/~rbpark
--
You're not drunk if you can lie on the floor without holding on.
		-- Dean Martin
--
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-masked].
To report problems, send mail to [email-masked]

---

From: Olivier Chapuis <[email-masked]>
Date: Sat, 11 Jan 2003 11:39:51 +0100

> Everyone else has moved on to XML, using Norm Walsh's very nice

There is not a big difference between SGML and XML (DocBook doc say
this). I will try it. I think that at the current step I just need to
change some path and name in the head of the source files.
But why XML is better than SGML for writing doc? 

> matter of fact the docbook-xsl package already includes a man

I will prefer to have our own tool for docbook to man. Reason:
When a doc update is needed the .sgml file should be edited and then
the man page should be generated (make manpage). Then, both files
should be committed and we may _not_ put the sgml files in the
distribution (just the manpage). If we use XSLT we should impose to
all FVWM developers to have all the XML/XSLT stuff (with the same
version). This is not reasonable (as it is reasonable to impose Perl)

For building the other formats (dvi/rtf/ps/html) one can use any
appropriate tools (jade or openjade or XSLT with the foo or the xyz
style-sheet ..etc.). Then we will distribute the best results.  We may
distribute the doc source and experimented user may build the doc with
particular features. This is one of the advantage of the SGML/XML -
DocBook stuff.

BTW, does XSLT allow to build tex?

Regards, Olivier

---

From: Dan Espen <[email-masked]>
Date: Sat, 11 Jan 2003 22:32:32 -0500

Olivier Chapuis <[email-masked]> writes:
> subject.

I'm sorry, what did Dominik say?

> I've just this mail in my brain but roughly speaking we need:
> 
> - The current man pages
> 

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.

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

> 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

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.

The little POD that I've seen looked better.  But I don't think
POD allows for images either.

-- 
Dan Espen                           E-mail: [email-masked]

---

From: parv <[email-masked]>
Date: Sun, 12 Jan 2003 00:16:51 -0500

in message <[email-masked]>, wrote
Dan Espen thusly...
> I'd add, the ability to include images.  Some of the documentation
> talks about visual effects, but there are no illustrations in our
> documentation.

(la)tex --> dvi (-->), ps, pdf

> happened, but I'm still not convinced that man pages are

i suppose man pages could become pure reference instead of being
both reference & explanation of things.  then, man pages could point
to appropriate places to look for details.  something like xv(1) but
not as extreme.

that way, those who need explanations could be better served, while
keeping man pages light & to the point foe those who are familiar w/
fvwm syntax.

> POD allows for images either.

POD is easy almost like plain text.  it, of course doesn't have
facilities to include images.  of course.

how about LaTeX (or TeX) then?

  - parv

--

---

From: Olivier Chapuis <[email-masked]>
Date: Sun, 12 Jan 2003 07:36:33 +0100

> (la)tex --> dvi (-->), ps, pdf

XML/SGM + DocBook ---> man page
                  |--> html
                  |--> (la)tex  --> dvi (-->), ps, pdf
                  |--> texinfo (never succed)
                  |--> whatever (needs some work)
> how about LaTeX (or TeX) then?

I like a lot Latex. I wrote my PhD. Thesis with it and a lot of
papers. For me it is the best language for printing output.  However,
we need the doc under man page and html format and using Latex as a
common source for all these formats is not a good idea. Moreover,
Latex is not so easy (you do not need to learn XML/SGML/HTML but Latex
needs some practices).

Olivier

---

From: Olivier Chapuis <[email-masked]>
Date: Sun, 12 Jan 2003 08:27:33 +0100

> But why XML is better than SGML for writing doc? 

Ok, XML is a subset of SGML. As XML is enought it is probably
better.

Olivier

---

From: Olivier Chapuis <[email-masked]>
Date: Sun, 12 Jan 2003 08:43:04 +0100

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

> 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

---

From: Olivier Chapuis <[email-masked]>
Date: Sun, 12 Jan 2003 08:46:25 +0100

I send an answer to this message but it does not appear.
Maybe it was condidered as a SPAM as it contains html?
I try again ...

Olivier

---

From: Mikhael Goikhman <[email-masked]>
Date: Sun, 12 Jan 2003 12:12:52 +0000

On 10 Jan 2003 23:26:41 +0100, Olivier Chapuis wrote:
> 
> I have a concrete proposition for improving FVWM documentation.

Looks pretty good to me.

I may write pod2xml convertor once I understand how it should work, so we
don't need to worry about the existing pod documentation.

If this helps, we may drop the current docs/ directory completely and
start a new doc/ directory with subdirectories from scratch.

Some text files (the current NEWS, AUTHORS come to mind) are only needed
to be converted to html and not other formats, so xml is not needed.
But this is not clear. As well as what to do (if at all) with fvwm.lsm,
DEVELOPERS and ChangeLog~s.

FAQ may be maintained as xml, it needs rewritting from scratch anyway.

COMMANDS.xml (or CommandList.xml) may be autogenerated from a slightly
modified fvwm/functable.c. I may do it later in a reusable way using
autogenerated perllib class and clean API.

Regards,
Mikhael.

---

From: Dan Espen <[email-masked]>
Date: Sun, 12 Jan 2003 10:21:57 -0500

Olivier Chapuis <[email-masked]> writes:
> On Sat, Jan 11, 2003 at 10:32:32PM -0500, Dan Espen wrote:
> 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."

OK, thanks.  This was     a discussion about not  having    duplicated
information in the source code, man pages and  a proposed tutorial.  I
suppose using docbook might help with that.

The format is more regular which might make it easier to generate or
parse.

> I do not understand. Really, SGML, XML and HTML is very very similar
> at the editor level and you say that you would like to use HTML.

The massive amount of markup in docbook format makes it hard
to actually read the text.

I realized that XEmacs wasn't highlighting the document by default.
I made some adjustments and I got some of the stuff to highlight but
theres still a huge amount of markup in the file.  I see that
SGML mode has a command to hide most of the markup which helps, but a
quick test shows that you can't edit with the markup hidden.
(Stuff gets put in the wrong place.)

Right now I'd say that this is still a problem, but not a big one.
I'd guess after I get used to sgml-mode, there might be more benefits
than problems.

> The advantage of DocBook is that the MarkUp's are "concepts" and not
> direct formating instruction.

Yep, thats a great advantage.

> I am afraid that POD is too weak. I will try to answer to Rob Park on
> this subject.

OK, I'm convinced that POD isn't better than Docbook.

I see that Docbook supports images.  I guessed that we still
couldn't use images because we want to convert Docbook to manpage
format.  I haven't looked at the process to convert Docbook
to man, but is there some way to mark text in such a way that
it will not appear in the man page?  I'm thinking of:

<inlineimageref>
The following shows how a HGradient appears:
<image>XXX</image>
</inlineimageref>

(The whole inlineimageref section would get dropped out when the man
page was generated.)

---

From: Olivier Chapuis <[email-masked]>
Date: Sun, 12 Jan 2003 07:14:58 +0100

8 Aug 2002  Len Philpot  Documentation (was: Re: FVWM: How do I start modules automatically?)

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.

> a link to the colorset section.

Yes link to other parts of any man page (and also to the FAQ).

> happened, but I'm still not convinced that man pages are

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

Olivier

---

From: Olivier Chapuis <[email-masked]>
Date: Sun, 12 Jan 2003 08:50:14 +0100

And:

 

Man page:

.TP

    

Olivier

---

From: Olivier Chapuis <[email-masked]>
Date: Sun, 12 Jan 2003 16:04:23 +0100

Answer attached as I think it is rejected by the SPAM filter.

Olivier

---

From: Olivier Chapuis <[email-masked]>
Date: Thu, 23 Jan 2003 12:17:12 +0100

> I'd guess after I get used to sgml-mode, there might be more benefits

What we can do (and I experiment this) is to add aliases.  This
involve to extand the dtd and to preprocess the document with a filter
style-sheet. Currently:

<acronym>   --> <ac>
<emphasis>  --> <em>
<quote>     --> <q>
<command>   --> <cmd>
<envar>     --> <ev>
<filename>  --> <f>
<option>    --> <opt>
<optional>  --> <otn>
<parameter> --> <pmt> and <pr> (for fvwm parameter reference)
<userinput> --> <ui>
...etc.

and we can add
<fc>: for fvwm commands
<fcr>: for fvwm commands references (see <fcr>KillModule</fcr>)
<fp>: for fvwm parameters
<fpr>: for fvwm  parameters references

I think that smaller MarkUp may help reading/editing the source.
Also, we may remove from the dtd some the Markup that we do not want
to use.
 
> (The whole inlineimageref section would get dropped out when the man

Yes this is possible.

Olivier