Re: [PATCH][GSoC] user-manual.txt: fix empty heading of introduction

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

Bagas Sanjaya <bagasdotme@gmail.com> writes:

> On 03/04/21 04.22, Junio C Hamano wrote:
>> I would have expected to see "before and after".  Is it too obvious
>> what the postimage would be?  Otherwise, a better presentation would
>> be to show (an excerpt from) diff between preimage and postimage
>> output.
>> Thanks.
>> 
> Attached is `diff -u` of generated HTML output, before and after this
> patch. The HTML is generated using Asciidoctor.

Unfortunately, that is more-or-less unreadable gunk.  Even for the
first few places that have differences, the output of diff between
raw HTML is not suited to spot that the first entry in the TOC has
changed classs from preface to chapter or how they are treated
differently.

What I did before sending out the message was to generate HTML for
the before and after versions, render them into text and then run
diff on them.  It showed that most changes are the chapter numbering
and cross reference, of course.  This was still hard to see, but at
least it was possible to eyeball what was going on [*].

While Firmin showed only the "before" version of .xml, a diff
between before-and-after versions of .xml turned out to be far
easier to see how the change propagates down the toolchain than
either of the above two.  It would have been  the best to have that,
instead of just the "before" image, in the explanation.

    --- user-manual.xml	2021-04-03 17:36:14.804344928 -0700
    +++ user-manual.xml	2021-04-03 17:36:44.599025868 -0700
    @@ -7,8 +7,8 @@
     <bookinfo>
         <title>Git User Manual</title>
     </bookinfo>
    -<preface>
    -<title></title>
    +<chapter id="introduction">
    +<title>Introduction</title>
     <simpara>Git is a fast distributed revision control system.</simpara>
     <simpara>This manual is designed to be readable by someone with basic UNIX
     command-line skills, but no previous knowledge of Git.</simpara>
    @@ -31,7 +31,7 @@
     without any explanation.</simpara>
     <simpara>Finally, see <xref linkend="todo"/> for ways that you can help make this manual more
     complete.</simpara>
    -</preface>
    +</chapter>
     <chapter id="repositories-and-branches">
     <title>Repositories and Branches</title>
     <section id="how-to-get-a-git-repository">

If an updated version is planned, I'd expect it to come with
something like the above indented patch plus a brief explanation of
side effects (i.e. we lost preface and we have renumbered the
chapters) in its proposed log message.

Thanks.


[Footnote]

* The text-rendered HTML would compare like this (just an excerpt).

--- /var/tmp/before.txt	2021-04-03 17:40:07.777307995 -0700
+++ /var/tmp/after.txt	2021-04-03 17:39:51.423836495 -0700
@@ -4,255 +4,259 @@
 
    Table of Contents
 
-   [1]1. Repositories and Branches
+   [1]1. Introduction
 
-   [2]How to get a Git repository
+   [2]2. Repositories and Branches
 

...

TOC numbering is of course off by one, as the patch promotes the
preface into the first chapter.

...

-   [114]B. Notes and todo list for this manual
+   [116]Todo list
 
-   [115]Todo list
+                            Chapter 1. Introduction
 
...

And of course, we now have the chapter title.

...

    Git is a fast distributed revision control system.
 
    This manual is designed to be readable by someone with basic UNIX
    command-line skills, but no previous knowledge of Git.
 
-   [116]Chapter 1, Repositories and Branches and [117]Chapter 2, Exploring
+   [117]Chapter 2, Repositories and Branches and [118]Chapter 3, Exploring

...

Cross references are all off-by-one, too.