From 304c872fe96078e928742c34501ee545e76b556c Mon Sep 17 00:00:00 2001
From: milde <milde@929543f6-e4f2-0310-98a6-ba3bd3dd1d04>
Date: Sat, 12 Oct 2019 20:38:10 +0000
Subject: [PATCH] Document descriptive auto-IDs and future changes to ID
 generation.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@8404 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
---
 docutils/HISTORY.txt          |  4 ++++
 docutils/RELEASE-NOTES.txt    | 18 +++++++++++++++++-
 docutils/docs/user/config.txt |  5 ++++-
 3 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/docutils/HISTORY.txt b/docutils/HISTORY.txt
index 044cc1356..a42ef959d 100644
--- a/docutils/HISTORY.txt
+++ b/docutils/HISTORY.txt
@@ -37,9 +37,13 @@ Changes Since 0.15
 * 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)
diff --git a/docutils/RELEASE-NOTES.txt b/docutils/RELEASE-NOTES.txt
index 24d8b063c..2c2758405 100644
--- a/docutils/RELEASE-NOTES.txt
+++ b/docutils/RELEASE-NOTES.txt
@@ -48,6 +48,19 @@ Future changes
 
 * 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,8 +72,11 @@ Future changes
   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
 ============
diff --git a/docutils/docs/user/config.txt b/docutils/docs/user/config.txt
index 6f47a724e..3a8c9bb9a 100644
--- a/docutils/docs/user/config.txt
+++ b/docutils/docs/user/config.txt
@@ -199,10 +199,13 @@ auto_id_prefix
 
 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
 ---------
 
-- 
2.11.4.GIT