Bug#865847: Use reStructuredText for Lintian manual
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 <lamby@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
Reply to: