Eric Kow <[EMAIL PROTECTED]> writes:
> The first is to make the Cabal-oriented build system as a supported
> build system alongside the current makefile (*). [...] but one of the
> approaches has strong community support, and it is the one we will be
> going with.
+1 for that rationale.
> (*) It may be wise for us to keep the makefile and configure around
> for at least one more major release; we can revisit this in a
> later thread.
+1, and I'll stop messing with it now, honest.
> Keep in mind that these are just my personal objectives. Let's now
> hear about yours.
Regarding (user) documentation, my goals are:
Short Term
==========
Finish reSTization and get it into unstable
Avoid duplication between manual and "darcs help" by continuing to
generate both from the same source, but move more of the literate lines
in Darcs.Commands.* into the cmd_helpl attribute.
Turn any literate-style api docs into haddock comments, and turn any
.lhs files that don't have literate documentation into plain .hs files.
Learn to use the wiki effectively, i.e. from the command-line and Emacs.
>From there, get an idea of what is and isn't already on the wiki. Get
into the habit of folding useful information from the mailing list and
BTS into the wiki.
Medium or Long Term
===================
Once the above short term goals are complete, if I'm still a lazy
underworing slob, officially take on the role of Documentation Manager.
Audit and refactor the user manual and wiki for relevance, clarity,
currency (e.g. referring to fixed bugs), etc. In particular, reduce
duplication of information between the two by working out the "best"
place for each section, and having the other sources simply reference
(link to) it.
Thinking up new ways to make it supremely convenient and easy for both
developer and user who *want* to hack on the documentation, to do so.
Hopefully the lightweight markup of reST is a step in the right
direction. (LaTeX is great if you already know it, but not everybody
wants to shave that much yak.)
Investigate refactoring darcsman to be more of a useful "cheat sheet"
and less of a huge dump.
Investigate ways to generate user manual in split-page HTML form,
without losing the ability to operate with standard reST tools
(docutils, rst2pdf, odtwriter).
Investigate the possibillity of moving the wiki to a Darcs repository
backend, reST format and an ikiwiki-style compile-to-static-pages
approach -- WITHOUT sacrificing the ability for novices to edit articles
directly in-browser. (Currentlt this requires significant development,
on the order of one SoC students.)
Solicit volunteers to translate the manual into languages other than
English; hopefully moving most of the manual out of src/ and into
doc/manual will make it easier to fork off doc/manual-{ja,pt_BR}.
Following on from that, investigate the possibility of a multi-lingual
framework (like gettext/.po for C) for the numerous English language
strings in the source code -- particularly cmd_description and cmd_help,
which are incorporated into the user manual.
_______________________________________________
darcs-users mailing list
[email protected]
http://lists.osuosl.org/mailman/listinfo/darcs-users
