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

[jfbu]

Hello Manfred

Le 3 oct. 2014 à 19:40, Manfred Lotz <manfred at dante.de> a écrit :

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

Believe it or not I have asked sysadmin to install pandoc at work, but 
I am still waiting. Perhaps I can also add we are still with TL2010, and
that asking sysadmin has not led anywhere so far. Not so long ago, we
were with TL2007 and I still recall how modern TL2010 appeared.

This said, I do my TeX things on my home laptop, and I have been playing
with Pandoc these last few days.

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

Making people happy is also my goal despite sysadmin ;-)

I tried pandoc -t plain but I am really tempted by mv README.md README,

there isn't much difference between README.md and its version with 
the Markdown light decoration taking away, and in fact, even without
any syntax highlighting I find the .md variant more readable (now...)

kind regards,

Jean-François

> 
> -- 
> Manfred
> 
>