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

[Manfred Lotz]

Hi Jean-Francois,

On Thu, 2 Oct 2014 20:52:32 +0200
jfbu <jfbu at free.fr> wrote:

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

I found Heiko's advice very good. You could choose a similar procedure.
>From README.md you could create a plain README text file by using for
instance pandoc which is part of most Linux distributions. 

Then you have a README which make us (the CTAN team) happy, and (as I
said the other day to somebody else) a happy CTAN team isn't such bad.



-- 
Manfred