Add todo items to the documentation.

Signed-off-by: Edward Z. Yang <ezyang@mit.edu>

diff --git a/doc/repository-conversion.rst b/doc/repository-conversion.rst
index b1d0699cf06346aacdca5a18f723e923b331bd37..b770aedc8a64b178cef33056a8831fe4d539da02 100644 (file)
--- a/doc/repository-conversion.rst
+++ b/doc/repository-conversion.rst
@@ -16,7 +16,14 @@ module for the application that implements application specific logic, such
 as how to install, upgrade or backup the installation.
 
 Here is a tutorial for performing a conversion, using Wordpress as
-an example.
+an example.  We will implement only the functions necessary for installing
+an application--upgrades and backups are not described here.
+
+.. todo::
+
+    This guide duplicates a lot of what would be covered if you were
+    discussing how to create a new application from scratch.  Those
+    bits should be separated out and put in their own document.
 
 Setup
 -----
@@ -368,8 +375,6 @@ is stored: a quick grep tells us that it's in :file:`wp-includes/version.php`:
 
 We could now grab the :mod:`re` module and start constructing a regex to grab ``2.0.4``, but it
 turns out this isn't necessary: :meth:`wizard.app.php.re_var` does this for us already!
-If such a module doesn't exist, you should create it and place an equivalent ``re_var()``
-function for that language there.
 
 With this function in hand, writing a version detection function is pretty straightforward.
 There is one gotcha: the value that ``re_var`` returns as the second subpattern is quoted (the reasons for this
@@ -411,15 +416,27 @@ are simply dictionaries of variable names to functions: when you call the
 function, it performs either an extraction or a substitution.  However, we can
 use higher-level constructs to generate these functions for us.
 
-The magic sauce is a data structure we'll refer to as ``seed``.  Its form is
-a dictionary of variable names to a tuple ``(filename, regular expression)``.
-If we manually coded one out, it might look like:
+The magic sauce is a data structure we'll refer to as ``seed``.  Its form is a
+dictionary of variable names to a tuple ``(filename, regular expression)``.
+The regular expression has a slightly special form (which we mentioned
+earlier): it contains three (not two or four) subpatterns; the second
+subpattern matches (quotes and all) the value that the regular expression is
+actually looking for, and the first and third subpatterns match everything to
+the left and right, respectively.
+
+.. note::
+
+    The flanking subpatterns make it easier to use this regular expression
+    to perform a substitution: we are then allowed to use ``\1FOOBAR\3`` as
+    the replace value.
+
+If we manually coded ``seed`` out, it might look like:
 
 .. code-block:: python
 
     seed = {
         'WIZARD_DBSERVER': ('wp-config.php', re.compile(r'''^(define\('DB_HOST', )(.*)(\))''', re.M)),
-        'WIZARD_DBNAME': ('wp-config.php', re.compile(r'''^(define\('DB_NAME', )(.*)(\)), re.M)),
+        'WIZARD_DBNAME': ('wp-config.php', re.compile(r'''^(define\('DB_NAME', )(.*)(\))''', re.M)),
     }
 
 There's a lot of duplication, though.  For one thing, the regular expressions are almost
@@ -440,6 +457,9 @@ identical, safe for a single substitution within the string.  We have a function
     to be safe for inclusion in a regular expression, and also let you pass a list,
     and have correct behavior.  Check out :mod:`wizard.app.php` for some examples.
 
+    Additionally, if you are implementing a function for another language, or a general pattern of
+    variables, consider placing it in an appropriate language module instead.
+
 We can shorten this even further: in most cases, all of the configuration values live in
 one file, so let's make ourselves a function that generates the whole tuple:
 
@@ -505,3 +525,18 @@ commit as ``appname-x.y.z-scripts``, or in this specific case::
 
     git tag wordpress-2.0.4-scripts
     git push --tags
+
+Further reading
+---------------
+
+You've only implemented a scriptsified version for only a single version; most applications
+have multiple versions--you will have to do this process again.  Fortunately, the most
+time consuming parts (implementing logic for :class:`wizard.app.Application`) are already,
+done so you'll only have to tweak these algorithms if the application changes their
+format.
+
+.. todo::
+
+    Ultimately, we should have another condensed page that describes how to craft
+    an update (with emphasis on what tests to perform to make sure things still
+    work), and pages on how to implement upgrades and backups.