Received: by 2002:a05:6a10:206:0:0:0:0 with SMTP id 6csp3064348pxj; Mon, 31 May 2021 19:22:22 -0700 (PDT) X-Google-Smtp-Source: ABdhPJyNQLDM8wNferLj8mJdrQyWsLLnJ0s8L09jEjb7I+8ev65hgACqW6u/zA2GbUwp6ASSBQ6w X-Received: by 2002:a17:906:46d1:: with SMTP id k17mr25636867ejs.77.1622514141821; Mon, 31 May 2021 19:22:21 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1622514141; cv=none; d=google.com; s=arc-20160816; b=K0TuYunxC2t+DO2XdsFUTitYu9/E8WWaY8wz009AjM6fcdUT70drzPWG1XSrTtSnqt Z73/KpfCyna5vTayCy2G6xsEzgZZExsNtZzmM6YBOR7+UkdoqQOUU3OEC4kVLBf/mYEo QkYAw8dAy37t1k/dGjbXnQ5JlF1tzRLncWevC/QXc34WQ/LWeu7LDCI888MjBAINgGNl m9oLAl/f42OzEsqFe/E5IBdlkbkDGh5qmFw0edynONN0VBhzjbq4JFQBY2iMUM7VZRCD KBsptTkPcZD0oEX2bKTDsXtqO5IyWccTbYZIetY3SHS6l2mc0s1tDSAhQ5jeEadj+EbI o9Gg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:mime-version:user-agent:message-id:in-reply-to :date:references:subject:cc:to:from; bh=1ZuPSjXxK/KzfZTovaR+X0LxyKJjZmy9Sr5qwWn6PQE=; b=INiKWF36+5lf1UAVCwh7PjXBIfIv1pGYkFEqK30O3NB1utemJSzW9Ix531pSxk8LZu u0H//b+UF8aNVT8sM1FTuLLBEWDDHeilVwNPK7k3VBcpZIPQOzqwyNTfsz9nuapfb5Xv gL47SaBXeCO5Hy9B1qG2ek6y9Ma4Qq7kAN2l8uAKP4gypVvQUm+9/p936vCoACxD/CH+ 22sceDIeukcBP9Wzr2/oBgE+dRgi5ZObzJDJn0EqIanOhubfr9JkrNgWlN8sTv/KplK8 0iEJQ/yhgnF7GbqKLv/fimuBhHAG9SvKLwtl2YL4zW6hwdqgXXRe66RC6qjUFAQKYpZG E3Yw== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=the-brannons.com Return-Path: Received: from vger.kernel.org (vger.kernel.org. [23.128.96.18]) by mx.google.com with ESMTP id lf9si7814434ejc.276.2021.05.31.19.21.59; Mon, 31 May 2021 19:22:21 -0700 (PDT) Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18; Authentication-Results: mx.google.com; spf=pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=the-brannons.com Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232524AbhFACUT (ORCPT + 99 others); Mon, 31 May 2021 22:20:19 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:58612 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S232268AbhFACUS (ORCPT ); Mon, 31 May 2021 22:20:18 -0400 X-Greylist: delayed 397 seconds by postgrey-1.37 at lindbergh.monkeyblade.net; Mon, 31 May 2021 19:18:38 PDT Received: from hurricane.the-brannons.com (hurricane.the-brannons.com [IPv6:2602:ff06:725:1:20::25]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 0BCC7C061574; Mon, 31 May 2021 19:18:37 -0700 (PDT) Received: from localhost ( [2602:3f:e0f9:dc00::2]) by hurricane.the-brannons.com (OpenSMTPD) with ESMTPSA id 9d9c450c (TLSv1.3:TLS_AES_256_GCM_SHA384:256:NO); Mon, 31 May 2021 19:11:57 -0700 (PDT) From: Chris Brannon To: Didier Spaier Cc: Samuel Thibault , Igor Matheus Andrade Torrente , speakup@linux-speakup.org, corbet@lwn.net, gregkh@linuxfoundation.org, grandmaster@al2klimov.de, rdunlap@infradead.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: Re: docs: Convert the Speakup guide to rst References: <20210531215737.8431-1-igormtorrente@gmail.com> <20210531220754.h4ep2dj65wl6hejf@begin> <393c2df8-9cb1-f428-5629-6e98c078c24f@slint.fr> Date: Mon, 31 May 2021 19:11:56 -0700 In-Reply-To: <393c2df8-9cb1-f428-5629-6e98c078c24f@slint.fr> (Didier Spaier's message of "Tue, 1 Jun 2021 00:42:22 +0200") Message-ID: <875yyygwpf.fsf@the-brannons.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.2 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Didier Spaier 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@chat.number89.net