On Fri, 3 Jan 2014, Remy 'Sieben' Leone wrote:
I want to probe the interest about moving the text files in the source code to markdown.
My short response would be: yes, I'm interested. Longer answers follow.
- Text documents in the curl source tree are not well formatted on phone/tablet
They're also not really meant to be read on such limited devices. We do provide webified versions of all relevant documentation on curl.haxx.se for those who prefer HTML to plain text. They should be fine for all sorts of portable devices.
I think of the docs in the source tree as there for those who get/download/read the code and I would expect that most people who do that don't do it on tablets. That's why I also insist on not switching to all-HTML situation, since I want the documentation to be readable for us who spend more time in a text editor with code (and prefer reading docs that way) than browsing web sites.
I'm not saying my view is the right or only view, I'm just explaining my general take on this. After all, I believe I am the author of most of the docs and most of the webifications of them.
- Add a .md name file extention - Do a little reformating to allow a satisfying rendering on github. Don't change much the files just a bunch of markup to have something prettier in github
Are you suggesting that most tablets/phones have markdown-capable readers? If not, isn't markdown "only" helping us in making the webification of the documentation easier and better?
I don't think we *have to* make it easier for people to read the documentation on github if we have it presented fine on our own site already.
- Is there any building documentation that use path in the source tree that would broke if the file are renamed?
Yes, a large portion of the curl web site. Parts of that portion would also break if you significantly change the layout of some of these files.
Any change like this needs to be made simultaneously in the source code tree and in the web site tree. We'd do it file by file I guess.
Do you think this could be acceped or you don't think it's interesting?
I think there are a few questions to answer: - what are the current worst offenders according to you (you in the big sense as in anyone who reads this)? I mean, where is the biggest gains to be had by a conversion. - then, as a follow-up based on the answer to the previous one, is to asess how much work it is to convert our existing infrastructure solution to a markdown-based one, and if it is worth the effort. - finally, a crucial factor for me is who's going to do the heavy lifting -- / daniel.haxx.se ------------------------------------------------------------------- List admin: http://cool.haxx.se/list/listinfo/curl-library Etiquette: http://curl.haxx.se/mail/etiquette.html
