Documentation update. Warn about file overwriting.

git-svn-id: https://svn.code.sf.net/p/docutils/code/trunk@8640 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

3 files changed, 64 insertions, 43 deletions

diff --git a/docutils/docs/howto/security.txt b/docutils/docs/howto/security.txt
index 2088f937a..6787439cf 100644
--- a/docutils/docs/howto/security.txt
+++ b/docutils/docs/howto/security.txt
@@ -19,11 +19,10 @@ not envisaged, therefore web security was not a consideration.  Once
 Docutils/reStructuredText started being incorporated into an
 ever-increasing number of web applications (blogs__, wikis__, content
 management systems, and others), several security issues arose and
-have been addressed.  This document provides instructions to help you
-secure the Docutils software in your applications.
-
-**Docutils does not come in a through-the-web secure state**, because this
-would inconvenience ordinary users.
+have been addressed.  Still, **Docutils does not come in a
+through-the-web secure state**, because this would inconvenience
+ordinary users.  This document provides pointers to help you secure
+the Docutils software in your applications.
 
 __ ../../FAQ.html#are-there-any-weblog-blog-projects-that-use-restructuredtext-syntax
 __ ../../FAQ.html#are-there-any-wikis-that-use-restructuredtext-syntax
@@ -32,25 +31,47 @@ __ ../../FAQ.html#are-there-any-wikis-that-use-restructuredtext-syntax
 The Issues
 ==========
 
+File Creation
+-------------
+
+Docutils does not do any checks before writing to a file:
+
+* Existing **files are overwritten** without asking!
+* Files may be **written to any location** accessible to the process.
+* There are **no restrictions to** the **file names**.
+
+Special care must be taken when allowing users to configure the *output
+destination* or the `warning_stream`_, `record_dependencies`_, or
+`_destination`_ settings.
+
+.. _warning_stream: ../user/config.html#warning-stream
+.. _record_dependencies: ../user/config.html#record-dependencies
+.. _`_destination`: ../user/config.html#destination
+
+
 External Data Insertion
 -----------------------
 
 There are several `reStructuredText directives`_ that can insert
-external data (files and URLs) into the immediate document.  These
+external data (files and URLs) into the output document.  These
 directives are:
 
-* "include_", by its very nature
-* "raw_", through its ``:file:`` and ``:url:`` options
-* "csv-table_", through its ``:file:`` and ``:url:`` options
+* "include_", by its very nature,
+* "raw_", through its ``:file:`` and ``:url:`` options,
+* "csv-table_", through its ``:file:`` and ``:url:`` options,
+* "image_", if `embed_images`_ is true.
 
 The "include_" directive and the other directives' file insertion
 features can be disabled by setting "file_insertion_enabled_" to
-0/false.
+"false__".
 
+__ ../user/config.html#configuration-file-syntax
 .. _reStructuredText directives: ../ref/rst/directives.html
 .. _include: ../ref/rst/directives.html#include
 .. _raw: ../ref/rst/directives.html#raw-directive
 .. _csv-table: ../ref/rst/directives.html#csv-table
+.. _image: ../ref/rst/directives.html#image
+.. _embed_images: ../user/config.html#embed-images
 .. _file_insertion_enabled: ../user/config.html#file-insertion-enabled
 
 
@@ -61,7 +82,7 @@ The "raw_" directive is intended for the insertion of
 non-reStructuredText data that is passed untouched to the Writer.
 This directive can be abused to bypass site features or insert
 malicious JavaScript code into a web page.  The "raw_" directive can
-be disabled by setting "raw_enabled_" to 0/false.
+be disabled by setting "raw_enabled_" to "false".
 
 .. _raw_enabled: ../user/config.html#raw-enabled
 
@@ -69,14 +90,14 @@ be disabled by setting "raw_enabled_" to 0/false.
 CPU and memory utilization
 --------------------------
 
-Parsing complex reStructuredText documents may require high processing
-ressources. This enables `Denial of Service` attacs using specially crafted
-input.
-
-It is recommended to enforce limits for the computation time and resource
-utilization of the Docutils process when processing untrusted input.
+Parsing **complex reStructuredText documents may require high
+processing ressources**. This enables `Denial of Service` attacs using
+specially crafted input.
 
-In addition, the "line_length_limit_" can be adapted.
+It is recommended to enforce limits for the computation time and
+resource utilization of the Docutils process when processing
+untrusted input. In addition, the "line_length_limit_" can be
+adapted.
 
 .. _line_length_limit: ../user/config.html#line-length-limit
 
@@ -91,8 +112,8 @@ If your application calls Docutils via one of the `convenience
 functions`_, you can pass a dictionary of default settings that
 override the component defaults::
 
-    defaults = {'file_insertion_enabled': 0,
-                'raw_enabled': 0}
+    defaults = {'file_insertion_enabled': False,
+                'raw_enabled': False}
     output = docutils.core.publish_string(
         ..., settings_overrides=defaults)
 
@@ -101,9 +122,9 @@ command-line options if applicable).  If this is not desired, you can
 disable configuration file processing with the ``_disable_config``
 setting::
 
-    defaults = {'file_insertion_enabled': 0,
-                'raw_enabled': 0,
-                '_disable_config': 1}
+    defaults = {'file_insertion_enabled': False,
+                'raw_enabled': False,
+                '_disable_config': True}
     output = docutils.core.publish_string(
         ..., settings_overrides=defaults)
 
diff --git a/docutils/docs/user/config.txt b/docutils/docs/user/config.txt
index cf4689ecc..3a7c36617 100644
--- a/docutils/docs/user/config.txt
+++ b/docutils/docs/user/config.txt
@@ -58,7 +58,7 @@ Paths are interpreted relative to the current working directory.
 Empty path items are ignored.
 
 In addition, a configuration file may be explicitly specified with the
-"--config" command-line option.  This configuration file is read after
+``--config`` command-line option.  This configuration file is read after
 the three implicit ones listed above (or the ones defined by the
 ``DOCUTILSCONFIG`` environment variable), and its entries will have
 priority.
@@ -956,21 +956,6 @@ attributes (values "compact" and "open") in the document.
 Default: enabled (True).
 Options: ``--compact-field-lists, --no-compact-field-lists``.
 
-embed_images
-~~~~~~~~~~~~
-
-Embed images in the output HTML file. If the image can be read from
-the local file system and its MIME type can be determined, it is
-base64_ encoded and included as a `data URI`_.
-
-Default: disabled (False).
-Options: ``--embed-images``, ``--link-images``
-
-New in Docutils 0.17.
-
-.. _base64: https://en.wikipedia.org/wiki/Base64
-.. _data URI: https://en.wikipedia.org/wiki/Data_URI_scheme
-
 
 .. _embed_stylesheet [html writers]:
 
@@ -1305,6 +1290,21 @@ __  https://www.w3.org/TR/html53/sections.html#the-h1-h2-h3-h4-h5-and-h6-element
 .. _HTML5: http://www.w3.org/TR/html5/
 
 
+embed_images
+""""""""""""
+
+Embed images in the output HTML file. If the image can be read from
+the local file system and its MIME type can be determined, it is
+base64_ encoded and included as a `data URI`_.
+
+Default: disabled (False).
+Options: ``--embed-images``, ``--link-images``
+
+New in Docutils 0.17.
+
+.. _base64: https://en.wikipedia.org/wiki/Base64
+.. _data URI: https://en.wikipedia.org/wiki/Data_URI_scheme
+
 
 [pep_html writer]
 ~~~~~~~~~~~~~~~~~
@@ -1738,7 +1738,7 @@ use_bibtex
 Specify style and database for the experimental `BibTeX` support, for
 example::
 
- --use-bibtex=mystyle,mydb1,mydb2
+  --use-bibtex=mystyle,mydb1,mydb2
 
 Default: "" (don't use BibTeX).  Option ``--use-bibtex``.
 
@@ -1855,8 +1855,8 @@ template__:
   "xelatex.tex" in the ``docutils/writers/latex2e/`` directory
   (installed automatically).
 
-  .. TODO: show full path with --help (like in the HTML writers) and
-     add the following line:
+  .. TODO: show full path with ``--help`` (like in the HTML writers)
+     and add the following line:
      for the exact machine-specific path, use the ``--help`` option).
 
   __ `template [latex writers]`_
diff --git a/docutils/docs/user/tools.txt b/docutils/docs/user/tools.txt
index b82f62fb2..2dd27c3f5 100644
--- a/docutils/docs/user/tools.txt
+++ b/docutils/docs/user/tools.txt
@@ -27,7 +27,7 @@ to generate a specific data format).
 Most front ends have common options and the same command-line usage
 pattern::
 
-    toolname [options] [<source> [<destination]]
+    toolname [options] [<source> [<destination>]]
 
 (The exceptions are buildhtml.py_ and rstpep2html.py_.)  See
 rst2html.py_ for concrete examples.  Each tool has a "``--help``"