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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.