Re: [PATCH v5] documentation: add tutorial for object walking

[Emily Shaffer <emilyshaffer@google.com>]

On Fri, Oct 11, 2019 at 07:50:10PM +0200, SZEDER Gábor wrote:
> On Thu, Oct 10, 2019 at 08:19:32AM -0700, Emily Shaffer wrote:
> > diff --git a/Documentation/MyFirstObjectWalk.txt b/Documentation/MyFirstObjectWalk.txt
> > new file mode 100644
> > index 0000000000..7085f17072
> > --- /dev/null
> > +++ b/Documentation/MyFirstObjectWalk.txt
> > @@ -0,0 +1,905 @@
> > +My First Object Walk
> > +======================
> 
> In our CI builds [1] Asciidoctor complains about the above line like
> this:
> 
>   asciidoctor: WARNING: MyFirstObjectWalk.txt: line 2: unterminated example block
> 
> I have no idea what it is trying to say, but I suspect that it
> complains about the length of that '=====' line not matching the
> length of the previous title line.  I kicked off a build with the
> '====' line shortened, and it did silence that warning, and the build
> succeeded.

Oh, I'm sure it's a consequence of changing it from "Revision" to
"Object" in the title.

> 
> Note, however, that we recently had a patch [2] that argued that a
> different header notation is better, at least for the Git User Manual.
> I'm not sure whether that applies for this tutorial as well; just
> mentioning it for consideration.

Interesting read! It looks like we actually do use the format that that
patch suggests is better, except for the title. I'll change the title to
come into line with everything else, since I'm sending a reroll anyways.

Thanks!
 - Emily