git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`

From
Johannes Schindelin <johannes.schindelin@gmx.de>
Date
Jan 12, 2017, 11:15 UTC
Message-ID
<alpine.DEB.2.20.1701121130190.3469@virtualbox>
In-Reply-To
<xmqqinpmpld0.fsf@gitster.mtv.corp.google.com>
Hi Junio,
On Tue, 10 Jan 2017, Junio C Hamano wrote:
Show 27 quoted lines
> Jeff King <peff@peff.net> writes:
> 
> > On Sat, Jan 07, 2017 at 02:03:30PM -0800, Junio C Hamano wrote:
> >
> >> Is that a longer way to say that the claim "... is designed as a
> >> book" is false?
> >> 
> >> > So I dunno. I really do think "article" is conceptually the most
> >> > appropriate style, but I agree that there are some book-like things
> >> > (like appendices).
> >> 
> >> ... Yeah, I should have read forward first before starting to insert
> >> my comments.
> >
> > To be honest, I'm not sure whether "book" versus "article" was really
> > considered in the original writing. I think we can call it whichever
> > produces the output we find most pleasing. I was mostly just pointing at
> > there are some tradeoffs in the end result in flipping the type.
> 
> I understand.  
> 
> And I tend to agree that the silliness you observed (like a t-o-c
> for a one-section "chapter") is not quite welcome.
> 
> For now I queued only 2/2 which looked good.  I won't object if
> somebody else rerolls 1/2 to appease AsciiDoctor, but let's take an
> obviously good bit first.

For fun, I just reverted the article->book patch and I was greeted with this:

-- snip --
    ASCIIDOC user-manual.xml
asciidoctor: ERROR: user-manual.txt: line 44: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 477: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 477: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 477: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 1003: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 1003: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 1003: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 1003: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 1720: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 1720: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 1720: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 1720: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 1720: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 2462: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 2462: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 2462: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 2462: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 2814: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 2814: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 2814: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 2958: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 2958: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 2958: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 3514: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 3514: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 3514: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 3771: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 3771: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 3771: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 4147: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 4147: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 4147: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 4395: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 4395: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 4395: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 4401: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 4401: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 4636: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 4636: only book doctypes can
contain level 0 sections
asciidoctor: ERROR: user-manual.txt: line 4636: only book doctypes can
contain level 0 sections
-- snap --

It still builds, funnily enough, but the result is definitely worse on the eyes. The page is *really* long, and structuring it into individual parts does help the readability.

Compare for yourself: https://dscho.github.io/git/index.html (this will go away at some point in the future, but I do not think there is a way for me to send two 200+kB HTML files to the Git mailing list).

Ciao, Dscho

P.S.: I also tried to use [glossary] and [appendix] as appropriate, but it seems that AsciiDoc *insists* on level-2 sections in an appendix, while AsciiDoctor *insists* on level-3 sections. In other words, the following diff on top of my patch series yields the warning "asciidoc: WARNING: user-manual.txt: line 4411: section title out of sequence: expect ed level 2, got level 3" with AsciiDoc, while AsciiDoctor is totally happy:

commit 900e193f15d5d2ef32285b1db9eb24c10710b7c1
Author: Johannes Schindelin <johannes.schindelin@gmx.de>
Date:   Thu Jan 12 12:06:16 2017 +0100
    fixup! asciidoctor: fix user-manual to be built by `asciidoctor`
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index bc29298678..c1ab6ce453 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -4392,25 +4392,23 @@ You see, Git is actually the best tool to find out
about the source of Git
 itself!
 
 [[glossary]]
+[glossary]
 Git Glossary
 ============
 
-[[git-explained]]
-Git explained
--------------
-
 include::glossary-content.txt[]
 
 [[git-quick-start]]
-Appendix A: Git Quick Reference
-===============================
+[appendix]
+Git Quick Reference
+===================
 
 This is a quick summary of the major commands; the previous chapters
 explain how these work in more detail.
 
 [[quick-creating-a-new-repository]]
 Creating a new repository
--------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 From a tarball:
 
@@ -4432,7 +4430,7 @@ $ cd project
 
 [[managing-branches]]
 Managing branches
------------------
+~~~~~~~~~~~~~~~~~
 
 -----------------------------------------------
 $ git branch	     # list all local branches in this repo
@@ -4497,7 +4495,7 @@ $ git branch -r			# list all remote
branches
 
 [[exploring-history]]
 Exploring history
------------------
+~~~~~~~~~~~~~~~~~
 
 -----------------------------------------------
 $ gitk			    # visualize and browse history
@@ -4533,7 +4531,7 @@ $ git bisect bad		# if this revision is bad.
 
 [[making-changes]]
 Making changes
---------------
+~~~~~~~~~~~~~~
 
 Make sure Git knows who to blame:
 
@@ -4564,7 +4562,7 @@ $ git commit -a	   # use latest content of all
tracked files
 
 [[merging]]
 Merging
--------
+~~~~~~~
 
 -----------------------------------------------
 $ git merge test   # merge branch "test" into the current branch
@@ -4575,7 +4573,7 @@ $ git pull . test  # equivalent to git merge test
 
 [[sharing-your-changes]]
 Sharing your changes
---------------------
+~~~~~~~~~~~~~~~~~~~~
 
 Importing or exporting patches:
 
@@ -4621,7 +4619,7 @@ $ git push example test
 
 [[repository-maintenance]]
 Repository maintenance
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~
 
 Check for corruption:
 
@@ -4637,12 +4635,9 @@ $ git gc
 
 
 [[todo]]
-Appendix B: Notes and todo list for this manual
-===============================================
-
-[[todo-list]]
-Todo list
----------
+[appendix]
+Notes and todo list for this manual
+===================================
 
 This is a work in progress.
Previous: Junio C HamanoNext: Junio C Hamano
Message 13 of 18 in “Fix the documentation to build with asciidoctor”
  1. 0/2 Fix the documentation to build with asciidoctorJohannes Schindelin, Jan 2, 2017
  2. 1/2 asciidoctor: fix user-manual to be built by `asciidoctor`Johannes Schindelin, Jan 2, 2017
  3. Jeff KingJan 4, 2017
  4. Lars SchneiderJan 5, 2017
  5. Johannes SchindelinJan 5, 2017
  6. Jeff KingJan 5, 2017
  7. Junio C HamanoJan 7, 2017
  8. brian m. carlsonJan 7, 2017
  9. Junio C HamanoJan 10, 2017
  10. Junio C HamanoJan 7, 2017
  11. Jeff KingJan 8, 2017
  12. Junio C HamanoJan 10, 2017
  13. Johannes SchindelinJan 12, 2017
  14. Junio C HamanoJan 12, 2017
  15. Junio C HamanoJan 13, 2017
  16. 2/2 giteveryday: unbreak rendering with AsciiDoctorJohannes Schindelin, Jan 2, 2017
  17. Jeff KingJan 4, 2017
  18. Junio C HamanoJan 7, 2017

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.