Issue 1221 Option lists in reST

Title Option lists in reST
Priority wishlist Status given-up
Milestone Resolved in
Superseder Nosy List darcs-devel, dmitry.kurochkin, kowey, thorkilnaur, twb
Assigned To
Topics Documentation

Created on 2008-11-11.07:02:20 by twb, last changed 2017-07-30.23:55:03 by gh.

msg6650 (view) Author: twb Date: 2008-11-11.07:02:17
It turns out that while the current output from "darcs --help" is
well-formed reST, it is not marked up quite correctly -- resulting in
ugly output.

Darcs help's output needs to be changed so as to be marked up well for
reST.  If people think the reST output is too ugly, we need instead to
continue down the preproc.hs route and have two versions of show() for
darcs commands -- one for TeX (now reST) and one for humans.

Here is the original reply from the rst2pdf maintainer:

On Mon, Nov 10, 2008 at 11:11:12AM -0200, Roberto Alsina wrote:
> Trent W. Buck writes:
>> Hi, see attached example.  It looks really ugly.
> I took a careful look today and I think your option lists are not
> correctly written.
> If you check the restructured text spec, when there are multiple
> options in a line, you need to separate them using ", " and you have
> multiple spaces. [...]  Also, option lists are not supposed to be
> indented, or they are interpreted as being inside a block quote.
> I think the html writer is producing a "nice" output mostly by
> coincidence :-)
msg6889 (view) Author: twb Date: 2008-12-25.01:00:14
Because Cabal cannot (currently) build intermediary binaries without then
installing them, src/darcsman.hs probably also needs to be subsumed into
the main darcs binary, so e.g. darcs --help-man or darcs help --man would
emit the manpage.

This being the case, it is probably reasonable to have three output formats:
darcs help emits human-readable help, darcs help --roff emits a manpage and
darcs help command --rest emits help for a command in slightly different reST
format.  If it's preferred, we could call the options --manpage and --user-manual
msg10663 (view) Author: kowey Date: 2010-04-04.09:37:12
Hi Trent, now that we have things like darcs help manpage, is it time to
wake this bug up?
Date User Action Args
2008-11-11 07:02:20twbcreate
2008-11-15 06:58:10twbsetassignedto: twb
nosy: kowey, dagit, simon, twb, thorkilnaur, dmitry.kurochkin
2008-12-19 09:49:11koweysetpriority: wishlist
nosy: kowey, dagit, simon, twb, thorkilnaur, dmitry.kurochkin
2008-12-25 01:00:19twbsetstatus: unread -> unknown
nosy: kowey, dagit, simon, twb, thorkilnaur, dmitry.kurochkin
messages: + msg6889
2009-08-10 23:51:22adminsetnosy: - dagit
2009-08-20 03:11:40twbsetstatus: unknown -> deferred
nosy: kowey, simon, twb, thorkilnaur, dmitry.kurochkin
2009-08-20 03:11:55twbsetassignedto: twb ->
nosy: kowey, simon, twb, thorkilnaur, dmitry.kurochkin
2009-08-25 17:34:20adminsetnosy: + darcs-devel, - simon
2009-08-27 14:28:34adminsetnosy: kowey, darcs-devel, twb, thorkilnaur, dmitry.kurochkin
2010-04-04 09:37:14koweysetstatus: deferred -> needs-implementation
topic: + Documentation
messages: + msg10663
2017-07-30 23:55:03ghsetstatus: needs-implementation -> given-up