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