darcs

Issue 1310 help documentation should be in manual

Title help documentation should be in manual
Priority feature Status resolved
Milestone Resolved in
Superseder Nosy List darcs-devel, dmitry.kurochkin, fx, kowey, thorkilnaur, tommy, twb
Assigned To twb
Topics

Created on 2009-01-11.15:55:20 by fx, last changed 2009-08-27.14:15:49 by admin.

Messages
msg7043 (view) Author: fx Date: 2009-01-11.15:55:17
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.
msg7169 (view) Author: twb Date: 2009-01-24.06:04:34
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.
msg7181 (view) Author: twb Date: 2009-01-25.18:19:39
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}.
msg7255 (view) Author: fx Date: 2009-02-01.18:34:04
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?
msg7371 (view) Author: tommy Date: 2009-03-01.23:43:00
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.
msg7372 (view) Author: twb Date: 2009-03-01.23:49:28
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.
msg7388 (view) Author: twb Date: 2009-03-03.01:42:20
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
History
Date User Action Args
2009-01-11 15:55:21fxcreate
2009-01-24 06:04:38twbsetstatus: unread -> unknown
assignedto: twb
messages: + msg7169
nosy: + twb
2009-01-24 06:06:53twbsetnosy: kowey, fx, simon, twb, thorkilnaur, dmitry.kurochkin
title: help documentation should be in manual -> Ensure cmd_help is included in user manual for all commands.
2009-01-25 02:16:21twbsetstatus: unknown -> has-patch
nosy: kowey, fx, simon, twb, thorkilnaur, dmitry.kurochkin
2009-01-25 18:19:42twbsetstatus: has-patch -> resolved
nosy: kowey, fx, simon, twb, thorkilnaur, dmitry.kurochkin
messages: + msg7181
2009-02-01 18:34:07fxsetstatus: resolved -> unknown
nosy: kowey, fx, simon, twb, thorkilnaur, dmitry.kurochkin
messages: + msg7255
title: Ensure cmd_help is included in user manual for all commands. -> help documentation should be in manual
2009-03-01 23:43:04tommysetpriority: feature
nosy: + tommy
messages: + msg7371
2009-03-01 23:49:31twbsetnosy: tommy, kowey, fx, simon, twb, thorkilnaur, dmitry.kurochkin
messages: + msg7372
2009-03-03 01:42:23twbsetstatus: unknown -> resolved
nosy: tommy, kowey, fx, simon, twb, thorkilnaur, dmitry.kurochkin
messages: + msg7388
2009-08-25 17:38:35adminsetnosy: + darcs-devel, - simon
2009-08-27 14:15:49adminsetnosy: tommy, kowey, fx, darcs-devel, twb, thorkilnaur, dmitry.kurochkin