[Docutils-develop] [docutils:patches] #187 Rename .txt files to .rst

[Adam T. <aa-...@us...>]

Hi Günter,

That text was written in 2002 -- twenty years ago.

I would argue that the *de facto*  reality is that ".rst" **is** the standard extension for reStructuredText files, and has been for quite some time -- it is required for Python Enhancement Proposals (PEP 12 [1]) and the Python documentation (since 2007 [2]). Wikipedia has used the `.rst` extension for 10 years [3]. The linux kernel has been using `.rst` files for 5 years, when they switched to reStructuredText [4]. Any tool using `linguist` will pick up `.rst` as the extension (since the start of the project in 2011) [5].

I could go on! My plea is to update the FAQ -- my suggested edit notes that "ReStructuredText files should be readable as plaintext", which I believe is in spirit of the original text. In response to the "why bother" comment in the original FAQ text -- I would argue it is as the rest of the world seems to assume that the extension is `.rst`, and Docutils as the official custodian of reStructuredText should embrace this.

A

---

Original FAQ text:

>**What's the standard filename extension for a reStructuredText file?:**
> It's ".txt".  Some people would like to use ".rest" or ".rst" or
> ".restx", but why bother?  ReStructuredText source files are meant to
> be readable as plaintext, and most operating systems already associate
> ".txt" with text files.  Using a specialized filename extension would
> require that users alter their OS settings, which is something that
> many users will not be willing or able to do.


[1]: https://python.github.io/peps/pep-0012/
[2]: https://github.com/python/cpython/tree/8ec7f656134b1230ab23003a94ba3266d7064122/Doc
[3]: https://en.wikipedia.org/w/index.php?title=ReStructuredText&diff=487960232&oldid=487396784
[4]: https://github.com/torvalds/linux/commit/22cba31bae9dc357622f09d22b82ca5a112b4fde#diff-65f82f80279ec12ce6d19e0a686d262618611be80d1a264e1cffed0d14c814a4
[5]: https://github.com/github/linguist/blob/37243ec6bed3e697beeb874fc94efb9e42ca7f8c/lib/linguist/extensions.yml#L502-L506


---

** [patches:#187] Rename .txt files to .rst**

**Status:** open
**Group:** None
**Created:** Wed Jan 05, 2022 05:51 PM UTC by Adam  Turner
**Last Updated:** Wed Jan 05, 2022 06:49 PM UTC
**Owner:** nobody


This change is in two parts -- the first commit does the rename and the second goes through and updates references to .txt files. All tests pass.

The benefit of this change is primarily for people -- on user interfaces with syntax highlighting (e.g. IntelliJ / VSCode / Notepad++ editors, code mirrors, etc), the text is presented natively as reStructuredText, and editor features can assist with e.g. autocompletion.

Docutils itself of course does not care which file extension is used. 

I have not renamed any of the include files or template files in `docutils.parsers` or `docutils.writers`, as they form part of the public API and would need a deprecation cycle (or aliasing in the parsing code)

A

Please see https://github.com/AA-Turner/docutils/pull/3 and https://github.com/AA-Turner/docutils/pull/3.patch for the commits and patch.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/patches/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/patches/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.