user-manual.txt: change header notation
authorMartin Ågren <martin.agren@gmail.com>
Sun, 22 Sep 2019 11:57:57 +0000 (13:57 +0200)
committerJunio C Hamano <gitster@pobox.com>
Sat, 28 Sep 2019 08:35:46 +0000 (17:35 +0900)
commitfd5b820d9c1688fde9505effd48a0d98be6a24cb
treebe196136d2cf95f7c6372d64f82d6466d85ad39c
parente79b34533affc98b78caa74700e182684d126e07
user-manual.txt: change header notation

When AsciiDoc processes user-manual.txt, it generates a book containing
chapters containing sections. So for example, we have chapter 6,
"Advanced branch management", which contains four relatively short
sections, 6.1-6.4. Asciidoctor generates a book containing *parts*
containing *chapters* instead. So part 6, "Advanced branch management"
contains four short chapters, 1-4. This looks a bit odd.

To make AsciiDoc (8.6.10) and Asciidoctor (1.5.5) handle these the same,
change from indicating chapters like so:

  [[foobar]]
  Foobar
  ======

to doing it like so:

  [[foobar]]
  == Foobar

Same thing for sections (line of dashes to ===), subsections (line of
tildes to ====) and subsubsections (line of carets to =====). Mark the
appendices with "[appendix]", which both AsciiDoc and Asciidoctor
understand. This means we need to drop the "Appendix X: " from their
titles, or those "Appendix X: " would be included literally in the name
of the appendix.

This commit is a no-op for AsciiDoc: The generated user-manual.xml is
identical before and after this patch. Asciidoctor now creates the same
chapter-section-subsection structure as AsciiDoc.

Changing the book title at the start of the document to similarly use
"=" instead of a line of equal signs makes no difference with any of the
engines, but let's do that change anyway for consistency.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Documentation/user-manual.txt