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

Re: [Docutils-users] Role for different human language?

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

Ahoj Matěj,

On 2020-02-23, Matěj Cepl wrote:
> On 2020-02-23, 16:23 GMT, Guenter Milde via Docutils-users wrote:
>> There is a method for defining the language of text parts: The 
>> HTML and LaTeX writers convert a "class" argument starting 
>> with ``language-`` in a language argument with the remainder,

> It really works for HTML5 and LaTeX, but unfortunately it 
> doesn’t for ODT.

This is a convention used in the HTML and LaTeX writers (the two I
regularely work with and on).

...

> I was trying a bug for this at 
> https://sourceforge.net/p/docutils/bugs, but I couldn’t find 
> anything. And I know, unsupported magical feature means it is 
> unsupported, but still it would be lovely to have the ODT 
> generator following the suite. Do you know whether there is such 
> bug?

I don't think it is a *bug*: The documentation says that class arguments
may be ignored by some writers.

I recommend filing an `enhancement request`__.

Thanks,
Günter

__ https://sourceforge.net/p/docutils/feature-requests/66/

[Docutils-users] HTML5 Translator footnote brackets missing

[Jan 'o. G. <1o...@gm...>]

Hello,
I've been playing around with a html5 translator for my pelican page and I
noticed that html5 translator
(docutils.writers.html5_polyglot.HTMLTranslator) is missing override
of visit_footnote_reference which adds brackets around the numbers like
this "Note [1]".
This looks like a major change (maybe not intentional) but I could not find
any reference in issues/bug or docs.

So I have a few questions:
1) What is the reason for dropping the brackets? (Bug or feature)
2) Would you recommend to use html5 translator or not yet?
3) Are there any plans or would devs consider a change or docs website
style - it's really difficult to navigate and especially hard to read for
people with dyslexia (me)?

Thank you
----
Jan

[Docutils-users] FileNotFoundError: [Errno 2] No such file or directory: '/usr/local/lib/python3.8/site-packages/html5css3/thirdparty/revealjs/css/theme/league.css'

[Patrick L. <pat...@gm...>]

*COMMAND:* rst2html5 --jquery --reveal-js --pretty-print-code --traceback
fortune.rst >deck1.html && o deck1.html

*Traceback* (most recent call last):
  File "/usr/local/bin/rst2html5", line 11, in <module>
    load_entry_point('rst2html5-tools==0.5.3', 'console_scripts',
'rst2html5')()
  File "/usr/local/lib/python3.8/site-packages/html5css3/main.py", line 32,
in main
    publish_cmdline(writer_name='html5', writer=html5css3.Writer(),
  File "/home/patrick/.local/lib/python3.8/site-packages/docutils/core.py",
line 353, in publish_cmdline
    output = pub.publish(
  File "/home/patrick/.local/lib/python3.8/site-packages/docutils/core.py",
line 220, in publish
    output = self.writer.write(self.document, self.destination)
  File
"/home/patrick/.local/lib/python3.8/site-packages/docutils/writers/__init__.py",
line 78, in write
    self.translate()
  File "/usr/local/lib/python3.8/site-packages/html5css3/__init__.py", line
257, in translate
    processor(tree, embed, params)
  File
"/usr/local/lib/python3.8/site-packages/html5css3/postprocessors.py", line
156, in revealjs
    head.append(css(theme_path, embed))
  File
"/usr/local/lib/python3.8/site-packages/html5css3/postprocessors.py", line
48, in css
    content = read_file(abspath(path))
  File
"/usr/local/lib/python3.8/site-packages/html5css3/postprocessors.py", line
21, in read_file
    return open(path).read()
FileNotFoundError: [Errno 2] No such file or directory:
'/usr/local/lib/python3.8/site-packages/html5css3/thirdparty/revealjs/css/theme/league.css'


*Docutils version (0.16 [release]),Python version (3.8.1)*
*Ubuntu Linux 18.04.3*

Re: [Docutils-users] Role for different human language?

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

On 2020-02-23, 16:23 GMT, Guenter Milde via Docutils-users wrote:
> There is a method for defining the language of text parts: The 
> HTML and LaTeX writers convert a "class" argument starting 
> with ``language-`` in a language argument with the remainder, 

Wow! Thank you. We have even undocumented functions in docutils! 
Kewl!

Thank you,

Matěj Cepl
-- 
https://matej.ceplovi.cz/blog/, Jabber: mc...@ce...
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
One reason that life is complex is that it has a real part and an
imaginary part.
    -- Andrew König

Re: [Docutils-users] Role for different human language?

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

On 2020-02-23, 16:23 GMT, Guenter Milde via Docutils-users wrote:
> There is a method for defining the language of text parts: The 
> HTML and LaTeX writers convert a "class" argument starting 
> with ``language-`` in a language argument with the remainder,

It really works for HTML5 and LaTeX, but unfortunately it 
doesn’t for ODT.

So, this rST:

    In the end both options happened. Uncle Harry in secret 
    asked the French :language-fr:`Bureau des Aurors` to sent 
    somebody to start the investigation,

gives me this lovely HTML:

    <p>In the end both options happened. Uncle Harry in secret 
    asked the French <span lang="fr">Bureau des Aurors</span> to 
    sent somebody to start the investigation,</p>

and this LaTeX (and the generator even managed to translate “ft” 
-> “french”):

    In the end both options happened. Uncle Harry in secret 
    asked the French \foreignlanguage{french}{Bureau des Aurors} 
    to sent somebody to start the investigation,

but ODT generator doesn’t catch this trick and creates a new 
empty style (which actually is not visible in the style tools in 
OOWriter):

    <text:p text:style-name="rststyle-textbody">In the end both 
    options happened. Uncle Harry in secret asked the French 
    <text:span text:style-name="rststyle-language-fr">Bureau des 
    Aurors</text:span>to sent somebody to start the 
    investigation,</text:p>

I was trying a bug for this at 
https://sourceforge.net/p/docutils/bugs, but I couldn’t find 
anything. And I know, unsupported magical feature means it is 
unsupported, but still it would be lovely to have the ODT 
generator following the suite. Do you know whether there is such 
bug?

Best,

Matěj
-- 
https://matej.ceplovi.cz/blog/, Jabber: mc...@ce...
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
Roses are red;
    Violets are blue.
I'm schizophrenic,
    And so am I.

Re: [Docutils-users] Role for different human language?

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

On 2020-02-22, Matěj Cepl wrote:
> I am looking for some markup which say that the phrase in the 
> text is of different human language. E.g., I have this paragraph 
> (written in otherwise English story):

>     In the end both options happened. Uncle Harry in secret 
>     asked the French Bureau des Aurors to sent somebody to start 
>     the investigation, and so I spent two afternoons in small 
>     café near my University with the French lady, who asked me 
>     very thoroughly about my story.

> Now, I would like to mark the term “Bureau des Aurors” so that 
> screen reader or other software know that it is not English and 
> behave accordingly. Is there a standard way how to do it? Yes, 
> I understand I can define my own custom role for it (translating 
> to ``<span lang="fr_FR">``), but isn’t there a standard role?

There is a method for defining the language of text parts: The HTML and
LaTeX writers convert a "class" argument starting with ``language-`` in a
language argument with the remainder, e.g.
::

  .. role:: language-de

  Let's count in German :language-de:`eins zwei drei`.

becomes in HTML::

  Let's count in German <span lang="de">eins zwei drei</span>.

and in LaTeX::

  Let’s count in German \foreignlanguage{ngerman}{eins zwei drei}.
  

For block-level elements, you can use the ``.. class::`` directive or
the :class: directive option.

See:
https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/test/functional/input/data/custom_roles.txt
https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/test/functional/expected/standalone_rst_html5.html#l1221
https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/test/functional/expected/standalone_rst_latex.tex#l1766

(Also, have a look for "Die Trichter" in these documents to see an example
to define a block's language.)

Hope this helps,

Günter

Re: [Docutils-users] Why smart quotes by default ?

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

On 2019-12-21, 04:09 GMT, Wes Hurd wrote:
> documentation cannot be expected to put all code
> snippets in code blocks.

This is the point where I disagree. That is exactly what is 
expected.

Matěj
-- 
https://matej.ceplovi.cz/blog/, Jabber: mc...@ce...
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
kakistocracy, n.: Government by the least qualified or most
unprincipled citizens.
  -- first used by Thomas Love Peacock in 1829

[Docutils-users] Role for different human language?

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

I am looking for some markup which say that the phrase in the 
text is of different human language. E.g., I have this paragraph 
(written in otherwise English story):

    In the end both options happened. Uncle Harry in secret 
    asked the French Bureau des Aurors to sent somebody to start 
    the investigation, and so I spent two afternoons in small 
    café near my University with the French lady, who asked me 
    very thoroughly about my story.

Now, I would like to mark the term “Bureau des Aurors” so that 
screen reader or other software know that it is not English and 
behave accordingly. Is there a standard way how to do it? Yes, 
I understand I can define my own custom role for it (translating 
to ``<span lang="fr_FR">``), but isn’t there a standard role?

Thank you for any ideas,

Matěj
-- 
https://matej.ceplovi.cz/blog/, Jabber: mc...@ce...
GPG Finger: 3C76 A027 CA45 AD70 98B5  BC1D 7920 5802 880B C9D8
 
This is a test of the emergency signature system. Were this an
actual signature, you would see amusing mottos, disclaimers,
a zillion net addresses, or edifying philosophical statements.
this is only test.

Re: [Docutils-users] Multi-line classifiers in definition lists

[Antony L. <ann...@gm...>]

No, but thanks for pointing to it.
Antony

On Fri, Feb 7, 2020 at 5:45 PM Guenter Milde via Docutils-users <
doc...@li...> wrote:

> On 2020-02-06, Antony Lee wrote:
>
> > Thanks for providing a nice list of test cases; I'll work on them.
>
> This is good news.
>
> Are you aware of the `Docutils test suite`__?
> I did not include examples of every test failure there in my test document.
>
> __ https://docutils.sourceforge.io/docs/dev/testing.html
>
>
> Günter
>
>
>
> _______________________________________________
> 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] Multi-line classifiers in definition lists

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

On 2020-02-06, Antony Lee wrote:

> Thanks for providing a nice list of test cases; I'll work on them.

This is good news.

Are you aware of the `Docutils test suite`__?
I did not include examples of every test failure there in my test document.

__ https://docutils.sourceforge.io/docs/dev/testing.html


Günter

Re: [Docutils-users] Multi-line classifiers in definition lists

[Antony L. <ant...@in...>]

Thanks for providing a nice list of test cases; I'll work on them.
Antony

On Fri, Feb 7, 2020 at 1:41 PM Guenter Milde via Docutils-users <
doc...@li...> wrote:

> On 2019-12-11, Antony Lee wrote:
>
> > Hi,
> > Sorry re-raising an old thread, but I had a quick revisit at this
> again...
> > As a reminder, this was about adding backslash-escaped line
> continuations,
> > so that one could write
>
> > term : info more info \
>
> >        and more info
>
> >     the definition
>
>
> > the idea being that numpydoc docstrings (by far the most widely used
> > docstring convention in the scientific python ecosystem) would benefit
> from
> > it.
>
> I like the idea but want it to be general: also long section headings,
> say, may benefit from this.
>
> > As it turns out the patch to achieve this is relatively simple:
>
> > diff --git i/docutils/docutils/statemachine.py
> > w/docutils/docutils/statemachine.py
> > index ec5351887..70aa9baea 100644
> > --- i/docutils/docutils/statemachine.py
> > +++ w/docutils/docutils/statemachine.py
> > @@ -311,6 +311,13 @@ class StateMachine(object):
> >             except IndexError:
> >                 self.line = None
> >                 raise EOFError
> > +            while self.line.endswith("\\"):
> > +                try:
> > +                    self.line_offset += 1
> > +                    self.line +=
> > self.input_lines[self.line_offset].lstrip()
> > +                except IndexError:
> > +                    self.line = None
> > +                    raise EOFError
> >             return self.line
> >         finally:
> >             self.notify_observers()
>
>
> > i.e. joining the backslash-escaped lines relatively early in the process.
>
> Unfortunately, this breaks our test suite and shows nasty side-effects in a
> small dedicated test file.
>
> > Please let me know the best way to proceed forward.
>
> We would need to sort out the problems and side-effects,
> test properly,
> document,
> and then implement it in the development version.
>
> Thanks for the proposal and remainder,
>
> Günter
>
>
> Test backslash escaping of line ends
> ------------------------------------
>
> There are side effects, the test suite fails.
>
> Lets have a closer look:
>
> Section headings
> ----------------
>
> Breaking long section headings fails:
>
> long and broken section heading\
> !
> -----------------------------------
>
> long section heading with broken underline
> -------------------------------\
> -------------------
>
>
> Paragraphs
> ----------
>
> This is a paragraph. \
> It's quite short.
>
> The text of all lines should be there,
> even if a line end is
> escaped with a backslash \
> somewhere in the middle.
>
> The second line of this paragraph
> contains an escaped line break \
> and is missing in the output!!
>
> Lists
> -----
>
> definition lists
> ````````````````
>
> using a backslash \
> escape
>     you can break the definition line
>
> escaping line ends: works in the \
>                  additional explanations
>     too.
>
> definition term
>    and definition with backslash \
>    escape. Again a line missing!!
>
> field lists
> ```````````
>
> :the field \
>  name:
>    and the content
>
> :a long and broken \
>  field name: start of content missing if placed on same line!!
>
> :field name: and broken \
>    content
>
> literal text
> --------------
>
> An example::
>
>       Whitespace, newlines, blank lines,
>         and all kinds of markup \
>       must be  preserved by literal blocks.
>
> Also ``inline \
> literals`` must keep the backslash and the escaped character!
>
>
>
> _______________________________________________
> 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] Multi-line classifiers in definition lists

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

On 2019-12-11, Antony Lee wrote:

> Hi,
> Sorry re-raising an old thread, but I had a quick revisit at this again...
> As a reminder, this was about adding backslash-escaped line continuations,
> so that one could write

> term : info more info \

>        and more info

>     the definition


> the idea being that numpydoc docstrings (by far the most widely used
> docstring convention in the scientific python ecosystem) would benefit from
> it.

I like the idea but want it to be general: also long section headings,
say, may benefit from this.

> As it turns out the patch to achieve this is relatively simple:

> diff --git i/docutils/docutils/statemachine.py
> w/docutils/docutils/statemachine.py
> index ec5351887..70aa9baea 100644
> --- i/docutils/docutils/statemachine.py
> +++ w/docutils/docutils/statemachine.py
> @@ -311,6 +311,13 @@ class StateMachine(object):
>             except IndexError:
>                 self.line = None
>                 raise EOFError
> +            while self.line.endswith("\\"):
> +                try:
> +                    self.line_offset += 1
> +                    self.line +=
> self.input_lines[self.line_offset].lstrip()
> +                except IndexError:
> +                    self.line = None
> +                    raise EOFError
>             return self.line
>         finally:
>             self.notify_observers()


> i.e. joining the backslash-escaped lines relatively early in the process.

Unfortunately, this breaks our test suite and shows nasty side-effects in a
small dedicated test file.

> Please let me know the best way to proceed forward.

We would need to sort out the problems and side-effects,
test properly,
document,
and then implement it in the development version.

Thanks for the proposal and remainder,

Günter


Test backslash escaping of line ends
------------------------------------

There are side effects, the test suite fails.

Lets have a closer look:

Section headings
----------------

Breaking long section headings fails:

long and broken section heading\
!
-----------------------------------

long section heading with broken underline
-------------------------------\
-------------------


Paragraphs
----------

This is a paragraph. \
It's quite short.

The text of all lines should be there,
even if a line end is
escaped with a backslash \
somewhere in the middle.

The second line of this paragraph
contains an escaped line break \
and is missing in the output!!

Lists
-----

definition lists
````````````````

using a backslash \
escape
    you can break the definition line

escaping line ends: works in the \
                 additional explanations
    too.

definition term
   and definition with backslash \
   escape. Again a line missing!!

field lists
```````````

:the field \
 name:
   and the content

:a long and broken \
 field name: start of content missing if placed on same line!!
 
:field name: and broken \
   content

literal text
--------------

An example::

      Whitespace, newlines, blank lines, 
        and all kinds of markup \
      must be  preserved by literal blocks.

Also ``inline \
literals`` must keep the backslash and the escaped character!

Re: [Docutils-users] docutils release 0.16

[engelbert g. <eng...@gm...>]

welcome

On Sun, 12 Jan 2020 at 17:46, David Goodger <go...@py...> wrote:

> Thank you for the release!
>
> David Goodger
> <https://david.goodger.org>
>
>
> On Sun, Jan 12, 2020 at 9:25 AM engelbert gruber <
> eng...@gm...> wrote:
>
>> Release 0.16 is out on pypi
>>
>> .. Note::
>>
>>    Docutils 0.15.x is the last version supporting Python 2.6, 3.3 and 3.4.
>>
>>    Docutils 0.16.x supports Python 2.7 and Python >= 3.5 natively,
>>    without the use of the ``2to3`` tool.
>>
>> * reStructuredText:
>>
>>   - Keep `backslash escapes`__ in the document tree. This allows, e.g.,
>>     escaping of author-separators in `bibliographic fields`__.
>>
>>   __
>> http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#escaping-mechanism
>>   __ docs/ref/rst/restructuredtext.html#bibliographic-fields
>>
>> * LaTeX writer:
>>
>>   - Informal titles of type "rubric" default to bold-italic and left
>> aligned.
>>   - Deprecate ``\docutilsrole`` prefix for styling commands:
>>     use ``\DUrole`` instead.
>>   - Fix topic subtitle.
>>   - Add "latex writers" to the `config_section_dependencies`.
>>   - Ignore classes for `rubric` elements
>>     (class wrapper interferes with LaTeX formatting).
>>
>> * tools/buildhtml.py
>>
>>   - New option "--html-writer" allows to select "html__" (default),
>>     "html4" or "html5".
>>
>>   __ html: docs/user/html.html#html
>>
>> * docutils/io.py
>>
>>   - Remove the `handle_io_errors` option from io.FileInput/Output.
>>
>> * docutils/nodes.py
>>
>>   - If `auto_id_prefix`_ ends with "%", this is replaced with the tag
>> name.
>>
>>   .. _auto_id_prefix: docs/user/config.html#auto-id-prefix
>>
>> * Various bugfixes and improvements (see HISTORY_).
>>
>>
>> _______________________________________________
>> 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] docutils release 0.16

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

Thank you for the release!

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


On Sun, Jan 12, 2020 at 9:25 AM engelbert gruber <eng...@gm...>
wrote:

> Release 0.16 is out on pypi
>
> .. Note::
>
>    Docutils 0.15.x is the last version supporting Python 2.6, 3.3 and 3.4.
>
>    Docutils 0.16.x supports Python 2.7 and Python >= 3.5 natively,
>    without the use of the ``2to3`` tool.
>
> * reStructuredText:
>
>   - Keep `backslash escapes`__ in the document tree. This allows, e.g.,
>     escaping of author-separators in `bibliographic fields`__.
>
>   __
> http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#escaping-mechanism
>   __ docs/ref/rst/restructuredtext.html#bibliographic-fields
>
> * LaTeX writer:
>
>   - Informal titles of type "rubric" default to bold-italic and left
> aligned.
>   - Deprecate ``\docutilsrole`` prefix for styling commands:
>     use ``\DUrole`` instead.
>   - Fix topic subtitle.
>   - Add "latex writers" to the `config_section_dependencies`.
>   - Ignore classes for `rubric` elements
>     (class wrapper interferes with LaTeX formatting).
>
> * tools/buildhtml.py
>
>   - New option "--html-writer" allows to select "html__" (default),
>     "html4" or "html5".
>
>   __ html: docs/user/html.html#html
>
> * docutils/io.py
>
>   - Remove the `handle_io_errors` option from io.FileInput/Output.
>
> * docutils/nodes.py
>
>   - If `auto_id_prefix`_ ends with "%", this is replaced with the tag name.
>
>   .. _auto_id_prefix: docs/user/config.html#auto-id-prefix
>
> * Various bugfixes and improvements (see HISTORY_).
>
>
> _______________________________________________
> 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] docutils release 0.16

[engelbert g. <eng...@gm...>]

Release 0.16 is out on pypi

.. Note::

   Docutils 0.15.x is the last version supporting Python 2.6, 3.3 and 3.4.

   Docutils 0.16.x supports Python 2.7 and Python >= 3.5 natively,
   without the use of the ``2to3`` tool.

* reStructuredText:

  - Keep `backslash escapes`__ in the document tree. This allows, e.g.,
    escaping of author-separators in `bibliographic fields`__.

  __
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#escaping-mechanism
  __ docs/ref/rst/restructuredtext.html#bibliographic-fields

* LaTeX writer:

  - Informal titles of type "rubric" default to bold-italic and left
aligned.
  - Deprecate ``\docutilsrole`` prefix for styling commands:
    use ``\DUrole`` instead.
  - Fix topic subtitle.
  - Add "latex writers" to the `config_section_dependencies`.
  - Ignore classes for `rubric` elements
    (class wrapper interferes with LaTeX formatting).

* tools/buildhtml.py

  - New option "--html-writer" allows to select "html__" (default),
    "html4" or "html5".

  __ html: docs/user/html.html#html

* docutils/io.py

  - Remove the `handle_io_errors` option from io.FileInput/Output.

* docutils/nodes.py

  - If `auto_id_prefix`_ ends with "%", this is replaced with the tag name.

  .. _auto_id_prefix: docs/user/config.html#auto-id-prefix

* Various bugfixes and improvements (see HISTORY_).

Re: [Docutils-users] Why smart quotes by default ?

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

On 2019-12-21, Wes Hurd wrote:

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

> Hi,

> Just out of curiosity, why does docutils use smart quotes by default ?

Actually, in Docutils smartquotes__ is an opt-in.

Maybe you mixed up Docutils and Sphinx or anothere add-on?

__ https://docutils.sourceforge.io/docs/user/config.html#smart-quotes

> Any programmer should know code and smart quotes don't mix (when they
> experience it), 

True.

> and documentation cannot be expected to put all code snippets in code
> blocks.

Here, opinions differ.

> Why create potential usability issues with smart quotes ?
> e.g. https://github.com/readthedocs/readthedocs.org/issues/6459

> IMO, the sane default would be to *not* use smart quotes.

Agreed. Therefore this is what Docutils does and recommends__ ...

__ file:///usr/local/src/docutils-git-svn/docutils/docs/user/smartquotes.html#why-you-might-not-want-to-use-smart-quotes-in-your-documents


Günter

[Docutils-users] Why smart quotes by default ?

[Wes H. <13...@gm...>]

Hi,

Just out of curiosity, why does docutils use smart quotes by default ?
Any programmer should know code and smart quotes don't mix (when they
experience it), and documentation cannot be expected to put all code
snippets in code blocks.

Why create potential usability issues with smart quotes ?
e.g. https://github.com/readthedocs/readthedocs.org/issues/6459

IMO, the sane default would be to *not* use smart quotes.

Cheers,

[Docutils-users] release 0.16rc1 out.

[engelbert g. <eng...@gm...>]

hei

pypi has docutils 0.16rc1 now

this can be installed with ::

  pip install --no-deps --pre docutils

repository is changed to 0.16rc2, waiting for bug fixes

release 0.16 in 2 to 4 weeks

cheers

Re: [Docutils-users] LaTeX bibliography option missing?

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

On 2019-12-16, Alan G. Isaac wrote:
> I'm needing the LaTeX writer for the first time in quite a while, and
> I may have forgotten some details.  I am using the useful option::

> 	--use-bibtex=mybst,mybib

Mind, that this option is neither documented nor tested.

> But unless I provide targets for all the citation references,
> I do not get citation references in the text.  Instead the citation
> references marked as errors. Since I provide the citation
> info in ``mybib``, this seems completely pointless; can it be turned off?

I can confirm the problem. Could you file a bug report, please?

Günter

[Docutils-users] LaTeX bibliography option missing?

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

I'm needing the LaTeX writer for the first time in quite a while, and
I may have forgotten some details.  I am using the useful option::

	--use-bibtex=mybst,mybib

But unless I provide targets for all the citation references,
I do not get citation references in the text.  Instead the citation
references marked as errors. Since I provide the citation
info in ``mybib``, this seems completely pointless; can it be turned off?

Alan Isaac

PS I was also reminded how grateful I am to be able to use the
``listlisting`` environment and not have it wrapped in a ``quote``
environment.  Even though this has been true for a while, I again
say thanks!

Re: [Docutils-users] Multi-line classifiers in definition lists

[Antony L. <ant...@be...>]

Hi,
Sorry re-raising an old thread, but I had a quick revisit at this again...
As a reminder, this was about adding backslash-escaped line continuations,
so that one could write

term : info more info \

       and more info

    the definition


the idea being that numpydoc docstrings (by far the most widely used
docstring convention in the scientific python ecosystem) would benefit from
it.
As it turns out the patch to achieve this is relatively simple:

diff --git i/docutils/docutils/statemachine.py
w/docutils/docutils/statemachine.py
index ec5351887..70aa9baea 100644
--- i/docutils/docutils/statemachine.py
+++ w/docutils/docutils/statemachine.py
@@ -311,6 +311,13 @@ class StateMachine(object):
            except IndexError:
                self.line = None
                raise EOFError
+            while self.line.endswith("\\"):
+                try:
+                    self.line_offset += 1
+                    self.line +=
self.input_lines[self.line_offset].lstrip()
+                except IndexError:
+                    self.line = None
+                    raise EOFError
            return self.line
        finally:
            self.notify_observers()


i.e. joining the backslash-escaped lines relatively early in the process.
Please let me know the best way to proceed forward.

Cheers,
Antony

On Mon, Oct 9, 2017 at 5:21 AM David Goodger <go...@py...> wrote:

> Oops, I meant to reply-all:
>
> On Oct 7, 2017 10:48 PM, "David Goodger" <dgo...@gm...> wrote:
>
> I like the idea of backslash-escape line continuations at the reST level.
> It's a general purpose change that could help in other areas too. It might
> have side effects though.
>
> Can't work on it right now: on vacation, cycle touring. I'll take a look
> when I get back in a week or so.
>
> David Goodger
>
>
> On Oct 4, 2017 1:37 PM, "Antony Lee" <ant...@be...> wrote:
>
> Hi all,
>
> Currently, RST specifies that entries in a definition list may be followed
> by a series of classifiers all on the same line, as in
>
>     term : classifier one : classifier 2
>         Definition
>
> This syntax is used by numpydoc (the de facto docstring standard in the
> scientific Python world) to document individual parameters of callables, as
> in
>
>     parameter_name : type_of_parameter
>         Description of the parameter.
>
> (see
> https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt#sections
> for details).
>
> In general, this approach yields highly legible raw docstrings, and can
> easily be converted into the Sphinx standard field list format (tools to do
> so include numpydoc and sphinx.ext.napoleon).
>
> However, it is awkward to include very long parameter "types" (e.g., an
> enumeration of allowable string values -- which I know is not strictly a
> type, but remains a common API) using this method, due to the restriction
> that the classifiers need to stay in one line.  In practice, this means
> that it is necessary to use a line continuation in the docstring, either
>
>     parameter_name : some long type \
> description
>         Description of parameter.
>
> or
>
>     parameter_name : some long type \
>                      description
>         Description of the parameter.
>
> The first form is ugly in the source, the second form is ugly when the
> docstring is viewed as a string (e.g. by pydoc) as all the spaces before
> ``description`` end up in the literal docstring.  See e.g.
> https://github.com/numpy/numpydoc/issues/87 for a longer discussion of
> the issue.
>
> While numpydoc can of course invent its own syntax, it would seem
> preferable if a standard way to write multi-line classifiers was specified
> by the RST standard.  Just checking for indentation is actually a bit
> ambiguous, because it is not clear how to parse
>
>     a : b
>         c
>
> (is ``c`` a continuation or a description?).  A possibility would be to
> support backslashed-line continuations at the RST level, so the Python
> docstring would look like
>
>     parameter_name : some long type \\
>                      description
>         Description of the parameter
>
> but RST would see a single backslash and know what to do; or require that
> continued classifier lines start also with ``: ``:
>
>     parameter_name : some long type
>                    : description
>         Description of the parameter
>
> Neither option is strictly fully back-compatible, but I hope one of them,
> or some similar solution, can be adopted.
>
> Antony Lee
>
> PS: As suggested on the docutils mailing list page, I am not subscribed to
> the list, so please CC me in the reply.  Thanks!
>
>
> ------------------------------------------------------------------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> _______________________________________________
> 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] docutils 0.16b0.dev0 released

[engelbert g. <eng...@gm...>]

This is a beta/release candidate for 0.16
it can be installed with ::

  pip install --pre docutils

Release Notes:

* General:

  - Dropped support for Python 2.6, 3.3 and 3.4
  - Docutils now supports Python 2.7 and Python 3.5+ natively,
    without the use of the ``2to3`` tool.

* reStructuredText:

  - Keep `backslash escapes`__ in the document tree. This allows, e.g.,
    escaping of author-separators in `bibliographic fields`__.

  __
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#escaping-mechanism
  __ docs/ref/rst/restructuredtext.html#bibliographic-fields

* LaTeX writer:

  - Informal titles of type "rubric" default to bold-italic and left
aligned.
  - Deprecate ``\docutilsrole`` prefix for styling commands:
    use ``\DUrole`` instead.
  - Fix topic subtitle.
  - Add "latex writers" to the `config_section_dependencies`.
  - Ignore classes for `rubric` elements
    (class wrapper interferes with LaTeX formatting).

* docutils/writers/manpage.py

  - Apply fix for [ 287 ] comma after option is bold.
  - Apply fix for [ 289 ], line starting with ``.`` in a text.

* docutils/writers/odf_odt/__init__.py:

  - Fix: ElementTree.getchildren deprecated warning

* tools/buildhtml.py

  - New option "--html-writer" allows to select "html__" (default),
    "html4" or "html5".

  __ html: docs/user/html.html#html

and some cleanup and speedup (by eric89gxl)

final release depending on feedback and free time

all the best

Re: [Docutils-users] GitHub & CSS Docs

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

On 2019-11-13, Jan 'oglop' Gazda wrote:

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

> Hello everyone,

> I noticed there are more and more requests in moving the project over to
> GitHub, may I know why are you not considering moving over?

The reasoning is unchanged: don't change a running system unless there is a
compelling reason to do so.

Switching to git as master repository format has advantages that may be
worth the effort (if done right), moving to another host does not seem so.


> Another question is about the documentation.
> I love RST especially due to it's style versatility and I think that
> docutils and Sphinx were the best inventions after python.
> But I suffer from dyslexia and current docs format makes it very difficult
> to read for me.

Can you elaborate? Is it about fonts, sizes or structure?

> It would much better to use Sphinx or some CSS which makes it easier to
> read.

> During my research I noticed several docutils forks around the internet
> (github) doing exactly the same thing I did (fork the docutils and process
> docs with sphinx)

> Here is an example of how does it look in my development flow with PyCharm.

> https://github.com/1oglop1/share/blob/master/README.rst

> Moving towards a better graphical style of docs would enhance the
> readability and prevented a repetitive work.

> Are there any obstacles preventing docutils from moving forward to this?

The idea is to have our documentation as a showcase of "pure" Docutils.

If limited CSS changes could help with readability, we may consider them.
OTOH, the CSS is deliberately "minimalistic".

You may also try to compile the docs with the "html5" writer.

Günter

[Docutils-users] GitHub & CSS Docs

[Jan 'o. G. <1o...@gm...>]

Hello everyone,

I noticed there are more and more requests in moving the project over to
GitHub, may I know why are you not considering moving over?

Another question is about the documentation.
I love RST especially due to it's style versatility and I think that
docutils and Sphinx were the best inventions after python.
But I suffer from dyslexia and current docs format makes it very difficult
to read for me.
It would much better to use Sphinx or some CSS which makes it easier to
read.

During my research I noticed several docutils forks around the internet
(github) doing exactly the same thing I did (fork the docutils and process
docs with sphinx)

Here is an example of how does it look in my development flow with PyCharm.

https://github.com/1oglop1/share/blob/master/README.rst

Moving towards a better graphical style of docs would enhance the
readability and prevented a repetitive work.

Are there any obstacles preventing docutils from moving forward to this?



Thank you.
Jan Gazda

Re: [Docutils-users] rst2latex and (un)numbered sections

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

On 2019-11-09, Martin Koutecký wrote:

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

> In LaTeX, one may write \section{...} for a numbered section and
> \section*{...} for an unnumbered section. This seems impossible with rST.
> Is this correct?

> I have a large document which I'm translating into LaTeX using rst2latex
> and (because of specific styling needs) I would like to have both numbered
> and unnumbered sections. Does anyone know a hack to do this?

How about something like the appended?

Günter


.. sectnum:: 

Section
=======

for an unnumbered section, use one of the "aside" objects, e.g.:

.. rubric:: A Rubric

The “rubric” directive inserts a “rubric_” element into the document tree. A
rubric is like an informal heading that doesn’t correspond to the
document’s structure.

.. _rubric: http://docutils.sourceforge.net/docs/user/latex.html#rubric


.. topic:: A Topic

  A topic_ is like a block quote with a title, or a self-contained section
  with no subsections.
  
.. _topic: http://docutils.sourceforge.net/docs/user/latex.html#topic-element


.. sidebar:: A Sidebar

  Sidebars_ are like miniature, parallel documents that occur inside other
  documents, providing related or reference material. 

.. _sidebars: http://docutils.sourceforge.net/docs/user/latex.html#sidebar


See also http://docutils.sourceforge.net/docs/ref/rst/directives.html


Styling
=======

All of these objects can by styled to look like a "normal" unnumbered
section of any level by re-defining the ``\DU...`` LaTeX commands in the
preamble or stylesheet.

Example styling (in style-sheet or latex-preamble_)::

  % rubrics as unnumbered section headings
  \newcommand{\DUrubric}[1]{\subsection*{#1}}%
  \newcommand{\DUsidebar}{}
  \newcommand{\DUtitletopic}[1]{\subsection*{#1}}
  \newcommand{\DUCLASStopic}{\renewenvironment{quote}{}{}}
  \newcommand{\DUtitlesidebar}[1]{\subsubsection*{#1}}

.. _latex-preamble:
   http://docutils.sourceforge.net/docs/user/latex.html#latex-preamble