It seems to me that the manual should contain as much documentation on
the commands as does their help output, but maybe people disagree and
there's a policy about it; I can't see any notes on how the system is
meant to work.  It looks as if you can get the `<name>_help' string into
the manual, but it may not be valid LaTeX or well formatted.

On Sun, Jan 11, 2009 at 04:55:17AM +0000, Dave Love wrote:
> It seems to me that the manual should contain as much documentation on
> the commands as does their help output, but maybe people disagree and
> there's a policy about it; I can't see any notes on how the system is
> meant to work.  It looks as if you can get the `<name>_help' string into
> the manual, but it may not be valid LaTeX or well formatted.

The cmd_description and cmd_help strings should be inserted into the
LaTeX manual by preproc.hs; in each src/Darcs/Commands/*.lhs there
should be a stanza

    \end{code}
    \haskell{foo_description}
    \options{foo}
    \haskell{foo_help}
    \begin{code}

If some file does not have that, I consider it a bug.

Note that some commands still have more-or-less identical text in
foo_description and foo_help, in which case foo_help should be
embellished before adding a \haskell{foo_help} line.

The following patch updated the status of issue1310 to be resolved:

* Resolve issue1310: create merged \darcsCommand{add}. 
Ignore-this: 945f45d0671c1e5a613ebfb3c4f90f59
This replaces inconsistent use of \haskell{add_description},
\options{add} and \haskell{add_help}.

You wrote: 

> The cmd_description and cmd_help strings should be inserted into the
> LaTeX manual by preproc.hs; in each src/Darcs/Commands/*.lhs there
> should be a stanza
>
>     \end{code}
>     \haskell{foo_description}
>     \options{foo}
>     \haskell{foo_help}
>     \begin{code}
>
> If some file does not have that, I consider it a bug.

I couldn't immediately figure out what was expected when I tried.  (Is
it documented for hackers?)  I can't remember what command I found the
problem with, but it was likely `show'.  Should I check sometime?

The use of help text in both the manual and the command help output is not fully
working.

The problem is the command_help string is used as plain text in the command help
output, and as LaTeX code in the manual. Some chars have special meaning in
LaTeX, and should therefore be quoted. If they are not, the build of the manual
fails. But if they are, the quoting turns up in the plain text in the command
help output.

A simple solution is to always write the command_help as plain text, and have
preproc quote special chars for LaTeX. This deprives the manual (both pdf and
html) of all special formating for these texts.

A more complex solution is to always write the command_help as LaTeX, and have
Command.get_command_help un-LaTeX the text before returning it. I don't think
this is a good solution, since a complete un-LaTeX-ing is unfeasible.

Another complex solution is to invent some simple markup for the command_help
strings, that can be translated into both LaTeX and plain text by preproc and
Command.get_command_help respectively. This could make use of the FancyPrinters
in darcs to highlight the "plain" text in the command help output.

On Sun, Mar 01, 2009 at 11:43:04PM -0000, Tommy Pettersson wrote:
> Another complex solution is to invent some simple markup for the
> command_help strings, that can be translated into both LaTeX and
> plain text by preproc and Command.get_command_help
> respectively. This could make use of the FancyPrinters in darcs to
> highlight the "plain" text in the command help output.

This is the approach I have implicitly been aiming for.

Such a lightweight markup language already exists -- reST.  The
expectation is that it be written as reST in the source code, and
emitted by "darcs help" either in plain text format or (with a new
--manual switch) as either LaTeX or reST, which would then be
incoporated into the static parts of the manual by Setup.lhs (which
subsumes the existing preproc.hs and GNUmakefile.

Parsing reST and emitting various formats can be done by the Pandoc
package, so theoretically this is another case of reducing internal
code in favour of external (second-party) Haskell packages.

I believe Tommy fixed this recently with this patch:

Mon Mar  2 12:11:45 EST 2009  Tommy Pettersson <ptp@lysator.liu.se>
  * remove escape of latex special chars in ShowRepo help text