From 96ebdac5277d0d3618355482a2d4f7bd7c2c0894 Mon Sep 17 00:00:00 2001 From: milde Date: Tue, 1 Sep 2020 21:50:38 +0000 Subject: [PATCH] small documentation update git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@8551 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docutils/docs/howto/security.txt | 35 ++++++++++++++++------------------- docutils/docs/ref/rst/directives.txt | 14 +++++++------- 2 files changed, 23 insertions(+), 26 deletions(-) diff --git a/docutils/docs/howto/security.txt b/docutils/docs/howto/security.txt index 0fc349167..a61109030 100644 --- a/docutils/docs/howto/security.txt +++ b/docutils/docs/howto/security.txt @@ -109,7 +109,7 @@ setting:: Via a Configuration File ------------------------ -You should secure Docutils via a configuration file: +You may secure Docutils via a configuration file: * if your application executes one of the `Docutils front-end tools`_ as a separate process; @@ -118,7 +118,7 @@ You should secure Docutils via a configuration file: * if you want to secure all Docutils deployments system-wide. If you call Docutils programmatically, it may be preferable to use the -methods described in section below. +methods described in the section above. Docutils automatically looks in three places for a configuration file: @@ -133,22 +133,12 @@ environment variable. Details about configuration files, the purpose of the various locations, and ``DOCUTILSCONFIG`` are available in the `"Configuration Files"`_ section of `Docutils Configuration`_. -To fully secure your Docutils installation, the configuration file +To fully secure a recent Docutils installation, the configuration file should contain the following lines:: [general] - file-insertion-enabled: - raw-enabled: - -.. Note:: Due to a bug in the definitions of these security-related - settings, the right-hand-side of the above lines (the values) - should be left blank, as shown. The bug was corrected on - 2006-11-12 and is reflected in Docutils releases 0.4.1 and higher. - In these versions, more verbose forms may be used, such as:: - - [general] - file-insertion-enabled: off - raw-enabled: no + file-insertion-enabled: off + raw-enabled: no .. _Docutils front-end tools: ../user/tools.html .. _"Configuration Files": ../user/config.html#configuration-files @@ -159,10 +149,17 @@ Version Applicability ===================== The ``file_insertion_enabled`` & ``raw_enabled`` settings were added -to Docutils 0.3.9; previous versions will ignore these settings. A -bug existed in the configuration file handling of these settings in -Docutils 0.4 and earlier. The bug was fixed with the 0.4.1 release on -2006-11-12. +to Docutils 0.3.9; previous versions will ignore these settings. + +A bug existed in the configuration file handling of these settings in +Docutils 0.4 and earlier: the right-hand-side of the (the +values) needed to be left blank:: + + [general] + file-insertion-enabled: + raw-enabled: + +The bug was fixed with the 0.4.1 release on 2006-11-12. Related Documents diff --git a/docutils/docs/ref/rst/directives.txt b/docutils/docs/ref/rst/directives.txt index 5960e5dcb..e598140ce 100644 --- a/docutils/docs/ref/rst/directives.txt +++ b/docutils/docs/ref/rst/directives.txt @@ -249,8 +249,6 @@ The following options are recognized: and the common options `:class:`_ and `:name:`_. -.. _substitution definition: restructuredtext.html#substitution-definitions - Figure ====== @@ -1292,11 +1290,13 @@ Non-standard element: imagemap. Directives for Substitution Definitions ----------------------------------------- -The directives in this section may only be used in substitution -definitions. They may not be used directly, in standalone context. +The directives in this section may only be used in `substitution +definitions`_. They may not be used directly, in standalone context. The `image`_ directive may be used both in substitution definitions and in the standalone context. +.. _substitution definitions: +.. _substitution definition: restructuredtext.html#substitution-definitions .. _replace: @@ -1310,8 +1310,8 @@ Replacement Text :Directive Content: A single paragraph; may contain inline markup. The "replace" directive is used to indicate replacement text for a -substitution reference. It may be used within substitution -definitions only. For example, this directive can be used to expand +substitution reference. It may be used within `substitution +definitions`_ only. For example, this directive can be used to expand abbreviations:: .. |reST| replace:: reStructuredText @@ -1342,7 +1342,7 @@ Unicode Character Codes :Directive Content: None. The "unicode" directive converts Unicode character codes (numerical -values) to characters, and may be used in substitution definitions +values) to characters, and may be used in `substitution definitions`_ only. The arguments, separated by spaces, can be: -- 2.11.4.GIT