[darcs-users] FYI: user-manual status.

Trent W. Buck trentbuck at gmail.com
Sat Nov 8 05:07:11 UTC 2008


Hi, this patch bundle is against the current unstable branch and
demonstrates the current status of the user-manual branch.  In
particular,

Done:

  - Convert .tex to reST.
  - Update make accordingly.

In progress:

  - Convert command documentation from literate comments (visible in
    user manual) to into cmd_help (visible in "darcs foo --help").

  - Obviate preproc by simply including the output of "darcs foo
    --help" in the user manual, since the darcs help output is already
    valid reST.

Not started:

  - Make the reST sources adhere to HACKING.txt guidelines.
  - Refactoring the actual content of the manual.

Apart from the last patch (the makefile one), all these patches should
be stable.  I reserve the privilege to amend the last one, because I
think I'll need to (if only to remove conflictors).

I'd like to apologize to Max and Mark, both of whom are interested in
contributing to the documentation.  I haven't been keeping them up to
date on progress, I haven't been pushing to the cho repo and I haven't
really delegated at all.  Sorry, guys!  I hope to change that once the
base reSTization is in unstable.  I hope to have a coherent bundle
ready for Eric sometime this weekend.

Sun Oct 26 14:03:53 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Delete xrefs icons.

Sun Oct 26 16:57:15 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Establish style conventions for reST user manual.

Sun Oct 26 18:00:46 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Move src/*.tex to doc/manual/*.txt.

Mon Oct 27 11:35:53 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Translate \label to reST.
  sed -i *.txt -e 's/\(.\)\(\\label\)/\1\n\2/' -e 's/\\label{\([^}]\+\)}/.. _\1:/'

Mon Oct 27 13:26:46 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Translate ``quotes'' to reST.
  sed -i *.txt -e "s/\`\`\|''/\"/g"

Mon Oct 27 14:02:31 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Translate TeX prelude to reST.

Mon Oct 27 14:30:14 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Translate \input{*.tex} to reST.
  Done by hand.

Mon Oct 27 14:41:17 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Reduce ToC bloat.

Mon Oct 27 14:41:41 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Improve PDF rendering.
  Add a header and footer, place a page break after the short ToC, then
  enforce two-column mode.

Mon Oct 27 15:12:34 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Link to (rather than including) to the GPL.
  
  Possibly this will be rolled back later, but for now I just want to
  avoid compilation errors in gpl.txt.

Sun Nov  2 17:06:39 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Partially rollback PDF improvements.
  
  The "header" and "footer" directives are also added to the HTML
  output, and header looks particularly ugly there.  I'm leaving the
  footer directive as is, because it's far less noticable on the HTML
  and more valuable for the PDF.

Mon Oct 27 13:47:38 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Translate \itemize to reST.
  sed -i *.txt -e '/\\begin{itemize}/,/\\end{itemize}/ s/\\item/- /' -e 's/\\\(begin\|end\){itemize}//'

Sun Nov  2 12:23:47 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Translate \input to reST (recursively).

Sun Nov  2 12:46:19 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Insert a blank line between command usage and description.
  
  For darcs help output to be valid reST input, there needs be a blank
  line between paragraphs.

Sun Nov  2 13:46:28 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Sort command-line options.
  
  For darcs help output to be valid reST input, the first option in each
  list of options MUST have a short version.  For example, "-v
  --verbose" is OK, but "--match" is not.

Sun Nov  2 23:32:27 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Make more documentation available in "darcs help".
  
  Some documentation that was going into the user manual would also be
  useful in "darcs help" output.  Move it into the commands' long help
  variables, so that it's available in *both* the manual and darcs help.

Mon Oct 27 13:29:03 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Translate \chapter, \section and \subsection to reST.
  sed -i *.txt -e '/\\chapter/a==============================' -e 's/\\chapter{\(.*\)}/\1/'
  sed -i *.txt -e '/\\section/a----------------------------------------------------------------------' -e 's/\\section\*\?{\(.*\)}/\1/'
  sed -i *.txt -e '/\\subsection/a~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~' -e 's/\\subsection\*\?{\(.*\)}/\1/'

Mon Oct 27 13:33:49 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Translate \verb to reST.
  sed -i *.txt -e 's/\\verb!\([^!]\+\)!/``\1``/g' -e 's/\\verb|\([^|]\+\)|/``\1``/g'
  sed -i *.txt -e 's/\\verb-\([^-]\+\)-/``\1``/g' -e 's/\\verb'\''\([^'\'']\+\)'\''/``\1``/g'

Mon Oct 27 13:39:43 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Translate --- (em dash) to reST.
  sed -ri *.txt -e 's/([^[:space:]-])---([^[:space:]-])/\1—\2/g'

Mon Oct 27 13:45:23 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Translate \emph to reST.
  sed -i *.txt -e 's/\\emph{\([^{}]*\)}/*\1*/g'

Mon Oct 27 13:51:31 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Translate \begin{verbatim} to reST.
  sed -i *.txt -e '/\\begin{verbatim}/,/\\end{verbatim}/ s/^/     /' -e '/\\begin{verbatim}/a::\n' -e 's/\\\(begin\|end\){verbatim}//'

Mon Oct 27 13:54:33 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Translate \tt and \em to reST.
  sed -i *.txt -e 's/{\\tt \+\([^{}]\+\)}/``\1``/g'
  sed -i *.txt -e 's/{\\em \+\([^{}]\+\)}/*\1*/g'

Mon Oct 27 14:12:44 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Translate \paragraph to reST.
  
  Done by hand.  I chose to use definition lists because it seemed the
  nearest equivalent.  In some cases I had to guess where the named
  "paragraph" ended, because really the paragraph names were mostly
  being abused as subsubsections.
  
  Probably during the cleanup pass, some of these should be turned into
  headings.  I'm particularly thinking of the long sections on GPG and
  procmail.

Mon Oct 27 15:32:42 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Translate tables to reST.
  Done manually, plus fixing the anchors via:
  sed -i *.txt -e '/.. _env:[[:alnum:]_]\+:/ s/env://'

Mon Oct 27 15:37:22 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Translate `single quotes' to reST.

Mon Oct 27 15:49:43 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Fix some indentation errors.

Mon Oct 27 15:50:25 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Fix some trailing comment errors.
  sed -i *.txt -e 's/%$//'

Mon Oct 27 15:51:36 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Fix a silly error.

Mon Oct 27 16:05:06 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Translate \ldots to reST.
  sed -i *.txt -e 's/\\ldots/.../g'
  
  Note that we don't use … because visually there's not much difference
  and unnecessary Unicode makes life harder for some contributors.

Mon Oct 27 16:07:05 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Translate ~ (non-breaking space) to reST.

Mon Oct 27 16:11:36 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Remove unnecessary escaping.

Mon Oct 27 16:14:08 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Translate \htmladdnormallinkfoot to reST.

Mon Oct 27 16:19:10 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Translate \ref to reST.

Mon Oct 27 16:24:28 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Translate spacing (\  and \@) to reST.

Mon Oct 27 16:29:54 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Translate \footnote to reST.

Wed Oct 29 14:57:06 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Conflict resolution.

Sun Nov  2 17:17:36 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Remove unnecessary headings.

Sun Nov  2 17:50:11 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Translate some TeX comments (%) to reST.

Sun Nov  2 17:51:25 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Remove unnecessary anchors.

Sat Nov  8 15:24:37 EST 2008  Trent W. Buck <trentbuck at gmail.com>
  * Teach make to render reST.

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: text/x-darcs-patch
Size: 412307 bytes
Desc: A darcs patch for your repository!
Url : http://lists.osuosl.org/pipermail/darcs-users/attachments/20081108/1d4a84f3/attachment-0001.bin 


More information about the darcs-users mailing list