[tex-live] Format of README file for a package
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 :
>> 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:
>> The CTAN web page
>> also shows the contents of README, but not from README.html
>> (security reasons?).
>> In the source repository at
>> 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
>> Yours sincerely
> Thanks Heiko, this is useful to me.
> Regarding the README.html not being automatically displayed on
> 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
> 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
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
More information about the tex-live