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

Re: [Docutils-users] table notes

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

On 5/17/2019 10:49 AM, David Goodger wrote:
> .. [1] But **not** a table legend; that still makes no sense to me.


I was certainly not suggesting such a terminology.
My point is rather that what reST refers to as a
figure "legend" is in fact a rather multi-use
container.  In fact, I do not think I have ever
used it to hold a legend; instead, I use it to
hold figure notes.  I would hazard that my usage
is the most common, since legend information is
very often part of the figure (in one way or another).
Example attached (from Jones 2015).

That said, tables often contain meaningful markers
or colors, whose meaning needs to be explicated in
the notes.  (E.g., markers of statistical significance
levels.)  This is quite similar to a figure legend.

Alan

Re: [Docutils-users] table notes

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

My distinction between titles and captions comes straight from `The
Chicago Manual of Style`: tables have titles above, figures have
captions below. The HTML <caption> tag seems to be the result of
conflation, shown in the first link you provided:

    The HTML Table Caption element (<caption>) specifies the caption
(or title) of a table

For table notes, I suggest simply adding them into the table itself.
This can be done now.

It's *possible* that Docutils could accommodate "table notes" [1]_,
but it would require specification (e.g. are they repeated when a
table is broken across pages, like a header? are they always at the
bottom of tables, even very long ones? etc.) and, of course,
implementation. I personally remain unconvinced.

.. [1] But **not** a table legend; that still makes no sense to me.

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

On Fri, 17 May 2019 at 08:38, Alan Isaac <ala...@gm...> wrote:
>
> I will try to keep it in mind when talking about reST,
> but I find your distinction between titles and captions to be
> unfamiliar.  E.g., the following usage is more familiar to me:
> https://developer.mozilla.org/en-US/docs/Web/HTML/Element/caption
> https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figcaption
>
> However, in this query my interest is (as in the Subject) how
> to handle table notes.  My observation is that just as figures
> allow figure notes (as part of the "legend" content), a table could
> similarly allow table notes.  These are a *very* often needed feature
> -- so much so, that tables without notes are often unacceptable.
> I've attached an "in the wild" example.  My query is whether
> docutils could consider accommodating such optional content
> for tables, paralleling the feature in figures.
>
> Cheers, Alan
>
>
> On 5/16/2019 10:09 PM, David Goodger wrote:
> > The table directive as implemented doesn't allow for a legend, just a
> > title. I can't think of why a table would need a legend, and I've
> > never seen one in the wild.
> >
> > Note: figures have captions (below), tables have titles (above).
> > They're not the same thing, and shouldn't be conflated.
> >
> > David Goodger
> > <https://david.goodger.org>
> >
> > On Thu, 16 May 2019 at 16:59, Alan Isaac <ala...@gm...> wrote:
> >>
> >> I'm looking at the documentation at
> >> http://docutils.sourceforge.net/docs/ref/rst/directives.html#table
> >> On my reading, it does not allow for the equivalent of the "legend"
> >> content in a figure.  What am I overlooking?
> >>
> >> Thanks, Alan Isaac
> >>
> >>
> >> On 5/16/2019 4:37 PM, David Goodger wrote:
> >>> That's what the "table" directive is for:
> >>> http://docutils.sourceforge.net/docs/ref/rst/directives.html#table
> >>>
> >>> David Goodger
> >>> <https://david.goodger.org>
> >>>
> >>> On Thu, 16 May 2019 at 15:03, Alan Isaac <ala...@gm...> wrote:
> >>>>
> >>>> In published work, tables and figures often require
> >>>> explanatory notes.
> >>>>
> >>>> In rst there appears to be an odd difference in structure between
> >>>> tables and figures.  A figure is understood to have three possible
> >>>> types of content, and image, a caption, and what is called a "legend"
> >>>> (which can hold explanatory notes).
> >>>>
> >>>> A table does not do this, but it could.
> >>>> Might this be considered as a possible enhancement?
> >>>>
> >>>> Thanks, Alan Isaac
> >>>>
> >>>>
> >>>> _______________________________________________
> >>>> 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] table notes

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

I will try to keep it in mind when talking about reST,
but I find your distinction between titles and captions to be
unfamiliar.  E.g., the following usage is more familiar to me:
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/caption
https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figcaption

However, in this query my interest is (as in the Subject) how
to handle table notes.  My observation is that just as figures
allow figure notes (as part of the "legend" content), a table could
similarly allow table notes.  These are a *very* often needed feature
-- so much so, that tables without notes are often unacceptable.
I've attached an "in the wild" example.  My query is whether
docutils could consider accommodating such optional content
for tables, paralleling the feature in figures.

Cheers, Alan


On 5/16/2019 10:09 PM, David Goodger wrote:
> The table directive as implemented doesn't allow for a legend, just a
> title. I can't think of why a table would need a legend, and I've
> never seen one in the wild.
> 
> Note: figures have captions (below), tables have titles (above).
> They're not the same thing, and shouldn't be conflated.
> 
> David Goodger
> <https://david.goodger.org>
> 
> On Thu, 16 May 2019 at 16:59, Alan Isaac <ala...@gm...> wrote:
>>
>> I'm looking at the documentation at
>> http://docutils.sourceforge.net/docs/ref/rst/directives.html#table
>> On my reading, it does not allow for the equivalent of the "legend"
>> content in a figure.  What am I overlooking?
>>
>> Thanks, Alan Isaac
>>
>>
>> On 5/16/2019 4:37 PM, David Goodger wrote:
>>> That's what the "table" directive is for:
>>> http://docutils.sourceforge.net/docs/ref/rst/directives.html#table
>>>
>>> David Goodger
>>> <https://david.goodger.org>
>>>
>>> On Thu, 16 May 2019 at 15:03, Alan Isaac <ala...@gm...> wrote:
>>>>
>>>> In published work, tables and figures often require
>>>> explanatory notes.
>>>>
>>>> In rst there appears to be an odd difference in structure between
>>>> tables and figures.  A figure is understood to have three possible
>>>> types of content, and image, a caption, and what is called a "legend"
>>>> (which can hold explanatory notes).
>>>>
>>>> A table does not do this, but it could.
>>>> Might this be considered as a possible enhancement?
>>>>
>>>> Thanks, Alan Isaac
>>>>
>>>>
>>>> _______________________________________________
>>>> 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] table notes

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

The table directive as implemented doesn't allow for a legend, just a
title. I can't think of why a table would need a legend, and I've
never seen one in the wild.

Note: figures have captions (below), tables have titles (above).
They're not the same thing, and shouldn't be conflated.

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

On Thu, 16 May 2019 at 16:59, Alan Isaac <ala...@gm...> wrote:
>
> I'm looking at the documentation at
> http://docutils.sourceforge.net/docs/ref/rst/directives.html#table
> On my reading, it does not allow for the equivalent of the "legend"
> content in a figure.  What am I overlooking?
>
> Thanks, Alan Isaac
>
>
> On 5/16/2019 4:37 PM, David Goodger wrote:
> > That's what the "table" directive is for:
> > http://docutils.sourceforge.net/docs/ref/rst/directives.html#table
> >
> > David Goodger
> > <https://david.goodger.org>
> >
> > On Thu, 16 May 2019 at 15:03, Alan Isaac <ala...@gm...> wrote:
> >>
> >> In published work, tables and figures often require
> >> explanatory notes.
> >>
> >> In rst there appears to be an odd difference in structure between
> >> tables and figures.  A figure is understood to have three possible
> >> types of content, and image, a caption, and what is called a "legend"
> >> (which can hold explanatory notes).
> >>
> >> A table does not do this, but it could.
> >> Might this be considered as a possible enhancement?
> >>
> >> Thanks, Alan Isaac
> >>
> >>
> >> _______________________________________________
> >> 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] table notes

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

I'm looking at the documentation at
http://docutils.sourceforge.net/docs/ref/rst/directives.html#table
On my reading, it does not allow for the equivalent of the "legend"
content in a figure.  What am I overlooking?

Thanks, Alan Isaac


On 5/16/2019 4:37 PM, David Goodger wrote:
> That's what the "table" directive is for:
> http://docutils.sourceforge.net/docs/ref/rst/directives.html#table
> 
> David Goodger
> <https://david.goodger.org>
> 
> On Thu, 16 May 2019 at 15:03, Alan Isaac <ala...@gm...> wrote:
>>
>> In published work, tables and figures often require
>> explanatory notes.
>>
>> In rst there appears to be an odd difference in structure between
>> tables and figures.  A figure is understood to have three possible
>> types of content, and image, a caption, and what is called a "legend"
>> (which can hold explanatory notes).
>>
>> A table does not do this, but it could.
>> Might this be considered as a possible enhancement?
>>
>> Thanks, Alan Isaac
>>
>>
>> _______________________________________________
>> 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] query about admonition classes convention

[Alan G. I. <ai...@am...>]

I am wondering why "admonition" is prepended to the title
for the class attribute, given that "admonition" is one
of the classes.  If this is to accommodate another write,
shouldn't that be handled by a multiple-class to single
identifier convention?

Also, has the current convention always applied?
It took me by surprise, possibly due to forgetfulness.

Thanks, Alan Isaac

Re: [Docutils-users] table notes

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

That's what the "table" directive is for:
http://docutils.sourceforge.net/docs/ref/rst/directives.html#table

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

On Thu, 16 May 2019 at 15:03, Alan Isaac <ala...@gm...> wrote:
>
> In published work, tables and figures often require
> explanatory notes.
>
> In rst there appears to be an odd difference in structure between
> tables and figures.  A figure is understood to have three possible
> types of content, and image, a caption, and what is called a "legend"
> (which can hold explanatory notes).
>
> A table does not do this, but it could.
> Might this be considered as a possible enhancement?
>
> Thanks, Alan Isaac
>
>
> _______________________________________________
> 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] table notes

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

In published work, tables and figures often require
explanatory notes.

In rst there appears to be an odd difference in structure between
tables and figures.  A figure is understood to have three possible
types of content, and image, a caption, and what is called a "legend"
(which can hold explanatory notes).

A table does not do this, but it could.
Might this be considered as a possible enhancement?

Thanks, Alan Isaac

[Docutils-users] rst2odt and large table/images

[POIRET <gil...@bz...>]

Hello, 

I'm still trying to produce automatically odt documents from
rst file. I have currently two problems, when using docutils0.14 /
rst2odt tool. 

With large table and images, those objects exceed table
boundaries, and so the produced document can't be used as is. 

I'm
sharing below my wonderings/changes to fix that. Any comment are
welcome. 

Regards, 

-- 

Gilles Poiret 

TABLE: 

          analysis:
in the visit_table function, the lines "style:width" are commented. 

  
      workaround Uncomment them solve my issue, even if using the
self.get_page_width() to compute the value should be better..I guess you
have chosen to comment them. Could you explain why please? 

         
drawback : the small tables become bigger, but at least the document is
consistent. 

IMAGE: 

analysis & workaround : nothing seems planed to
avoid this behavior. I added the following in the
get_image_scaled_width_height function. Not perfect, especially if the
image is not put at the beginning of a line, but it's better than the
current situation, at least for me. 

-- at the beginning of the
function 

       line_width = self.get_page_width() # GP - the call of
this code can be removed below, in the "if width_unit == '%' test" 

--
at the end of the function 

        width *= scale
        height *=
scale

        if width > line_width:      # GP - resize the image to
fit the page size if bigger
            ratio_vs_pagesize = line_width /
width
            width = line_width
            height *=
ratio_vs_pagesize

        width = '%.2fcm' % width
        height =
'%.2fcm' % height
        return width, height 

Environment : Debian 10
"testing" / package python3-docutils 0.14+dfsg-4             

  

Re: [Docutils-users] manpage infilicity

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

On 2019-04-07, D. Hugh Redelmeier wrote:
>| From: D. Hugh Redelmeier <hu...@mi...>

>| On Fedora 29, the dnf(1) has a formatting ugliness:

...

> But wait!  I do see problems with the input to nroff.

> It is generated by sphinx.  My impression is that sphinx is also a
> part of the docutils project.

Not exactly. Sphinx uses Docutils as a library for the conversion
but adds an additional layer.

So, the error may be in Sphinx, in the Docutils manpage writer, or in the 
input for Spinx or the Docutils manpage writer (should be a file with
reStructured text like "dnf.rst" or "dnf.txt".

There are some restrictions on the allowed input, especially for 
option lists. See
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#option-lists

Günter

Re: [Docutils-users] manpage infilicity

[D. H. R. <hu...@mi...>]

| From: D. Hugh Redelmeier <hu...@mi...>

| On Fedora 29, the dnf(1) has a formatting ugliness:

In private email, it was pointed out that this ugliness probably
didn't come from rst2man or sphinx.

I'm trying to track down just where it comes from.  I found out that
the plumbing of the man command has gotten a lot more complicated than
when I last paid attention (1980s?).

In this case, a preformatted man page, generated by sphinx, is
distributed by Fedora.  When the man command is issued, apparently a
pipeline is created.

	something does gunzip |
	/usr/bin/preconv -e UTF-8 |
	/usr/bin/tbl |
	/usr/bin/nroff -mandoc -Tutf8 |
	/usr/bin/less # as if -r

At the moment, it looks as if nroff is the culprit.

nroff performs nicely if it is invoked with
	 -rLL=86n
and badly with
	 -rLL=85n

The -r flag sets the "number register".  According to groff_man(7), LL
is line length.  "n" is a scaling factor so that these numbers are in
ens, the width of the character n.

But wait!  I do see problems with the input to nroff.

It is generated by sphinx.  My impression is that sphinx is also a
part of the docutils project.

I generated this with
  gunzip -c /usr/share/man/man8/dnf.8.gz | preconv -e UTF-8 | tbl

Here is a section of interest:

   203	.TP
   204	.B \fB\-d <debug level>, \-\-debuglevel=<debug level>\fP
   205	Debugging output level. This is an integer value between 0 (no additional information strings) and 10 (shows all debugging information, even that not understandable to the user), default is 2. Deprecated, use \fB\-v\fP instead.
   206	.TP
   207	.B \fB\-\-debugsolver\fP
   208	Dump data aiding in dependency solver debugging into \fB\&./debugdata\fP\&.
   209	.UNINDENT
   210	.sp
   211	\fB\-\-disableexcludes=[all|main|<repoid>], \-\-disableexcludepkgs=[all|main|<repoid>]\fP
   212	.INDENT 0.0
   213	.INDENT 3.5
   214	Disable the configuration file excludes. Takes one of the following three options:
   215	.INDENT 0.0
   216	.IP \(bu 2
   217	\fBall\fP, disables all configuration file excludes
   218	.IP \(bu 2
   219	\fBmain\fP, disables excludes defined in the \fB[main]\fP section
   220	.IP \(bu 2
   221	\fBrepoid\fP, disables excludes defined for the given repository
   222	.UNINDENT
   223	.UNINDENT
   224	.UNINDENT
   225	.INDENT 0.0
   226	.TP
   227	.B \fB\-\-disable, \-\-set\-disabled\fP

Lines 203-205 show what a normal option description turns into.  Ditto
206-208.  Notice that no explicit indentation is specified.

man(7) descibes .TP as starting a paragraph with a hanging tag.  The
tag is given on the next line.

(Note that the tag is emboldened twice-over (.B and \fB).
This seems like an inconsequential bug.)

Things go weird at line 209, for the --debugexcludes option.
For one thing, .TP isn't used.  For another, there seems to be a lot
of explicit indenting going on.

The indenting is wrong.  It does not match that of other options.

But even with these fixed (by manual editing of the generated nroff
file), my original problem is not solved.  The tag is still split in a
bad place.

Some explicit indentation is probably needed since the paragraph
contains nested paragraphs (the bullet points).  I don't know what the
correct indentation is.

Re: [Docutils-users] manpage infilicity

[D. H. R. <hu...@mi...>]

Oops: this might be a problem with Sphinx, not rst2doc.
I've not figured out the plumbing.

| From: D. Hugh Redelmeier <hu...@mi...>
| 
| On Fedora 29, the dnf(1) has a formatting ugliness:
| 
|        --disableexcludes=[all|main|<repoid>],               --disableexcludep‐
|        kgs=[all|main|<repoid>]
|           Disable  the configuration file excludes. Takes one of the following
|           three options:
| 
| (I hope your MUA doesn't muck that up.)
| 
| The .rst is:
| 
| ``--disableexcludes=[all|main|<repoid>], --disableexcludepkgs=[all|main|<repoid>]``
| 
|     Disable the configuration file excludes. Takes one of the following three options:
| 
| 
| Clearly, to a human, rst2man should break this differently:
| 
|        --disableexcludes=[all|main|<repoid>],
|        --disableexcludepkgs=[all|main|<repoid>]
| 	    Disable the configuration file excludes. Takes one of the following three options:
| 
| Why?
| 
| - placing a break in a keyword instead of at a space is wrong
| 
| - placing a break in a keyword instead of at a word boundary is wrong
| 
| - breaking a keyword at a random spot is wrong (although finding
|   syllable boundaries in made-up words is difficult)
| 
| - turning the single space into 15 spaces is just putting salt on the wound
| 
| Is this a bug in rst2man or a bug in the dnf.rst file?
| 
| <https://github.com/rpm-software-management/dnf/blob/master/doc/command_ref.rst>

[Docutils-users] manpage infilicity

[D. H. R. <hu...@mi...>]

On Fedora 29, the dnf(1) has a formatting ugliness:

       --disableexcludes=[all|main|<repoid>],               --disableexcludep‐
       kgs=[all|main|<repoid>]
          Disable  the configuration file excludes. Takes one of the following
          three options:

(I hope your MUA doesn't muck that up.)

The .rst is:

``--disableexcludes=[all|main|<repoid>], --disableexcludepkgs=[all|main|<repoid>]``

    Disable the configuration file excludes. Takes one of the following three options:


Clearly, to a human, rst2man should break this differently:

       --disableexcludes=[all|main|<repoid>],
       --disableexcludepkgs=[all|main|<repoid>]
	    Disable the configuration file excludes. Takes one of the following three options:

Why?

- placing a break in a keyword instead of at a space is wrong

- placing a break in a keyword instead of at a word boundary is wrong

- breaking a keyword at a random spot is wrong (although finding
  syllable boundaries in made-up words is difficult)

- turning the single space into 15 spaces is just putting salt on the wound

Is this a bug in rst2man or a bug in the dnf.rst file?

<https://github.com/rpm-software-management/dnf/blob/master/doc/command_ref.rst>

Re: [Docutils-users] How to keep paragraphs or table rows together

[Matěj C. <mc...@ce...>]

On 2018-08-28, 08:08 GMT, R. Diez via Docutils-users wrote:
> The one thing that bothers me most often with Microsoft Word 
> or LibreOffice Writer is that paragraphs or tables are not 
> kept together when generating a PDF or printing.

LibreOffice Table/Insert table ... and in the dialog check 
"Don't split table over page breaks" (that's back-translation 
from Czech menus).

Of course, I prefer reStructuredText myself, but it is not 
excuse for not knowing your tools.

Best,

Matěj
-- 
https://matej.ceplovi.cz/blog/, Jabber: mc...@ce...
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
See, when the GOVERNMENT spends money, it creates jobs; whereas
when the money is left in the hands of TAXPAYERS, God only knows
what they do with it. Bake it into pies, probably. Anything to
avoid creating jobs.
    -- Dave Barry

Re: [Docutils-users] Test suite failure

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

Dear Tony,

could you re-send as simple text message (no HTML), please?
I am following the group via the GMANE news interface and all I see is:

On 2019-03-02, Tony Craig wrote:

> [-- Type: text/plain, Encoding:  --]

> [-- Skipped Type: text/html --]
> [-- Type: text/plain, Encoding: 7bit --]


> [-- Type: text/plain, Encoding: 7bit --]


Thanks,

Günter

[Docutils-users] Test suite failure

[Tony C. <tcr...@gm...>]

Re: [Docutils-users] rst2odt and odf-config-file option

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

On 2019-02-08, Dave Kuhlman wrote:

...

> So, I need to ask: We want a *single* version that runs under both
> Python 2 and Python 3, right?

This is a long term goal, but currently, Docutils requires conversion with
2to3 during installation to run with Py 3.

> Since a version that has been converted with `2to3` only runs under
> Python 3, I'll need to do the following:

> 1. Convert `odf_odt/__init__.py` so that it runs under both Python 2
>    and Python 3.  Then do a commit and check-in.

> 2. Add Gilles's change.  Then do a commit and check-in.

> 3. Do the clean-up for `flake8` and `pep8`.  Then do a commit and
>    check-in.

> I'm pretty sure that is what we want.  But, I thought I'd ask,
> because the number of changes needed for Python 3 is quite large.

This will become easier once we drop supporting Python 2.6 and older 3.x
versions after the 0.15 release.

> In the meantime, I'll get started.  Suggestions and guidance will be
> welcomed.

If you are not put off by the large changes, go ahead now. Otherwise add the
change to the Python-2 version and run the tests on both.

I do the Python 3 tests with

  # convert with 2to3:
  
  cd ~/Code/Python/docutils/docutils
  python3 setup.py build || exit $?
  
  # and run the tests there::
  
  python3.5 test3/alltests.py || exit $?


Günter

Re: [Docutils-users] rst2odt and odf-config-file option

[Dave K. <dku...@da...>]

I've run into a bit of a problem.

I've used docutils `odf_odt/__init__.py` under Python3.  That works.
But, the reason is because the version I've used is out of the
Anaconda Python 3 distribution, *and* that has been converted for
Python 3.  The version in the docutils SVN repository has *not* been
converted.  Maybe Gilles is using the Anaconda version, too.  I'm
pretty sure that they (the people at `https://www.anaconda.com`) ran
`odf_odt/__init__.py` through `2to3` and used that result, as is.
When I run the Python 2 version through `2to3` I get a file that's
identical to theirs, except for one more recent change.

So, I need to ask: We want a *single* version that runs under both
Python 2 and Python 3, right?

Since a version that has been converted with `2to3` only runs under
Python 3, I'll need to do the following:

1. Convert `odf_odt/__init__.py` so that it runs under both Python 2
   and Python 3.  Then do a commit and check-in.

2. Add Gilles's change.  Then do a commit and check-in.

3. Do the clean-up for `flake8` and `pep8`.  Then do a commit and
   check-in.

I'm pretty sure that is what we want.  But, I thought I'd ask,
because the number of changes needed for Python 3 is quite large.

In the meantime, I'll get started.  Suggestions and guidance will be
welcomed.

Dave


On Thu, Feb 07, 2019 at 12:04:47PM -0800, Dave Kuhlman wrote:
> Gilles,
> 
> Ugh.  Did I really do that?
> 
> Thanks for this fix.
> 
> I'll do some testing and will check the unit tests.  Then I'll push
> it back to the repo.
> 
> Question for the docutils list: When I apply the `flake8` style and
> error checker to `__init__.py`, I get lots of warnings (405 when I
> count them with `wc`).  Most of them have to do with indentation,
> missing or extra blank lines, missing or extra spaces, etc.  I'm
> willing to clean those up.  Or, would that amount of changes be too
> disruptive (for example, in making svn history less useful)?  Anyone
> have an opinion?  Clean it up?  Leave it alone?  If I do it, I'll
> make an extra check-in with only those cleanup changes.
> 
> Dave K
> 
> On Thu, Feb 07, 2019 at 01:48:42PM +0100, POIRET via Docutils-users wrote:
> >    Hello,
> > 
> >    I guess I've found a bug on rst2odt.py
> > 
> >    --
> > 
> >    I wanted to apply custom style with rst2odt, and discovered the
> >    --odf-config-file option.
> > 
> >    This option allows to map the default style to a custom one (so, used in
> >    conjunction with --template option).
> > 
> >    But it was not working on my environment (Debian 9, python3, docutils 1.4)
> > 
> >    --
> > 
> >    The __init__ method (l. 888) of the ODFTranslator class initializes a
> >    dictionary : format_map, but it's filled only for python2
> > 
> >    Involved file:
> >    /usr/lib/python3/dist-packages/docutils/writers/odf_odt/__init__.py
> > 
> >           parser = ConfigParser()
> >                parser.read(self.settings.odf_config_file)
> >                for rststyle, format in parser.items("Formats"):
> >                    if rststyle not in self.used_styles:
> >                        self.document.reporter.warning(
> >                            'Style "%s" is not a style used by odtwriter.' % (
> >                                rststyle, ))
> >                    if sys.version_info.major == 2:
> >                        self.format_map[rststyle] = format.decode('utf-8')
> >                   # my addition below
> > 
> >                   else:
> >                        self.format_map[rststyle] = format
> > 
> >    ---
> > 
> >  After applying my update, it works. (never tested with python2)
> > 
> > 
> >    Let me know if I can do something else.
> > 
> >    Regards,
> > 
> >    --
> > 
> >    Gilles
> > 
> >     
> > 
> >     
> > 
> >     
> 
> 
> > _______________________________________________
> > Docutils-users mailing list
> > Doc...@li...
> > https://lists.sourceforge.net/lists/listinfo/docutils-users
> > 
> > Please use "Reply All" to reply to the list.
> 
> 
> -- 
> 
> Dave Kuhlman
> http://www.davekuhlman.org
> 
> 
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
> 
> Please use "Reply All" to reply to the list.

-- 

Dave Kuhlman
http://www.davekuhlman.org

Re: [Docutils-users] rst2odt and odf-config-file option

[Matěj C. <mc...@ce...>]

On 2019-02-07, 20:04 GMT, Dave Kuhlman wrote:
> Question for the docutils list: When I apply the `flake8` 
> style and error checker to `__init__.py`, I get lots of 
> warnings (405 when I count them with `wc`).  Most of them have 
> to do with indentation, missing or extra blank lines, missing 
> or extra spaces, etc.  I'm willing to clean those up.  Or, 
> would that amount of changes be too disruptive (for example, 
> in making svn history less useful)?  Anyone have an opinion?  
> Clean it up?  Leave it alone?  If I do it, I'll make an extra 
> check-in with only those cleanup changes.

I have no authority to speak for anybody, but my comment would 
be:

+1 but do it in one commit named "PEP8ization" or something like 
that, which should in effect have no change to the 
functionality. Don't mix it with the real changes like fixing 
bugs.

Matěj
-- 
https://matej.ceplovi.cz/blog/, Jabber: mc...@ce...
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
Give a man a regular expression and he’ll match a string… teach
him to make his own regular expressions and you’ve got a man with
problems.
  -- yakugo in http://regex.info/blog/2006-09-15/247#comment-3022

Re: [Docutils-users] rst2odt and odf-config-file option

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

Flake8: As long as you do a separate check-in, I don't see a problem.
+0, because "A Foolish Consistency is the Hobgoblin of Little Minds"
(as noted in PEP 8 itself).

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

On Thu, 7 Feb 2019 at 14:32, Dave Kuhlman <dku...@da...> wrote:
>
> Gilles,
>
> Ugh.  Did I really do that?
>
> Thanks for this fix.
>
> I'll do some testing and will check the unit tests.  Then I'll push
> it back to the repo.
>
> Question for the docutils list: When I apply the `flake8` style and
> error checker to `__init__.py`, I get lots of warnings (405 when I
> count them with `wc`).  Most of them have to do with indentation,
> missing or extra blank lines, missing or extra spaces, etc.  I'm
> willing to clean those up.  Or, would that amount of changes be too
> disruptive (for example, in making svn history less useful)?  Anyone
> have an opinion?  Clean it up?  Leave it alone?  If I do it, I'll
> make an extra check-in with only those cleanup changes.
>
> Dave K
>
> On Thu, Feb 07, 2019 at 01:48:42PM +0100, POIRET via Docutils-users wrote:
> >    Hello,
> >
> >    I guess I've found a bug on rst2odt.py
> >
> >    --
> >
> >    I wanted to apply custom style with rst2odt, and discovered the
> >    --odf-config-file option.
> >
> >    This option allows to map the default style to a custom one (so, used in
> >    conjunction with --template option).
> >
> >    But it was not working on my environment (Debian 9, python3, docutils 1.4)
> >
> >    --
> >
> >    The __init__ method (l. 888) of the ODFTranslator class initializes a
> >    dictionary : format_map, but it's filled only for python2
> >
> >    Involved file:
> >    /usr/lib/python3/dist-packages/docutils/writers/odf_odt/__init__.py
> >
> >           parser = ConfigParser()
> >                parser.read(self.settings.odf_config_file)
> >                for rststyle, format in parser.items("Formats"):
> >                    if rststyle not in self.used_styles:
> >                        self.document.reporter.warning(
> >                            'Style "%s" is not a style used by odtwriter.' % (
> >                                rststyle, ))
> >                    if sys.version_info.major == 2:
> >                        self.format_map[rststyle] = format.decode('utf-8')
> >                   # my addition below
> >
> >                   else:
> >                        self.format_map[rststyle] = format
> >
> >    ---
> >
> >  After applying my update, it works. (never tested with python2)
> >
> >
> >    Let me know if I can do something else.
> >
> >    Regards,
> >
> >    --
> >
> >    Gilles
> >
> >
> >
> >
> >
> >
>
>
> > _______________________________________________
> > Docutils-users mailing list
> > Doc...@li...
> > https://lists.sourceforge.net/lists/listinfo/docutils-users
> >
> > Please use "Reply All" to reply to the list.
>
>
> --
>
> Dave Kuhlman
> http://www.davekuhlman.org
>
>
> _______________________________________________
> 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] rst2odt and odf-config-file option

[Dave K. <dku...@da...>]

Gilles,

Ugh.  Did I really do that?

Thanks for this fix.

I'll do some testing and will check the unit tests.  Then I'll push
it back to the repo.

Question for the docutils list: When I apply the `flake8` style and
error checker to `__init__.py`, I get lots of warnings (405 when I
count them with `wc`).  Most of them have to do with indentation,
missing or extra blank lines, missing or extra spaces, etc.  I'm
willing to clean those up.  Or, would that amount of changes be too
disruptive (for example, in making svn history less useful)?  Anyone
have an opinion?  Clean it up?  Leave it alone?  If I do it, I'll
make an extra check-in with only those cleanup changes.

Dave K

On Thu, Feb 07, 2019 at 01:48:42PM +0100, POIRET via Docutils-users wrote:
>    Hello,
> 
>    I guess I've found a bug on rst2odt.py
> 
>    --
> 
>    I wanted to apply custom style with rst2odt, and discovered the
>    --odf-config-file option.
> 
>    This option allows to map the default style to a custom one (so, used in
>    conjunction with --template option).
> 
>    But it was not working on my environment (Debian 9, python3, docutils 1.4)
> 
>    --
> 
>    The __init__ method (l. 888) of the ODFTranslator class initializes a
>    dictionary : format_map, but it's filled only for python2
> 
>    Involved file:
>    /usr/lib/python3/dist-packages/docutils/writers/odf_odt/__init__.py
> 
>           parser = ConfigParser()
>                parser.read(self.settings.odf_config_file)
>                for rststyle, format in parser.items("Formats"):
>                    if rststyle not in self.used_styles:
>                        self.document.reporter.warning(
>                            'Style "%s" is not a style used by odtwriter.' % (
>                                rststyle, ))
>                    if sys.version_info.major == 2:
>                        self.format_map[rststyle] = format.decode('utf-8')
>                   # my addition below
> 
>                   else:
>                        self.format_map[rststyle] = format
> 
>    ---
> 
>  After applying my update, it works. (never tested with python2)
> 
> 
>    Let me know if I can do something else.
> 
>    Regards,
> 
>    --
> 
>    Gilles
> 
>     
> 
>     
> 
>     


> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
> 
> Please use "Reply All" to reply to the list.


-- 

Dave Kuhlman
http://www.davekuhlman.org

[Docutils-users] rst2odt and odf-config-file option

[POIRET <gil...@bz...>]

Hello, 

I guess I've found a bug on rst2odt.py 

-- 

I wanted to
apply custom style with rst2odt, and discovered the --odf-config-file
option. 

This option allows to map the default style to a custom one
(so, used in conjunction with --template option). 

But it was not
working on my environment (Debian 9, python3, docutils 1.4) 

-- 

The
__init__ method (l. 888) of the ODFTranslator class initializes a
dictionary : format_map, but it's filled only for python2 

Involved
file:
/usr/lib/python3/dist-packages/docutils/writers/odf_odt/__init__.py 

  
   parser = ConfigParser()
           
parser.read(self.settings.odf_config_file)
            for rststyle,
format in parser.items("Formats"):
                if rststyle not in
self.used_styles:
                    self.document.reporter.warning(
  
                    'Style "%s" is not a style used by odtwriter.' % (

                          rststyle, ))
                if
sys.version_info.major == 2:
                   
self.format_map[rststyle] = format.decode('utf-8')
               # my
addition below 

               else:
                   
self.format_map[rststyle] = format 

---

After applying my update, it
works. (never tested with python2)

Let me know if I can do something
else. 

Regards, 

-- 

Gilles 

  

Re: [Docutils-users] How to break up long URLs

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

On 2018-10-11, Gregory Elkinbard wrote:

> Hi folks,

> I have URLs which are longer then 79 characters, how do I break them up
> in docutils compliant manner. I tried “\cr” but this results in an
> error.

You can insert linebreaks in the link target::

  test_
  
  .. _test: http://exam
            ple.org
          
results in the pseudoxml output ::

  <document source="/tmp/url.rst">
      <paragraph>
          <reference name="test" refuri="http://example.org">
              test
      <target ids="test" names="test" refuri="http://example.org">

with the line break and leading whitespace removed from the URL.


Günter

[Docutils-users] How to break up long URLs

[Gregory E. <gel...@ju...>]

Hi folks,
I have URLs which are longer then 79 characters, how do I break them up in docutils compliant manner.
I tried “\cr” but this results in an error.

Thanks
Greg

Re: [Docutils-users] include :code: eats tabs

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

Dear Chris,

On 2018-08-28, Chris Pickel wrote:

> [-- Type: text/plain, Encoding: quoted-printable --]

> I tried using the “include” directive with :code: and :tab-width: -1.
> For some reason, all of the tabs disappeared.
...
> If I remove :tab-width: -1, Pygments no longer detects the tabbed
> lines as errors, but the quoted output still can’t be copy-pasted, as
> hard tabs are required in Makefiles.

Thank you for reporting the problem. Indeed, negative values for the
"tab-width" option work only with files included as "literal".
This restriction is currently not documented in 
http://docutils.sourceforge.net/docs/ref/rst/directives.html#including-an-external-document-fragment

Literal tabs can be preserved in "code" inclusions, too ---
please try the following patch for the directive code:

diff --git a/trunk/docutils/docutils/parsers/rst/directives/misc.py b/trunk/docutils/docutils/parsers/rst/directives/misc.py
index 638974230..fab450a6d 100644
--- a/trunk/docutils/docutils/parsers/rst/directives/misc.py
+++ b/trunk/docutils/docutils/parsers/rst/directives/misc.py
@@ -144,6 +144,9 @@ class Include(Directive):
             return [literal_block]
         if 'code' in self.options:
             self.options['source'] = path
+            # Convert tabs to spaces, if `tab_width` is negative.
+            if tab_width < 0:
+                include_lines = rawtext.splitlines()
             codeblock = CodeBlock(self.name,
                                   [self.options.pop('code')], # arguments
                                   self.options,


LaTeX ignores leading whitespace, so the following is a workaround to
get a visible representation of literal tabs in LaTeX-generated PDF (there
is no easy way to achieve preservation of TAB characters in drag and drop
from the PDF, though).

diff --git a/trunk/docutils/docutils/writers/latex2e/__init__.py b/trunk/docutils/docutils/writers/latex2e/__init__.py
index 0463e3504..fafab2c34 100644
--- a/trunk/docutils/docutils/writers/latex2e/__init__.py
+++ b/trunk/docutils/docutils/writers/latex2e/__init__.py
@@ -1516,6 +1516,10 @@ class LaTeXTranslator(nodes.NodeVisitor):
                 table[ord('>')] = ur'\textgreater{}'
         if self.insert_non_breaking_blanks:
             table[ord(' ')] = ur'~'
+            # tab chars may occur in included files (literal or code)
+            # quick-and-dirty replacement with spaces
+            # (for better results use `--literal-block-env=lstlisting`)
+            table[ord('\t')] = u'~' * self.settings.tab_width
         # Unicode replacements for 8-bit tex engines (not required with XeTeX/LuaTeX):
         if not self.is_xetex:
             if not self.latex_encoding.startswith('utf8'):

sincerely,

Günter