darcs

Issue 2307 document "darcs help markdown" and "darcs help manpage" (ProbablyiEasy)

Title document "darcs help markdown" and "darcs help manpage" (ProbablyiEasy)
Priority Status resolved
Milestone Resolved in 2.12.0
Superseder Nosy List DaniilFrumin, markstos, twb
Assigned To
Topics Documentation

Created on 2013-02-22.14:05:40 by markstos, last changed 2015-06-16.18:13:03 by noreply.

Files
File name Uploaded Type Edit Remove
add-information-about-_darcs-help-manpage_-and-_darcs-help-markdown_.dpatch DaniilFrumin, 2015-06-12.21:33:36 application/octet-stream
Messages
msg16720 (view) Author: markstos Date: 2013-02-22.14:05:37
1. Summarise the issue (what were doing, what went wrong?)

I find "darcs help manpage" and "darcs help markdown" to be useful, but 
they are not documented. 

2. What behaviour were you expecting instead?

I expect "darcs help --help" to list these options, and likely "darcs 
help" to. The docs should exclude example syntaxes to use to read the 
file:

  # read the docs as a manpage
  darcs help manpage | man -l - 

 # read the docs as HTML with a console based browser. 
 darcs help markdown | markdown | w3m -T text/html

It would also be nice to provide an example of how it might be used on a 
desktop, where a GUI web-browser is launched to display the HTML docs. 

Finally, this could be a separate "issue" but "darcs help" should also 
mention the wiki which is a great additional source of documentation. 

Currently it pessimistically links to the bug tracker, but not the wiki.

3. What darcs version are you using? (Try: darcs --exact-version)

     2.9.7 (+ 86 patches)
msg16721 (view) Author: simon Date: 2013-02-22.17:17:38
Interesting additions!

Perhaps help --markdown and help --manpage would be more logical since 
they are output modes not the thing you're asking for help on. Also we 
currently say "With an extra argument, darcs help foo prints detailed 
help about the darcs command foo."
msg18466 (view) Author: DaniilFrumin Date: 2015-06-12.21:33:36
Hello, everyone. Sorry for digging this ticket out, but this still
hasn't really been fixed.

For ease of implementation, I propose the attached patch.
Attachments
msg18469 (view) Author: bfrk Date: 2015-06-13.12:36:28
An unrelated issue, perhaps, but these two commands should use a pager!
(Under the usual side conditions: a pager is available, standard output
is a terminal etc).
msg18520 (view) Author: noreply Date: 2015-06-16.18:13:01
The following patch sent by Daniil Frumin <dan@covariant.me> updated issue issue2307 with
status=resolved;resolvedin=2.12.0 HEAD

* resolve issue2307: Add information about 'darcs help manpage' and 'darcs help markdown' 
Ignore-this: fb3a3fef5e274dbd4d154cacad4489e9
History
Date User Action Args
2013-02-22 14:05:40markstoscreate
2013-02-22 17:17:39simonsetmessages: + msg16721
title: document "darcs hep markdown" and "darcs help manpage" (ProbablyiEasy) -> document "darcs help markdown" and "darcs help manpage" (ProbablyiEasy)
2015-06-12 21:33:37DaniilFruminsetstatus: unknown -> needs-diagnosis/design
nosy: + DaniilFrumin
messages: + msg18466
files: + add-information-about-_darcs-help-manpage_-and-_darcs-help-markdown_.dpatch
2015-06-13 12:36:29bfrksetmessages: + msg18469
2015-06-16 18:13:03noreplysetstatus: needs-diagnosis/design -> resolved
messages: + msg18520
resolvedin: 2.12.0