Hi Jani Nikula, On 6/1/21 8:28 AM, Jani Nikula wrote:
On Mon, 31 May 2021, Igor Matheus Andrade Torrente <igormtorrente@xxxxxxxxx> 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@xxxxxxxxx> --- 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 TeamUse 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 documentunder 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 userinterface 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 SpeakupI'd drop the numbers and let Sphinx take care of this.+====================If your system administrator has installed Speakup to work with yourspecific 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=ltlkThis command would tell Speakup to look for and use a LiteTalk orDoubleTalk 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 terminalLooks 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 inconjunction 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 inthis 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 theproper 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 farright 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 | moreIn order to speed the boot process, and to silence the speaking of thebootup 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 consoleDefinition list? Ditto for all the similar cases.It's also worth noting that the insert key on the keypad is mappedas 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
