[Biopython-dev] Using markup for the README file on GitHub

[Peter Cock]

On Wed, Jun 6, 2012 at 1:27 PM, Wibowo Arindrarto
<w.arindrarto at gmail.com> wrote:
> Hi everyone,
>
>> The major downside is for any markup to be rendered on GitHub,
>> you must use one of the supported extensions - which is a problem
>> for projects using README (no extension) or README.txt (which
>> is nicer for Windows users). As per a heated discussion on GitHub
>> https://github.com/github/markup/issues/3 it appears the hack
>> solution for projects wanting to maintain their existing convention
>> is to add a symlink with the markup extension (e.g. README.md
>> if using the markdown flavour), which is what I have tried on this
>> branch: https://github.com/peterjc/biopython/tree/markup
>>
>> I didn't include all of Matt's changes since I wanted to balance the
>> rendered display and maximizing the plain text human readability.
>>
>> While this does add a 'strange' file to the root folder, I think this is
>> probably a reasonable compromise.
>>
>> What do you all think?
>
> The symlink seems like a reasonable compromise for now. If Github
> reads from symlinks, a slightly different approach may be to simply
> add a 'README.md' (or .rst) symlink pointing to the original README or
> README.txt file.

That is the workaround I tested on my branch.

> We can then exclude README.md in the manifest file,
> so anyone downloading the package doesn't have to bother with it.

Good plan for the manifest - that solves the 'distraction' issue nicely.
The only people who would see the file are those looking at GitHub
or using git directly.

> For the markup, I agree that .rst seems to be a better choice. To keep
> it readable by humans, we can keep all hyperlinks as footnotes (per
> http://docutils.sourceforge.net/docs/user/rst/quickref.html#hyperlink-targets),
> right?

I'd stick with standalone hyperlinks as currently used in the README
file.

Peter