On 6/11/19 3:29 AM, Markus Armbruster wrote:
> Peter Maydell <peter.mayd...@linaro.org> writes:
>
>> On Tue, 21 May 2019 at 19:56, Peter Maydell <peter.mayd...@linaro.org> wrote:
>>>
>>> Currently we have a vague plan that we should migrate our
>>> documentation away from Texinfo to using Sphinx, plus some isolated
>>> bits of documentation already in .rst format. This email is an attempt
>>> to sketch out a transition plan for getting us from where we are today
>>> to where (I think) we want to be.
>>
>> Since nobody seemed to disagree particularly with this sketch,
>
> I don't think rST is an improvement over Texinfo. As Paolo said, it's
> the Perl of ASCII-based markups. But I (reluctantly) agree with Paolo
> that our current mix of Texinfo, rST, Markdown, and ad hoc markup is
> worse than consistent use of one markup system, even if it's an
> ill-conceived one like rST.
>
> March of progress, I guess.
>
> [...]
>
I will say that at a minimum I enjoy the combination of sphinx and rST
because at least we can error out on warnings and check that the cross
references are valid.
Markdown is a hot mess of a non-spec that is subtly different for just
about every implementation, and we procedurally check none of ours.
At least rST is one thing, I guess. And that it's extensible via sphinx
is nice.
--js
