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

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 2, 2021, 22:23 UTC
Message-ID: <xmqqblaw2un9.fsf@gitster.g>
In-Reply-To: <xmqqsg482x4f.fsf@gitster.g>

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

Show 17 quoted lines

> Junio C Hamano <gitster@pobox.com> writes:
>
>> Firmin Martin <firminmartin24@gmail.com> writes:
>>
>>> For future reference, here are the content of the relevant & auto-generated files
>>> before this commit.
>>
>> 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.
>
> Another thing to look out for.  I do not think git.info is the only
> consumer of user-manual.txt.  Does this change affect the other
> consumer, user-manual.html, and if so how?

So, here is what "before and after" of the user-manual.xml output file looks like. It shows that the standalone document loses its Preface and all the chapters have been renumbered (because what was in the Preface has become the first chapter).

To pages like http://git-scm.com/docs/user-manual that take our source material and show them in preformatted, this change will cascade through. Hopefully these places won't be upset for not having the Preface (e.g. this particular site does not even refer to the chapters as "chapter 1", "chapter 2", etc.) but we'd never know until we try and break them ;-)

--- user-manual-without-patch.xml +++ user-manual.xml

@@ -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 @@ pages, or <ulink url="git-help.html">git-help(1)
 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">