Re: [Denemo-devel] Documentation Cleanup

[Richard Shann]

On Wed, 2009-06-17 at 00:04 -0400, Benjamin wrote:
> In the repository, the /doc directory could be cleaner.  For example,
> DESIGN and DESIGN.lilypond contain overlapping information, ROADMAP
> doesn't match the roadmap on the website,
The website contains the up-to-date information on design, roadmap todo
etc.  Being a wiki it is much easier to maintain than the files in git,
so I think those things in git could be reduced to links.


>  there are files that could be
> generated instead of included (e.g. 4for2.abc), README is out of date,
> all of the files are poorly formatted, and the DocBook format is
> unreadable.
> 
> I propose the following changes:
> 
> - Reformat and clean up all the documentation
> - Convert all the documentation to restructured text

What is restructured text?
 The only documentation I am maintaining is doc/denemomanual.xml (and I
am deriving denemo-manual.html from it via a command hacked out of the
makefile, because this is also checked in to git). I edit it (rather
painfully) in emacs.


> - Move all documentation to the /doc directory
> - Add a code-and-documentation-generation phase to the build.  This
>   should happen before the release so it wont add dependencies.
>   (i.e. The generated files should be included in the snapshots and
>   releases but not in git)
> - Add a document describing the overall layout of the code and suggest
>   an approach to reading it.
> 
> Given approval, I am willing to try my hand at making these changes.
That would be great - let me know if you are going to do something with
doc/denemomanual.xml so that we don't have to merge any work.

Richard


> 
> 
> _______________________________________________
> Denemo-devel mailing list
> address@hidden
> http://lists.gnu.org/mailman/listinfo/denemo-devel