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

[Jani Nikula <jani.nikula@linux.intel.com>]

On Tue, 01 Jun 2021, Igor Torrente <igormtorrente@gmail.com> wrote:
> 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:
>>> -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.

I was thinking:

acntsa
  Accent SA

acntpc
  Accent PC

apollo
  Apollo

[...]

Simply by looking at what the data appears to be, and trying to match
that with the semantically appropriate rst construct. Maybe you think
that's too verbose or takes too much vertical space or isn't grep
friendly - and it's fine. I'm just making suggestions.

Another, more condensed alternative is to use tables, but that can
become annoying to maintain if you don't get the column widths right
from the start.

https://docutils.sourceforge.io/docs/user/rst/quickref.html#tables

>>> +
>>> +.. 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 :)

Maybe just like this?

.. note::

   Speakup does **NOT** support usb connections!

   Speakup also does **NOT** support the internal Tripletalk!


Again, I'm not insisting on any of these changes, I'm just suggesting
things you might find helpful!


BR,
Jani.

-- 
Jani Nikula, Intel Open Source Graphics Center