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

[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

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

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

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?

I wanted to implement the following: for a normal section, just write

Section
=======

but for an unnumbered section, write

STARRED Section
===================

and then in LaTeX redefine the \section command with ifthen to give
\section*{Section} (gobble "STARRED ") if the title begun with the special
string and to give \section{Section} if it did not start with that special
string. But this also seems quite hard to do.

Happy to hear your advice,
Martin

Re: [Docutils-users] replacement directive and formatting tables (in vim)

[Saša J. <sja...@gm...>]

On Tue, 5 Nov 2019 16:33:30 -0600
David Goodger <go...@py...> wrote:

> I use it on my personal machine (Ubuntu Linux, where it's an input
> system configuration option) and at work (Windows, via WinCompose). I
> can easily type any àçċéñţëđ characters, and I can add custom compose
> key combinations for any Unicode characters I like, e.g.
> ◀▶⇒∞Σ♡∀×✖★∅⚠⎄ (all typed with my standard keyboard, e.g.
> [compose]+[=]+[>] gives ⇒). It works with any software.

Yeah, I'm using GNOME and it would work, but not sure how it
practical it would be when I've > 20 symbols which I regularly have
to use...


Sincerely,
Gour

-- 
As a blazing fire turns firewood to ashes, O Arjuna, so does the
fire of knowledge burn to ashes all reactions to material activities.

Re: [Docutils-users] replacement directive and formatting tables (in vim)

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

Another option is direct Unicode text entry via the Compose Key system:
https://en.wikipedia.org/wiki/Compose_key

I use it on my personal machine (Ubuntu Linux, where it's an input system
configuration option) and at work (Windows, via WinCompose). I can easily
type any àçċéñţëđ characters, and I can add custom compose key combinations
for any Unicode characters I like, e.g. ◀▶⇒∞Σ♡∀×✖★∅⚠⎄ (all typed with my
standard keyboard, e.g. [compose]+[=]+[>] gives ⇒). It works with any
software.

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


On Tue, 5 Nov 2019 at 05:57, Saša Janiška <sja...@gm...> wrote:

> On Mon, 4 Nov 2019 10:58:43 -0000 (UTC)
> Guenter Milde via Docutils-users <doc...@li...>
> wrote:
>
> > Unfortunately, there is no simple way to use a different syntax for
> > replacements.
>
> OK.
>
> > You may use `simple tables`__ without |, but maybe these cannot be
> > formatted by your editor.
>
> Correct.
>
> > You could also try to teach the table formatter the difference
> > between a table column separator (with whitespace around, regexp "(^|
> > )[|]( |$)") and the replacement syntax (no inner whitespace).
>
> Yeah, that is one possibility.
>
> > Finally, it may be simpler to use the Unicode characters directly via
> > drag-and drop
>
> Well, I use many symbols...
>
> > or group-replacing a placeholder in the editor.
>
> ..will think about it.
>
> Thank you for your input.
>
>
> Sincerely,
> Saša
>
> --
> The working senses are superior to dull matter; mind is higher
> than the senses; intelligence is still higher than the mind;
> and he [the soul] is even higher than the intelligence.
>
>
>
>
> _______________________________________________
> 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] reStructuredText and Localization of Documents, Scaling to Lots of Content, Managed Over Time

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

On 2019-10-31, Kent Borg wrote:
> I am wondering about tools and techniques to help manage translating and 
> localizing documents. Particularly when scaled up and used over time.

Did you have a look at the translating extension for Sphinx?
(I know it exists, but don't know a URL or details.)

> Some considerations:

> - Say a commercial service produces a translated rST document, how might 
> we easily know that it is structurally the same (that the RST didn't 
> accidentally get edited)?

It would be possible code a transform that strips all Text
nodes when exporting. Alternatively, you may use XSLT processing of the
Docutils XML output...

But you may also think about different order of marked-up words or links due
to different grammatical rules in the respective languages...


> - As documents change over time, sometimes there will only be small 
> changes. We don't want to waste time and money redoing the entire 
> document, but the translator should be able to see the whole document, 
> to see the context, but only translate the changed part. (Alternatively, 
> maybe in the only-one-change example, the translator needs to change in 
> a different part of the document because of a change in terminology that 
> should correspond.)

You may split the document source in a master and several child documents.
Pass the relevant child rST and an export of the complete document to the
translating service...


> Some of the things I am wondering about slide into content management 
> questions and don't have any language-specific aspects and are just 
> worrying about managing rST documents over time, maybe with shared 
> components that are used via include directives, etc.

Being text based, rST documents are well suited for version management via
Git or similar.


As a Python package, Docutils can be used as module of a wider system.
Limits are your imagination and coding ressources.

> I note that the Wikipedia has a page on content management systems, and 
> another page on translation management systems. I'm wondering about rST 
> considerations...


Günter

Re: [Docutils-users] replacement directive and formatting tables (in vim)

[Saša J. <sja...@gm...>]

On Mon, 4 Nov 2019 10:58:43 -0000 (UTC)
Guenter Milde via Docutils-users <doc...@li...>
wrote:

> Unfortunately, there is no simple way to use a different syntax for
> replacements.

OK.

> You may use `simple tables`__ without |, but maybe these cannot be
> formatted by your editor.

Correct.

> You could also try to teach the table formatter the difference
> between a table column separator (with whitespace around, regexp "(^|
> )[|]( |$)") and the replacement syntax (no inner whitespace).

Yeah, that is one possibility.

> Finally, it may be simpler to use the Unicode characters directly via
> drag-and drop 

Well, I use many symbols...

> or group-replacing a placeholder in the editor.

..will think about it.

Thank you for your input.


Sincerely,
Saša

-- 
The working senses are superior to dull matter; mind is higher
than the senses; intelligence is still higher than the mind;
and he [the soul] is even higher than the intelligence.

Re: [Docutils-users] replacement directive and formatting tables (in vim)

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

On 2019-11-03, Saša Janiška wrote:
> Hello,

> in my content I have a need to use many replacement directives, e.g. for
> entering Unicode characters for planets, so I have things like:

> .. |Jupiter| replace:: ♃

> However, since rst uses '|' as table's cell separator, when I use the
> above-like replacement directives, they clash with the code used to
> reformat tables in vim (using https://github.com/gu-fan/riv.vim)
> package, so I wonder if someone can provide some workaround to be able
> to stay with rst **and** using vim editor?

Unfortunately, there is no simple way to use a different syntax for
replacements.

You may use `simple tables`__ without |, but maybe these cannot be formatted
by your editor.

__ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#simple-tables

You could also try to teach the table formatter the difference between a
table column separator (with whitespace around, regexp "(^| )[|]( |$)")
and the replacement syntax (no inner whitespace).

Finally, it may be simpler to use the Unicode characters directly via
drag-and drop or group-replacing a placeholder in the editor.

Ahoj,

Günter

[Docutils-users] replacement directive and formatting tables (in vim)

[Saša J. <sja...@gm...>]

Hello,

in my content I have a need to use many replacement directives, e.g. for
entering Unicode characters for planets, so I have things like:

.. |Jupiter| replace:: ♃

However, since rst uses '|' as table's cell separator, when I use the
above-like replacement directives, they clash with the code used to
reformat tables in vim (using https://github.com/gu-fan/riv.vim)
package, so I wonder if someone can provide some workaround to be able
to stay with rst **and** using vim editor?


Sincerely,
Saša

-- 
Before giving up this present body, if one is able to tolerate
the urges of the material senses and check the force of desire and
anger, he is well situated and is happy in this world.