Garden ReST.

README.rst

@@ -4,28 +4,29 @@ Zope External Editor
 The Zope External Editor is a new way to integrate Zope more seamlessly with
 client-side tools. It has the following features:
 
-    - Edit objects locally, directly from the ZMI.
+- Edit objects locally, directly from the ZMI.
 
-    - Works with any graphical editor application that can open a file from the
-      command line, including: emacs, gvim, xemacs, nedit, gimp, etc.
+- Works with any graphical editor application that can open a file from the
+  command line, including: emacs, gvim, xemacs, nedit, gimp, etc.
 
-    - Automatically saves changes back to Zope without ending the editing session.
+- Automatically saves changes back to Zope without ending the editing
+  session.
 
-    - Associate any client-side editor application with any Zope object by
-      meta-type or content-type. Both text and binary object content can be
-      edited.
+- Associate any client-side editor application with any Zope object by
+  meta-type or content-type. Both text and binary object content can be
+  edited.
 
-    - Locks objects while they are being edited. Automatically unlocks them when
-      the editing session ends.
+- Locks objects while they are being edited. Automatically unlocks them
+  when the editing session ends.
 
-    - Can add file extensions automatically to improve syntax highlighting or
-      file type detection.
+- Can add file extensions automatically to improve syntax highlighting or
+  file type detection.
 
-    - Works with basic auth, cookie auth and Zope versions. Credentials are
-      automatically passed down to the helper application. No need to
-      reauthenticate.
+- Works with basic auth, cookie auth and Zope versions. Credentials are
+  automatically passed down to the helper application. No need to
+  reauthenticate.
 
-    - https support (Openssl required)
+- https support (Openssl required)
 
 Using It
 --------
@@ -74,43 +75,43 @@ file, and has no concept of where it originated from.
 To solve this problem, I have developed a helper application whose job is
 essentially two-fold:
 
-    - Determine the correct editor to launch for a given Zope object
+- Determine the correct editor to launch for a given Zope object
 
-    - Get the data back into Zope when the changes are saved
+- Get the data back into Zope when the changes are saved
 
 So, let's take a step by step look at how it works:
 
-    1. You click on the external editor link (the pencil icon) in the Zope
-       management interface.
+1. You click on the external editor link (the pencil icon) in the Zope
+   management interface.
 
-    2. The product code on the server creates a response that encapsulates the
-       necessary meta-data (URL, meta-type, content-type, cookies, etc) and the
-       content of the Zope object, which can be text or binary data. The
-       response has the contrived content-type "application/x-zope-edit".
+2. The product code on the server creates a response that encapsulates the
+   necessary meta-data (URL, meta-type, content-type, cookies, etc) and the
+   content of the Zope object, which can be text or binary data. The
+   response has the contrived content-type "application/x-zope-edit".
 
-    3. The browser receives the request, and finds our helper application
-       registered for "application/x-zope-edit". It saves the response data
-       locally to disk and spawns the helper app to process it.
+3. The browser receives the request, and finds our helper application
+   registered for "application/x-zope-edit". It saves the response data
+   locally to disk and spawns the helper app to process it.
 
-    4. The helper app, reads its config file and the response data file. The
-       meta-data from the file is parsed and the content is copied to a new
-       temporary file. The appropriate editor program is determined based on
-       the data file and the configuration.
+4. The helper app, reads its config file and the response data file. The
+   meta-data from the file is parsed and the content is copied to a new
+   temporary file. The appropriate editor program is determined based on
+   the data file and the configuration.
 
-    5. The editor is launched as a sub-process of the helper app, passing it the
-       file containing the content data.
+5. The editor is launched as a sub-process of the helper app, passing it the
+   file containing the content data.
 
-    6. If so configured, the helper app sends a WebDAV lock request back to Zope
-       to lock the object.
+6. If so configured, the helper app sends a WebDAV lock request back to Zope
+   to lock the object.
 
-    7. Every so often (if so configured), the helper app stats the content file
-       to see if it has been changed. If so, it sends an HTTP PUT request
-       back to Zope containing the new data.
+7. Every so often (if so configured), the helper app stats the content file
+   to see if it has been changed. If so, it sends an HTTP PUT request
+   back to Zope containing the new data.
 
-    8. When the editor is closed, the content file is checked one more time and
-       uploaded if it has changed. Then a WebDAV unlock request is sent to Zope.
+8. When the editor is closed, the content file is checked one more time and
+   uploaded if it has changed. Then a WebDAV unlock request is sent to Zope.
 
-    9. The helper application exits.
+9. The helper application exits.
 
 Configuration
 -------------
@@ -126,7 +127,9 @@ directory.
 
 The configuration file follows the standard Python ConfigParser format,
 which is pretty much like the old .ini file format from windows. The file
-consists of sections and options in the following format::
+consists of sections and options in the following format:
+
+.. code-block:: ini
 
     [section 1]
     option1 = value
@@ -140,51 +143,69 @@ Options
 
 The available options for all sections of the config file are:
 
-    editor -- Command line or plugin name used to invoke the editor
-    application. On Windows, if no editor setting is found for an object you
-    edit, the helper app will search the file type registry for an
-    appropriate editor based on the content-type or file extension of the
-    object (which can be specified using the extension option below). By
-    default, the file path of the local file being edited is appended to
-    this command line. To insert the file path in the middle of your
-    command, use "$1" for Unix and "%1" for Windows respectively.
-
-    save_interval -- (float) The interval in seconds that the helper
-    application checks the edited file for changes.
-
-    use_locks -- (1 or 0) Whether to use WebDAV locking. The user editing must
-    have the proper WebDAV related permissions for this to work.
-
-    always_borrow_locks -- (1 or 0) When use_locks is enabled this features
-    suppresses warnings when trying to edit an object you have already locked.
-    When enabled, external editor will always "borrow" the existing lock token
-    instead of doing the locking itself. This is useful when using CMFStaging
-    for instance. If omitted, this option defaults to 0.
-
-    cleanup_files -- (1 or 0) Whether to delete the temp files created.
-    WARNING the temp file coming from the browser contains authentication
-    information and therefore setting this to 0 is a security risk,
-    especially on shared machines. If set to 1, that file is deleted at the
-    earliest opportunity, before the editor is even spawned. Set to 0 for
-    debugging only.
-
-    extension -- (text) The file extension to add to the content file. Allows
-    better handling of images and can improve syntax highlighting.
-
-    temp_dir -- (path) Path to store local copies of object data being
-    edited. Defaults to operating system temp directory. *Note: this setting
-    has no apparent effect on Windows* 8^(
-
-    long_file_name -- (1 or 0) Whether to include the whole path to the
-    object including the hostname in the file name (the default) or just the
-    id of the object being edited. Turn this option off for shorter file
-    names in your editors, and for editors that don't like long names.
-
-    file_name_separator -- (string) Character or characters used to separate
-    path elements in long files names used by external editor. Defaults to
-    a comma (,). This must be a legal character for use in file names on
-    your platorm (i.e., don't use a path separator character!). This option
-    is ignored if 'long_file_name' is set to 0.
+``editor``
+
+    Command line or plugin name used to invoke the editor application. On
+    Windows, if no editor setting is found for an object you edit, the
+    helper app will search the file type registry for an appropriate editor
+    based on the content-type or file extension of the object (which can be
+    specified using the extension option below). By default, the file path
+    of the local file being edited is appended to this command line. To
+    insert the file path in the middle of your command, use "$1" for Unix
+    and "%1" for Windows respectively.
+
+``save_interval``
+
+    (float) The interval in seconds that the helper application checks the
+    edited file for changes.
+
+``use_locks``
+
+    (1 or 0) Whether to use WebDAV locking. The user editing must have the
+    proper WebDAV related permissions for this to work.
+
+``always_borrow_locks``
+
+    (1 or 0) When use_locks is enabled this features suppresses warnings
+    when trying to edit an object you have already locked.  When enabled,
+    external editor will always "borrow" the existing lock token instead of
+    doing the locking itself. This is useful when using CMFStaging for
+    instance. If omitted, this option defaults to 0.
+
+``cleanup_files``
+
+    (1 or 0) Whether to delete the temp files created.  WARNING the temp
+    file coming from the browser contains authentication information and
+    therefore setting this to 0 is a security risk, especially on shared
+    machines. If set to 1, that file is deleted at the earliest
+    opportunity, before the editor is even spawned. Set to 0 for debugging
+    only.
+
+``extension``
+
+    (text) The file extension to add to the content file. Allows better
+    handling of images and can improve syntax highlighting.
+
+``temp_dir``
+
+    (path) Path to store local copies of object data being edited. Defaults
+    to operating system temp directory. *Note: this setting has no apparent
+    effect on Windows* 8^(
+
+``long_file_name``
+
+    (1 or 0) Whether to include the whole path to the object including the
+    hostname in the file name (the default) or just the id of the object
+    being edited. Turn this option off for shorter file names in your
+    editors, and for editors that don't like long names.
+
+``file_name_separator``
+
+    (string) Character or characters used to separate path elements in long
+    files names used by external editor. Defaults to a comma (,). This must
+    be a legal character for use in file names on your platorm (i.e., don't
+    use a path separator character!). This option is ignored if
+    'long_file_name' is set to 0.
 
 Sections
 --------
@@ -199,18 +220,18 @@ used.
 
 Additional sections can apply to a particular domain, content-type or
 meta-type. Since objects can have all these properties, the options are
-applied in this order of precedence.
+applied in this order of precedence:
 
-    - `[content-type:text/html]` -- Options by whole content-type come first.
+1. Options by whole content-type (e.g., `[content-type:text/html]`).
 
-    - `[content-type:text/*]` -- Options by major content-type come second.
+2. Options by major content-type (e.g., `[content-type:text/*]`).
 
-    - `[meta-type:File]` -- Options by Zope meta-type are third.
+3. Options by Zope meta-type (e.g., `[meta-type:File]`).
 
-    - `[domain:www.mydomain.com]` -- Options by domain follow. Several
-      sections can be added for each domain level if desired.
+4. Options by domain (e.g., `[domain:www.mydomain.com]`). Several
+   sections can be added for each domain level if desired.
 
-    - `[general]` -- General options are last.
+5.  General options (i.e., `[general]`).
 
 This scheme allows you to specify an extension by content-type, the
 editor by meta-type, the locking settings by domain and the remaining
@@ -261,16 +282,19 @@ still use the plugin where possible.
 Plugin Notes
 ------------
 
-Photoshop -- Photoshop's COM API is quite limited, and external editor
-cannot detect that you have closed a file until you exit the entire
-application (it can still detect saves). Therefore you may want to turn
-off DAV locking (use_locks=0) or borrow locks (always_borrow_locks=1)
-when using it.
+Photoshop
 
-Dreamweaver -- External editor cannot detect when you have finished
-editing a single file. Objects edited with Dreamweaver will remain
-locked on the server until you exit the application. As with Photoshop
-above, you may want to turn off locking for Dreamweaver.
+    Photoshop's COM API is quite limited, and external editor cannot detect
+    that you have closed a file until you exit the entire application (it
+    can still detect saves). Therefore you may want to turn off DAV locking
+    (use_locks=0) or borrow locks (always_borrow_locks=1) when using it.
+
+Dreamweaver
+
+    External editor cannot detect when you have finished editing a single
+    file. Objects edited with Dreamweaver will remain locked on the server
+    until you exit the application. As with Photoshop above, you may want
+    to turn off locking for Dreamweaver.
 
 If your favorite editor needs a plugin because the general support is
 not good enough, please let me know. Keep in mind that I must be able to
@@ -305,11 +329,11 @@ application. You can take advantage of this functionality easily in your
 own content management applications.
 
 Say you have an FTP editable object, "document", in a Zope folder named
-"my_stuff". The URL to view the object would be::
+"my_stuff". The URL to view the object would be:
 
     http://zopeserver/my_stuff/document
 
-The URL to kick off the external editor on this document would be::
+The URL to kick off the external editor on this document would be:
 
     http://zopeserver/my_stuff/externalEdit_/document
 
@@ -318,7 +342,9 @@ the end of the URL. Because `externalEdit_` is required to work on Python
 Scripts and Page Templates, which swallow the remaining path segments on
 the URL following themselves, you must put the call to `externalEdit_`
 *directly before* the object to be edited. You could do this in ZPT using
-some TAL in a Page Template like::
+some TAL in a Page Template like:
+
+.. code-block:: html
 
     <a href='edit'
        attributes='href
@@ -330,10 +356,12 @@ As an alternative, you can also pass the path the object you want to edit
 directly to the `externalEdit_` object when you call its index_html method.
 It can be called either directly by URL or from a python script.
 `externalEdit_` will return the proper response data for the object to edit.
-Here are some examples::
+Here are some examples:
 
     http://zopeserver/externalEdit_?path=/my_stuff/document
 
+.. code-block:: python
+
     return context.externalEdit_.index_html(
         context.REQUEST, context.RESPONSE, path='/my_stuff/document')
 
@@ -343,7 +371,7 @@ after displaying a confirmation dialog box. Although you can make this
 automatic by specifying 'always_borrow_locks = 1' in the External Editor
 config file, it may be desireable to make this the default behavior when
 using that server. To facilitate this, you can specify that locks
-should be automatically borrowed in the URL (New in 0.7)::
+should be automatically borrowed in the URL (New in 0.7):
 
     http://zopeserver/my_stuff/externalEdit_/document?borrow_lock=1
 
@@ -357,7 +385,9 @@ an empty string.
 The method is 'externalEditLink_(object)'. The object argument is the
 object to create the link for if appropriate. Here is some example page
 template code that inserts links to objects in the current folder and the
-external editor icon where appropriate::
+external editor icon where appropriate:
+
+.. code-block:: html
 
     <div tal:repeat="object here/objectValues">
       <a href="#"