Document subdirectory note format (for keeping extra materials)

1 files changed, 12 insertions, 6 deletions

diff --git a/README b/README
index 0ef2788..c75e205 100644
--- a/README
+++ b/README
@@ -93,10 +93,14 @@ The body of a note is free-form. However, for clarity, it makes sense to avoid
 using '-' for lists in the body ('*' for the first level and '~' for the second
 level are good options).
 
-Notes can be saved in two ways. Simple notes without a body or with a body
+Notes can be saved in three ways. Simple notes without a body or with a body
 containing one or two paragraphs can be written in the list files. These files
 can appear at the top level or in any subdirectory. More complex notes can be
-placed in their own files.
+placed in their own files. Finally, notes that have addition material (what
+traditional bug trackers would call "attachments") should be placed into their
+own subdirectories with both the directory and the note file (inside that
+subdirectory) having the same name. Other than that, such a subdirectory is
+free form; it can contain other files and subdirectories.
 
 If a note is written in the list file, then its body must be indented two
 spaces to align with the start of the summary. Notes are separated with blank
@@ -139,9 +143,10 @@ to bump at least the minor version.
 
 Note also that we can move notes freely between files. For example, we may add
 a new subdirectory and move all the notes that affect this functionality from
-the top-level list file. Or we can move a note from list to its own file. For
-example, if we start expanding on our "Implement pluggable formatter" idea,
-then it probably makes sense to move it into its own file.
+the top-level list file. Or we can move a note from list to its own file or
+from a file to a subdirectory if we need to keep some additional files with the
+note. For example, if we start expanding on our "Implement pluggable formatter"
+idea, then it probably makes sense to move it into its own file.
 
 When committing (in the git sense) changes to the database, use a separate
 commit for each note. When committing a newly added note, the commit message
@@ -157,7 +162,8 @@ If you only have a single issue added in the database then you can use the add
 script to automate it. This script will commit the new issues with the correct
 message and, unless the -c option is specified, push the result to origin. This
 should make filing new notes a fairly burdenless process: write a note using
-your favorite text editor and run the add script.
+your favorite text editor and run the add script. Note that the add script
+currently cannot handle notes with extra files.
 
 Once a note is acted upon (implemented or you have decided not to do anything
 about it), you can either delete it or move it to the reference. Simply