[IPython-dev] Link broken on github main-page

[MinRK]

On Wed, Feb 16, 2011 at 21:54, Fernando Perez <fperez.net at gmail.com> wrote:

> On Tue, Feb 15, 2011 at 10:38 AM, MinRK <benjaminrk at gmail.com> wrote:
> > The link is broken because GitHub doesn't support using '.txt' as a reST
> > extension, so it's interpreting the wrong text as a link.  We should
> > probably rename README.txt to README.rst, and link to the new doc page.
> > Is there a reason to *not* use .rst instead of .txt?
>
> Well, docutils does suggest using txt as the reST extension, their
> argument being that they ultimately are text files.  And on more
> gui-oriented platforms, it was deemed as nicer for new users who could
> double-click on a .txt file and get automatically a text editor
> instead of a dialog about what application to use.  So historically,
> we went with txt.
>

That makes sense.  Basic reST with headers, sections, emphasis and blocks is
perfectly readable
as nicely formatted plaintext.  However, to me it seems like if you want a
file to read
as plaintext as well as reST, you shouldn't use the markup that is less
readable like `link text <http://hiddenlink.com>`_,
and you can use .rst as an extension when you do use the extended reST bits.

My vote:

either a) remove the hidden links for better .txt readability (and correct
GH link parsing)
or b) rename to .rst so it looks nice on GitHub

I lean towards b), but if there really is a significant number of people who
actually read READMEs but are foiled by a .rst extension, then we can stick
to a).



>
> But I have no strong feelings on the matter, so if you guys prefer to
> switch over to rst so the github setup is smoother, I won't oppose it
> in any way.
>
> Cheers,
>
> f
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/ipython-dev/attachments/20110216/48734a34/attachment.html>