[tex-live] Format of README file for a package

[Heiko Oberdiek]

Hello,

On 10/02/2014 07:37 AM, jfbu wrote:
> in preparation for an update on CTAN to a package of mine, I have used
> Markdown syntax in the README file
>
> from the point of view of the TeXLive distribution and texdoc,
> is it possible to name the file README.md rather than README,
> or is there some implicit rule that the README should have
> precisely that filename?
>
> Can I join also README.html which would be the already converted-to
> -html variant? (I will ask that also to CTAN)
>
> and should README.html be rather packagenameReadme.html for example?
I am not a TeX Live or CTAN manager, but I can report, how I
have solved the issue for project latex-tds. As markup language
I had chosen asciidoc instead of Markdown and have put
the "source file" README.asciidoc to the sources. The generated
files are:
* README (real ASCII, without markup)
* README.html
* README.pdf

If texdoc is called to find the documentation for latex-tds, it
finds them in the following order:
1 TDS:doc/latex/latex-tds/README
2 TDS:doc/latex/latex-tds/README.pdf
3 TDS:doc/latex/latex-tds/README.html

These three files are also in CTAN:
  CTAN:macros/contrib/latex/latex-tds/README{,.pdf,html}

The CTAN web page
  http://www.ctan.org/tex-archive/macros/latex/contrib/latex-tds
also shows the contents of README, but not from README.html
(security reasons?).

In the source repository at
  https://github.com/oberdiek/latex-tds
I have put README.asciidoc top-level, because github is able
to handle and display this format. (And the other files
are generated files anyway and do not belong to a source
repository.)

Yours sincerely
  Heiko