Document subdirectory note format (for keeping extra materials)

2 files changed, 22 insertions, 10 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
diff --git a/README.cli b/README.cli
index 91ae0f2..63c2e2f 100644
--- a/README.cli
+++ b/README.cli
@@ -116,10 +116,14 @@ The body of a note is free-form. However, for clarity, it makes sense to avoid
 using '\c{-}' for lists in the body ('\c{*}' for the first level and '\c{~}'
 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 \c{list} files. These
 files can appear at the top level or in any subdirectory. More complex notes
-can be placed in their own files.
+can be 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 \c{list} file, then its body must be indented two
 spaces to align with the start of the summary. Notes are separated with blank
@@ -167,7 +171,8 @@ 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 \c{list} file. Or we can move a note from \c{list} to its own
-file. For example, if we start expanding on our \"Implement pluggable
+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 \c{git} sense) changes to the database, use a separate
@@ -188,7 +193,8 @@ If you only have a single issue added in the database then you can use the
 \c{add} script to automate it. This script will commit the new issues with the
 correct message and, unless the \c{-c} option is specified, push the result to
 \c{origin}. This should make filing new notes a fairly burdenless process:
-write a note using your favorite text editor and run the \c{add} script.
+write a note using your favorite text editor and run the \c{add} script. Note
+that the \c{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