Change the `initial_header_level`_ setting's default to "2"

Browsers use the `same style for <h1> and <h2> when it's
nested in a section`.
cf. https://stackoverflow.com/questions/39547412/same-font-size-for-h1-and-h2-in-article

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

1 files changed, 15 insertions, 2 deletions

diff --git a/docutils/docs/user/config.txt b/docutils/docs/user/config.txt
index 3bc29674b..ca3139e99 100644
--- a/docutils/docs/user/config.txt
+++ b/docutils/docs/user/config.txt
@@ -976,7 +976,9 @@ initial_header_level
 The initial level for header elements.  This does not affect the
 document title & subtitle; see doctitle_xform_.
 
-Default: 1 (for "<h1>").  Option: ``--initial-header-level``.
+Default: writer dependent (see `[html4css1 writer]`_, `[html5 writer]`_,
+`[pep_html writer]`_).
+Option: ``--initial-header-level``.
 
 
 math_output
@@ -1139,7 +1141,7 @@ Pass an empty string (to either "stylesheet" or "stylesheet_path") to
 deactivate stylesheet inclusion.
 
 Default: writer dependent (see `[html4css1 writer]`_, `[html5 writer]`_,
-[pep_html writer]_).
+`[pep_html writer]`_).
 Options: ``--stylesheet-path``.
 
 __ `embed_stylesheet [html writers]`_
@@ -1216,6 +1218,9 @@ It shares all settings defined in the `[html writers]`_
 
 Writer specific defaults:
 
+`initial_header_level`_
+  1 (for "<h1>")
+
 `stylesheet_path <stylesheet_path [html writers]_>`__:
   "html4css1.css"
 
@@ -1253,15 +1258,20 @@ It shares all settings defined in the `[html writers]`_
 
 Writer specific defaults:
 
+`initial_header_level`_
+  2 (for "<h2>", cf. the `HTML5.3 Working Draft`__)
+
 `stylesheet_path <stylesheet_path [html writers]_>`__:
   "minimal.css,plain.css"
 
 New in Docutils 0.13.
 
+__  https://www.w3.org/TR/html53/sections.html#the-h1-h2-h3-h4-h5-and-h6-elements
 .. _HTML5 Writer: html.html#html5-polyglot
 .. _HTML5: http://www.w3.org/TR/html5/
 
 
+
 [pep_html writer]
 ~~~~~~~~~~~~~~~~~
 
@@ -1271,6 +1281,9 @@ all settings defined in the `[html writers]`_ and `[html4css1 writer]`_
 
 Writer specific defaults:
 
+`initial_header_level`_
+  1 (for "<h1>")
+
 `stylesheet_path <stylesheet_path [html writers]_>`__:
   "pep.css"