Re: [PATCH 2/2] doc: add new Git tutorial for beginners
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Oct 20, 2026, 19:13 UTC
- Message-ID
- <xmqqjyncuqwk.fsf@gitster.g>
- In-Reply-To
- <xmqq1p9kw6qu.fsf@gitster.g>
Junio C Hamano <gitster@pobox.com> writes:
Show 19 quoted lines
> Junio C Hamano <gitster@pobox.com> writes: > >> Julia Evans <julia@jvns.ca> writes: >> >>>> The goal is well described, and overall the tutorial is well-paced >>>> and avoids common beginner traps. Since Ben has covered the text >>>> fairly well, the remainder of this message has just some leftover >>>> nitpicks. >> >> My local build of 'seen' just saw these: >> >> gittutorial.adoc:124: section delimiter not preceded by an empty line >> gittutorial.adoc:487: section delimiter not preceded by an empty line >> >> I haven't checked what these two lines contain yet. > > Now I have. It was the underline-hyphen thing. The earlier one is > for Step 3. I missed, and the later one is what I pointed out in the > nitpick.
Regarding the topic in your other message, this discussion helps us contrast the two styles offered by AsciiDoc.
The Atx-style headers, e.g.,
= This is a first level header == this is a second level header
free us from the need to count characters for Setext-style headers, e.g.,
This is a first level header ============================ This is a second level header -----------------------------
Besides, counting characters becomes tricky once we step outside US-ASCII anyway, which is another reason to prefer the modern Atx-style prefix format.
I find it somewhat harder to notice when a section is at the wrong level in a document using Atx-style headers. With Setext-style, the long underline makes mismatches stand out; indeed, that is how I caught a handful of mistakes over the course of this project that I suspect I otherwise wouldn't have found. Once found, however, such a mistake is easier to correct.