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

[jfbu]

Le 3 oct. 2014 à 02:20, Heiko Oberdiek <heiko.oberdiek at googlemail.com> a écrit :

> 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

Thanks Heiko, this is useful to me. 

Regarding the README.html not being automatically displayed on 
> http://www.ctan.org/tex-archive/macros/latex/contrib/latex-tds
there is a link README.html near the top of the file list, thus
in my view, this is ok the way it is. 

I mailed ctan at dante.de, and Petra from the CTAN team
told me there was no  automated process,  during the submission 
I should make a Note to the CTAN maintainers to signal the files 
which are candidate to be listed on the 
/tex-archive/macros/latex/contrib/package
page.

The other thing she told me is that README must be named that way,
with no extension, for its contents to be displayed automatically.

What I forgot to mention in my first message here is that README.md
is among the files extracted from the .dtx. Then during pdf creation
I am currently including it verbatim as a section of the documentation.

I could not do that with README (afaik)
as TeX's \input adds .tex extension to filenames without extension.

Thus README.md is the natural thing for me to work with, but it is no 
big deal to rename it to README before packaging my submission. And 
anyhow it is mandatory for CTAN displaying it.

Your message makes me think that rather than including the README.md 
verbatim, as a section in the package PDF documentation, I could as well 
choose to provide a separate README.pdf.

Indeed I already had experimented with producing README.pdf using Pandoc 
from README.md and it's fine.

Best regards

Jean-Francois