docutils-users — General discussions, questions, help requests.

Re: [Docutils-users] Literal code blocks ...

[Wol <ant...@yo...>]

On 22/02/2022 11:17, Guenter Milde via Docutils-users wrote:
> On 2022-02-21, Wol wrote:
>> Now this gets really weird ...
> 
> It seems the reason is that you
> 
> * don't tell us what you use (apparently Sphinx, not Docutils),
> 
> * ask at a Docutils users list,

Sorry. I looked on the Sphinx web site for the support mailing list, and 
this was it ... if it's not where you go for Sphinx support, then 
somebody needs to tell the Sphinx webmaster!
> 
> * want to achieve something where Sphinx works differently from vanilla
>    Docutils (overriding the "class" directive, overriding the interpretation
>    of "literal blocks").
>    
> Depending on your task and wider circumstances, you may consider, e.g.
> 
> * using a simple text format with fixed width fonts and forget about
>    any kind of markup.
> 
> * use Docutils instead of Sphinx, read some basic documentation and ask for
>    specific problems here,
>    
> * use Sphinx, read some basic documentation (https://sphinx-doc.org/)
>    and ask for specific problem there.

Except that "there" is apparently here ...
>    
> Trying to vent your undestandable frustation somewhere else might improve
> the responses from people that develop the tools in their spare time.
> 
Sorry ...

Cheers,
Wol

Re: [Docutils-users] Literal code blocks ...

[Wol <ant...@yo...>]

On 22/02/2022 01:03, Adam Turner wrote:
> It would be very helpful for you to share a link to a repo that contains 
> a minimal reproducer - I've had to guess a few things about your setup here.
> 
>  > But, forgetting all the grief so far, how would YOU recommend me to
> achieve what I'm actually aiming for, which is plain text laid out in
> columns?
> 
> If you're using Sphinx, the |.. class::|​ directive is renamed to |.. 
> rst-class::|​. Does |.. rst-class:: borderless|​ work?
> 
Running Sphinx v4.3.2
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] SMA/SMA301
/home/anthony/gitstuff/ScarletDME/docs/source/SMA/SMA301.rst:81: 
WARNING: Invalid class attribute value for "rst-class" directive: 
"borderless
=========== =========================================================
Item-Id -   A character string (maximum 48 characters) which

As you can see, it doesn't like it ...

This is what the source file looks like ...


.. rst-class:: borderless
    =========== =========================================================
    Item-Id -   A character string (maximum 48 characters) which
                uniquely identifies an item within a file. The item-id


And the output is that the table just disappears ...


> 
>> I DON'T want it to LOOK like it's been laid out as a table...
> 
> By this do you just mean you don't want borders to be shown?
> 
Yup.

(Actually, I'd like to learn how all this works :-) But I need to get 
something that works, and then and can try and understand WHY it works :-)

Cheers,
Wol

Re: [Docutils-users] Literal code blocks ...

[Guenter M. <mi...@us...>]

On 2022-02-21, Wol wrote:
> Now this gets really weird ...

It seems the reason is that you 

* don't tell us what you use (apparently Sphinx, not Docutils),

* ask at a Docutils users list,

* want to achieve something where Sphinx works differently from vanilla
  Docutils (overriding the "class" directive, overriding the interpretation
  of "literal blocks").
  
Depending on your task and wider circumstances, you may consider, e.g.

* using a simple text format with fixed width fonts and forget about
  any kind of markup.

* use Docutils instead of Sphinx, read some basic documentation and ask for
  specific problems here,
  
* use Sphinx, read some basic documentation (https://sphinx-doc.org/)
  and ask for specific problem there.
  
Trying to vent your undestandable frustation somewhere else might improve
the responses from people that develop the tools in their spare time.

Günter

Re: [Docutils-users] Literal code blocks ...

[Adam T. <aat...@ou...>]

It would be very helpful for you to share a link to a repo that contains a minimal reproducer - I've had to guess a few things about your setup here.

> But, forgetting all the grief so far, how would YOU recommend me to
achieve what I'm actually aiming for, which is plain text laid out in
columns?

If you're using Sphinx, the .. class::​ directive is renamed to .. rst-class::​. Does .. rst-class:: borderless​ work?


> I DON'T want it to LOOK like it's been laid out as a table...

By this do you just mean you don't want borders to be shown?

A

Re: [Docutils-users] Literal code blocks ...

[Wol <ant...@yo...>]

Now this gets really weird ...

I've put in a second literal block and what does it do? Lays it out as 
plain text, EXACTLY AS I WOULD EXPECT! Apart from the background, which 
I don't really want.

But, forgetting all the grief so far, how would YOU recommend me to 
achieve what I'm actually aiming for, which is plain text laid out in 
columns? Thing is, a lot of what I'm doing is I'm starting with two 
columns, and then splitting up the second column in two, that sort of 
thing ...

(I want it to look modern, proportional fonts, etc etc, but while it is 
a table I DON'T want it to LOOK like it's been laid out as a table...)

Cheers,
Wol

On 21/02/2022 20:20, Wol wrote:
> Literal blocks
> 
> Literal code blocks (ref) are introduced by ending a paragraph with the 
> special marker ::. The literal block must be indented (and, like all 
> paragraphs, separated from the surrounding ones by blank lines):
> 
> This is a normal text paragraph. The next paragraph is a code sample::
> 
>     It is not processed in any way, except
>     that the indentation is removed.
> 
>     It can span multiple lines.
> 
> This is a normal text paragraph again.
> 
> The handling of the :: marker is smart:
> 
> -------------------------------------------------------------------------
> 
> That's basically copied straight out of the documentation. So why, when 
> I declare a code block, has it been formatted?
> 
> If it's not processed in any way, why have I got colour-highlighting, 
> and bold text? Dunno what else it'll do ...
> 
> Or is trying to use Sphinx to write documentation just an exercise in 
> frustration? Okay, it has printed it cleanly in a fixed-width font, but 
> it certainly doesn't appear to have done what the documentation says it 
> does!
> 
> Cheers,
> Wol
> 
> 
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
> 
> Please use "Reply All" to reply to the list.

[Docutils-users] Literal code blocks ...

[Wol <ant...@yo...>]

Literal blocks

Literal code blocks (ref) are introduced by ending a paragraph with the 
special marker ::. The literal block must be indented (and, like all 
paragraphs, separated from the surrounding ones by blank lines):

This is a normal text paragraph. The next paragraph is a code sample::

    It is not processed in any way, except
    that the indentation is removed.

    It can span multiple lines.

This is a normal text paragraph again.

The handling of the :: marker is smart:

-------------------------------------------------------------------------

That's basically copied straight out of the documentation. So why, when 
I declare a code block, has it been formatted?

If it's not processed in any way, why have I got colour-highlighting, 
and bold text? Dunno what else it'll do ...

Or is trying to use Sphinx to write documentation just an exercise in 
frustration? Okay, it has printed it cleanly in a fixed-width font, but 
it certainly doesn't appear to have done what the documentation says it 
does!

Cheers,
Wol

Re: [Docutils-users] simple table without formatting

[Wol <ant...@yo...>]

On 20/02/2022 17:34, Guenter Milde via Docutils-users wrote:
> On 2022-02-20, Wols Lists wrote:
> 
> ...
> 
>>>> This is oh so simple with tabs or fixed width fonts - why do so many
>>>> modern systems find it almost impossible!
> 
> ...
> 
>> What I'm *transcribing* is a document where they DID force columns with
>> spaces and tabs :-)
> 
> You can, of course just do it this way: write your document with fixed-width
> font.
> 
> If you want this as part of a reStructuredText document (i.e. documentation
> done with Sphinx or Docutils), you must use "literal blocks"::
> 
>     Here       the
>     spacing    is     preserved.
>     
> You may also include a file "as is" with
> 
> .. include::  my-tabbed-document.txt
>     :literal:
>     
> But I recommend using a simple table, a field-list or a description list,
> IMV this looks and "behaves" better in a browser or on paper.
> 
Well, I think I'm giving up on most of this, at least until I can put 
this up where someone can actually debug the mess.

The reason I want to get rid of the grid lines is they basically screw 
up the display. But ":class: borderless" just seems to be a total waste 
of time!  Sorry, I do appreciate all the help, but it's just not doing 
anything!

So what is the correct syntax for declaring a literal block? And here's 
hoping it actually does what it claims!

Sorry, but I'm really getting totally jaded at getting absolutely no-where!

Here's hoping I won't be hassling you with more problems trying to get 
literal to work!

Cheers,
Wol

Re: [Docutils-users] simple table without formatting

[Guenter M. <mi...@us...>]

On 2022-02-20, Wol wrote:
> On 20/02/2022 18:30, Guenter Milde via Docutils-users wrote:
>> On 2022-02-20, Wols Lists wrote:

>> ...

>>> Okay, done a bit of googling, ended up with this, and I've still got
>>> grid lines everywhere ...
>>> .. table::
>>>      :class: borderless
>>> =========== =========================================================
>>> Item-Id -   A character string (maximum 48 characters) which
>>>               uniquely identifies an item within a file. The item-id
>>>               may include any characters except system delimiters,
>>>               however the use of blanks, single quotes, quotes,
>>>               commas, and backslash characters may require special
>>>               considerations.
>> In order to get it working this way, you need to*nest*  the table in the
>> directive (i.e. indent it to the same amount as the second line):

>> .. table::
>>     :class:  borderless

>>     ============== ===================================================
>>     Item-Id -      A character string (maximum 48 characters) which
>>                    uniquely identifies an item within a file.

> /home/anthony/gitstuff/ScarletDME/docs/source/SMA/SMA301.rst:80: 
> WARNING: Error in "table" directive:
> invalid option block.

> .. table::
>     :class:  borderless
>     =========== =========================================================
>     Item-Id -   A character string (maximum 48 characters) which

You are missing the empty line between the option block and the table!

> > In Sphinx, the "class" directive is used for other purposes by default
> > and must be activated in the setup.py config file.

> ??? What setup file? Where? How? Is this the cause of my error above? Is 
> it the conf.py file?

No.  See
https://docutils.sourceforge.io/docs/user/config.html#configuration-files
Ask on the Sphinx list where Sphinx expects a project-specific Docutils 
configuration file.

Günter

Re: [Docutils-users] simple table without formatting

[Wol <ant...@yo...>]

On 20/02/2022 18:30, Guenter Milde via Docutils-users wrote:
> On 2022-02-20, Wols Lists wrote:
> 
> ...
> 
>> Okay, done a bit of googling, ended up with this, and I've still got
>> grid lines everywhere ...
>> .. table::
>>      :class: borderless
>> =========== =========================================================
>> Item-Id -   A character string (maximum 48 characters) which
>>               uniquely identifies an item within a file. The item-id
>>               may include any characters except system delimiters,
>>               however the use of blanks, single quotes, quotes,
>>               commas, and backslash characters may require special
>>               considerations.
> In order to get it working this way, you need to*nest*  the table in the
> directive (i.e. indent it to the same amount as the second line):
> 
> .. table::
>     :class:  borderless
>     
>     ============== ===================================================
>     Item-Id -      A character string (maximum 48 characters) which
>                    uniquely identifies an item within a file.

/home/anthony/gitstuff/ScarletDME/docs/source/SMA/SMA301.rst:80: 
WARNING: Error in "table" directive:
invalid option block.

.. table::
    :class:  borderless
    =========== =========================================================
    Item-Id -   A character string (maximum 48 characters) which

 > In Sphinx, the "class" directive is used for other purposes by default
 > and must be activated in the setup.py config file.

??? What setup file? Where? How? Is this the cause of my error above? Is 
it the conf.py file?

Cheers,
Wol

Re: [Docutils-users] simple table without formatting

[Guenter M. <mi...@us...>]

On 2022-02-20, Wols Lists wrote:

...

> Okay, done a bit of googling, ended up with this, and I've still got 
> grid lines everywhere ...

> .. table::
>     :class: borderless
>=========== =========================================================
> Item-Id -   A character string (maximum 48 characters) which
>              uniquely identifies an item within a file. The item-id
>              may include any characters except system delimiters,
>              however the use of blanks, single quotes, quotes,
>              commas, and backslash characters may require special
>              considerations.

In order to get it working this way, you need to *nest* the table in the
directive (i.e. indent it to the same amount as the second line):

.. table::
   :class:  borderless
   
   ============== ===================================================
   Item-Id -      A character string (maximum 48 characters) which
                  uniquely identifies an item within a file.
                  ...
               
    ...           ...             
   ============== ===================================================
 
In Docutils, you can easily avoid the indenting with a "prefix" class
directive:

.. class:: borderless

============== ===================================================
Item-Id -      A character string (maximum 48 characters) which
               uniquely identifies an item within a file.
               ...
            
 ...           ...             
============== ===================================================

In Sphinx, the "class" directive is used for other purposes by default
and must be activated in the setup.py config file.

You can also set a default class for all tables in a document with
the table_style configuration setting.
https://docutils.sourceforge.io/docs/user/config.html#table-style
This should work in Docutils and Sphinx.


Instead of a table, you may use lists:

A definition list
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#definition-lists

Item-Id -      
  A character string (maximum 48 characters) which uniquely identifies an
  item within a file. ...
            
...
  ...             
  
or a field list  
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#field-lists

:Item-Id: A character string (maximum 48 characters) which uniquely identifies an
          item within a file. ...
:...:     ...             

The layout/formatting of the lists can be customized in a stylesheet.


Hope this helps a bit.
Güner

Re: [Docutils-users] simple table without formatting

[Guenter M. <mi...@us...>]

On 2022-02-20, Wols Lists wrote:

...

>>> This is oh so simple with tabs or fixed width fonts - why do so many 
>>> modern systems find it almost impossible!

...

> What I'm *transcribing* is a document where they DID force columns with 
> spaces and tabs :-)

You can, of course just do it this way: write your document with fixed-width
font.

If you want this as part of a reStructuredText document (i.e. documentation
done with Sphinx or Docutils), you must use "literal blocks"::

   Here       the
   spacing    is     preserved.
   
You may also include a file "as is" with

.. include::  my-tabbed-document.txt
   :literal:
   
But I recommend using a simple table, a field-list or a description list,
IMV this looks and "behaves" better in a browser or on paper.

Günter

Re: [Docutils-users] simple table without formatting

[Wols L. <ant...@yo...>]

On 20/02/2022 16:29, Martin Koutecký wrote:
> You're missing a space:
> .. class:: borderless

Thanks. But this is where proportional fonts really mess up. But even 
with fixed-width, what space where?!

As far as I can tell, I've got exactly what you wrote:

dot dot space class colon colon space borderless

and it's not working. stick a space after class and it has no effect.

I just don't know what I'm doing, and nothing works.

2.2 Structural Terms:
.....................

.. class:: borderless
=========== =========================================================
Item-Id -   A character string (maximum 48 characters) which
             uniquely identifies an item within a file. The item-id
             may include any characters except system delimiters,
             however the use of blanks, single quotes, quotes,
             commas, and backslash characters may require special
             considerations.

Cheers,
Wol
> 
> M.
> 
> Dne ne 20. 2. 2022 16:44 uživatel Wols Lists <ant...@yo... 
> <mailto:ant...@yo...>> napsal:
> 
>     On 20/02/2022 15:22, David Goodger wrote:
>      > It appears that you're constructing an ordered list whose content
>      > contains line breaks. Maybe this will do what you want:
>      >
>      > 1. | I now want this
>      >     | text properly left aligned.
>      >
>      > See
>      >
>     https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#line-blocks
>     <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#line-blocks>
> 
>      >
>     <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#line-blocks
>     <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#line-blocks>>
> 
>     Thanks. But that seems to be - as it says - for where the LINE
>     structure
>     is important. I don't care about the lines, it's a paragraph.
>      >
>      > If it's something more complicated, ".. class:: borderless"
>     preceding a
>      > table may work.
> 
>     Which is where Marcelo left me - sticking "..class:: borderless" before
>     the table just prints "class borderless" before the table, and does
>     absolutely nothing to the table itself ...
>      >
>      > And it's not "malarkey", it's "markup".
>      > ;-)
>      > (but seriously, "malarkey" is derogatory, slightly insulting)
>      >
>     I think I understand the sentiment there, but as far as I can make out
>     this particular malarkey is not just markup, but it's python, css, and
>     god knows what else, all of which I've never got to grips with. So if
>     I'm using mildly offensive language, it's because I'm getting extremely
>     frustrated with all these words where I understand perfectly what they
>     SAY, but don't have a damn clue what they MEAN! :-)
> 
>     Cheers,
>     Wol
> 
>      > David Goodger
>      >
>      >
>      > David Goodger
>      > <https://david.goodger.org <https://david.goodger.org>
>     <https://david.goodger.org <https://david.goodger.org>>>
>      >
>      >
>      > On Sat, Feb 19, 2022 at 8:00 PM Wol <ant...@yo...
>     <mailto:ant...@yo...>
>      > <mailto:ant...@yo...
>     <mailto:ant...@yo...>>> wrote:
>      >
>      >     I'm trying to create a simple table, the sort that one would
>     do on a
>      >     typewriter using tabs. How on earth do you do it!
>      >
>      >     Something simple like
>      >
>      >     1.      I now want this
>      >              text properly left aligned.
>      >
>      >     Note that there is NO boxing around it - from what I can make
>     out as
>      >     soon as you tell Sphinx "this is a table" it goes and makes
>     the table
>      >     structure visible! But it's not a table I want - I just want tab
>      >     indented text or similar!
>      >
>      >     But as soon as I attempt to treat it like tab-indented, all my
>      >     indentation gets screwed up and I end up with something like
>      >
>      >     1. I now want this
>      >             text properly left aligned.
>      >
>      >     This is oh so simple with tabs or fixed width fonts - why do
>     so many
>      >     modern systems find it almost impossible!
>      >
>      >     Cheers,
>      >     Wol
>      >
>      >
>      >     _______________________________________________
>      >     Docutils-users mailing list
>      > Doc...@li...
>     <mailto:Doc...@li...>
>      >     <mailto:Doc...@li...
>     <mailto:Doc...@li...>>
>      > https://lists.sourceforge.net/lists/listinfo/docutils-users
>     <https://lists.sourceforge.net/lists/listinfo/docutils-users>
>      >     <https://lists.sourceforge.net/lists/listinfo/docutils-users
>     <https://lists.sourceforge.net/lists/listinfo/docutils-users>>
>      >
>      >     Please use "Reply All" to reply to the list.
>      >
> 
> 
> 
>     _______________________________________________
>     Docutils-users mailing list
>     Doc...@li...
>     <mailto:Doc...@li...>
>     https://lists.sourceforge.net/lists/listinfo/docutils-users
>     <https://lists.sourceforge.net/lists/listinfo/docutils-users>
> 
>     Please use "Reply All" to reply to the list.
> 

Re: [Docutils-users] simple table without formatting

[Martin K. <alq...@gm...>]

You're missing a space:
.. class:: borderless

M.

Dne ne 20. 2. 2022 16:44 uživatel Wols Lists <ant...@yo...>
napsal:

> On 20/02/2022 15:22, David Goodger wrote:
> > It appears that you're constructing an ordered list whose content
> > contains line breaks. Maybe this will do what you want:
> >
> > 1. | I now want this
> >     | text properly left aligned.
> >
> > See
> >
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#line-blocks
> > <
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#line-blocks
> >
>
> Thanks. But that seems to be - as it says - for where the LINE structure
> is important. I don't care about the lines, it's a paragraph.
> >
> > If it's something more complicated, ".. class:: borderless" preceding a
> > table may work.
>
> Which is where Marcelo left me - sticking "..class:: borderless" before
> the table just prints "class borderless" before the table, and does
> absolutely nothing to the table itself ...
> >
> > And it's not "malarkey", it's "markup".
> > ;-)
> > (but seriously, "malarkey" is derogatory, slightly insulting)
> >
> I think I understand the sentiment there, but as far as I can make out
> this particular malarkey is not just markup, but it's python, css, and
> god knows what else, all of which I've never got to grips with. So if
> I'm using mildly offensive language, it's because I'm getting extremely
> frustrated with all these words where I understand perfectly what they
> SAY, but don't have a damn clue what they MEAN! :-)
>
> Cheers,
> Wol
>
> > David Goodger
> >
> >
> > David Goodger
> > <https://david.goodger.org <https://david.goodger.org>>
> >
> >
> > On Sat, Feb 19, 2022 at 8:00 PM Wol <ant...@yo...
> > <mailto:ant...@yo...>> wrote:
> >
> >     I'm trying to create a simple table, the sort that one would do on a
> >     typewriter using tabs. How on earth do you do it!
> >
> >     Something simple like
> >
> >     1.      I now want this
> >              text properly left aligned.
> >
> >     Note that there is NO boxing around it - from what I can make out as
> >     soon as you tell Sphinx "this is a table" it goes and makes the table
> >     structure visible! But it's not a table I want - I just want tab
> >     indented text or similar!
> >
> >     But as soon as I attempt to treat it like tab-indented, all my
> >     indentation gets screwed up and I end up with something like
> >
> >     1. I now want this
> >             text properly left aligned.
> >
> >     This is oh so simple with tabs or fixed width fonts - why do so many
> >     modern systems find it almost impossible!
> >
> >     Cheers,
> >     Wol
> >
> >
> >     _______________________________________________
> >     Docutils-users mailing list
> >     Doc...@li...
> >     <mailto:Doc...@li...>
> >     https://lists.sourceforge.net/lists/listinfo/docutils-users
> >     <https://lists.sourceforge.net/lists/listinfo/docutils-users>
> >
> >     Please use "Reply All" to reply to the list.
> >
>
>
>
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>

Re: [Docutils-users] simple table without formatting

[Wols L. <ant...@yo...>]

On 20/02/2022 15:22, David Goodger wrote:
> It appears that you're constructing an ordered list whose content 
> contains line breaks. Maybe this will do what you want:
> 
> 1. | I now want this
>     | text properly left aligned.
> 
> See 
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#line-blocks 
> <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#line-blocks>

Thanks. But that seems to be - as it says - for where the LINE structure 
is important. I don't care about the lines, it's a paragraph.
> 
> If it's something more complicated, ".. class:: borderless" preceding a 
> table may work.

Which is where Marcelo left me - sticking "..class:: borderless" before 
the table just prints "class borderless" before the table, and does 
absolutely nothing to the table itself ...
> 
> And it's not "malarkey", it's "markup".
> ;-)
> (but seriously, "malarkey" is derogatory, slightly insulting)
> 
I think I understand the sentiment there, but as far as I can make out 
this particular malarkey is not just markup, but it's python, css, and 
god knows what else, all of which I've never got to grips with. So if 
I'm using mildly offensive language, it's because I'm getting extremely 
frustrated with all these words where I understand perfectly what they 
SAY, but don't have a damn clue what they MEAN! :-)

Cheers,
Wol

> David Goodger
> 
> 
> David Goodger
> <https://david.goodger.org <https://david.goodger.org>>
> 
> 
> On Sat, Feb 19, 2022 at 8:00 PM Wol <ant...@yo... 
> <mailto:ant...@yo...>> wrote:
> 
>     I'm trying to create a simple table, the sort that one would do on a
>     typewriter using tabs. How on earth do you do it!
> 
>     Something simple like
> 
>     1.      I now want this
>              text properly left aligned.
> 
>     Note that there is NO boxing around it - from what I can make out as
>     soon as you tell Sphinx "this is a table" it goes and makes the table
>     structure visible! But it's not a table I want - I just want tab
>     indented text or similar!
> 
>     But as soon as I attempt to treat it like tab-indented, all my
>     indentation gets screwed up and I end up with something like
> 
>     1. I now want this
>             text properly left aligned.
> 
>     This is oh so simple with tabs or fixed width fonts - why do so many
>     modern systems find it almost impossible!
> 
>     Cheers,
>     Wol
> 
> 
>     _______________________________________________
>     Docutils-users mailing list
>     Doc...@li...
>     <mailto:Doc...@li...>
>     https://lists.sourceforge.net/lists/listinfo/docutils-users
>     <https://lists.sourceforge.net/lists/listinfo/docutils-users>
> 
>     Please use "Reply All" to reply to the list.
> 

Re: [Docutils-users] simple table without formatting

[David G. <go...@py...>]

It appears that you're constructing an ordered list whose content contains
line breaks. Maybe this will do what you want:

1. | I now want this
   | text properly left aligned.

See
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#line-blocks

If it's something more complicated, ".. class:: borderless" preceding a
table may work.

And it's not "malarkey", it's "markup".
;-)
(but seriously, "malarkey" is derogatory, slightly insulting)

David Goodger


David Goodger
<https://david.goodger.org>


On Sat, Feb 19, 2022 at 8:00 PM Wol <ant...@yo...> wrote:

> I'm trying to create a simple table, the sort that one would do on a
> typewriter using tabs. How on earth do you do it!
>
> Something simple like
>
> 1.      I now want this
>         text properly left aligned.
>
> Note that there is NO boxing around it - from what I can make out as
> soon as you tell Sphinx "this is a table" it goes and makes the table
> structure visible! But it's not a table I want - I just want tab
> indented text or similar!
>
> But as soon as I attempt to treat it like tab-indented, all my
> indentation gets screwed up and I end up with something like
>
> 1. I now want this
>        text properly left aligned.
>
> This is oh so simple with tabs or fixed width fonts - why do so many
> modern systems find it almost impossible!
>
> Cheers,
> Wol
>
>
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>

Re: [Docutils-users] simple table without formatting

[Wols L. <ant...@yo...>]

On 20/02/2022 01:44, Marcelo Huerta wrote:
> Wol escribió el 19/2/2022 a las 21:10:
> 
>> I'm trying to create a simple table, the sort that one would do on a 
>> typewriter using tabs. How on earth do you do it!
> 
> Forget the typewriter. We're using computers.
> 
>> This is oh so simple with tabs or fixed width fonts - why do so many 
>> modern
>> systems find it almost impossible!
> 
> Because currently markup languages tend to be semantic. We're not in the 
> age
> of punchcards where the only document type is text and we force columns 
> with
> spaces or tabs. And, of course, trying to align text that way doesn't 
> make any sense if you're using variable width fonts.
> 
> What you're showing is either a table of a series of containers. 
> Presentation
> is best left to the renderer. You are rendering to HTML and don't like the
> table borders? Write your content as a table, add :class: borderless to 
> your table, and that's it.
> 
Okay, done a bit of googling, ended up with this, and I've still got 
grid lines everywhere ...

.. table::
    :class: borderless
=========== =========================================================
Item-Id -   A character string (maximum 48 characters) which
             uniquely identifies an item within a file. The item-id
             may include any characters except system delimiters,
             however the use of blanks, single quotes, quotes,
             commas, and backslash characters may require special
             considerations.
...
...

At least it compiles, which is more than my initial attempts :-)

Cheers,
Wol

Re: [Docutils-users] simple table without formatting

[Wols L. <ant...@yo...>]

On 20/02/2022 01:44, Marcelo Huerta wrote:
> Wol escribió el 19/2/2022 a las 21:10:
> 
>> I'm trying to create a simple table, the sort that one would do on a 
>> typewriter using tabs. How on earth do you do it!
> 
> Forget the typewriter. We're using computers.
> 
>> This is oh so simple with tabs or fixed width fonts - why do so many 
>> modern
>> systems find it almost impossible!
> 
> Because currently markup languages tend to be semantic. We're not in the 
> age
> of punchcards where the only document type is text and we force columns 
> with
> spaces or tabs. And, of course, trying to align text that way doesn't 
> make any sense if you're using variable width fonts.
> 
> What you're showing is either a table of a series of containers. 
> Presentation
> is best left to the renderer. You are rendering to HTML and don't like the
> table borders? Write your content as a table, add :class: borderless to 
> your table, and that's it.
> 
Thank you very much.

What I'm *transcribing* is a document where they DID force columns with 
spaces and tabs :-)

But yes, I was expecting to have to do something like that, I'm fine 
with it, I'm just completely new to all this malarkey and didn't have a 
clue *how* to do it.

Thanks again,
Wol

Re: [Docutils-users] simple table without formatting

[Marcelo H. <mar...@gm...>]

Wol escribió el 19/2/2022 a las 21:10:

> I'm trying to create a simple table, the sort that one would do on a 
> typewriter using tabs. How on earth do you do it!

Forget the typewriter. We're using computers.

> This is oh so simple with tabs or fixed width fonts - why do so many modern
> systems find it almost impossible!

Because currently markup languages tend to be semantic. We're not in the age
of punchcards where the only document type is text and we force columns with
spaces or tabs. And, of course, trying to align text that way doesn't make any 
sense if you're using variable width fonts.

What you're showing is either a table of a series of containers. Presentation
is best left to the renderer. You are rendering to HTML and don't like the
table borders? Write your content as a table, add :class: borderless to your 
table, and that's it.

-- 
    o-=< Marcelo >=-o

[Docutils-users] simple table without formatting

[Wol <ant...@yo...>]

I'm trying to create a simple table, the sort that one would do on a 
typewriter using tabs. How on earth do you do it!

Something simple like

1.	I now want this
	text properly left aligned.

Note that there is NO boxing around it - from what I can make out as 
soon as you tell Sphinx "this is a table" it goes and makes the table 
structure visible! But it's not a table I want - I just want tab 
indented text or similar!

But as soon as I attempt to treat it like tab-indented, all my 
indentation gets screwed up and I end up with something like

1. I now want this
       text properly left aligned.

This is oh so simple with tabs or fixed width fonts - why do so many 
modern systems find it almost impossible!

Cheers,
Wol

Re: [Docutils-users] Type hints for Docutils - docutils-stubs or types-docutils?

[Guenter M. <mi...@us...>]

Dear Matt,

On 2021-12-21, Matt Documatt wrote:
> Hi, there are at least two projects trying to do the same - provide
> type hints for Docutils.

> In past, I used docutils-stub
> (https://github.com/tk0miya/docutils-stubs), but it doesn't cover a few
> past versions. It is the work of great Sphinx guy Takeshi Komya.

> Recently, I discovered types-docutils
> (https://pypi.org/project/types-docutils/) that look "official" as it
> is part of typeshed.

> Which one to use? Who maintains the second one?

Both are 3rd party projects. While Takeshi Komya is a regular
contributor to docutils-devel and the ticket system, types-docutils is
completely independent. It seems to be a "community project" with several
contributors visible in
https://github.com/python/typeshed/tree/master/stubs/docutils.
I am not aware of problem reports for either of them.


After dropping support for Python 2.7, Docutils may start annotating public
classes, functions, and methods.

Günter

[Docutils-users] Type hints for Docutils - docutils-stubs or types-docutils?

[Matt D. <ma...@do...>]

Hi,
there are at least two projects trying to do the same - provide type hints for Docutils.

In past, I used docutils-stub (https://github.com/tk0miya/docutils-stubs), but it doesn't cover a few past versions. It is the work of great Sphinx guy Takeshi Komya.

Recently, I discovered types-docutils (https://pypi.org/project/types-docutils/) that look "official" as it is part of typeshed.

Which one to use? Who maintains the second one?

--
Matt
https://techwriter.documatt.com

Re: [Docutils-users] Open Access book (scientific visualization) using rst

[Martin K. <m...@ef...>]

Thanks for sharing!
What have been the advantages of using rST over raw latex, and why did you
make that choice?
Thanks,
Martin

On Tue, Nov 23, 2021 at 8:45 PM Nicolas P. Rougier (inria) <
nic...@in...> wrote:

>
> It's a regular bibtex file but I use a \nocite{*} in the latex
> template so it's not totally automated.
>
> Nicolas
>
> "Alan G. Isaac" <ala...@gm...> writes:
>
> > Wow!
> > Thanks for sharing!
> >
> > Did you create the bibliography by hand?
> >
> > Alan Isaac
> >
> >
> > On 11/23/2021 1:26 PM, Nicolas P. Rougier (inria) wrote:
> >> Hi all,
> >> I've just released an open access PDF book (on scientifif
> >> visualization) using restructured text that I converted to
> >> latex
> >> with a slightly modified rst2latex.py script and for some pages
> >> I
> >> had no choice but to use raw-latex directives. I think the
> >> result is
> >> nice.
> >> Book:
> >> https://www.labri.fr/perso/nrougier/scientific-visualization.html
> >> Sources:
> >> https://github.com/rougier/scientific-visualization-book
> >> Feel free to copy the book style if you like it.
> >> Cheers,
> >> Nicolas
> >>
> >> _______________________________________________
> >> Docutils-users mailing list
> >> Doc...@li...
> >> https://lists.sourceforge.net/lists/listinfo/docutils-users
> >> Please use "Reply All" to reply to the list.
> >
> >
> > _______________________________________________
> > Docutils-users mailing list
> > Doc...@li...
> > https://lists.sourceforge.net/lists/listinfo/docutils-users
> >
> > Please use "Reply All" to reply to the list.
>
>
>
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>

Re: [Docutils-users] Open Access book (scientific visualization) using rst

[Nicolas P. R. (inria) <nic...@in...>]

I find Latex markup/syntax a bit too intrusive when writing. Using 
rst was a great way to stick to content without paying too much 
attention to layout.

Nicolas

Martin Koutecký <m...@ef...> writes:

> Thanks for sharing!
> What have been the advantages of using rST over raw latex, and 
> why did
> you make that choice?
> Thanks,
> Martin
>
> On Tue, Nov 23, 2021 at 8:45 PM Nicolas P. Rougier (inria)
> <nic...@in...> wrote:
>
>     It's a regular bibtex file but I use a \nocite{*} in the 
>     latex 
>     template so it's not totally automated.
>
>     Nicolas
>
>     "Alan G. Isaac" <ala...@gm...> writes:
>
>     > Wow!
>     > Thanks for sharing!
>     >
>     > Did you create the bibliography by hand?
>     >
>     > Alan Isaac
>     >
>     >
>     > On 11/23/2021 1:26 PM, Nicolas P. Rougier (inria) wrote:
>     >> Hi all,
>     >> I've just released an open access PDF book (on scientifif
>     >> visualization) using restructured text that I converted 
>     >> to 
>     >> latex
>     >> with a slightly modified rst2latex.py script and for some 
>     >> pages
>     >> I
>     >> had no choice but to use raw-latex directives. I think 
>     >> the 
>     >> result is
>     >> nice.
>     >> Book:
>     >>
>     https://www.labri.fr/perso/nrougier/scientific-visualization.html
>     >> Sources: 
>     >> https://github.com/rougier/scientific-visualization-book
>     >> Feel free to copy the book style if you like it.
>     >> Cheers,
>     >> Nicolas
>     >> 
>     >> _______________________________________________
>     >> Docutils-users mailing list
>     >> Doc...@li...
>     >> https://lists.sourceforge.net/lists/listinfo/docutils-users
>     >> Please use "Reply All" to reply to the list.
>     >
>     >
>     > _______________________________________________
>     > Docutils-users mailing list
>     > Doc...@li...
>     > https://lists.sourceforge.net/lists/listinfo/docutils-users
>     >
>     > Please use "Reply All" to reply to the list.
>
>     _______________________________________________
>     Docutils-users mailing list
>     Doc...@li...
>     https://lists.sourceforge.net/lists/listinfo/docutils-users
>
>     Please use "Reply All" to reply to the list.

Re: [Docutils-users] Open Access book (scientific visualization) using rst

[Nicolas P. R. (inria) <nic...@in...>]

It's a regular bibtex file but I use a \nocite{*} in the latex 
template so it's not totally automated.

Nicolas

"Alan G. Isaac" <ala...@gm...> writes:

> Wow!
> Thanks for sharing!
>
> Did you create the bibliography by hand?
>
> Alan Isaac
>
>
> On 11/23/2021 1:26 PM, Nicolas P. Rougier (inria) wrote:
>> Hi all,
>> I've just released an open access PDF book (on scientifif
>> visualization) using restructured text that I converted to 
>> latex
>> with a slightly modified rst2latex.py script and for some pages 
>> I
>> had no choice but to use raw-latex directives. I think the 
>> result is
>> nice.
>> Book:
>> https://www.labri.fr/perso/nrougier/scientific-visualization.html
>> Sources: 
>> https://github.com/rougier/scientific-visualization-book
>> Feel free to copy the book style if you like it.
>> Cheers,
>> Nicolas
>> 
>> _______________________________________________
>> Docutils-users mailing list
>> Doc...@li...
>> https://lists.sourceforge.net/lists/listinfo/docutils-users
>> Please use "Reply All" to reply to the list.
>
>
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.

Re: [Docutils-users] Open Access book (scientific visualization) using rst

[Alan G. I. <ala...@gm...>]

Wow!
Thanks for sharing!

Did you create the bibliography by hand?

Alan Isaac


On 11/23/2021 1:26 PM, Nicolas P. Rougier (inria) wrote:
> 
> Hi all,
> 
> I've just released an open access PDF book (on scientifif visualization) using restructured text that I converted to latex with a slightly modified rst2latex.py 
> script and for some pages I had no choice but to use raw-latex directives. I think the result is nice.
> 
> Book: https://www.labri.fr/perso/nrougier/scientific-visualization.html
> Sources: https://github.com/rougier/scientific-visualization-book
> 
> Feel free to copy the book style if you like it.
> Cheers,
> Nicolas
> 
> 
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
> 
> Please use "Reply All" to reply to the list.