docutils-develop — For developer discussions of the implementation.

[Docutils-develop] [docutils:feature-requests] #93 Mod operator for math2html

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

- **summary**: Mod operator for the HTML Parser --> Mod operator for math2html
- **Group**:  --> Default



---

** [feature-requests:#93] Mod operator for math2html**

**Status:** open
**Group:** Default
**Created:** Sat Sep 03, 2022 08:43 PM UTC by Daniel James Perry
**Last Updated:** Wed Sep 07, 2022 11:18 AM UTC
**Owner:** nobody


The latex to html/css code is quite impressive, but it's missing the `\\mod` command (as well as other similar commands like `\\pmod`. It should be a trivial thing to do.

BTW please get with the times and start using git PLEASE.


---

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] [docutils:patches] #197 MathML: support pandoc(1) as an external converter

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

Thank you for the patch.

A test with the maths documentation source
"docutils/docs/ref/rst/mathematics.txt" revealed:

* it takes loooong to run,
* there are > 120 conversion errors (unknown AMSmath macros),
* the error messages need getting used to,
* the successfull conversions are similar to the native MathML support.

What are the advantages over native MathML?

[Docutils-develop] [docutils:bugs] #459 Invalid circular inclusion warning when including multiple documents from a directive

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

`insert_input()` is an undocumented (internal) auxiliary method. 
Maybe the custom directive can subclass or call `directives.misc.Include` instead.

Just emptying  the document's `include_log` breaks the detection of circular inclusions :( 
(You will only recognise this in CI, if there are test cases that have both, the custom directive and a circular inclusion.)

Checking the test example file, I realized that it reports:
~~~
file1.rst:1: (WARNING/2) circular inclusion in "include" directive:
file1.rst
> file1.rst
~~~
i.e. the inclusion detection assumes that "file1.rst" includes itself recursively!
This is due to a wrong usage of `state_machine.insert_input()`: 
the line written by `DirectiveThatIncludes.run()` will (when parsed) include the source "name", but it is not from source "name".  With
~~~
    def run(self):
        name = self.content[0]
        source = self.state_machine.input_lines.source(
            self.lineno - self.state_machine.input_offset - 1)
        self.state_machine.insert_input(
            ['.. include:: %s' % name], source)
        return []
~~~
there is no warning (because, the inclusion of "file1" and "file2" uses the stock `misc.Directive`class that handles circular inclusion detection fine).
Even when using
~~~
    def run(self):
        name = self.content[0]
        with open(name) as f:
            lines = f.read()
        self.state_machine.insert_input(lines, name)
        return []
~~~
the circular-inclusion warning does not  appear here.


---

** [bugs:#459] Invalid circular inclusion warning when including multiple documents from a directive**

**Status:** pending-works-for-me
**Created:** Thu Oct 20, 2022 10:30 PM UTC by Ian Wienand
**Last Updated:** Thu Oct 27, 2022 08:34 PM UTC
**Owner:** nobody
**Attachments:**

- [circular-ref-bug.py](https://sourceforge.net/p/docutils/bugs/459/attachment/circular-ref-bug.py) (1.2 kB; text/x-python)


The recent sphinx release has found what I think is a problem in the circular-reference detection in docutils.

We have a situation where we build a page with a directive that automatically includes a file (readme from a sub-component).  In some cases, these readme's might then also include another file (e.g. similar components share a common file about their arguments, etc.).  So we have a include hierarchy like

~~~
 .. include:: ./component/README.rst
   .. include:: common.rst
.. include:: ./component2/README.rst
  .. include:: common.rst
~~~

Our directive works by reading the `README.rst` file and then using `self.state_machine.insert_input()`

Our build started failing due a `circular inclusion in "include" directive` which comes from the *second* inclusion of the `common.rst` above.  In this situation, I don't believe there is any circular inclusion -- we want the same content included twice; but it is not referencing itself.

I think it has something to do with `self.state.document.include_log` thinking that it has seen `common.rst` before.

I have isolated this down to the smallest example I can think of and attached that; it is also at https://paste.opendev.org/show/brTxHYllHebBIs1wHbfM/

When I run this I get

~~~
$ ./docutils-venv/bin/python3 ./recursive.py 
Write combined.rst
Write file1.rst
Write file2.rst
Write common.rst
file1.rst:1: (WARNING/2) circular inclusion in "include" directive:
file1.rst
> file1.rst
~~~



---

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] #456 Latex Blank lines in Block Math Environment

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

- **status**: open --> pending-works-for-me
- **Comment**:

I cannot find spurious newlines in `latex2e/__init__.py` and no blank lines in {equation*} environments in the LaTeX test output. Nor in the output of "rst2latex" for a local copy of https://docutils.sourceforge.io/docs/ref/rst/mathematics.txt.

Please provide a minimal  example (input file + generated latex file), the Docutils version and eventual extensions/wrappers.



---

** [bugs:#456] Latex Blank lines in Block Math Environment**

**Status:** pending-works-for-me
**Created:** Thu Sep 01, 2022 09:14 PM UTC by Daniel James Perry
**Last Updated:** Sat Sep 10, 2022 02:11 PM UTC
**Owner:** nobody


The latex writer has a serious bug regarding block math displays.
According to the book *More Math into Latex*:
> No blank lines are permitted within an equation or equation* environment.

But if you look at the code that's **exactly what it does.** The resulting Latex output is incorrect.
Please fix this as soon as possible.

BTW get with the times and start using git please.


---

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] #197 MathML: support pandoc(1) as an external converter

[Ximin L. <inf...@us...>]

---

** [patches:#197] MathML: support pandoc(1) as an external converter**

**Status:** open
**Group:** None
**Created:** Fri Oct 28, 2022 02:21 PM UTC by Ximin Luo
**Last Updated:** Fri Oct 28, 2022 02:21 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-MathML-support-pandoc-1-as-an-external-converter.patch](https://sourceforge.net/p/docutils/patches/197/attachment/0001-MathML-support-pandoc-1-as-an-external-converter.patch) (3.5 kB; text/x-patch)


In my personal experience, `pandoc` is more reliable than `latexml`, e.g. the current support for the latter in docutils does not automatically include amsfonts which prevents things like mathbb from working. In `pandoc` it Just Works.


---

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:patches] #196 Revert header/footer borders in minimal.css

[Ximin L. <inf...@us...>]

I would argue that, a true meaning of "minimal" means a common subset of what all documentation generators might expect from the background browser. In which case, headers and footers don't naturally start off having lines. This is my motivation for the patch in the first place - I am mixing different documentation generators whilst trying to retain their "minimal.css" equivalents, and this definition from docutils is making its output look different from the others. (And my current workaround is to override these definitions to `none` locally for my use case.)

However, if you consider strict backwards compatibility more important, then this is a judgment I can't argue against, and we can leave this patch out and close this issue. This information is useful for me though - at least I can expect this behaviour to be stable for docutils in the long run, and therefore my workaround can also remain stable in the long run.



---

** [patches:#196]  Revert header/footer borders in minimal.css**

**Status:** open
**Group:** None
**Created:** Wed Oct 26, 2022 10:57 PM UTC by Ximin Luo
**Last Updated:** Fri Oct 28, 2022 11:19 AM UTC
**Owner:** nobody
**Attachments:**

- [4.patch](https://sourceforge.net/p/docutils/patches/196/attachment/4.patch) (654 Bytes; text/x-patch)


These were uncommented in r8472 but that commit only talks about switching to html5 semantic tags, not changing the actual meaning of minimal.css

I assume this is a mistake; it interferes with the purpose of this stylesheet as a minimal stylesheet, and plain.css overrides this later anyway with border:none.



---

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] [docutils:patches] #185 Core: Implement publish_doctree using publish_programmatically

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

On 2022-10-27, Adam Turner via Docutils-develop wrote:

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

> Thanks for the patch, applied in [r9176].

...

> > AFAICT there's nothing special about `publish_doctree` that justifies
> > *not* implementing it in terms of `publish_programmatically`?

... besides the number of function arguments in
publish_programmatically() exceeds the "sane limit" according to pylint.

Günter

[Docutils-develop] [docutils:patches] #196 Revert header/footer borders in minimal.css

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

Lines separating header and footer from the main part of the document were hard-coded as `<hr>` elements until [r8472] (cf. the changes to the test documents in this commit).
This hard-coded line was replaced with CSS markup that retains the appearance used in the html4css1 writer but is easier to re-style. 

The "minimal.css" style sheet is intended to make all logical markup elements defined by Docutils/rST visually discernible. This is especially important for Docutils elements that do not have a HTML equivalent.
Since HTML5, header and footer have a native HTML representation, however the default rendering in Mozilla and Chromium does nothing to make them stand out from the rest of the document.

Removing the CSS definitions as proposed by the patch would break backwards compatibility for users of "minimal.css" together with a custom style sheet.


---

** [patches:#196]  Revert header/footer borders in minimal.css**

**Status:** open
**Group:** None
**Created:** Wed Oct 26, 2022 10:57 PM UTC by Ximin Luo
**Last Updated:** Thu Oct 27, 2022 07:57 AM UTC
**Owner:** nobody
**Attachments:**

- [4.patch](https://sourceforge.net/p/docutils/patches/196/attachment/4.patch) (654 Bytes; text/x-patch)


These were uncommented in r8472 but that commit only talks about switching to html5 semantic tags, not changing the actual meaning of minimal.css

I assume this is a mistake; it interferes with the purpose of this stylesheet as a minimal stylesheet, and plain.css overrides this later anyway with border:none.



---

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:bugs] #459 Invalid circular inclusion warning when including multiple documents from a directive

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

- **status**: open --> pending-works-for-me
- **Comment**:

Thank you for reporting a problem. 
It seems related to the changes required to fix [bugs:#366] in [r8851].

With the stock `include` directive, Docutils correctly identifies "common.rst" as included from different files and does not throw the "circular inclusion" error.
The custom directive does not add the logging information required for the detection of this case. Compare the last lines of `directives.misc.Include.run` (lines 198 ff. in docutils/parsers/rst/directives/misc.py).



---

** [bugs:#459] Invalid circular inclusion warning when including multiple documents from a directive**

**Status:** pending-works-for-me
**Created:** Thu Oct 20, 2022 10:30 PM UTC by Ian Wienand
**Last Updated:** Thu Oct 20, 2022 10:30 PM UTC
**Owner:** nobody
**Attachments:**

- [circular-ref-bug.py](https://sourceforge.net/p/docutils/bugs/459/attachment/circular-ref-bug.py) (1.2 kB; text/x-python)


The recent sphinx release has found what I think is a problem in the circular-reference detection in docutils.

We have a situation where we build a page with a directive that automatically includes a file (readme from a sub-component).  In some cases, these readme's might then also include another file (e.g. similar components share a common file about their arguments, etc.).  So we have a include hierarchy like

~~~
 .. include:: ./component/README.rst
   .. include:: common.rst
.. include:: ./component2/README.rst
  .. include:: common.rst
~~~

Our directive works by reading the `README.rst` file and then using `self.state_machine.insert_input()`

Our build started failing due a `circular inclusion in "include" directive` which comes from the *second* inclusion of the `common.rst` above.  In this situation, I don't believe there is any circular inclusion -- we want the same content included twice; but it is not referencing itself.

I think it has something to do with `self.state.document.include_log` thinking that it has seen `common.rst` before.

I have isolated this down to the smallest example I can think of and attached that; it is also at https://paste.opendev.org/show/brTxHYllHebBIs1wHbfM/

When I run this I get

~~~
$ ./docutils-venv/bin/python3 ./recursive.py 
Write combined.rst
Write file1.rst
Write file2.rst
Write common.rst
file1.rst:1: (WARNING/2) circular inclusion in "include" directive:
file1.rst
> file1.rst
~~~



---

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] #185 Core: Implement publish_doctree using publish_programmatically

[Adam T. <aa-...@us...>]

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



---

** [patches:#185] Core: Implement publish_doctree using publish_programmatically**

**Status:** closed-fixed
**Group:** None
**Created:** Fri Aug 20, 2021 02:58 AM UTC by Clément Pit-Claudel
**Last Updated:** Thu Oct 27, 2022 09:38 AM UTC
**Owner:** nobody
**Attachments:**

- [1-core-refactor.patch](https://sourceforge.net/p/docutils/patches/185/attachment/1-core-refactor.patch) (1.4 kB; text/x-patch)


This is mostly cosmetic; I ran across it as I was reading through the code to implement a related function.

AFAICT there's nothing special about `publish_doctree` that justifies *not* implementing it in terms of `publish_programmatically`?


---

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:patches] #185 Core: Implement publish_doctree using publish_programmatically

[Adam T. <aa-...@us...>]

Thanks for the patch, applied in [r9176].

A


---

** [patches:#185] Core: Implement publish_doctree using publish_programmatically**

**Status:** open
**Group:** None
**Created:** Fri Aug 20, 2021 02:58 AM UTC by Clément Pit-Claudel
**Last Updated:** Fri Aug 20, 2021 02:58 AM UTC
**Owner:** nobody
**Attachments:**

- [1-core-refactor.patch](https://sourceforge.net/p/docutils/patches/185/attachment/1-core-refactor.patch) (1.4 kB; text/x-patch)


This is mostly cosmetic; I ran across it as I was reading through the code to implement a related function.

AFAICT there's nothing special about `publish_doctree` that justifies *not* implementing it in terms of `publish_programmatically`?


---

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:patches] #196 Revert header/footer borders in minimal.css

[Adam T. <aa-...@us...>]

The patch is reasonable, but I defer to @milde for rationale here as he authored the original change.

A


---

** [patches:#196]  Revert header/footer borders in minimal.css**

**Status:** open
**Group:** None
**Created:** Wed Oct 26, 2022 10:57 PM UTC by Ximin Luo
**Last Updated:** Wed Oct 26, 2022 11:00 PM UTC
**Owner:** nobody
**Attachments:**

- [4.patch](https://sourceforge.net/p/docutils/patches/196/attachment/4.patch) (654 Bytes; text/x-patch)


These were uncommented in r8472 but that commit only talks about switching to html5 semantic tags, not changing the actual meaning of minimal.css

I assume this is a mistake; it interferes with the purpose of this stylesheet as a minimal stylesheet, and plain.css overrides this later anyway with border:none.



---

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:patches] #196 Revert header/footer borders in minimal.css

[Ximin L. <inf...@us...>]

Link to r8472 for convenience: https://sourceforge.net/p/docutils/code/8472/


---

** [patches:#196]  Revert header/footer borders in minimal.css**

**Status:** open
**Group:** None
**Created:** Wed Oct 26, 2022 10:57 PM UTC by Ximin Luo
**Last Updated:** Wed Oct 26, 2022 10:57 PM UTC
**Owner:** nobody
**Attachments:**

- [4.patch](https://sourceforge.net/p/docutils/patches/196/attachment/4.patch) (654 Bytes; text/x-patch)


These were uncommented in r8472 but that commit only talks about switching to html5 semantic tags, not changing the actual meaning of minimal.css

I assume this is a mistake; it interferes with the purpose of this stylesheet as a minimal stylesheet, and plain.css overrides this later anyway with border:none.



---

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:patches] #196 Revert header/footer borders in minimal.css

[Ximin L. <inf...@us...>]

---

** [patches:#196]  Revert header/footer borders in minimal.css**

**Status:** open
**Group:** None
**Created:** Wed Oct 26, 2022 10:57 PM UTC by Ximin Luo
**Last Updated:** Wed Oct 26, 2022 10:57 PM UTC
**Owner:** nobody
**Attachments:**

- [4.patch](https://sourceforge.net/p/docutils/patches/196/attachment/4.patch) (654 Bytes; text/x-patch)


These were uncommented in r8472 but that commit only talks about switching to html5 semantic tags, not changing the actual meaning of minimal.css

I assume this is a mistake; it interferes with the purpose of this stylesheet as a minimal stylesheet, and plain.css overrides this later anyway with border:none.



---

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] [question] docutils - license

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

Dear Pankaj Kapse,

On 2022-09-19, Pankaj Vishnu KAPSE via Docutils-develop wrote:

> I would like to know more about docutils license to use it as python
> package.

The `Conditions for Docutils redistribution`,
https://docutils.sourceforge.io/COPYING.html
should give you all required details.

sincerely
Günter Milde

[Docutils-develop] [docutils:patches] #195 invalid html for citation nodes with no siblings

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

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

Fixed in [r9126]. 
Thank you for report, analysis, and patch.



---

** [patches:#195] invalid html for citation nodes with no siblings**

**Status:** open-fixed
**Group:** None
**Created:** Thu Aug 25, 2022 08:46 AM UTC by Matthias C. M. Troffaes
**Last Updated:** Tue Oct 11, 2022 02:02 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Fix-previous_sibling-in-case-index-is-0.patch](https://sourceforge.net/p/docutils/patches/195/attachment/0001-Fix-previous_sibling-in-case-index-is-0.patch) (970 Bytes; application/octet-stream)


When citations appear in a parent that has no other siblings besides this single citation, a spurious `</div>` is generated resulting in invalid html code. It appears that this is because the opening `<div role="list" class="citation-list">` is not being generated. I've tracked it to this docutils failing to add an opening div for the citation list here:

https://github.com/docutils/docutils/blob/master/docutils/docutils/writers/_html_base.py#L632

It gets then closed here leading to the extra tag:

https://github.com/docutils/docutils/blob/master/docutils/docutils/writers/_html_base.py#L640

Basically, this is due to odd behaviour of previous_sibling: if index relative to parent is zero and there are no other siblings, it returns the node itself instead of None. This looks like a docutils bug, and the attached patch fixes  the issue.
    
Originally reported here: https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/309 .

Also reported here: https://github.com/sphinx-doc/sphinx/issues/10784 .


---

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:patches] #195 invalid html for citation nodes with no siblings

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

- Description has changed:

Diff:

~~~~

--- old
+++ new
@@ -1,4 +1,4 @@
-When citations appear in a parent that has no other siblings besides this single citation, a spurious </div> is generated resulting in invalid html code. It appears that this is because the opening <div role="list" class="citation-list"> is not being generated. I've tracked it to this docutils failing to add an opening div for the citation list here:
+When citations appear in a parent that has no other siblings besides this single citation, a spurious `</div>` is generated resulting in invalid html code. It appears that this is because the opening `<div role="list" class="citation-list">` is not being generated. I've tracked it to this docutils failing to add an opening div for the citation list here:
 
 https://github.com/docutils/docutils/blob/master/docutils/docutils/writers/_html_base.py#L632
 
@@ -8,6 +8,6 @@
 
 Basically, this is due to odd behaviour of previous_sibling: if index relative to parent is zero and there are no other siblings, it returns the node itself instead of None. This looks like a docutils bug, and the attached patch fixes  the issue.
     
-Originally reported here: https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/309.
+Originally reported here: https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/309 .
 
-Also reported here: https://github.com/sphinx-doc/sphinx/issues/10784.
+Also reported here: https://github.com/sphinx-doc/sphinx/issues/10784 .

~~~~




---

** [patches:#195] invalid html for citation nodes with no siblings**

**Status:** open
**Group:** None
**Created:** Thu Aug 25, 2022 08:46 AM UTC by Matthias C. M. Troffaes
**Last Updated:** Tue Oct 11, 2022 12:52 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Fix-previous_sibling-in-case-index-is-0.patch](https://sourceforge.net/p/docutils/patches/195/attachment/0001-Fix-previous_sibling-in-case-index-is-0.patch) (970 Bytes; application/octet-stream)


When citations appear in a parent that has no other siblings besides this single citation, a spurious `</div>` is generated resulting in invalid html code. It appears that this is because the opening `<div role="list" class="citation-list">` is not being generated. I've tracked it to this docutils failing to add an opening div for the citation list here:

https://github.com/docutils/docutils/blob/master/docutils/docutils/writers/_html_base.py#L632

It gets then closed here leading to the extra tag:

https://github.com/docutils/docutils/blob/master/docutils/docutils/writers/_html_base.py#L640

Basically, this is due to odd behaviour of previous_sibling: if index relative to parent is zero and there are no other siblings, it returns the node itself instead of None. This looks like a docutils bug, and the attached patch fixes  the issue.
    
Originally reported here: https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/309 .

Also reported here: https://github.com/sphinx-doc/sphinx/issues/10784 .


---

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:patches] #195 invalid html for citation nodes with no siblings

[Abramo B. <abr...@us...>]

I confirm that the patch fixes the problem of unmatched `</div>` generation.


---

** [patches:#195] invalid html for citation nodes with no siblings**

**Status:** open
**Group:** None
**Created:** Thu Aug 25, 2022 08:46 AM UTC by Matthias C. M. Troffaes
**Last Updated:** Thu Aug 25, 2022 08:49 AM UTC
**Owner:** nobody
**Attachments:**

- [0001-Fix-previous_sibling-in-case-index-is-0.patch](https://sourceforge.net/p/docutils/patches/195/attachment/0001-Fix-previous_sibling-in-case-index-is-0.patch) (970 Bytes; application/octet-stream)


When citations appear in a parent that has no other siblings besides this single citation, a spurious </div> is generated resulting in invalid html code. It appears that this is because the opening <div role="list" class="citation-list"> is not being generated. I've tracked it to this docutils failing to add an opening div for the citation list here:

https://github.com/docutils/docutils/blob/master/docutils/docutils/writers/_html_base.py#L632

It gets then closed here leading to the extra tag:

https://github.com/docutils/docutils/blob/master/docutils/docutils/writers/_html_base.py#L640

Basically, this is due to odd behaviour of previous_sibling: if index relative to parent is zero and there are no other siblings, it returns the node itself instead of None. This looks like a docutils bug, and the attached patch fixes  the issue.
    
Originally reported here: https://github.com/mcmtroffaes/sphinxcontrib-bibtex/issues/309.

Also reported here: https://github.com/sphinx-doc/sphinx/issues/10784.


---

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:bugs] Re: #458 Two issues regarding manpage writer and .TH

[Dmitry S. <man...@us...>]

Pandoc seems to have its own manpage reader: https://github.com/jgm/pandoc/blob/master/src/Text/Pandoc/Readers/Man.hs.


---

** [bugs:#458] Two issues regarding manpage writer and .TH**

**Status:** open
**Labels:** manpage writer 
**Created:** Mon Sep 05, 2022 11:13 AM UTC by Dmitry Shachnev
**Last Updated:** Fri Oct 07, 2022 08:57 AM UTC
**Owner:** nobody


Dear docutils developers,

I received two bug reports in Debian regarding the content of .TH macro in man pages:

First bug — https://bugs.debian.org/1016527 — asks that the value of `--date` argument be used for the third argument of `.TH`, instead of putting it on a separate line (Generated on: YYYY-MM-DD).

Second bug — https://bugs.debian.org/1018737 — asks that docutils not set fifth argument of `.TH` to empty string, but omit it completely and rely on the default value.

Please see those bugs for more detailed descriptions (and some discussion, in the first bug).


---

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: #458 Two issues regarding manpage writer and .TH

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

mqDmitry
> AFAIK, it will work. The behavior may differ, in that groff(1) and
> mandoc(1) produce a default text, while others may not produce any text
> at all, but it should work.

I sometime test layout groff and try with mandoc what are the "others" ?  


---

** [bugs:#458] Two issues regarding manpage writer and .TH**

**Status:** open
**Labels:** manpage writer 
**Created:** Mon Sep 05, 2022 11:13 AM UTC by Dmitry Shachnev
**Last Updated:** Wed Sep 07, 2022 12:08 PM UTC
**Owner:** nobody


Dear docutils developers,

I received two bug reports in Debian regarding the content of .TH macro in man pages:

First bug — https://bugs.debian.org/1016527 — asks that the value of `--date` argument be used for the third argument of `.TH`, instead of putting it on a separate line (Generated on: YYYY-MM-DD).

Second bug — https://bugs.debian.org/1018737 — asks that docutils not set fifth argument of `.TH` to empty string, but omit it completely and rely on the default value.

Please see those bugs for more detailed descriptions (and some discussion, in the first bug).


---

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] [question] docutils - license

[Pankaj V. K. <pan...@hs...>]

Hi Team

I would like to know more about docutils license to use it as python package. I should help me answering some question before I use it within my organization codebase. Cheers!

Thanks and Regards,

Pankaj Kapse
GCP Cloud Engineer
HSBC Technology - Pune, Level 1, HTI 1.0, Pune, India
-----------------------------------------------------------------------
External : +91-20-3095-4348
Mobile : +91-9324484538
-----------------------------------------------------------------------



PUBLIC




*******************************************************************
This e-mail is confidential. It may also be legally privileged. 
If you are not the addressee you may not copy, forward, disclose 
or use any part of it. If you have received this message in error, 
please delete it and all copies from your system and notify the 
sender immediately by return e-mail.
Internet communications cannot be guaranteed to be timely, 
secure, error or virus-free. The sender does not accept liability 
for any errors or omissions.
*******************************************************************
"SAVE PAPER - THINK BEFORE YOU PRINT!" 

[Docutils-develop] [docutils:feature-requests] Re: #91 Include directive path argument should support a configurable root.

[Michal U. <xev...@us...>]

I'm fine with both. Both `<>` and `/` make sense and are a convention in some technologies. And btw, paths and URLs are both part of URIs. I would not support `\`, C and C++ do not support it either and I haven't seen `\` as a path separator in any web tech too.


---

** [feature-requests:#91] Include directive path argument should support a configurable root.**

**Status:** open
**Group:** Default
**Created:** Tue May 03, 2022 04:03 PM UTC by Michal Urbanski
**Last Updated:** Tue Sep 13, 2022 11:13 AM UTC
**Owner:** nobody


I'm building a static website using restructuredtext and I'm really annoyed by the lack of support for root-relative paths.

I have already implemented multiple directive plugins for my website build process, some of which use external files in a different format. They use the convention that if a path begins with /, they are relative to the root directory of the project.

IMO the requirement for relative paths is very limiting - I could have a directory with files intended for inclusion but:

- I would need to use `../../` which is very ugly
- relative paths are different depending on the current file path - this is very fragile and limits 

An additional argument is that C and C++ have been using #include for like 40 years and relative paths (while sometimes useful) are only for specific cases. The leading convention is to use root-relative paths.

I could implement another plugin for it but ... copy-pasting docutils own code only to change few lines is definitely smelly.


---

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] Re: #91 Include directive path argument should support a configurable root.

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

> I would argue the first option (include root) is the simpler and more explicit / less surprising choice.

This depends on what you  are using as comparison:

* `/` as "project root" is similar to handling of absolute URLs by http servers.
    However, we want to use it for *files*, not *URLS*.
    Open issue: support only `/` or also `\`?
*  `<...>` is already used for *standard “include” data files* (cf. directives.html).
    C and C++ use this syntax with a configurable search path for the`#include` preprocessor directive.


---

** [feature-requests:#91] Include directive path argument should support a configurable root.**

**Status:** open
**Group:** Default
**Created:** Tue May 03, 2022 04:03 PM UTC by Michal Urbanski
**Last Updated:** Tue Sep 13, 2022 11:04 AM UTC
**Owner:** nobody


I'm building a static website using restructuredtext and I'm really annoyed by the lack of support for root-relative paths.

I have already implemented multiple directive plugins for my website build process, some of which use external files in a different format. They use the convention that if a path begins with /, they are relative to the root directory of the project.

IMO the requirement for relative paths is very limiting - I could have a directory with files intended for inclusion but:

- I would need to use `../../` which is very ugly
- relative paths are different depending on the current file path - this is very fragile and limits 

An additional argument is that C and C++ have been using #include for like 40 years and relative paths (while sometimes useful) are only for specific cases. The leading convention is to use root-relative paths.

I could implement another plugin for it but ... copy-pasting docutils own code only to change few lines is definitely smelly.


---

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] #91 Include directive path argument should support a configurable root.

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

A file with unit tests.

TODO:

* Support for "csv-table" directive.
* How to treat image files that are read-in with imagelib?
*  Documentation


Attachments:

- [0001-Add-unit-tests-for-include-root-setting.patch](https://sourceforge.net/p/docutils/feature-requests/_discuss/thread/a885b6f1ca/2e27/attachment/0001-Add-unit-tests-for-include-root-setting.patch) (3.7 kB; text/x-patch)


---

** [feature-requests:#91] Include directive path argument should support a configurable root.**

**Status:** open
**Group:** Default
**Created:** Tue May 03, 2022 04:03 PM UTC by Michal Urbanski
**Last Updated:** Mon Aug 15, 2022 10:04 PM UTC
**Owner:** nobody


I'm building a static website using restructuredtext and I'm really annoyed by the lack of support for root-relative paths.

I have already implemented multiple directive plugins for my website build process, some of which use external files in a different format. They use the convention that if a path begins with /, they are relative to the root directory of the project.

IMO the requirement for relative paths is very limiting - I could have a directory with files intended for inclusion but:

- I would need to use `../../` which is very ugly
- relative paths are different depending on the current file path - this is very fragile and limits 

An additional argument is that C and C++ have been using #include for like 40 years and relative paths (while sometimes useful) are only for specific cases. The leading convention is to use root-relative paths.

I could implement another plugin for it but ... copy-pasting docutils own code only to change few lines is definitely smelly.


---

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:bugs] #454 [DOC] borderless option said to remove borders "around" table but removes every border

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

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

Fixed in [r9124]. Thank you for reporting.



---

** [bugs:#454] [DOC] borderless option said to remove borders "around" table but removes every border**

**Status:** closed-fixed
**Created:** Sat Aug 06, 2022 01:41 PM UTC by jfbu
**Last Updated:** Sat Aug 27, 2022 09:14 PM UTC
**Owner:** nobody


I tested [borderless](https://docutils.sourceforge.io/docs/user/config.html#table-style) with `rst2html.py` and found out that produced table was literally "borderless" which contradicted what I had understood from the documentation:
```
borderless

    No borders around the table.
```
I was expecting no top, right, botttom and left borders but *all* borders of *all cells* are removed.  However I am not educated enough in Tables so maybe my expectation was too ill-informed.  Or I misunderstand "around", as I am not native speaker.




---

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.