= D'Note

* home: http://proutils.github.com/dnote
* source: http://github.com/proutils/dnote
* forum: http://googlegroups.com/group/proutils


== DESCRIPTION

Extract developement notes from source code and generate some nice
output formats for them.


== SYNOPSIS

=== Note Structure

D'Note scans for the common noting pattern used by develepors of many laguages of an all-caps label
followed bt a colon. To be more specific, for D'Note to recogznie a note, it needs ot follow this 
simple set of rules:

1) Notes start with an all-caps label puctuated with a colon, followed by the note's text.

  # LABEL: description ...

2) Specially designated notes can omit the colon. By default these are +TODO+,
+FIXME+ and +OPTIMIZE+.

  # TODO description ...

3) Any note that requires more than one line must remain flush to the left
margin (the margin is set by the first line). This is done because RDoc will mistake
the note for a <tt>&lt;pre&gt;</tt> block if it is indented.

  # LABEL: description ...
  # continue ...

4) An alternative to the limitation of the last rule is to indent the whole note, making it 
a <tt>&lt;pre&gt;</tt> block. Then the text layout is free-form.

  # This is a description of something...
  #
  #   LABEL: description ...
  #          continue ...

That's all there is to it, if I can convince the developers of RDoc to add recognize labels,
we may eventually be able to relax the flush rule, which would be very nice.


=== Generating Notes

As you can see the commandline interface is quite straight-forward.

  Usage: dnote [OPTIONS] path1 [path2 ...]
   
  OUTPUT FORMAT: (choose one)
          --rdoc                       RDoc comment format
          --markdown                   Markdown wiki format
          --xml                        XML markup format
          --html                       HTML markup format
          --yaml                       YAML serialization format
          --json                       JSON serialization format
   
  OTHER OPTIONS:
          --label                      labels to collect
      -t, --title [TITLE]              title to use in headers
   
  STANDARD OPTIONS:
      -v, --verbose                    extra verbose output
          --debug                      debug mode
      -h, --help                       show this help information

The default path is <tt>**/*.rb</tt> and the default format <tt>--rdoc</tt>. 
Here is an example of DNote's current notes in RDoc format:

  = Development Notes

  == TODO

  === file://lib/dnote/notes.rb

  * TODO: Add ability to read header notes. They oftern
  have a outline format, rather then the single line. (19)
  * TODO: Need good CSS file. (22)
  * TODO: Need XSL? (24)

  === file://plug/syckle/services/dnote.rb

  * TODO: Should this service be part of the +site+ cycle? (18)

  (4 TODOs)



== INSTALLATION

The usual RubyGem's command:

  $ sudo gem install dnote


== COPYRIGHTS

(MIT License)

Copyright (c) 2006, 2009 Thomas Sawyer

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.