[Docutils-checkins] SF.net SVN: docutils:[8404] trunk/docutils

[<mi...@us...>]

Revision: 8404
          http://sourceforge.net/p/docutils/code/8404
Author:   milde
Date:     2019-10-12 20:38:10 +0000 (Sat, 12 Oct 2019)
Log Message:
-----------
Document descriptive auto-IDs and future changes to ID generation.

Modified Paths:
--------------
    trunk/docutils/HISTORY.txt
    trunk/docutils/RELEASE-NOTES.txt
    trunk/docutils/docs/user/config.txt

Modified: trunk/docutils/HISTORY.txt
===================================================================
--- trunk/docutils/HISTORY.txt	2019-10-11 10:09:53 UTC (rev 8403)
+++ trunk/docutils/HISTORY.txt	2019-10-12 20:38:10 UTC (rev 8404)
@@ -37,9 +37,13 @@
 * docutils/nodes.py
 
   - Speed up Node.next_node().
+  - If `auto_id_prefix`_ ends with a "%", this is replaced with the tag
+    name.
   - Warn about Node.traverse() returning an iterator instead of a list
     in future.
 
+  .. _auto_id_prefix: docs/user/config.html#auto-id-prefix
+
 * docutils/statemachine.py
 
   - Patch [ 158 ]: Speed up patterns by saving compiled versions (eric89gxl)

Modified: trunk/docutils/RELEASE-NOTES.txt
===================================================================
--- trunk/docutils/RELEASE-NOTES.txt	2019-10-11 10:09:53 UTC (rev 8403)
+++ trunk/docutils/RELEASE-NOTES.txt	2019-10-12 20:38:10 UTC (rev 8404)
@@ -48,7 +48,20 @@
 
 * Remove ``utils.unique_combinations``
   (obsoleted by ``itertools.combinations``).
+  
+* The id_prefix_ setting will be prepended to the `reference name`_ *before*
+  conversion to an ID. (Currently it is prepended as-is, without checking
+  for conformance to Docutils' `ID naming rules`_.) This may change
+  generated IDs.
+  
+  Example: with ``--id-prefix="DU"``, a section with title "34.
+  May" currently gets the ID ``DU-may`` and after the change the ID
+  ``du-34-may``.
 
+* The default value for auto_id_prefix_ will change to "%". This means
+  auto-generated IDs will use the tag name as prefix. Set auto_id_prefix_ to
+  "id" if you want unchanged IDs or to "%" if you want descriptive IDs.
+
 * The default HTML writer "html" with frontend ``rst2html.py`` may change
   from "html4css1" to "html5".
 
@@ -59,9 +72,12 @@
   generated HTML code, e.g. because you use a custom style sheet or
   post-processing that may break otherwise.
 
+.. _id_prefix: docs/user/config.html#id-prefix
+.. _auto_id_prefix: docs/user/config.html#auto-id-prefix
 .. _rst2html.py: docs/user/tools.html#rst2html-py
+.. _reference name: docs/ref/rst/restructuredtext.html#reference-names
+.. _ID naming rules: docs/ref/rst/directives.html#rationale
 
-
 Release 0.16
 ============
 

Modified: trunk/docutils/docs/user/config.txt
===================================================================
--- trunk/docutils/docs/user/config.txt	2019-10-11 10:09:53 UTC (rev 8403)
+++ trunk/docutils/docs/user/config.txt	2019-10-12 20:38:10 UTC (rev 8404)
@@ -199,10 +199,13 @@
 
 Prefix prepended to all auto-generated IDs generated within the
 document, after id_prefix_.
+A trailing "%" is replaced with the tag name (new in Docutils 0.16).
 
-Default: "id".
+Default: "id". (Will be `changed to "%" in future`__.)
 Options: ``--auto-id-prefix`` (hidden, intended mainly for programmatic use).
 
+__ ../../RELEASE-NOTES.html#future-changes
+
 datestamp
 ---------
 

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.