Re: [PATCH 2/2] doc: add new Git tutorial for beginners

[Junio C Hamano <gitster@pobox.com>]

Junio C Hamano <gitster@pobox.com> writes:

> 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.