lkml.org 
[lkml]   [2021]   [Jun]   [1]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
Patch in this message
/
SubjectRe: [PATCH v2] docs: Convert the Speakup guide to rst
From
Date
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
>

\
 
 \ /
  Last update: 2021-06-01 17:12    [W:1.502 / U:0.012 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site