[Doc-SIG] Re: DPS file extensions

[Tony J Ibbs (Tibs)]

David Goodger wrote:
> After reconsidering Tony's original question and the ensuing
> discussion:
>
> > Could I suggest that we coin a standard extension for
> > DPS/reST files?
>
> I withdraw my objections to using a filename extension for
> reStructuredText files (be it .rst, .rest, .restxt, .rstxt,
> .rtxt, .rst.txt, .rest.txt, whatever), but I am loathe to
> *require* such an extension.

I agree that we shouldn't *require* an extension - sorry if it came over
as if I was being *that* awkward. I would rather like to have an
"extension you use by convention if you're going to use it" in the
documentation - but your list has several interesting possibilities
(although not the ones with two dots, please).

Of those given, I think the ones I lean towards most would be:

.rtxt    -- short, looks like .txt a bit
.restxt  -- a little long, but explicit
.rest    -- probably too unobvious

Hmm - so maybe the first with a side-option of the second...

> I'd rather not change the extensions of the files in */spec/,
> because people won't know what to make of them, whereas with
> .txt its obvious on first sight.

It's your directory, so (by the decision above) your decision. I
(myself, me) would still err on the side of introducing an extension by
example (since the directory is called "docs", etc., etc.), but this is
the sort of discussion to have over a drink (tea, coffee, cider,
spatlese, whatever) and we're on different sides of an ocean, so it's
probably better left for now!

> In Python-source mode (see? more than just docstrings ;-),
> __docformat__ contains the name of the markup language. Filename
> extensions don't apply here.

Sorry, me leaving out "obvious" stuff again - one of my "supporting
issues" was that in Python source code we already have established a way
of doing this job - but I didn't mention it since I'd already written
enough stuff, and I wasn't sure I could make it make sense.

> When processing standalone plaintext files, the user ought to know
> what s/he's got. A specific filename extension would be useful here,
> but a pain to the casual Windows and Mac user (no double-clicking
> to edit).

Extensions, as we've said, don't apply on Macs, so don't use them (but
isn't it a norm to register new filetypes on Macs so the correct icon
comes up?)

Windows actually makes it very easy to associate a file extension and an
icon - it can be done via the file Explorer Options/File Types
interface. And choosing how to *edit* an unknown extension is a matter
of telling the system once, and asking it to remember it, *if* it hasn't
been set up by the installer (difficult, as what one person uses to edit
text files may not be another person's preference).

And the same concerns *do* apply to a "modern" Unix-oid system, as well,
in these days of Gnome, KDE and other such things.

Anyway, too much text written by me on too little issue...

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Give a pedant an inch and they'll take 25.4mm
(once they've established you're talking a post-1959 inch, of course)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)