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

[Wibowo Arindrarto]

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. We can then exclude README.md in the manifest file,
so anyone downloading the package doesn't have to bother with it.

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?

Bow