Re: Documentation for new command?

[seventh guardian]

Hello Dominik,

On 7/12/07, Dominik Vogt <[EMAIL PROTECTED]> wrote:

I've just committed the new command "EchoFuncDefinition" which
prints a function definition to the console (useful for debugging
functions).

Nice addition, it should be useful.

 But I've no idea what I have to do to write the
documentation (I daid that I would be unable to write
documentation if it's scattered over several files, didn't I?).
Here it is in man page format:

  EchoFuncDefinition function

  The
  .B EchoFuncDefinition
  is similar to the
  .B Echo
  command but prints the definition fo the given
  .I function
  to
  .IR stderr .
  It is useful to find out how fvwm handles quoting and for
  debugging functions.

About the doc page creation, it seemed simple at first, but I had to
search hard for the relevant info. Maybe a clearer how-to should be
created? This is the first time I'm creating a manual entry, so here
are my steps:

1. enter doc/commands
2. copy a similar command like Echo.xml to EchoFuncDefinition.xml

3. change the section id, title and cmdsynopsis to the correct name
4. change the arg in cmdsynopsis from 'string' to 'function'

5. change the "para" section according to the previous menu entry,
noting that the reference to the 'Echo' command should obey the
convention in README in order to generate an appropriate link. It
would become like this:

<para>The
<emphasis remap='B'>EchoFuncDefinition</emphasis>
is similar to the
<fvwmref cmd="Echo"/>
command but prints the definition for the given
<replaceable>function</replaceable>
to
<filename>stderr</filename>.
It is useful to find out how fvwm handles quoting and for
debugging functions
.</para>

6. now it's time for adding it to doc/fvwm/userFunctions.xml, which
seems the most relevant group for it.

7. then add it to the Makefile.am COMMANDS variable.
8. finally it's a matter of creating a changelog entry and adding it to cvs

This seems fairly simple now, but took me some time to figure out. I
believe there should be a how-to somewhere.. Maybe I'll do it, as soon
as I get in the mood ( now is time for lunch :)

Cheers,
 Renato