+
+
Developer's take note! All those TODO's and FIXME's floating around
+ your source code are rotting away. They are trapped, and in desperate need of your attention.
+
+
But not to fret! D'Note will help you liberate them. D'Note will scan your
+ source code for labeled comments; collect, collate and sort them; and then return them to you in a
+ format of your choosing. Wunderbar!
+
+
Note Structure
+
+
D'Note scans for the common "LABEL:" pattern (all-caps label followed by a colon) used by many
+ developers of many languages. To be more specific, for D'Note to recognize a note, it needs to
+ conform to the following simple set of rules:
+
+
1) Notes start with an all-caps label punctuated with a colon, followed by the note's text.
+
+
+ # LABEL: description ...
+
+
+
+
+
2) 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 second line for a <pre> block if it is indented.
+
+
+ # LABEL: description ...
+ # continue ...
+
+
+
3) An alternative to the limitation of the last rule is to indent the whole note (making
+ the whole note a <pre> block with regards to RDoc). 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 recognition of
+ labels, we may eventually be able to relax the flush rule too, which would be very nice.
+
+
There is also a command-line option, --no-colon, which deactives the need for
+ a colon after the note label. However this often produces false positives, so it's use is
+ discouraged.
+
+
Generating Notes
+
+
As you can see the commandline interface is quite straight-forward.
+
+
+ USAGE:
+
+ dnote [OPTIONS] path1 [path2 ...]
+
+ OUTPUT FORMAT: (choose one)
+ -f, --format NAME select a format [text]
+ -C, --custom FILE use a custom ERB template
+ --file shortcut for text/file format
+ --list shortcut for text/list format
+
+ OTHER OPTIONS:
+ -l, --label LABEL labels to collect
+ --[no-]colon match labels with/without colon suffix
+ -m, --marker MARK alternative remark marker
+ -u, --url TEMPLATE url template for line entries (for HTML)
+ -c, --context INTEGER number of lines of context to display
+ -x, --exclude PATH exclude file or directory
+ -i, --ignore NAME ignore file based on any part of pathname
+ -t, --title TITLE title to use in header
+ -o, --output PATH save to file or directory
+ -n, --dryrun do not actually write to disk
+ --debug debug mode
+
+ COMMAND OPTIONS:
+ -T, --templates list available format templates
+ -h, --help show this help information
+
+
+
There are a variety of formats are available, here are examples of some of the
+ XML, HTML and YAML
+ formats. You can get a list of all available format templates using the -T option.
+
+
The default path is **/*.rb and the default format -f text.
+ Here is an example of DNote's own notes in -f rdoc format:
+
+
+ = Development Notes
+
+ == TODO
+
+ === file://lib/dnote/notes.rb
+
+ * TODO: Add ability to read header notes. They often
+ have a outline format, rather then the single line. (19)
+ * TODO: Need CSS? (22)
+ * TODO: Need XSL? (24)
+
+ === file://plug/syckle/services/dnote.rb
+
+ * TODO: Should this service be part of the +site+ cycle? (18)
+
+ (4 TODOs)
+
+
+
In the future the parsing may imnprove to allow page-top outlined notes as well.
+
+
+
+