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

[jfbu]

Le 4 oct. 2014 à 05:49, Manfred Lotz <manfred at dante.de> a écrit :

> 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


Hi Manfred, and thanks for the tip. 

I tried the lynx way, I was curious to see how the table of
content, added during html creation via the pandoc --toc option
and whose positioning in the html file I had been twiddling with
using a CSS element, would end up being treated by lynx: it just
appears in an unsurprising position near the top of file (I was a
bit disappointed, hoping that it would be more like how it is
displayed in the html browser), with an automated enumeration of
its successive items. There are other differences from the pandoc
-t plain way, the list items are not separated by blank lines,
left and right margins appear to (perhaps) be mimicking the
margin-left and margin-right of my body element in the html 

..., all in all, I think I will opt for the pandoc -t plain way. 

and now that I have done this bit of experimenting, I admit that
removing the Markdown marks does make for smoother reading of
pure text. Especially so for the Change Log which has plenty of
`\macro`'s: with all those `'s gone, the reading is easier.

Best regards
Jean-François