Hi Chris, tldr; I am comfortable with any format you like, but please consider that I have to re-write much of the documentation. Could we convert to Markdown when I am done?
On Sat, Aug 10, 2019 at 10:17 AM Chris Lamb <la...@debian.org> wrote: > > So, whilst this might sound like the usual tedious "my format is > better than your format" argument, the consensus and trend over the > most recent couple of years has been free software projects either > starting or migrating text to using Markdown over every other format > else bar none. > > For example, GitLab (including Salsa) and GitHub (ie. > the "rest" of the internet, sigh...) are certainly are using this > format. Hey, I am not alone! The person who made Github and Gitlab possible, and therefore enabled Markdown's meteoric rise, actually likes reStructuredText better. The Linux kernel switched from Docbook to reStructuredText in 2016. Is that not a reasonable step for Lintian to emulate? I also asked on #debian-mentors, where RST came up. As you already wrote, RST and Markdown are not that different, certainly when compared to Docbook. RST, however, is a lot better suited for technical documentation, especially APIs. [1] Is popularity always a good measure? Nearly 90% of desktop computers run MS Windows. [2] :) > Thus, would it be a lot of work to quickly move to that from here > whilst we are making the time and effort to make the change? In general, it should be super easy. RST has a lot more features, which sometimes causes problems when converting [3] but the Lintian manual is relatively short, and only one document, so it can't be a huge problem. Please allow me point out, however, that I plan substantial changes for Lintian (of course, with your approval) in addition to the ones we have already made. I therefore expect to spend a lot of time creating new documentation. Could we perhaps convert it to Markdown when I am done with it? Kind regards, Felix [1] http://www.zverovich.net/2016/06/16/rst-vs-markdown.html [2] https://en.wikipedia.org/wiki/Usage_share_of_operating_systems#Desktop_and_laptop_computers [3] https://stackoverflow.com/questions/45633709/how-to-convert-rst-files-to-md