From: Johannes Schindelin <Johannes.Schindelin@gmx.de>
To: Junio C Hamano <gitster@pobox.com>
Cc: "Jeff King" <peff@peff.net>,
git@vger.kernel.org, 마누엘 <nalla@hamal.uberspace.de>
Subject: Re: [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor`
Date: Thu, 12 Jan 2017 12:15:08 +0100 (CET) [thread overview]
Message-ID: <alpine.DEB.2.20.1701121130190.3469@virtualbox> (raw)
In-Reply-To: <xmqqinpmpld0.fsf@gitster.mtv.corp.google.com>
Hi Junio,
On Tue, 10 Jan 2017, Junio C Hamano wrote:
> 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.
next prev parent reply other threads:[~2017-01-12 11:15 UTC|newest]
Thread overview: 18+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-01-02 16:03 [PATCH 0/2] Fix the documentation to build with asciidoctor Johannes Schindelin
2017-01-02 16:03 ` [PATCH 1/2] asciidoctor: fix user-manual to be built by `asciidoctor` Johannes Schindelin
2017-01-04 8:08 ` Jeff King
2017-01-05 10:05 ` Lars Schneider
2017-01-05 13:49 ` Johannes Schindelin
2017-01-05 16:45 ` Jeff King
2017-01-07 22:00 ` Junio C Hamano
2017-01-07 22:08 ` brian m. carlson
2017-01-10 22:59 ` Junio C Hamano
2017-01-07 22:03 ` Junio C Hamano
2017-01-08 3:27 ` Jeff King
2017-01-10 23:04 ` Junio C Hamano
2017-01-12 11:15 ` Johannes Schindelin [this message]
2017-01-12 19:30 ` Junio C Hamano
2017-01-13 18:31 ` Junio C Hamano
2017-01-02 16:04 ` [PATCH 2/2] giteveryday: unbreak rendering with AsciiDoctor Johannes Schindelin
2017-01-04 8:15 ` Jeff King
2017-01-07 22:05 ` Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=alpine.DEB.2.20.1701121130190.3469@virtualbox \
--to=johannes.schindelin@gmx.de \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=nalla@hamal.uberspace.de \
--cc=peff@peff.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox