docutils-develop — For developer discussions of the implementation.

[Docutils-develop] [docutils:bugs] #357 rst2odt ignores start value of numbered lists

[Günter M. <mi...@us...>]

- **summary**: rst2odt generates numbered lists, when it shouldn't --> rst2odt ignores start value of numbered lists
- **Comment**:

Docutils' reStructuredtext parser recognizes the "date paragraphs" as enumerated lists.
This is a known problem that can only be worked around (see https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#enumerated-lists).

A quick fix would be to use a non-breaking space after the day number: `9. června` or escape the dot or the space `10\. června`,` 10.\ června`.
You could also consider turning the "date paragraphs" into section headings, use a description list, or mark the dates as hyperlink targets:

     10. června
     ''''''''''
     Začali jsme sestup po severní...
     
     10. června
         Začali jsme sestup po severní
     
     _`7. července`

Why does it "work" with HTML5?
The parser  parses the leading number into a "start" value attribute (check with rst2pseudoxml). 
The HTML writer uses `<ol>` tags (ordered list)  and  passes the "start" attribute. Hence, in the browser it may look fine (depending on the CSS styling).

The ODT writer, OTOH, seems to ignore the "start" attribute and hence every 
"date paragraph" starts with 1.



---

** [bugs:#357] rst2odt ignores start value of numbered lists**

**Status:** open
**Labels:** ODT Writer 
**Created:** Wed Jan 30, 2019 01:26 PM UTC by Matej Cepl
**Last Updated:** Tue Mar 03, 2020 09:41 PM UTC
**Owner:** nobody
**Attachments:**

- [32_Peru.html](https://sourceforge.net/p/docutils/bugs/357/attachment/32_Peru.html) (16.6 kB; text/html)
- [32_Peru.odt](https://sourceforge.net/p/docutils/bugs/357/attachment/32_Peru.odt) (9.9 kB; application/vnd.oasis.opendocument.text)
- [32_Peru.rst](https://sourceforge.net/p/docutils/bugs/357/attachment/32_Peru.rst) (2.0 kB; application/octet-stream)


I have here a simple document in rST (it is actually Czech translation of one chapter of this fanfiction 
https://www.fanfiction.net/s/12407442/32/ ; I hope it is so simple, I don't need to make a simplified version). It pretends to be a sheet from a diary so it is full of lines (in Czech date format)

30. ledna 2019

(which is how you write January 30th, 2019 in Czech). rst2html5 correctly understands that this is not numbered list and leave those paragraphs as they are. rst2odt however tries to make a numbered list out of these and fails spectaluraly.

Using python3-docutils-0.14-2.1 on openSUSE/Tumbleweed (updated  as of today) with python3-3.6.5-3.4.x86_64. I have checked with diff and tools/rst2odt.py is essentially identical with /usr/bin/rst2odt from that package.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:bugs] Re: #453 [DOC] generic "admonition" directive also listed as specific

[Günter M. <mi...@us...>]

Thank you for the suggestions. 

Looking at the examples in
https://docutils.sourceforge.io/docs/user/rst/demo.html#admonitions, I
found additionally `remarque` ("Anmerkung")
and `avis` ("avis au lecteur", "Ratschlag").

Unfortunately, `conseil` is already used for the specific admonition
`hint` (maybe this should have been `indication`).

`encart` and `cartouche` may be too ambiguous in the context of
documentation documents (we already use `encadré` for `sidebar`).


---

** [bugs:#453] [DOC] generic "admonition" directive also listed as specific**

**Status:** open
**Created:** Wed Jul 27, 2022 09:53 AM UTC by jfbu
**Last Updated:** Sat Jul 30, 2022 07:09 PM UTC
**Owner:** nobody


I quite probably miss something obvious but [admonition directives documentation](https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions) is not clear in so far as it lists "admonition" as a specific admonition type then describes it as being a generic type (which requires a title).


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:bugs] Re: #453 [DOC] generic "admonition" directive also listed as specific

[jfbu <jf...@us...>]

> About translating "admonition": We look for an umbrella term for the specific admonitions
(attention, caution , danger, error, hint, important, note, tip, warning) and similar block elements.

quick (French) thoughts:

* `annonce`: it is very different from `admonition` but conveys the idea of an announcement, which in practice is what the Docutils admonitions do.
* `encart`: this is from press media, it designates in particular advertisements ("encart publicitaire")
* `panneau`: here I take inspiration from being a member of one of the last generations allowed to drive by ourselves mobile engines; this designates indications on side of roads "panneau de signalisation", "panneau routier".  And inside such a "panneau" there can be "encarts" for example the name of a major city might be printed on top of a rectangular area in Green.
* `cartouche`: for example hieroglyphs may be written in such a `cartouche`; but the word also designates other things such as ammunition, see https://fr.wikipedia.org/wiki/Cartouche. I feel it is not too bad in fact although often in typography a `cartouche` contains not a general message but identifiers for example on subjects of a written examination at universities.

all for now.




---

** [bugs:#453] [DOC] generic "admonition" directive also listed as specific**

**Status:** open
**Created:** Wed Jul 27, 2022 09:53 AM UTC by jfbu
**Last Updated:** Thu Jul 28, 2022 05:08 PM UTC
**Owner:** nobody


I quite probably miss something obvious but [admonition directives documentation](https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions) is not clear in so far as it lists "admonition" as a specific admonition type then describes it as being a generic type (which requires a title).


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:bugs] #453 [DOC] generic "admonition" directive also listed as specific

[Günter M. <mi...@us...>]

Thanks for the "nitpicking" - fixed in [r9115].

About translating "admonition": We look for an umbrella term for the specific admonitions
(attention, caution , danger, error, hint, important, note, tip, warning) and similar block elements.

Unfortunately, the English term "admonition" has also the meaning "reproof" (fr: exhortation, de: Ermahnung). Usage in rST does certainly **not** "relate to moral delinquencies" with the object to "prevent further transgression".
A number of translations got this wrong.
Swedish, Russian, and Ukrainean use a term that translates also to "remark", which is a better match for our use case. Other matches would be  translations to "advise", "advisory", "warning note" or similar.


---

** [bugs:#453] [DOC] generic "admonition" directive also listed as specific**

**Status:** open
**Created:** Wed Jul 27, 2022 09:53 AM UTC by jfbu
**Last Updated:** Thu Jul 28, 2022 12:20 PM UTC
**Owner:** nobody


I quite probably miss something obvious but [admonition directives documentation](https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions) is not clear in so far as it lists "admonition" as a specific admonition type then describes it as being a generic type (which requires a title).


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:bugs] #453 [DOC] generic "admonition" directive also listed as specific

[jfbu <jf...@us...>]

> Could you check, if the changes in [r9112] help to avoid the confusion?

Yes, looks good to me (with nits ;-).  I checked this as a diff from a git checkout of commit 3c8063b4b59 with its parent and noticed some inserted whitespace:
~~~diff
diff --git a/docutils/docs/ref/doctree.txt b/docutils/docs/ref/doctree.txt
index 14410a4ea..ab1342a1e 100644
--- a/docutils/docs/ref/doctree.txt
+++ b/docutils/docs/ref/doctree.txt
@@ -424,6 +424,9 @@ Details
 :Analogues:
     ``admonition`` has no direct analogues in common DTDs.  It can be
     emulated with primitives and type effects.
+    
+    The specific admonitions caution_, note_, tip_, and warning_ 
+    are analogous to the respective DocBook elements.
~~~
This does not show above but whitespace is at start of "empty" line underneath `type effects.` and there is space character after `warning_`.

About this other hunk:

~~~diff
-.. From Webster's Revised Unabridged Dictionary (1913) [web1913]:
-   Admonition
-      Gentle or friendly reproof; counseling against a fault or
-      error; expression of authoritative advice; friendly caution
-      or warning.
+Admonitions ("safety messages" or "hazard statements") can appear anywhere
+an ordinary body element can.  They contain arbitrary body elements.
+Typically, an admonition is rendered as an offset block in a document,
+sometimes outlined or shaded,
 
-      Syn: {Admonition}, {Reprehension}, {Reproof}.
+Docutils defines a `generic admonition`_ as well as a set of
+`specific admonitions`_.
~~~
shouldn't the comma after shaded be a full stop rather?
About
> The overlap of the semantics of the specific admonitions makes translation very tricky,
a possible German translation may be "Warnhinweis".

I noticed that French has similar conundrum.  Currently "admonition" is translated as... `admonition` but this is a litterary word that relatively little of our contemporaries under 50 years of age will understand.  A more common French word (still at a level of demanding language) is `admonestation` but it then acquires a meaning like `réprimande` which is too strong. I could not find immediately a good translation but will try to program my brain to think about it during next night shift.

Reference: http://stella.atilf.fr/Dendien/scripts/tlfiv5/advanced.exe?8;s=1136435550;  but I don't know if this direct link works.  Else go to http://atilf.atilf.fr/tlf.htm, click the prominent button and enter `admonition` in the search form.



---

** [bugs:#453] [DOC] generic "admonition" directive also listed as specific**

**Status:** open
**Created:** Wed Jul 27, 2022 09:53 AM UTC by jfbu
**Last Updated:** Thu Jul 28, 2022 11:09 AM UTC
**Owner:** nobody


I quite probably miss something obvious but [admonition directives documentation](https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions) is not clear in so far as it lists "admonition" as a specific admonition type then describes it as being a generic type (which requires a title).


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:bugs] #453 [DOC] generic "admonition" directive also listed as specific

[Günter M. <mi...@us...>]

Thank you for reporting. You found a documentation bug.
Could you check, if the changes in [r9112] help to avoid the confusion?

Docutils uses the term "admonition" in the sense of "safety message" or "hazard statement", not as reprimand or rebuke. (The German translation in parsers/rst/languages/de.py got this wrong.
A possible German translation may be "Warnhinweis" but the overlap of the semantics of the specific admonitions makes translation very tricky.)


---

** [bugs:#453] [DOC] generic "admonition" directive also listed as specific**

**Status:** open
**Created:** Wed Jul 27, 2022 09:53 AM UTC by jfbu
**Last Updated:** Wed Jul 27, 2022 09:53 AM UTC
**Owner:** nobody


I quite probably miss something obvious but [admonition directives documentation](https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions) is not clear in so far as it lists "admonition" as a specific admonition type then describes it as being a generic type (which requires a title).


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:bugs] #453 [DOC] generic "admonition" directive also listed as specific

[jfbu <jf...@us...>]

---

** [bugs:#453] [DOC] generic "admonition" directive also listed as specific**

**Status:** open
**Created:** Wed Jul 27, 2022 09:53 AM UTC by jfbu
**Last Updated:** Wed Jul 27, 2022 09:53 AM UTC
**Owner:** nobody


I quite probably miss something obvious but [admonition directives documentation](https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions) is not clear in so far as it lists "admonition" as a specific admonition type then describes it as being a generic type (which requires a title).


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:patches] #194 Deprecate PEP 263 coding slugs support

[Günter M. <mi...@us...>]

The (still provisional) "inspecting_codecs" package is now available on
https://codeberg.org/milde/inspecting-codecs.


---

** [patches:#194] Deprecate PEP 263 coding slugs support**

**Status:** open
**Group:** None
**Created:** Thu Jun 09, 2022 10:48 PM UTC by Adam  Turner
**Last Updated:** Fri Jul 15, 2022 12:52 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Deprecate-PEP-263-coding-slugs.patch](https://sourceforge.net/p/docutils/patches/194/attachment/0001-Deprecate-PEP-263-coding-slugs.patch) (5.5 kB; application/octet-stream)


Python 3 uses utf-8 as the encoding for Python source files, there is no longer a compelling use-case for the support, which adds complexity to the IO implementation.

I propose deprecating support for removal in 1.0, but 2.0 might be a better option.

Support was added in [r4506].

A


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/patches/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/patches/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

Re: [Docutils-develop] Ukranian translation

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

On 2022-07-13, Guenter Milde via Docutils-develop wrote:
> On 2022-07-12, Adam Turner wrote:

>> A contributor to Sphinx has provided a Ukrainian translation (formatted
>> as a PR against an old version of Docutils) at
>> https://github.com/kazanzhy/docutils/pull/1 .

Dmytro Kazanzhy updated his patch and I submitted it in [r9111].

(It was against a really old Docutils version: smartquotes.py supports
Ukrainian since release 0.14 (2017-08-03).)

Adam, could you please inform Dmytro that the Docutils repo-version now
supports Ukrainian and he may try a snapshot or repository check-out?

Thanks,

Günter

[Docutils-develop] [docutils:patches] #194 Deprecate PEP 263 coding slugs support

[Günter M. <mi...@us...>]

> IMO, it is more safe keep "source code encoding both visible and changeable on a per-source file basis". [PEP 263]

OTOH, this feature does not need to be implemented in docutils.io.
The attached "inspecting_codecs" package is a first try to implement the current default behaviour as a codec -- allowing Docutils to use standard io tools. 
BTW: It also recognizes PEP-263-like encoding declarations in UTF-16 and UTF-32.
With a replacement sufficiently stable and available either inside Docutils or as separate package,
deprecating the current encoding handling is OK.


Attachments:

- [inspecting_codecs-0.1.0.tar.gz](https://sourceforge.net/p/docutils/patches/_discuss/thread/d27c8d1320/268e/attachment/inspecting_codecs-0.1.0.tar.gz) (10.3 kB; application/gzip)


---

** [patches:#194] Deprecate PEP 263 coding slugs support**

**Status:** open
**Group:** None
**Created:** Thu Jun 09, 2022 10:48 PM UTC by Adam  Turner
**Last Updated:** Tue Jun 14, 2022 10:15 AM UTC
**Owner:** nobody
**Attachments:**

- [0001-Deprecate-PEP-263-coding-slugs.patch](https://sourceforge.net/p/docutils/patches/194/attachment/0001-Deprecate-PEP-263-coding-slugs.patch) (5.5 kB; application/octet-stream)


Python 3 uses utf-8 as the encoding for Python source files, there is no longer a compelling use-case for the support, which adds complexity to the IO implementation.

I propose deprecating support for removal in 1.0, but 2.0 might be a better option.

Support was added in [r4506].

A


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/patches/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/patches/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:feature-requests] Re: #36 option for disallowing file overwrites

[Günter M. <mi...@us...>]

> I like the --output= solution
> of course this will break a ton of scripts therefore requires
> a deprecation warning and will take years

Indeed. 

We may start with deprecating the "-o" shortcut for "--output-encoding".
(And, for symmetry "-i" for "--input-encoding".)


---

** [feature-requests:#36] option for disallowing file overwrites**

**Status:** pending
**Group:** 
**Created:** Fri Mar 15, 2013 10:43 PM UTC by Jakub Wilk
**Last Updated:** Fri Jul 08, 2022 08:24 AM UTC
**Owner:** nobody


A Debian user complained that if you use a wildcard as input file name, and the wildcard unexpectedly expands to two names, then rst2html will overwrite your files:
http://bugs.debian.org/654690

Would if be possible to add an option for not overwriting output files, that you could add to your configuration file, and later override from command line if needed?



---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

Re: [Docutils-develop] Ukranian translation

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

Dear Adam,

On 2022-07-12, Adam Turner wrote:
> Dear Günter,

> A contributor to Sphinx has provided a Ukrainian translation (formatted
> as a PR against an old version of Docutils) at
> https://github.com/kazanzhy/docutils/pull/1 .

Looks good to me.
Three points:

- The copyright and docstring in parsers/rst/languages/uk.py needs
  updating.

- The encoding declaration and the "u" string prefixes are no longer
  required.

- 'list-table' is a table with the source in form of a nested unordered list.
  The translation should use whatever is common in Ukrainean for such
  lists (Polish uses 'tabela-listowa').

I recommend using transliterations instead of Latin in 'meta',
'тестова-директива-restructuredtext', 'unicode', and maybe a translated
abbreviation (or abbreviated translation) in 'csv-таблиця' for
practical reasons: It removes the need to switch the keyboard language
when typing the rST source.
The English directive and role names are valid alternatives in
non-English documents.


> The repository is still in a frozen state for substantive changes post
> the 0.19 release, but I wanted to raise this to you so that we can
> include it as soon as possible,

It is now a week since the release and I am not aware of any bug reports.
So this non-invasive, backwards-compatible change should be OK.

> Please let me know if you'd like me to reformat as a patch against
> current master or if you're happy to work with it.

It would be nice, if you could discuss the required/suggested changes with
the OP and reformat. (We also need a HISTORY entry.)


Thank you

Günter

[Docutils-develop] Ukranian translation

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

Dear Günter,

A contributor to Sphinx has provided a Ukrainian translation (formatted as a PR against an old version of Docutils) at https://github.com/kazanzhy/docutils/pull/1 . 

The repository is still in a frozen state for substantive changes post the 0.19 release, but I wanted to raise this to you so that we can include it as soon as possible, I'm told this is blocking the Ukranian translation of the Python documentation. Please let me know if you'd like me to reformat as a patch against current master or if you're happy to work with it.

Thanks,
Adam

[Docutils-develop] [docutils:feature-requests] Re: #36 option for disallowing file overwrites

[engelbert g. <gr...@us...>]

I like the --output= solution

of course this will break a ton of scripts
therefor requires a deprecation warning 
and will take years


---

** [feature-requests:#36] option for disallowing file overwrites**

**Status:** pending
**Group:** 
**Created:** Fri Mar 15, 2013 10:43 PM UTC by Jakub Wilk
**Last Updated:** Thu Jul 07, 2022 08:54 PM UTC
**Owner:** nobody


A Debian user complained that if you use a wildcard as input file name, and the wildcard unexpectedly expands to two names, then rst2html will overwrite your files:
http://bugs.debian.org/654690

Would if be possible to add an option for not overwriting output files, that you could add to your configuration file, and later override from command line if needed?



---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:feature-requests] #36 option for disallowing file overwrites

[Günter M. <mi...@us...>]

The original problem (accidential overwriting because of shell expansion,  http://bugs.debian.org/654690) would also be solved by a different syntax for the output file:
instead of `rst2html infile outfile` we could use the signature

    rst2html infile [infile2 [infile3 [...]]] --output=outfile
 which would:
 
 - prevent interpretation of an "accidential" second argument as outfile (and hence overwriting),
 - be in line with [usability recommendations](https://clig.dev/#arguments-and-flags),
 - allow chaining of rST source files, e.g. prepending a file that defines roles or substitutions or combining  chapters/parts without requiring a master document. 



---

** [feature-requests:#36] option for disallowing file overwrites**

**Status:** pending
**Group:** 
**Created:** Fri Mar 15, 2013 10:43 PM UTC by Jakub Wilk
**Last Updated:** Thu Jul 07, 2022 08:21 PM UTC
**Owner:** nobody


A Debian user complained that if you use a wildcard as input file name, and the wildcard unexpectedly expands to two names, then rst2html will overwrite your files:
http://bugs.debian.org/654690

Would if be possible to add an option for not overwriting output files, that you could add to your configuration file, and later override from command line if needed?



---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:feature-requests] #36 option for disallowing file overwrites

[Günter M. <mi...@us...>]

Since 3.3, Python's standard `open()` supports the "mode" argument value
 'x' open for exclusive creation, failing if the file already exists
 which could help with the implementation of such an option.




---

** [feature-requests:#36] option for disallowing file overwrites**

**Status:** pending
**Group:** 
**Created:** Fri Mar 15, 2013 10:43 PM UTC by Jakub Wilk
**Last Updated:** Sat Mar 16, 2013 05:57 PM UTC
**Owner:** nobody


A Debian user complained that if you use a wildcard as input file name, and the wildcard unexpectedly expands to two names, then rst2html will overwrite your files:
http://bugs.debian.org/654690

Would if be possible to add an option for not overwriting output files, that you could add to your configuration file, and later override from command line if needed?



---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

Re: [Docutils-develop] Participation in Docutils: Documentation Utilities project.

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

Dear Paola Zambrano,

thank you for your interest in the Docutils project.
Sorry for the late answer, we were busy preparing the 0.19 release.

On 2022-06-18, DENNISSE PAOLA ZAMBRANO MONSERRATE wrote:

> We are a group of students from the State Technical University of Quevedo
> and we want to participate in the Docutils: Documentation Utilities project.
> We are interested in working on usability issues. We carry out usability
> tests to find aspects to improve in the Docutils: Documentation Utilities
> application.
> The final result of the usability tests will be shared with the community.
> We would like to know if it is possible to participate in the project.

The envisaged kind of participation (tests and sharing the results and
possible suggestions) should be possible without any prerequisites:

Anyone with an account on sourceforge.net can open tickets at the Docutils
projects trackers:

Bugs (wrong behaviour) to https://sourceforge.net/p/docutils/bugs/

Feature-Requests (missing features, ways to improve) to
https://sourceforge.net/p/docutils/feature-requests/


Please keep in mind, that Docutils is a command line program - we do not
offer a graphical user interface, nor do we plan to add one.
On the topic of usability of command line interfaces (CLI), I found
https://clig.dev/ an interesting reading.


Sincerely
Günter Milde

Re: [Docutils-develop] release 0.19 up on pypi

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

On 2022-07-05, engelbert gruber wrote:

> Release 0.19 (2022-07-05)
>=========================

...

Thank you, Engelbert for the release.

I suggest we wait with the next changes to the code for a week to be
prepared for a fixup in case of bug reports.

Günter

[Docutils-develop] [docutils:bugs] #350 odf_odt Writer prints "The system cannot find the path specified" on Windows

[Günter M. <mi...@us...>]

- **status**: open-fixed --> closed-fixed
- **Comment**:

Fixed in Docutils 0.19.
Thank you for the report.



---

** [bugs:#350] odf_odt Writer prints "The system cannot find the path specified" on Windows**

**Status:** closed-fixed
**Created:** Mon Aug 20, 2018 01:43 PM UTC by Ovidiu Ciule
**Last Updated:** Mon Nov 15, 2021 06:12 PM UTC
**Owner:** nobody


Hi there,

The odf_odt Writer currently prints an error message on Windows that cannot be captured with the usual stdout/stderr capture techniques, since it originates in a popen.

To reproduce, it's enough to call "rst2odt.py some_valid_source.rst whatever.odt"

I found the bug on Python 3.6.5 and Docutils 0.14, but the faulty popen call is present in latest docutils

The output odt file is created as expected, but we see "The system cannot find the path specified" printed in the terminal. Worse, any application code using odf_odt Writer will print this error message. The message is not capturable AFAIK with the usual stdout/stderr techniques (contextlib.redirect_stdout or similar) since it originates in a popen call.

The faulty popen call is in http://svn.code.sf.net/p/docutils/code/trunk/docutils/docutils/writers/odf_odt/__init__.py

class ODFTranslator, method setup_paper:

fin = os.popen("paperconf -s 2> /dev/null")

On Windows, the "/dev/null" path does not exist (except specific cases such as the Windows 10 WSL Linux subsystem. The shell thus prints the error.

I propose this patch which seems compatible with both Python > 2.4 and 3:

fin = subprocess.check_output("paperconf -s", stderr=subprocess.DEVNULL)

This is tested and works on windows with python 3. It should work fine on Linux and MacOS.






---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:bugs] #430 avoid mutables as default functions arguments

[Günter M. <mi...@us...>]

- **status**: open-fixed --> closed-fixed
- **Comment**:

Fixed in Docutils 0.19.
Thank you for the report.



---

** [bugs:#430] avoid mutables as default functions arguments**

**Status:** closed-fixed
**Labels:** rst parser 
**Created:** Mon Oct 25, 2021 09:53 AM UTC by Dimitri Papadopoulos
**Last Updated:** Wed Dec 29, 2021 12:19 PM UTC
**Owner:** Günter Milde


Mutables shouldn't be used as default parameters, it is a Python anti-pattern. See for example:
* [Default Parameter Values in Python](https://web.archive.org/web/20200221224620/http://effbot.org/zone/default-values.htm)
* [Python Mutable Defaults Are The Source of All Evil](https://florimond.dev/en/posts/2018/08/python-mutable-defaults-are-the-source-of-all-evil/)
* [The Hitchhiker's Guide to Python - Common Gotchas](https://docs.python-guide.org/writing/gotchas/#mutable-default-arguments)
* [Python Pitfall: Mutable Default Arguments](https://towardsdatascience.com/python-pitfall-mutable-default-arguments-9385e8265422)

Mutable default arguments are used in a few places in docutils. Just grep `=[]` and `={}` and retain function definitions.

Mutable default arguments can also be found in the documentation:
https://docutils.sourceforge.io/docs/howto/rst-roles.html#define-the-role-function
https://docutils.sourceforge.io/docs/howto/rst-roles.html#rfc-reference-role

Of course, that's not an immediate problem if the mutable arguments are actually not mutated by the function, but it remains an anti-pattern that may create problems in the future.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:bugs] #436 docutils doesn't build with Python 3.11

[Günter M. <mi...@us...>]

- **status**: open-fixed --> closed-fixed



---

** [bugs:#436] docutils doesn't build with Python 3.11**

**Status:** closed-fixed
**Created:** Fri Nov 26, 2021 12:39 PM UTC by Tomáš Hrnčiar
**Last Updated:** Wed Jul 06, 2022 07:46 AM UTC
**Owner:** nobody


Hello,

in Fedora we started with rebuilding Python packages with preleases of Python 3.11, currently it is 2nd alpha. 

Docutils doesn't build because 3.11 adds support for null characters in the csv module, which breaks a test. See reproducer below.

>>> import csv
>>> from docutils.parsers.rst.directives import tables
>>> with open('utf-16.csv', 'rb') as f: csv_data = f.read()
... 
>>> csv_data = str(csv_data, 'latin1').splitlines()
>>> reader = csv.reader([tables.CSVTable.encode_for_csv(line + '\n') for line in csv_data])
>>> next(reader)

Python 3.11:

['þÿ\x00"\x00T\x00r\x00e\x00a\x00t\x00"\x00', '\x00 \x00"\x00Q\x00u\x00a\x00n\x00t\x00i\x00t\x00y\x00"\x00', '\x00 \x00"\x00D\x00e\x00s\x00c\x00r\x00i\x00p\x00t\x00i\x00o\x00n\x00"\x00']

Python 3.10:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
_csv.Error: line contains NUL



---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:bugs] #435 invalid references in "problematic" nodes with report_level=4

[Günter M. <mi...@us...>]

- **status**: open-fixed --> closed-fixed
- **Comment**:

Fixed in release 0.19.
Thank you for the report.



---

** [bugs:#435] invalid references in "problematic" nodes with report_level=4**

**Status:** closed-fixed
**Created:** Tue Nov 16, 2021 04:50 PM UTC by Dmitry Shachnev
**Last Updated:** Fri Feb 04, 2022 08:40 AM UTC
**Owner:** nobody


I don’t know if you will consider it a bug, but I decided to report it nevertheless.

When input reStructuredText has errors and you silence them with report_level=4, the following HTML will be generated:
```python
>>> from docutils.core import publish_parts
>>> parts = publish_parts('`', settings_overrides={'report_level': 4}, writer_name='html5')
>>> print(parts['html_body'])
<main>
<p><a href="#system-message-1"><span class="problematic" id="problematic-1">`</span></a></p>
</main>
```

The link is pointing to `#system-message-1`, however there is no element with `id="system-message-id"` because the warning itself was not generated.


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:bugs] #436 docutils doesn't build with Python 3.11

[Günter M. <mi...@us...>]

Fixed in release 0.19.
Thank you for reporting and testing.


---

** [bugs:#436] docutils doesn't build with Python 3.11**

**Status:** open-fixed
**Created:** Fri Nov 26, 2021 12:39 PM UTC by Tomáš Hrnčiar
**Last Updated:** Wed Jul 06, 2022 07:45 AM UTC
**Owner:** nobody


Hello,

in Fedora we started with rebuilding Python packages with preleases of Python 3.11, currently it is 2nd alpha. 

Docutils doesn't build because 3.11 adds support for null characters in the csv module, which breaks a test. See reproducer below.

>>> import csv
>>> from docutils.parsers.rst.directives import tables
>>> with open('utf-16.csv', 'rb') as f: csv_data = f.read()
... 
>>> csv_data = str(csv_data, 'latin1').splitlines()
>>> reader = csv.reader([tables.CSVTable.encode_for_csv(line + '\n') for line in csv_data])
>>> next(reader)

Python 3.11:

['þÿ\x00"\x00T\x00r\x00e\x00a\x00t\x00"\x00', '\x00 \x00"\x00Q\x00u\x00a\x00n\x00t\x00i\x00t\x00y\x00"\x00', '\x00 \x00"\x00D\x00e\x00s\x00c\x00r\x00i\x00p\x00t\x00i\x00o\x00n\x00"\x00']

Python 3.10:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
_csv.Error: line contains NUL



---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:bugs] Re: #436 docutils doesn't build with Python 3.11

[Günter M. <mi...@us...>]

> reading a utf-16 file in latin1 gives funny results.

In the test, this is intentional. In praxi, utf-16 is recognized by the BOM and correctly decoded, if the "input_encoding" setting is left at its default (None).

> maybe breaking processing of the file would be better than producing garbled output

See [feature-requests:#92].


---

** [bugs:#436] docutils doesn't build with Python 3.11**

**Status:** open-fixed
**Created:** Fri Nov 26, 2021 12:39 PM UTC by Tomáš Hrnčiar
**Last Updated:** Sun Nov 28, 2021 10:36 AM UTC
**Owner:** nobody


Hello,

in Fedora we started with rebuilding Python packages with preleases of Python 3.11, currently it is 2nd alpha. 

Docutils doesn't build because 3.11 adds support for null characters in the csv module, which breaks a test. See reproducer below.

>>> import csv
>>> from docutils.parsers.rst.directives import tables
>>> with open('utf-16.csv', 'rb') as f: csv_data = f.read()
... 
>>> csv_data = str(csv_data, 'latin1').splitlines()
>>> reader = csv.reader([tables.CSVTable.encode_for_csv(line + '\n') for line in csv_data])
>>> next(reader)

Python 3.11:

['þÿ\x00"\x00T\x00r\x00e\x00a\x00t\x00"\x00', '\x00 \x00"\x00Q\x00u\x00a\x00n\x00t\x00i\x00t\x00y\x00"\x00', '\x00 \x00"\x00D\x00e\x00s\x00c\x00r\x00i\x00p\x00t\x00i\x00o\x00n\x00"\x00']

Python 3.10:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
_csv.Error: line contains NUL



---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.

[Docutils-develop] [docutils:feature-requests] #92 Warn of problematic characters.

[Günter M. <mi...@us...>]

---

** [feature-requests:#92] Warn of problematic characters.**

**Status:** open
**Group:** Default
**Created:** Wed Jul 06, 2022 07:41 AM UTC by Günter Milde
**Last Updated:** Wed Jul 06, 2022 07:41 AM UTC
**Owner:** nobody


Unprintable characters like NULL in the rST source are most probable an indication of a problem
(corrupt source file, wrong encoding, ...). 
The same goes for combining characters at the start of a line, etc.
It may be helpful, if Docutils issued a Warning for problematic characters in the source (except for literals).


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/feature-requests/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/feature-requests/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.