README.rdoc in dnote-0.9 vs README.rdoc in dnote-1.0
- old
+ new
@@ -11,41 +11,86 @@
output formats for them.
== SYNOPSIS
-Developer notes it the source code must be formatted as follows:
+=== 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 ...
-Any description that takes up more than one line must remain flush to the left
-margin (if the first line is flush to the left margin too) b/c RDoc will mistake
-of formatting the remaining lines as a +pre+ block it if is not. So...
+2) Specially designated notes can omit the colon. By default these are +TODO+,
++FIXME+ and +OPTIMIZE+.
- # LABEL: ... description ...
- # continue ...
+ # TODO description ...
-All consecutive notes must be separated by a blank lines.
+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><pre></tt> block if it is indented.
# LABEL: description ...
- #
- # LABEL: description ...
+ # continue ...
-Without the blank line the second note will be taken to be part of the first.
+4) An alternative to the limitation of the last rule is to indent the whole note, making it
+a <tt><pre></tt> block. Then the text layout is free-form.
-Alternately the whole note can be made a +pre+ block by indention. Then the
-layout if freed-form.
-
# This is a description of something...
#
# LABEL: description ...
- # continued ...
+ # continue ...
-With properly formatted notes, we then use the +dnote+ command line tool.
+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.
- $ dnote
-And lo! Pretty output. See <tt>dnote --help</tt> for more options.
+=== 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: