Rename .txt files to .rst

Docutils is quite clear about the standard filename extension for a reStructuredText file, so I don't see this accepted anytime soon.

The policies advise:

• Add an Emacs "local variables" block in a comment at the end of the document. See the end of this document for an example.

Compatible editors can use this to set the editing mode.

In the jed programmer's editor, I use a hook

% set rst (reStructured Text) mode for some cases
define text_mode_hook()
{
   % Set rst_mode for text files in the Docutils SVN working dir
   % and the Docutils test dir
   if ((is_substr(buffer_filename(), "docutils") or
       is_substr(buffer_filename(), "Test/Docutils"))
       and not is_substr(buffer_filename(), "Makefile")) {
      rst_mode();
      return(1);
   }
 % ...
 }

Maybe something similar is available in other "intelligent" editors, too.

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.

The links didn't render for some reason, let me try again:

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

Hei,

first of all I appreciate Adam nudging, although the project must slow him down, because not every docutils user is a programmer. For example removng rst2html.py is a 2 second change for Adam (more like 2 minutes for me) but might be hard for people running the same script for 10 years.

As for the file extension:

1. Adam's plea (very understandable) highlighting as the editor recognizes the file extension.
2. Editing or viewing for normal users. Will windows ask what to do with .rst files ?

I don't know
cheers

Will windows ask what to do with .rst files

Yes, if you double click on the file it will open a pop-up asking what application you want to use to edit the files, and then you can select 'notepad' (preinstalled) or any other text editor. Windows can then remember the file association.

removng rst2html.py ... might be hard for people running the same script for 10 years

I do understand entirely -- any change is by its very nature breaking fron the status quo ante.

The latest patch I proposed though has no breaking changes (keeps rst2html.py etc), but less of the enhancements.

Can I take it that you'd support this change @grubert? (Trying to forge consensus!)

A

P.S. I have added an image of the file association pop-up box, as it is on my Windows 10 PC.

The "de facto" status is why I did not reject the proposal right away.
I am not against "endorsing" rst as extension for rST files.
However, I remember David Goodger beeing very clear about his preference in this question on several occasions.
I don't think it is an urgent issue, so I prefer to let David decide.

Perhaps if we don't hear from him in a month (early Februray) we could revisit this issue? (I was taught to try to be explicit rather than 'in the future' for reminders!)

A

Thinking about this, I now favour changing the extension of rST source files to .rst. The PEP sources at peps.python.org are an "official precedence case".

Writer template files are not rST sources and should keep their extension.

Standard include files shoud change after an advance warning and transition period.
(We can implement a fallback with warning in the "include" directive implementation.)

I have recreated the branch/patch for the rename, please have a look:

• https://github.com/AA-Turner/docutils/pull/17
• https://github.com/AA-Turner/docutils/pull/17.patch

All .txt files in docutils/, web/, and sandbox/infrastructure/ have been renamed.

Writer template files remain unchanged.

A

We would need to adapt background scripts, too. I am unsure whether the following changes correctly describe the behaviour after applying this patch :

--- a/sandbox/infrastructure/docutils-update.local
+++ b/sandbox/infrastructure/docutils-update.local
@@ -14,10 +14,10 @@
 #
 # ATTENTION
 #
-# Any .html document with a corresponding .txt file is regenerated 
-# if the .txt has changed, but no new .html files will be generated.
+# Any .html document with a corresponding .rst file is regenerated 
+# if the .rst has changed, but no new .html files will be generated.
 #
-# * Funny thing: sf hides README.txt files.
+# * Funny thing: sf hides README.rst files.
 #
 # ATTENTION

I downloaded the patch set and tried to commit it to a local branch but failed:

milde@heinz:/usr/local/src/docutils-git-svn/docutils/docutils > git am -3 /tmp/17.patch 
Applying: Rename all .txt files to .rst
Applying: Update references to .txt files
Using index info to reconstruct a base tree...
M   docutils/test/test_utils/test__init__.py
.git/rebase-apply/patch:7937: trailing whitespace.
# Any .html document with a corresponding .rst file is regenerated 
error: patch failed: docutils/docs/ref/rst/history.rst:1
error: docutils/docs/ref/rst/history.rst: patch does not apply
error: Did you hand edit your patch?
It does not apply to blobs recorded in its index.
Patch failed at 0002 Update references to .txt files
hint: Use 'git am --show-current-patch=diff' to see the failed patch
When you have resolved this problem, run "git am --continue".
If you prefer to skip this patch, run "git am --skip" instead.
To restore the original branch and stop patching, run "git am --abort".

nut i would only apply on svn ... might be not what's wanted

applied the patch