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

[Manfred Lotz]

Hi Jean-François,
Of course, you could consider to just copy README.md -> REAMDE.

Otherwise: pandoc -f markdown -t plain -o README README.md

You might have seen that pandoc supports different flavors of markdown.
Check which one is suitable for you.

You could even try this, going md --> html --> plain

pandoc -f markdown -t html -o README.html README.md
lynx -nolist -display-charset UTF-8 -dump README.html > README

Adjust encoding (-display-charset) to your needs and check if this looks
better or worse than the short pandoc way.

-- 
Manfred
 

On Fri, 3 Oct 2014 22:47:01 +0200
jfbu <jfbu at free.fr> wrote:


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