Re: [PATCH 4/5] doc: use .adoc extension for AsciiDoc files

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

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

> "D. Ben Knoble" <ben.knoble@gmail.com> writes:
>
>>> Do we pass SubmittingPatches (and CodingGuidelines for that matter)
>>> through AsciiDoc?  They do not even have .txt suffix, so I suspect
>>> it is not.
>>
>> I don't know how (I didn't dig), but we do build and package
>> HTML-ified SubmittingPatches as both $(git
>> --html-path)/SubmittingPatches.{html,txt}. I don't see a build output
>
> I was wondering why we remove SubmittingPatches.txt with "make
> clean" there the other day.  There is a Documentation/Makefile
> target to create %.txt from % applied for SubmittingPatches.

Interesting.  I very much am sympathetic to the original reasoning
why Documentation/Makefile is set up this way at 049e64aa
(Documentation: convert SubmittingPatches to AsciiDoc, 2017-11-12).

Here is what its commit log message says:

    Since the makefile needs a .txt extension in order to build with the
    rest of the documentation, simply copy the file.  Ignore the temporary
    file so it doesn't get checked in accidentally, and remove it as part of
    the clean process.  Do this instead of renaming the file so that people
    who have already linked to the documentation (who we're trying to help)
    don't find their links broken.  Avoid symlinking since Windows will not
    like that.

One could argue that we made a lot more damage when we renamed all
the .txt files to .adoc to external links people have had forever,
but I guess SubmittingPatches is more special than say git-add.txt
or git.txt for that matter, as the latter class have preformatted
".html" copies people would link to rather than the original ".txt".

Before the "let's avoid renaming and instead copy to a temporary
.txt file to run AsciiDoc on it" commit, it seems that we kept the
file in our source tree without copying anywhere else?  It is very
much understandable as the target audiences are those who want to
work on our code, so it is a fair assumption that they have local
copies at hand, without others having to give them public URLs to
read on the Web.

"CodingGuidelines" is still treated that way, which is probably what
we want to fix, by exposing it on the Web.  I'd imagine that it is
sufficient to just rename it to "CodingGuidelines.adoc" without
worrying about those who "have already linked to the documentation",
but others may feel differently.  And if we do decide to rename it,
we may want to rethink what we do to "SubmittingPatches" as well.

We've had ".html" versions of the document out there for very long,
so hopefully people would already have updated their links to point
them, not the one without any suffix, in which case we can stop
special casing "SubmittingPatches".

Thanks.