Bug#865847: Use reStructuredText for Lintian manual

2019-08-14 Thread Felix Lechner
Hi Chris,

On Mon, Aug 12, 2019 at 2:09 PM Chris Lamb  wrote:
>
> I would concede that RST might be more suitable for more complex
> requirements indeed.

Ok, I am going to merge this soon. At least it's a step in the right
direction. Let's see if we all can get comfortable with the RST
format.

I am currently writing a brief testing manual. (After that, I hope to
freeze the list of untested tags.) That will be a good experiment from
all sides with respect to the format.

Thank you to Russ for the comment about the policy document. I would
have preferred more consensus; perhaps it is safe to say that we are
all -1 on docbook.

Kind regards,
Felix



Bug#865847: Use reStructuredText for Lintian manual

2019-08-12 Thread Chris Lamb
Hi Felix,

> 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?

I would concede that RST might be more suitable for more complex
requirements indeed.

However, if you are to invest further time in $format it doesn't make
sense to convert to $another right at the end. Thus, if you really are
a +1 on RST then sense to start and finish with that.


Regards,

-- 
  ,''`.
 : :'  : Chris Lamb
 `. `'`  la...@debian.org  chris-lamb.co.uk
   `-



Bug#865847: Use reStructuredText for Lintian manual

2019-08-10 Thread Russ Allbery
Felix Lechner  writes:

> 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]

For what it's worth, we looked at Markdown for Debian Policy and went with
RST instead because Markdown just doesn't have enough features for large
documents.  Lintian's documentation may not be large enough for it to
matter, but Markdown, while more featureful than POD, isn't that much more
featureful and has some definite gaps.  (Even assuming that one uses a
variant of Markdown with table and definition list support, which can be a
bit hard to find.)

-- 
Russ Allbery (r...@debian.org)   



Bug#865847: Use reStructuredText for Lintian manual

2019-08-10 Thread Felix Lechner
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  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



Bug#865847: Use reStructuredText for Lintian manual

2019-08-10 Thread Chris Lamb
Hi Felix,

> Lintian's manual was converted to reStructuredText format. This MR uses 
> rst2html to generate the HTML version.

First, thanks for working on this. Really appreciated.

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.

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? I think
you have done most of the work, at the very least; the formats are
very similar.


Regards,

-- 
  ,''`.
 : :'  : Chris Lamb
 `. `'`  la...@debian.org  chris-lamb.co.uk
   `-



Bug#865847: Use reStructuredText for Lintian manual

2019-08-10 Thread Felix Lechner
 Control: tag -1 + patch

Lintian's manual was converted to reStructuredText format. This MR uses
rst2html to generate the HTML version.

https://salsa.debian.org/lintian/lintian/merge_requests/245

This RST file was generated from the existing manual in Docbook format
using:

pandoc -f docbook -t rst doc/lintian.xml > doc/lintian.rst

The resulting file showed the following three errors when used to generate
HTML with rst2html from python3-docutils:

lintian.rst:366: (ERROR/3) Unexpected indentation.
lintian.rst:363: (WARNING/2) Inline literal start-string without
end-string.
lintian.rst:367: (WARNING/2) Block quote ends without a blank line;
unexpected unindent.

The errors disappeared after a single, multi-space indent in line 366 was
removed manually using an editor.

RST does not have a facility to split documents into multiple output files
(although a 'toctree' directive could link multiple documents.) For now,
the HTML manual is one large, contiguous file.

Installs the single HTML file and the reStructuredText file in the user
package. Sets a link to the RST version with the ending *.txt in hope of
avoiding breakage.

Updates doc-base entries to point to the single HTML file and to the RST
file in lieu of plain text documentation.