<html> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <style type="text/css" style="display:none;"></style> </head> <body dir="ltr"> <div id="divtagdefaultwrapper" style="font-size:12pt;color:#000000;font-family:Calibri,Arial,Helvetica,sans-serif;" dir="ltr"> Hello guys, I want to propose a port of the current HTML documentation to a markdown-like syntax. Current problems Right now I see some problems with the approach used. <ul> <li>People maintaining the documentation must know basic HTML syntax;</li><li>There is no easy way to add a new release page; <ul> <li>You need to open the index file and make changes there; </li><li>You need to make a new file that will say what has been changed;</li><li>You need to remember to update the release notes pages;</li></ul> </li><li>The current website has many HTML tags not being closed;</li><li>The website don't fit well in mobile area. (The layout is not responsive);</li><li>Making any change to the layout is very hard, because you need to rewrite many pages;</li><li>The current website doesn't show all the possibilities of the library. The website has a 1990 layout, and I think having a new layout would benefit the project; </li></ul> Proposal for Markdown Rewriting the documentation in a markdown syntax can bring some benefits to the development, like: <ul> <li>Anyone writing for freedesktop.org, StackOverflow and Github already knows the markdown syntax.</li><li>Independence of HTML. The developer don't need to worry if the HTML output will be correct. The generator makes all the translation from markdown to HTML;</li><li>Easily change the layout of the site, simply changing the theme; (I don't think you change the layout much, but allowing it to be easy wont hurt)</li><li>Creating a new release post can be maded easy, using some static site generator, for example, pelican; </li></ul> Right now I have maded a partial port from HTML to Markdown. The code can be found here: <a href="https://github.com/jlHertel/mesa-pelican" class="OWAAutoLink" id="LPlnk197398" previewremoved="true"> https://github.com/jlHertel/mesa-pelican</a> I'm using the pelican static site generator with a layout ported from Wordpress using Twitter Bootstrap CSS. A live preview can be found here: <a href="http://mesa.jeanhertel.com.br/" class="OWAAutoLink" id="LPlnk73940" previewremoved="true"> http://mesa.jeanhertel.com.br/</a> The static site generator tool and the theme used can be ignored if you want, the point here is to rewrite the documentation in a way that is easy to maintain and that don't need a good knowledge in HTML. Please leave your comments on the proposal. Best Regards Jean Hertel ------------------ Some terms used are web-focused, so I will leave some links if anyone don't know what I mean: Twitter Bootstrap Css: <a href="http://getbootstrap.com/" class="OWAAutoLink" id="LPlnk863139" previewremoved="true"> http://getbootstrap.com/</a> Responsive layout: <a href="https://en.wikipedia.org/wiki/Responsive_web_design" class="OWAAutoLink" id="LPlnk206622" previewremoved="true"> https://en.wikipedia.org/wiki/Responsive_web_design</a> Pelican static site generator: <a href="https://blog.getpelican.com/" class="OWAAutoLink" id="LPlnk432434" previewremoved="true"> https://blog.getpelican.com/</a> Markdown: <a href="https://en.wikipedia.org/wiki/Markdown" class="OWAAutoLink" id="LPlnk170906" previewremoved="true"> https://en.wikipedia.org/wiki/Markdown</a> </div> </body> </html>