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

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

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.