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. * People maintaining the documentation must know basic HTML syntax; * There is no easy way to add a new release page; * You need to open the index file and make changes there; * You need to make a new file that will say what has been changed; * You need to remember to update the release notes pages; * The current website has many HTML tags not being closed; * The website don't fit well in mobile area. (The layout is not responsive); * Making any change to the layout is very hard, because you need to rewrite many pages; * 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; Proposal for Markdown Rewriting the documentation in a markdown syntax can bring some benefits to the development, like: * Anyone writing for freedesktop.org, StackOverflow and Github already knows the markdown syntax. * 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; * 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) * Creating a new release post can be maded easy, using some static site generator, for example, pelican; Right now I have maded a partial port from HTML to Markdown. The code can be found here: https://github.com/jlHertel/mesa-pelican 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: http://mesa.jeanhertel.com.br/ 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: http://getbootstrap.com/ Responsive layout: https://en.wikipedia.org/wiki/Responsive_web_design Pelican static site generator: https://blog.getpelican.com/ Markdown: https://en.wikipedia.org/wiki/Markdown
_______________________________________________ mesa-dev mailing list mesa-dev@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/mesa-dev