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

jfbu jfbu at free.fr
Thu Oct 2 21:06:41 CEST 2014

```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)
>>>
>> 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
>> the "source file" README.asciidoc to the sources. The generated
>> files are:
>> * README (real ASCII, without markup)
>>
>> If texdoc is called to find the documentation for latex-tds, it
>> finds them in the following order:
>>
>> These three files are also in CTAN:
>>
>> The CTAN web page
>> http://www.ctan.org/tex-archive/macros/latex/contrib/latex-tds
>> (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.
>
> from README.md and it's fine.
>
> Best regards
>
> Jean-Francois