Re: [PATCH v2] docs: Convert the Speakup guide to rst

[Igor Torrente <igormtorrente@gmail.com>]

Hi Jani Nikula,

On 6/1/21 8:28 AM, Jani Nikula wrote:
> On Mon, 31 May 2021, Igor Matheus Andrade Torrente <igormtorrente@gmail.com> wrote:
>> Modify some parts of the text and add the necessary formatting to leverage
>> the rst features. Including links, code-blocks, bullet lists, etc.
>>
>> Also, adds a table of contents at the beginning and a section to the
>> license.
>>
>> This change helps integrate this documentation to the rest of the rst
>> documentation.
>>
>> Signed-off-by: Igor Matheus Andrade Torrente <igormtorrente@gmail.com>
>> ---
>>
>> V2: Rebase the patch to cover the commit cae2181b498fe
>>
>> ---
>>   Documentation/admin-guide/index.rst           |    1 +
>>   .../{spkguide.txt => spkguide.rst}            | 1026 +++++++++--------
>>   2 files changed, 574 insertions(+), 453 deletions(-)
>>   rename Documentation/admin-guide/{spkguide.txt => spkguide.rst} (75%)
>>
>> diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
>> index 423116c4e787..c45121777ecf 100644
>> --- a/Documentation/admin-guide/index.rst
>> +++ b/Documentation/admin-guide/index.rst
>> @@ -112,6 +112,7 @@ configure specific aspects of kernel behavior to your liking.
>>      ras
>>      rtc
>>      serial-console
>> +   spkguide
>>      svga
>>      syscall-user-dispatch
>>      sysrq
>> diff --git a/Documentation/admin-guide/spkguide.txt b/Documentation/admin-guide/spkguide.rst
>> similarity index 75%
>> rename from Documentation/admin-guide/spkguide.txt
>> rename to Documentation/admin-guide/spkguide.rst
>> index 977ab3f5a0a8..e254af41a8e9 100644
>> --- a/Documentation/admin-guide/spkguide.txt
>> +++ b/Documentation/admin-guide/spkguide.rst
>> @@ -1,14 +1,20 @@
>> -
>> +========================
>>   The Speakup User's Guide
>> -For Speakup 3.1.2 and Later
>> -By Gene Collins
>> -Updated by others
>> -Last modified on Mon Sep 27 14:26:31 2010
>> -Document version 1.3
>> +========================
>> +
>> +| For Speakup 3.1.2 and Later
>> +| By Gene Collins
>> +| Updated by others
>> +| Last modified on Mon Jan 21 17:08:21 2021
>> +| Document version 1.3
>> +
>>   
>> -Copyright (c) 2005  Gene Collins
>> -Copyright (c) 2008  Samuel Thibault
>> -Copyright (c) 2009, 2010  the Speakup Team
>> +Copyright and License
>> +=====================
>> +
>> +| Copyright (c) 2005  Gene Collins
>> +| Copyright (c) 2008  Samuel Thibault
>> +| Copyright (c) 2009, 2010  the Speakup Team
> 
> Use a field list?
> 
> https://docutils.sourceforge.io/docs/user/rst/quickref.html#field-lists

That what I was looking for when converting this text, thanks!

> 
>>   
>>   Permission is granted to copy, distribute and/or modify this document
>>   under the terms of the GNU Free Documentation License, Version 1.2 or
>> @@ -17,7 +23,40 @@ Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
>>   copy of the license is included in the section entitled "GNU Free
>>   Documentation License".
>>   
>> +
>> +Contents
>> +========
>> +
>> +* `Preface`_.
>> +
>> +* `1.  Starting Speakup`_
>> +* `2.  Basic operation`_
>> +* `3.  Using the Speakup Help System`_
>> +* `4.  Keys and Their Assigned Commands`_
>> +* `5.  The Speakup Sys System`_
>> +* `6.  Changing Synthesizers`_
>> +* `7.  Loading modules`_
>> +* `8.  Using Software Synthesizers`_
>> +     - `8.1. Espeakup`_
>> +     - `8.2. Speech Dispatcher`_
>> +* `9.  Using The DecTalk PC Card`_
>> +* `10.  Using Cursor Tracking`_
>> +* `11.  Cut and Paste`_
>> +* `12.  Changing the Pronunciation of Characters`_
>> +* `13.  Mapping Keys`_
>> +* `14.  Internationalizing Speakup`_
>> +     - `14.1.  Files Under the i18n Subdirectory`_.
>> +     - `14.2.1.  Loading Your Own Messages`_.
>> +     - `14.2.2. Choose a language`_.
>> +     - `14.3.  No Support for Non-Western-European Languages`_.
>> +* `15.  Using Speakup's Windowing Capability`_
>> +* `16.  Tools for Controlling Speakup`_
>> +     - `16.1.  Speakupconf`_.
>> +     - `16.2.  Talkwith`_
> 
> There's a directive for this:
> 
> .. contents::
> 
> The document didn't use to have a manually updated contents, why add one
> now that you can have it automated?
> 
> https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents

Thanks, I will change it!

> 
>> +
>> +
>>   Preface
>> +=======
>>   
>>   The purpose of this document is to familiarize users with the user
>>   interface to Speakup, a Linux Screen Reader.  If you need instructions
>> @@ -37,7 +76,9 @@ with speech access unaided by a sighted person.  Again, these details
>>   are beyond the scope of this manual, but the user should be aware of
>>   them.  See the web site mentioned above for further details.
>>   
>> +
> 
> Unnecessary extra blank line, but okay.

For me these blank lines makes the rst more readable in the text editor 
like vim.

> 
>>   1.  Starting Speakup
> 
> I'd drop the numbers and let Sphinx take care of this.
> 
>> +====================
>>   
>>   If your system administrator has installed Speakup to work with your
>>   specific synthesizer by default, then all you need to do to use Speakup
>> @@ -58,41 +99,43 @@ build and install your own kernel.
>>   If your kernel has been compiled with Speakup, and has no default
>>   synthesizer set, or you would like to use a different synthesizer than
>>   the default one, then you may issue the following command at the boot
>> -prompt of your boot loader.
>> +prompt of your boot loader.::
>>   
>> -linux speakup.synth=ltlk
>> +  linux speakup.synth=ltlk
>>   
>>   This command would tell Speakup to look for and use a LiteTalk or
>>   DoubleTalk LT at boot up.  You may replace the ltlk synthesizer keyword
>>   with the keyword for whatever synthesizer you wish to use.  The
>> -speakup.synth parameter will accept the following keywords, provided
>> +``speakup.synth`` parameter will accept the following keywords, provided
>>   that support for the related synthesizers has been built into the
>>   kernel.
>>   
>> -acntsa -- Accent SA
>> -acntpc -- Accent PC
>> -apollo -- Apollo
>> -audptr -- Audapter
>> -bns -- Braille 'n Speak
>> -dectlk -- DecTalk Express (old and new, db9 serial only)
>> -decext -- DecTalk (old) External
>> -dtlk -- DoubleTalk PC
>> -keypc -- Keynote Gold PC
>> -ltlk -- DoubleTalk LT, LiteTalk, or external Tripletalk (db9 serial only)
>> -spkout -- Speak Out
>> -txprt -- Transport
>> -dummy -- Plain text terminal
>> -
>> -Note: Speakup does * NOT * support usb connections!  Speakup also does *
>> -NOT * support the internal Tripletalk!
>> +| acntsa -- Accent SA
>> +| acntpc -- Accent PC
>> +| apollo -- Apollo
>> +| audptr -- Audapter
>> +| bns -- Braille 'n Speak
>> +| dectlk -- DecTalk Express (old and new, db9 serial only)
>> +| decext -- DecTalk (old) External
>> +| dtlk -- DoubleTalk PC
>> +| keypc -- Keynote Gold PC
>> +| ltlk -- DoubleTalk LT, LiteTalk, or external Tripletalk (db9 serial only)
>> +| spkout -- Speak Out
>> +| txprt -- Transport
>> +| dummy -- Plain text terminal
> 
> Looks like a definition list?
> 
> https://docutils.sourceforge.io/docs/user/rst/quickref.html#definition-lists

If the '|' is replaced by definition-list, I'll have to skip a line to 
each item so the sphinx doesn't concatenate them into a single line. 
Like this:

keywords
   acntsa -- Accent SA

   acntpc -- Accent PC

   apollo -- Apollo
   [...]


There's a way to do that without these blank lines?

For me, it doesn't look very good, but I think the tradeoff worth it 
improves readability to speakup users. If it is the case.

> 
>> +
>> +.. note::
>> +
>> +   | Speakup does **NOT** support usb connections!
>> +   | Speakup also does **NOT** support the internal Tripletalk!
> 
> Why the pipes "|"?

This is the way I found to separate these sentences into two different 
lines. I'm gladly accepting a better solution for this :)

> 
>>   
>>   Speakup does support two other synthesizers, but because they work in
>>   conjunction with other software, they must be loaded as modules after
>>   their related software is loaded, and so are not available at boot up.
>>   These are as follows:
>>   
>> -decpc -- DecTalk PC (not available at boot up)
>> -soft -- One of several software synthesizers (not available at boot up)
>> +| decpc -- DecTalk PC (not available at boot up)
>> +| soft -- One of several software synthesizers (not available at boot up)
>>   
>>   See the sections on loading modules and software synthesizers later in
>>   this manual for further details.  It should be noted here that the
>> @@ -102,7 +145,9 @@ the boot process, such action must be configured by your system
>>   administrator.  This will mean that you will hear some, but not all,  of
>>   the bootup messages.
>>   
>> +
>>   2.  Basic operation
>> +===================
>>   
>>   Once you have booted the system, and if necessary, have supplied the
>>   proper bootup parameter for your synthesizer, Speakup will begin
>> @@ -115,10 +160,12 @@ screen using the kernel, and must get their keyboard input through the
>>   kernel, they are automatically handled properly by Speakup.  There are a
>>   few exceptions, but we'll come to those later.
>>   
>> -Note:  In this guide I will refer to the numeric keypad as the keypad.
>> -This is done because the speakupmap.map file referred to later in this
>> -manual uses the term keypad instead of numeric keypad.  Also I'm lazy
>> -and would rather only type one word.  So keypad it is.  Got it?  Good.
>> +.. note::
>> +
>> +  In this guide I will refer to the numeric keypad as the keypad.
>> +  This is done because the speakupmap.map file referred to later in this
>> +  manual uses the term keypad instead of numeric keypad.  Also I'm lazy
>> +  and would rather only type one word.  So keypad it is.  Got it?  Good.
>>   
>>   Most of the Speakup review keys are located on the keypad at the far
>>   right of the keyboard.  The numlock key should be off, in order for these
>> @@ -131,9 +178,9 @@ You probably won't want to listen to all the bootup messages every time
>>   you start your system, though it's a good idea to listen to them at
>>   least once, just so you'll know what kind of information is available to
>>   you during the boot process.  You can always review these messages after
>> -bootup with the command:
>> +bootup with the command::
>>   
>> -dmesg | more
>> +  dmesg | more
>>   
>>   In order to speed the boot process, and to silence the speaking of the
>>   bootup messages, just press the keypad enter key.  This key is located
>> @@ -164,19 +211,19 @@ the speech with keypad enter, or use any of the Speakup review keys.
>>   Here are some basic Speakup review keys, and a short description of what
>>   they do.
>>   
>> -keypad 1 -- read previous character
>> -keypad 2 -- read current character (pressing keypad 2 twice rapidly will speak
>> -	the current character phonetically)
>> -keypad 3 -- read next character
>> -keypad 4 -- read previous word
>> -keypad 5 -- read current word (press twice rapidly to spell the current word)
>> -keypad 6 -- read next word
>> -keypad 7 -- read previous line
>> -keypad 8 -- read current line (press twice rapidly to hear how much the
>> -	text on the current line is indented)
>> -keypad 9 -- read next line
>> -keypad period -- speak current cursor position and announce current
>> -	virtual console
>> +| keypad 1 -- read previous character
>> +| keypad 2 -- read current character (pressing keypad 2 twice rapidly will speak
>> +	      the current character phonetically)
>> +| keypad 3 -- read next character
>> +| keypad 4 -- read previous word
>> +| keypad 5 -- read current word (press twice rapidly to spell the current word)
>> +| keypad 6 -- read next word
>> +| keypad 7 -- read previous line
>> +| keypad 8 -- read current line (press twice rapidly to hear how much the
>> +	      text on the current line is indented)
>> +| keypad 9 -- read next line
>> +| keypad period -- speak current cursor position and announce current
>> +		   virtual console
> 
> Definition list?
> 
> Ditto for all the similar cases.
> 
>>   
>>   It's also worth noting that the insert key on the keypad is mapped
>>   as the speakup key.  Instead of pressing and releasing this key, as you
>> @@ -190,16 +237,18 @@ Speakup will say, "You turned me off.", or "Hey, that's better."  When
>>   Speakup is turned off, no new text on the screen will be spoken.  You
>>   can still use the reading controls to review the screen however.
>>   
> 
> [snip]
> 
>> +
>> +Document License
>> +================
>> +
> 
> Using SPDX might be nice.

I was just trying to respect the original text as much as possible, but 
I don't mind change it if everybody agrees with it.

> 
>>                   GNU Free Documentation License
>>                     Version 1.2, November 2002
>>   
>>   
>> - Copyright (C) 2000,2001,2002  Free Software Foundation, Inc.
>> - Everyone is permitted to copy and distribute verbatim copies
>> - of this license document, but changing it is not allowed.
>> +Copyright (C) 2000,2001,2002  Free Software Foundation, Inc.
>> +Everyone is permitted to copy and distribute verbatim copies
>> +of this license document, but changing it is not allowed.
>>   
>>   
>>   0. PREAMBLE
>