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

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 6, 2025, 23:47 UTC
Message-ID: <xmqqh656hbzy.fsf@gitster.g>
In-Reply-To: <xmqqo6zeixnk.fsf@gitster.g>

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

Show 11 quoted lines

>> Hi Brian. How about also renaming SubmittingPatches to
>> SubmittingPatches.adoc? This is AsciiDoc according to 049e64aa50
>> (Documentation: convert SubmittingPatches to AsciiDoc, 2017-11-12).
>
> 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 would prefer to see the general rule to be to rename s/txt/adoc/
> ONLY for files that we actually use AsciiDoc to convert to HTML or
> manpages, and leave other sleeping dogs unmolested.

The above is for ultra short-term.

Once the main part of the documentation changes to .adoc graduates to 'master', I do not mind another topic that updates those without the .txt suffix to learn to be formatted with AsciiDoc. And as a part of such an effort, such files will gain the .adoc suffix since that is how the Makefile finds which files to format with AsciiDoc.

We might decide not to format them with AsciiDoc simply because we have nowhere to _install_ them, though. Even in such a case, we may still want to give them the .adoc suffix, just to help editors.

Thanks.