Messages in this thread Patch in this message | | | Subject | Re: [PATCH v2] docs: Convert the Speakup guide to rst | From | Igor Torrente <> | Date | Tue, 1 Jun 2021 12:11:26 -0300 |
| |
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 >
| |