linux-kernel - Re: docs: Convert the Speakup guide to rst

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:   Mon, 31 May 2021 19:11:56 -0700
From:   Chris Brannon <chris@...-brannons.com>
To:     Didier Spaier <didier@...nt.fr>
Cc:     Samuel Thibault <samuel.thibault@...-lyon.org>,
        Igor Matheus Andrade Torrente <igormtorrente@...il.com>,
        speakup@...ux-speakup.org, corbet@....net,
        gregkh@...uxfoundation.org, grandmaster@...klimov.de,
        rdunlap@...radead.org, linux-doc@...r.kernel.org,
        linux-kernel@...r.kernel.org
Subject: Re: docs: Convert the Speakup guide to rst

Didier Spaier <didier@...nt.fr> writes:

>> Mmm, I'm unsure how the result is readable with the speakup screen
>> reader itself. I have attached the result, could people on the speakup
>> mailing list check how well it goes? If it significantly degrades
>> readability, we'll have to reject the move to rst formatting, since in
>> the end it's people who use the speakup screen reader who need to be
>> able to read this document.
>> Samuel
>
> Can we not have two versions? I don't have Sphinx installed (used to format
> https://www.kernel.org/doc/html/latest/index.html) but converted
> speakup.rst to
> html5 using rst2html5.py and indeed the output is way better looking
> and easier
> to navigate than the txt version.

RST is ok with Speakup et al, both in source form and when converted to HTML
and rendered in a console browser.

> Is it still true? PS I widely prefer the asciidoc/asciidoctor format
> than rst,
> but the choice has been done for the Linux Kernel documentation, I know...

I knew you were a man of impeccably good taste, Didier, and this
confirms it.  From a technical standpoint, asciidoc is meant as a
readable plain-text representation of docbook, so it is easily
convertable to the formats supported by docbook.  But the kernel has
settled on RST.  Speakup docs should use whatever the rest of the kernel
docs are using, and I see no compelling reason why they cannot.

-- 
Chris Brannon
Founder: Blind and Low Vision Unix Users Group (https://blvuug.org/).
Personal website: (https://the-brannons.com/)
Chat: IRC: teiresias on libera.chat and OFTC, XMPP: chris@...t.number89.net