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

[jfbu]

Le 2 oct. 2014 à 20:52, jfbu <jfbu at free.fr> a écrit :

> 
> 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

and let me add that your README.html is (1) very inspiring and (2) many 
orders  of magnitude more ample than the README I currently have in mind 
for my project (this is also why I did not even think about producing 
a pure ASCII version with no mark-up, because the mark-up is quite light
and could possibly become obtrusive only for a much longer file with
additional inner references or other stuff)

thanks again for the explanations in your message

Jean-Francois