docutils-develop — For developer discussions of the implementation.

[Docutils-develop] [docutils:feature-requests] #100 Support SVG hyperlinks and event handling

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

- Description has changed:

Diff:

~~~~

--- old
+++ new
@@ -1,3 +1,3 @@
 SVG supports embedded hyperlinks, and the ability to trigger scripts on keyboard, mouse, and document events.  But docutils does not, because SVG files are referenced by HTML "img" elements instead of "svg" elements.
 
-Might be best to use the SVG "image" element, nested in a HTML "svg" element, to reference the underlying SVG file.
+<s>Might be best to use the SVG "image" element, nested in a HTML "svg" element, to reference the underlying SVG file.</s>

~~~~

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

[r9517] implements embedding SVG in an  `<svg>` element, so embedded SVG images are now interactive.



---

**[feature-requests:#100] Support SVG hyperlinks and event handling**

**Status:** open-fixed
**Group:** Default
**Created:** Wed Nov 01, 2023 09:15 PM UTC by Karl O. Pinc
**Last Updated:** Sat Dec 16, 2023 10:46 PM UTC
**Owner:** nobody


SVG supports embedded hyperlinks, and the ability to trigger scripts on keyboard, mouse, and document events.  But docutils does not, because SVG files are referenced by HTML "img" elements instead of "svg" elements.

<s>Might be best to use the SVG "image" element, nested in a HTML "svg" element, to reference the underlying SVG file.</s>


---

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] #102 Image height/width attributes

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

Thank you for the report.

The reason for using the "style" attribute to set the image size is the need to accomodate relative units. Using it for absolute units¹ as well is done to make the code simpler and the behaviour more predictable.

1. AFAIK, specifying image size via a CSS style also prevents layout shifts so this may be a "false positive" by Lighthouse (but see also https://www.smashingmagazine.com/2020/03/setting-height-width-images-important-again/).

2. Safeguarding via "Content Security Policy" is less important for the main use case of Doctuils-generated HTML documents -- static HTML pages.
It may become important if the Docutils output is used as building block in dynamic pages that allow "user  feedback". 
We need to find a consensus, whether this merits a complication of the code with conditional use of "style" vs. "width"/"height" or could be cared for using of the new "CSP: style-src-attr" directive.

¹Absolute units include "plain ol integers". E.g., `height="12"` is the same height as `style="height: 12px;"`.



---

**[feature-requests:#102] Image height/width attributes**

**Status:** open
**Group:** None
**Created:** Wed Dec 20, 2023 02:35 PM UTC by toastal
**Last Updated:** Wed Jan 03, 2024 12:00 PM UTC
**Owner:** nobody


When setting `:width:` or `:height:` on an image, the output is a `<image style="width: $W; height: $H">`. This isn’t the expected out put as there are & have been `width` & `height` attributes for the `<img>` tag for a long time. One might assume this is the same affect, but there are some important problems & why I think this is a bug for incorrect implementation.

1. Tools like Lighthouse, et al. show users to have width/height as a optimization so the browser can calculate & the image size properly without having to do a layout shift which is great
2. A good CSP (Content Security Policy) should never include `unsafe-inline` as this can be an attack surface but the output of `:width:` & `:height:` do just this.

The way to solve this to keep out unneeded inline style practice for good CSP but still have the width/height is to just use `<img width="$W" height="$H">` (at least when units are not specified).

What I may not be accounting for: units. `12px` is not the same as `12rem` or `12ex` or `12vw`. However, what I had input in my image was just plain ol’ integers got back something I didn’t expect: a) something using `px` (I‘m exclusively using relative unit like `em`, `rem`, etc.) and b) not using the attributes since the number I gave had no units.


---

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] #102 Image height/width attributes

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

Ticket moved from /p/docutils/bugs/478/


---

**[feature-requests:#102] Image height/width attributes**

**Status:** open
**Group:** None
**Created:** Wed Dec 20, 2023 02:35 PM UTC by toastal
**Last Updated:** Wed Jan 03, 2024 12:00 PM UTC
**Owner:** nobody


When setting `:width:` or `:height:` on an image, the output is a `<image style="width: $W; height: $H">`. This isn’t the expected out put as there are & have been `width` & `height` attributes for the `<img>` tag for a long time. One might assume this is the same affect, but there are some important problems & why I think this is a bug for incorrect implementation.

1. Tools like Lighthouse, et al. show users to have width/height as a optimization so the browser can calculate & the image size properly without having to do a layout shift which is great
2. A good CSP (Content Security Policy) should never include `unsafe-inline` as this can be an attack surface but the output of `:width:` & `:height:` do just this.

The way to solve this to keep out unneeded inline style practice for good CSP but still have the width/height is to just use `<img width="$W" height="$H">` (at least when units are not specified).

What I may not be accounting for: units. `12px` is not the same as `12rem` or `12ex` or `12vw`. However, what I had input in my image was just plain ol’ integers got back something I didn’t expect: a) something using `px` (I‘m exclusively using relative unit like `em`, `rem`, etc.) and b) not using the attributes since the number I gave had no units.


---

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] #100 Support SVG hyperlinks and event handling

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

With the SVG embedding patch proposed in the last  [comment](https://sourceforge.net/p/docutils/feature-requests/40/#7204) to feature-requests:#40, re-using SVG elements across embedded images works (but will have to be done by authors, not "automagically" by Doctutils.
Example attached.


Attachments:

- [blue-user.svg](https://sourceforge.net/p/docutils/feature-requests/_discuss/thread/1de312bd8b/4eea/attachment/blue-user.svg) (149 Bytes; image/svg+xml)
- [circles.svg](https://sourceforge.net/p/docutils/feature-requests/_discuss/thread/1de312bd8b/4eea/attachment/circles.svg) (148 Bytes; image/svg+xml)
- [green-user.svg](https://sourceforge.net/p/docutils/feature-requests/_discuss/thread/1de312bd8b/4eea/attachment/green-user.svg) (128 Bytes; image/svg+xml)


---

**[feature-requests:#100] Support SVG hyperlinks and event handling**

**Status:** open
**Group:** Default
**Created:** Wed Nov 01, 2023 09:15 PM UTC by Karl O. Pinc
**Last Updated:** Tue Nov 14, 2023 05:01 PM UTC
**Owner:** nobody


SVG supports embedded hyperlinks, and the ability to trigger scripts on keyboard, mouse, and document events.  But docutils does not, because SVG files are referenced by HTML "img" elements instead of "svg" elements.

Might be best to use the SVG "image" element, nested in a HTML "svg" element, to reference the underlying SVG file.


---

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] #40 Option to embed images as data uri in rst2html

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

A patch for direct SVG embedding on top of [r9503].


Attachments:

- [0001-Embed-SVG-images-as-svg-instead-of-data-URI.patch](https://sourceforge.net/p/docutils/feature-requests/_discuss/thread/35b2e928/7204/attachment/0001-Embed-SVG-images-as-svg-instead-of-data-URI.patch) (23.6 kB; text/x-patch)


---

**[feature-requests:#40] Option to embed images as data uri in rst2html**

**Status:** open
**Group:** Default
**Labels:** rst2html 
**Created:** Wed Dec 03, 2014 09:43 PM UTC by Iiro Laiho
**Last Updated:** Thu Dec 14, 2023 04:49 PM UTC
**Owner:** nobody


It would be nice if rst2html had an option to embed images as base64 data uris in html files. Then you could make a single file html document that could be e.g. easily mailed as an attachment.


---

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] #40 Option to embed images as data uri in rst2html

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

The "image" directive now has a  :loading: option. [r9496]


---

**[feature-requests:#40] Option to embed images as data uri in rst2html**

**Status:** open
**Group:** Default
**Labels:** rst2html 
**Created:** Wed Dec 03, 2014 09:43 PM UTC by Iiro Laiho
**Last Updated:** Sun Nov 26, 2023 10:52 PM UTC
**Owner:** nobody


It would be nice if rst2html had an option to embed images as base64 data uris in html files. Then you could make a single file html document that could be e.g. easily mailed as an attachment.


---

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] #85 Enable easily-typed hard line-breaks in paragraphs.

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

See [#101] for the suggestion of a new "doctree" element for hard line breaks.


---

**[feature-requests:#85] Enable easily-typed hard line-breaks in paragraphs.**

**Status:** closed-works-for-me
**Group:** Default
**Labels:** linebreaks 
**Created:** Sat Jan 01, 2022 08:21 AM UTC by jon
**Last Updated:** Tue Dec 12, 2023 08:12 PM UTC
**Owner:** nobody


During the last few weeks I've spent some time
carefully studying reStructuredText and Python-Markdown.

I would prefer to write with reStructuredText,
but Markdown has one feature that is lacking in reST:
easy-to-type line-breaks in paragraphs.

I'm addicted to semantic line breaking.
I think in medium-length phrases that can fit in one line.
Probably this was heightened by working with video subtitles,
but I've always felt that prose can be understood more quickly
if the line-breaks fall between semantic units.

Even when I can't make semantic units fit neatly,
I still like to control where the lines break.

An extension for Python-Markdown, nl2br,
completely disables markdown's removal of line-breaks,
so I can simply write the way I usually do.

With another markdown extension, you type a backslash
to indicate that you want to keep the following line-break.

I'm aware of the methods available in reST:
starting every line of a block with `| `,
or typing something like `|br|` at the end of a line.
They're not really suitable to use with every line of every paragraph.

Perhaps the removal of line-breaks from paragraphs is baked so deeply into reST 
that it's not practical to change the current behaviour?

Anyway, my question/feature-request is: can you make 
either or both of the following methods available to users?

1. Preferably, set a document-wide parameter 
   that causes actual line-breaks in paragraphs to be kept.

2. If that's not practical, create a hard line-break 
   by typing a backslash immediately before a line-break 
   (with or without a space before the backslash).

I'd like to convert my reST docs to html5, using `<br>\n` for line breaks.

I don't understand why arbitrary line-breaks are the norm. In early email and code editors line length was limited, but I don't see why any form of markup or markdown expects people to insert them these days. When I don't want semantic breaks, I simply don't insert any breaks at all, and then a paragraph is a single unbroken line that gets wrapped at the margins. Why isn't *this* the norm?

Hope my point of view makes at least a little sense to you.



---

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] #101 New "doctree" element for hard line breaks.

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

---

**[feature-requests:#101] New "doctree" element for hard line breaks.**

**Status:** open
**Group:** Default
**Created:** Tue Dec 12, 2023 08:16 PM UTC by Günter Milde
**Last Updated:** Tue Dec 12, 2023 08:16 PM UTC
**Owner:** nobody


Not providing for "hard line break elements" in the Docutils document model and reStructuredText syntax was a deliberate decision at the time these two were devised.

However, times have changed and there are new arguments and use-cases for hard line breaks.
(cf.  the  [comments in #85](https://sourceforge.net/p/docutils/feature-requests/85/#d02b)).
Something like a `<br>` inline node or special handling of `<inline class=line-break>` inline nodes may be considered. The latter would not change the document model and could be implemented at the writer level or via stylesheet rules.

Whether to add a reStructuredText syntax for hard line breaks can be decided independently.
The current rules require a non-white character in a role defined with `.. role:: line-break`.
    



---

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] #85 Enable easily-typed hard line-breaks in paragraphs.

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

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

The original request is most easily handled by a custom style sheet (cf. [comment](https://sourceforge.net/p/docutils/feature-requests/85/#711b/63e6/13e5/712d/0bd0/d497). 
The issue of a dedicated "hard" line break syntax and doctree element should be discussed separately.



---

**[feature-requests:#85] Enable easily-typed hard line-breaks in paragraphs.**

**Status:** closed-works-for-me
**Group:** Default
**Labels:** linebreaks 
**Created:** Sat Jan 01, 2022 08:21 AM UTC by jon
**Last Updated:** Tue Dec 12, 2023 08:02 PM UTC
**Owner:** nobody


During the last few weeks I've spent some time
carefully studying reStructuredText and Python-Markdown.

I would prefer to write with reStructuredText,
but Markdown has one feature that is lacking in reST:
easy-to-type line-breaks in paragraphs.

I'm addicted to semantic line breaking.
I think in medium-length phrases that can fit in one line.
Probably this was heightened by working with video subtitles,
but I've always felt that prose can be understood more quickly
if the line-breaks fall between semantic units.

Even when I can't make semantic units fit neatly,
I still like to control where the lines break.

An extension for Python-Markdown, nl2br,
completely disables markdown's removal of line-breaks,
so I can simply write the way I usually do.

With another markdown extension, you type a backslash
to indicate that you want to keep the following line-break.

I'm aware of the methods available in reST:
starting every line of a block with `| `,
or typing something like `|br|` at the end of a line.
They're not really suitable to use with every line of every paragraph.

Perhaps the removal of line-breaks from paragraphs is baked so deeply into reST 
that it's not practical to change the current behaviour?

Anyway, my question/feature-request is: can you make 
either or both of the following methods available to users?

1. Preferably, set a document-wide parameter 
   that causes actual line-breaks in paragraphs to be kept.

2. If that's not practical, create a hard line-break 
   by typing a backslash immediately before a line-break 
   (with or without a space before the backslash).

I'd like to convert my reST docs to html5, using `<br>\n` for line breaks.

I don't understand why arbitrary line-breaks are the norm. In early email and code editors line length was limited, but I don't see why any form of markup or markdown expects people to insert them these days. When I don't want semantic breaks, I simply don't insert any breaks at all, and then a paragraph is a single unbroken line that gets wrapped at the margins. Why isn't *this* the norm?

Hope my point of view makes at least a little sense to you.



---

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: #85 Enable easily-typed hard line-breaks in paragraphs.

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

Docutils preserves line-breaks and writes tham (as `\n`) into the output document.
For HTML, a custom style-sheet with the CSS rule `p {white-space: break-spaces}` should suffice to get "semantic line breaks" as intended.
(Tested with the example below + a bullet list.)


---

**[feature-requests:#85] Enable easily-typed hard line-breaks in paragraphs.**

**Status:** open
**Group:** Default
**Labels:** linebreaks 
**Created:** Sat Jan 01, 2022 08:21 AM UTC by jon
**Last Updated:** Tue Jan 04, 2022 10:33 AM UTC
**Owner:** nobody


During the last few weeks I've spent some time
carefully studying reStructuredText and Python-Markdown.

I would prefer to write with reStructuredText,
but Markdown has one feature that is lacking in reST:
easy-to-type line-breaks in paragraphs.

I'm addicted to semantic line breaking.
I think in medium-length phrases that can fit in one line.
Probably this was heightened by working with video subtitles,
but I've always felt that prose can be understood more quickly
if the line-breaks fall between semantic units.

Even when I can't make semantic units fit neatly,
I still like to control where the lines break.

An extension for Python-Markdown, nl2br,
completely disables markdown's removal of line-breaks,
so I can simply write the way I usually do.

With another markdown extension, you type a backslash
to indicate that you want to keep the following line-break.

I'm aware of the methods available in reST:
starting every line of a block with `| `,
or typing something like `|br|` at the end of a line.
They're not really suitable to use with every line of every paragraph.

Perhaps the removal of line-breaks from paragraphs is baked so deeply into reST 
that it's not practical to change the current behaviour?

Anyway, my question/feature-request is: can you make 
either or both of the following methods available to users?

1. Preferably, set a document-wide parameter 
   that causes actual line-breaks in paragraphs to be kept.

2. If that's not practical, create a hard line-break 
   by typing a backslash immediately before a line-break 
   (with or without a space before the backslash).

I'd like to convert my reST docs to html5, using `<br>\n` for line breaks.

I don't understand why arbitrary line-breaks are the norm. In early email and code editors line length was limited, but I don't see why any form of markup or markdown expects people to insert them these days. When I don't want semantic breaks, I simply don't insert any breaks at all, and then a paragraph is a single unbroken line that gets wrapped at the margins. Why isn't *this* the norm?

Hope my point of view makes at least a little sense to you.



---

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] #68 Adding syntax for role parameters

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

See [#96] for another use case.


---

**[feature-requests:#68] Adding syntax for role parameters**

**Status:** open
**Group:** Default
**Created:** Fri Jan 31, 2020 11:28 PM UTC by adam
**Last Updated:** Fri Jan 31, 2020 11:28 PM UTC
**Owner:** nobody


Hello Docutils team,

Sometimes I would like to pass options to role functions for adding domain-specific metadata. For example,

For citation page numbers:

~~~rst
As discussed in :cite:[p.99]`knuth1968`, the implementation ...
~~~

In a cookbook:
~~~rst
If you like, add some :liquid-ingredient:[20ml, spicyness=7]`Tabasco sauce`. 
~~~


As discussed in [this Docutils mailing-list thread](https://sourceforge.net/p/docutils/mailman/message/34894112/), AsciiDoc [uses a syntax](https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#images) like this:

~~~
Click image:icons/play.png[Play, title="Play"] to get the party started.
~~~

I like the idea of passing positional and named options in brackets.

Is there a possibility of Docutils supporting this feature? 


---

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] #96 <abbr> abbreviations tag

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

Depends an a solution for [#68] "Adding syntax for role parameters".


---

**[feature-requests:#96] <abbr> abbreviations tag**

**Status:** pending
**Group:** Default
**Created:** Wed Jul 12, 2023 06:19 AM UTC by toastal
**Last Updated:** Mon Nov 13, 2023 10:40 PM UTC
**Owner:** nobody


I would like to see inline support for `<abbr>` tags.

> The `abbr` element represents an abbreviation or acronym, optionally with its expansion. The `title` attribute may be used to provide an expansion of the abbreviation. The attribute, if specified, must contain an expansion of the abbreviation, and nothing else.

https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-abbr-element

These are useful for jargon-heavy content like documentation and can help with accessibility.


---

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] #60 Allow definition_list_item to have multiple terms

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

A test script to generate output with a "hand-crafted" document tree with extra term in a definition list.

Currently fails with "html5" writer, the "html4" writer produces invalid output (missing `</dt>`). The "manpage" writer does not fail, however the second term becomes part of the common definition (at least visibly) in the `man` output. 
LaTeX needs a bit of adaption, too.


Attachments:

- [multiple_definition_list_terms.py](https://sourceforge.net/p/docutils/feature-requests/_discuss/thread/28a1d7bcc1/218e/attachment/multiple_definition_list_terms.py) (1.4 kB; text/x-python)


---

**[feature-requests:#60] Allow definition_list_item to have multiple terms**

**Status:** open
**Group:** Default
**Created:** Thu Jan 03, 2019 09:10 AM UTC by Takeshi KOMIYA
**Last Updated:** Fri Nov 12, 2021 11:03 AM UTC
**Owner:** nobody
**Attachments:**

- [support_multiple_terms_on_definition_list_item.patch](https://sourceforge.net/p/docutils/feature-requests/60/attachment/support_multiple_terms_on_definition_list_item.patch) (3.7 kB; application/octet-stream)


In HTML  spec, definition list accepts multiple terms in a item.  This patch allows doctree model to have multiple terms as children of definition_list_item also.
https://www.w3.org/TR/html52/grouping-content.html#the-dl-element

In sphinx, a custom directive named "glossary" allows multiple terms for one definition_list_item.
https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#glossary


---

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: #97 --disable-tab-expansion flag

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

The negative value for the TAB expansion width is only supported for literal inclusions, not for the main document or included rST files.


---

**[feature-requests:#97] --disable-tab-expansion flag**

**Status:** open
**Group:** Default
**Created:** Sun Jul 16, 2023 09:21 AM UTC by toastal
**Last Updated:** Thu Nov 09, 2023 05:04 PM UTC
**Owner:** nobody


> Spaces are recommended for indentation, but tabs may also be used. Tabs will be converted to spaces. Tab stops are at every 8th column (processing systems may make this value configurable).

Why tho? By converting tabs to spaces, we lose the accessibility aspect that tabs provide by letting the reader decide what’s comfortable to them as tab-width should be configurable on the reader’s side, not the writer’s. Some programming languages, like Go, tabs are overwhelmingly preferred & sometimes even required. Copying some code would not work.

I would like to see a `--disable-tab-expansion` flag that lets the author choose how they want their output to be output.


---

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] [PATCH 0/9] Allow literal tabs in reStructuredText

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

Dear Jax,

On 2023-10-29, Jarret "Jax" Renker via Docutils-develop wrote:

> I'm sending you a draft on how to handle literal tab characters inside
> reStructuredText documents.

Thank you for the suggestion and patch set!

I finally found the time to "immerse myself" into the TAB problem.
Sorry for the late answer.

...
> Currently it is impossible for the *output* of a literal block to
> contain tabs. This breaks some listings, e.g. Makefile:
...
> This behaviour is also contrary to my expectation that a literal block
> leaves its content untouched.

This is indeed one of the "warts"¹ in Docutils.

¹ Things that are ugly but kept for "practical reasons".

...
> Currently, the tab character is only supported for included CSV tables
> but not for inline ones.
...

This is a valid complaint, too, but it is less strong than the
"literal-block" one, as it should be not too much pain for authors to
change to a different delimiter for *embedded* CSV values. (The output
uses a different delimiter anyway.)


Now we have to find out, if solving these issues without introducing a
bunch of new problems is possible and worth the effort.


> The problem is that all tab characters get replaced *prior* to parsing,
> namely in string2lines().


> An attempt for a solution
>=========================

> In an attempt to fix this, I toyed around with not replacing tab
> characters before parsing but handling them during parsing.  The parts
> concerned with indention parsing are the methods trim_left() and
> get_indented() of StringList. Adjusting them lets things "just
> work(tm)".  This is a draft, so some details and corner cases must
> still be sorted out.

The draft demonstrates a possible way forward and solves the issue in
"well behaved" cases.

Unfortunately, there are set of small issues, some failures and a general
problem. Let's start with the last:


Generic Problem: shifting post-tab text.
----------------------------------------

TAB expands to a 1 … tab-width spaces, depending on position::

    for i in range(8):
        s = f"{i*'·'}\t{(8-i)*'·'}"
        print((s, s.expandtabs(8)))

Therefore, shortening from the left affects the expansion of the remainder::

    from docutils.statemachine import logical_rslice  # added in patch 4/9

    sample = 3 * '·\t·'
    print(f'{sample=}')
    print('i sample shortened by i and expanded')
    print('- ----------------------------------')
    for i in range(8):
       print(i, i*' ', repr(logical_rslice(sample, i, 8).expandtabs(8)))
    print()


This may break documents, e.g. if a table is aligned with TABs:

table::
    ==========  ==
    Mueller\t3
    Maier\t1
    Maierhuber\t5
    ==========  ==

(Mind, that in rST, you may nest a literal block in a table cell!)


Workaround: 
  Request that block-indentation must be a multiple of "tab-width"
  if there are literal TABs in an indented text block.

  `docutils.statemachine.logical_rslice()` may issue a Warning and
  expand the remainder before returnig if there are TABs in it.

...

> Obviously we should somehow use the docutils.conf option tab_width.

Indeed. Unfortunately, I am not familiar with the parser, too, and its
author David Goodger is less active on docutils-develop nowadays.


Test failure 
------------

The test suit (alltests.py) fails after applying the patches. 
The failing test is in
test/test_parsers/test_rst/test_directives/test_include.py 
(custom TAB expansion with included code),
so this may be an aftereffect of not observing the "tab-width" setting.

I found some more problematic cases, some of them relate to the
`generic problem` above but there seems to be at least one more problem
with nested parsing...

~~~
from docutils.core import publish_parts

sample = """
This is a simple test

        a block
                with definition list (space indented)

        a block
\t        with definition list (TAB + space indented)

\ta block
\t\twith definition list (TAB indented)

        A block
        \twith definition list (space + TAB indented)

.. note::
\tsomething
\t\tis up

a literal block::

\t  less\tindented first line
\t\tdo we want leading spaces here?

A table using TABs for alignment

==========      ==
Mueller\t\t3
Maier\t\t1
Maierhuber\t5
==========      ==

A similar table in a block-quote

    ==========  ==
    Mueller\t3
    Maier\t1
    Maierhuber\t5
    ==========  ==
"""

print(publish_parts(sample)['whole'])

~~~

Smaller Problems
----------------

:1/9: parsers.rst.Parser.parse() and statemachine.string2lines() are
      part of the API: changes must be backwards compatible or announced
      in the RELEASE-NOTES 2 releases in advance.
      → e.g., tab_width < 0 → don't replace
:2/9: dito. → Test for old and new behaviour.

:3/9: → We need more test cases for "mixed" indentation and different
      `tab-width`. (maybe later)
      
:4/9: term "logical": are there analogues, precedences?
      suggestion: logical → expanded | tab_expanded | ...?
        
      logical_rslice(): "rslice()" was proposed as a reverse variant of
      the "slice()" standard function.
      → shorten(s, by, tab_width) | lshorten(s, by, tab_width)

sincerely,

Günter

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

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

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

There is a fixup for config.txt in the pipeline but currently uploads with git svn have timeouts:(



---

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

**Status:** open-fixed
**Group:** Default
**Created:** Tue May 03, 2022 04:03 PM UTC by Michal Urbanski
**Last Updated:** Wed Nov 29, 2023 09:01 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:feature-requests] #91 Include directive path argument should support a configurable root.

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

Commit [r9492] implements the new config setting "root-prefix".
Applied to absolute file paths in the "includ", "raw" and "cvs-table" directives  and the conversion of  an absolut image URI to a local filesystem path by the "html4", "html5", and "odt" writers.


---

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

**Status:** pending
**Group:** Default
**Created:** Tue May 03, 2022 04:03 PM UTC by Michal Urbanski
**Last Updated:** Mon Nov 20, 2023 07:56 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:bugs] #355 Emacs: rst-adjust does not use the visual length if the title contains non-ASCII characters

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

- **labels**:  --> emacs mode



---

**[bugs:#355] Emacs: rst-adjust does not use the visual length if the title contains non-ASCII characters**

**Status:** pending-works-for-me
**Labels:** emacs mode 
**Created:** Sat Dec 29, 2018 10:17 AM UTC by Hong
**Last Updated:** Tue Mar 03, 2020 09:41 PM UTC
**Owner:** Stefan Merten


If the title contains non-ASCII characters, rst-adjust seems to use the size of memory of the title instead of its visual length. For example,

~~~
My §2
===|
~~~

where `|` is the cursor. Calling rst-adjust produces three more `=`s but there should be only two more `=`s.


---

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] #473 Pip installs an incompatible version (20.1) for Python 2

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

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

> The output of pip install docutils -vvv shows that previous versions are correctly rejected, but 20.1 is accepted for some reason:

Actually, links to incompatible *wheels* (`*.whl`) are skipped but **all** *source package*  links `*.tar.gz` are considered for the next step (selecting the newest).

After downloading the newest tar.gz (instead of a compatible wheel!), it starts:
>
     Running setup.py (path:/tmp/pip-build-U_uehq/docutils/setup.py) egg_info for package docutils
    Running command python setup.py egg_info
      /usr/lib64/python2.7/distutils/dist.py:267: UserWarning: Unknown distribution option: 'python_requires'
      warnings.warn(msg)

IAW, the item `'python-requires': '>=3.7'` in the `package_data` is ignored and
the package set up despite the incompatibility :(

As a workaround, one could consider a Python-version check throwing an Exeption under 2.x.
However, since [r9450] there is no `setup.py` (replaced by a `pyproject.tom`).
This should also lead to older `pip` versions failing instead of installing an icompatible version
(or, maybe, even to installing the correct version...).



---

**[bugs:#473] Pip installs an incompatible version (20.1) for Python 2**

**Status:** open-fixed
**Created:** Thu Aug 31, 2023 10:29 AM UTC by Richard Fennessy
**Last Updated:** Sun Nov 12, 2023 06:00 PM UTC
**Owner:** nobody


Hi,

Recently, we've noticed that running the command `pip install docutils` on an old host with only Python 2 installed has begun to install an incompatible version, `20.1`. (First noticed when the incompatibility broke `awscli`).

The output of `pip install docutils -vvv` shows that previous versions are correctly rejected, but  `20.1` is accepted for some reason:

(truncated for clarity)
~~~
    Found link https://files.pythonhosted.org/packages/57/b1/b880503681ea1b64df05106fc7e3c4e3801736cf63deffc6fa7fc5404cf5/docutils-0.18.1.tar.gz#sha256=679987caf361a7539d76e584cbeddc311e3aee937877c87346f31debc63e9d06 (from https://pypi.org/simple/docutils/), version: 0.18.1
    Found link https://files.pythonhosted.org/packages/ac/f7/aec2c4e0acabe771b207ff2b480f2bc1adaef02771ff12f9561e66df33cf/docutils-0.19b1-py2.py3-none-any.whl#sha256=bf87502630148119873347981a8efc2438e6f254f995b7699501f0e4aa538915 (from https://pypi.org/simple/docutils/), version: 0.19b1
    Found link https://files.pythonhosted.org/packages/cf/65/85a3da30f9a256a29b9cf947d603848eb6a4339900df73fbd56551c8b844/docutils-0.19b1.tar.gz#sha256=79b3ab5228b154ecaf4cbf08a1d8c213e3a127826193bafb5a035d0a7a88af0c (from https://pypi.org/simple/docutils/), version: 0.19b1
    Skipping link https://files.pythonhosted.org/packages/93/69/e391bd51bc08ed9141ecd899a0ddb61ab6465309f1eb470905c0c8868081/docutils-0.19-py3-none-any.whl#sha256=5e1de4d849fee02c63b040a4a3fd567f4ab104defd8a5511fbbc24a8a017efbc (from https://pypi.org/simple/docutils/); it is not compatible with this Python
    Found link https://files.pythonhosted.org/packages/6b/5c/330ea8d383eb2ce973df34d1239b3b21e91cd8c865d21ff82902d952f91f/docutils-0.19.tar.gz#sha256=33995a6753c30b7f577febfc2c50411fec6aac7f7ffeb7c4cfe5991072dcf9e6 (from https://pypi.org/simple/docutils/), version: 0.19
    Skipping link https://files.pythonhosted.org/packages/73/f1/455c0f5f29e853956947745299e65c494fe7ed49bce41fd05a738d931da3/docutils-0.20rc1-py3-none-any.whl#sha256=f9cd313159e9611199127c59b63c4890e808cb8cb6c2fe5f9a271cfd6df32676 (from https://pypi.org/simple/docutils/); it is not compatible with this Python
    Found link https://files.pythonhosted.org/packages/1d/0e/f03180dcf1e0727083dc5a303f15cacaf7ae1686f0a4efc295f5ff938197/docutils-0.20rc1.tar.gz#sha256=1077d5e5a529972f340550a99f55c59420095e40eb0eef0824083557a6589e98 (from https://pypi.org/simple/docutils/), version: 0.20rc1
    Skipping link https://files.pythonhosted.org/packages/41/3b/11740ed0f36e408ff3d5bd259af0c3330d899c17562f9964b7fbc90756f9/docutils-0.20-py3-none-any.whl#sha256=a428f10de4de4774389734c986a01b4af2d802d26717108b0f1b9356862937c5 (from https://pypi.org/simple/docutils/); it is not compatible with this Python
    Found link https://files.pythonhosted.org/packages/e6/a9/8ddfaa7a9414e42520e0041d1354ebda699e4eb1b47e2f1b6d8bda66aba6/docutils-0.20.tar.gz#sha256=f75a5a52fbcacd81b47e42888ad2b380748aaccfb3f13af0fe69deb759f01eb6 (from https://pypi.org/simple/docutils/), version: 0.20
    Skipping link https://files.pythonhosted.org/packages/26/87/f238c0670b94533ac0353a4e2a1a771a0cc73277b88bff23d3ae35a256c1/docutils-0.20.1-py3-none-any.whl#sha256=96f387a2c5562db4476f09f13bbab2192e764cac08ebbf3a34a95d9b1e4a59d6 (from https://pypi.org/simple/docutils/); it is not compatible with this Python
    Found link https://files.pythonhosted.org/packages/1f/53/a5da4f2c5739cf66290fac1431ee52aff6851c7c8ffd8264f13affd7bcdd/docutils-0.20.1.tar.gz#sha256=f08a4e276c3a1583a86dce3e34aba3fe04d02bba2dd51ed16106244e8a923e3b (from https://pypi.org/simple/docutils/), version: 0.20.1
  Using version 0.20.1 (newest of versions: 0.3, 0.3.5, 0.3.7, 0.3.9, 0.4, 0.5, 0.6, 0.7, 0.8, 0.8.1, 0.9, 0.9.1, 0.10, 0.11, 0.12, 0.13.1, 0.14, 0.15, 0.15.post1, 0.15.1, 0.15.1.post1, 0.15.2, 0.16, 0.17, 0.17.1, 0.18, 0.18.1, 0.19, 0.20, 0.20.1)
  Looking up "https://files.pythonhosted.org/packages/1f/53/a5da4f2c5739cf66290fac1431ee52aff6851c7c8ffd8264f13affd7bcdd/docutils-0.20.1.tar.gz" in the cache
  Current age based on date: 759150
  Freshness lifetime from max-age: 365000000
  The response is "fresh", returning cached response
  365000000 > 759150
  Using cached https://files.pythonhosted.org/packages/1f/53/a5da4f2c5739cf66290fac1431ee52aff6851c7c8ffd8264f13affd7bcdd/docutils-0.20.1.tar.gz
  Downloading from URL https://files.pythonhosted.org/packages/1f/53/a5da4f2c5739cf66290fac1431ee52aff6851c7c8ffd8264f13affd7bcdd/docutils-0.20.1.tar.gz#sha256=f08a4e276c3a1583a86dce3e34aba3fe04d02bba2dd51ed16106244e8a923e3b (from https://pypi.org/simple/docutils/)
  Running setup.py (path:/tmp/pip-build-U_uehq/docutils/setup.py) egg_info for package docutils
    Running command python setup.py egg_info
    /usr/lib64/python2.7/distutils/dist.py:267: UserWarning: Unknown distribution option: 'python_requires'
      warnings.warn(msg)
    running egg_info
    creating pip-egg-info/docutils.egg-info
    writing pip-egg-info/docutils.egg-info/PKG-INFO
    writing top-level names to pip-egg-info/docutils.egg-info/top_level.txt
    writing dependency_links to pip-egg-info/docutils.egg-info/dependency_links.txt
    writing entry points to pip-egg-info/docutils.egg-info/entry_points.txt
    writing manifest file 'pip-egg-info/docutils.egg-info/SOURCES.txt'
    warning: manifest_maker: standard file '-c' not found

    package init file 'docutils/parsers/rst/include/__init__.py' not found (or not a regular file)
    package init file 'docutils/writers/s5_html/themes/__init__.py' not found (or not a regular file)
    package init file 'docutils/writers/s5_html/themes/default/__init__.py' not found (or not a regular file)
    reading manifest file 'pip-egg-info/docutils.egg-info/SOURCES.txt'
    reading manifest template 'MANIFEST.in'
    warning: no previously-included files found matching 'test/alltests.out'
    warning: no previously-included files found matching 'test/record.txt'
    warning: no previously-included files matching '*.pyc' found anywhere in distribution
    warning: no previously-included files matching '*~' found anywhere in distribution
    warning: no previously-included files matching '__pycache__' found anywhere in distribution
    warning: no previously-included files matching '.DS_Store' found anywhere in distribution
    writing manifest file 'pip-egg-info/docutils.egg-info/SOURCES.txt'
  Source in /tmp/pip-build-U_uehq/docutils has version 0.20.1, which satisfies requirement docutils from https://files.pythonhosted.org/packages/1f/53/a5da4f2c5739cf66290fac1431ee52aff6851c7c8ffd8264f13affd7bcdd/docutils-0.20.1.tar.gz#sha256=f08a4e276c3a1583a86dce3e34aba3fe04d02bba2dd51ed16106244e8a923e3b
~~~

pip version 8.1.2
CentOS Linux 7 (Core)
Linux 3.10.0-1160.95.1.el7.x86_64


---

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] #78 Support lazy loading for image and figure

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

See [feature-requests:#40] for discussion about a matching option for the "image" directive to configure the behaviour for individual images.


---

**[feature-requests:#78] Support lazy loading for image and figure**

**Status:** closed-fixed
**Group:** Default
**Created:** Sun Mar 28, 2021 10:40 PM UTC by Tim Hoffmann
**Last Updated:** Sun Oct 31, 2021 10:00 AM UTC
**Owner:** nobody


Lazy loading can be achieved by adding a `loading` attribute to the `<img>` tag in HTML `<img ... loading="lazy">`.

https://html.spec.whatwg.org/multipage/urls-and-fetching.html#lazy-loading-attributes

The ReST code should probably look like this:
~~~
.. image:: test.png
   :loading: lazy
~~~
and 
~~~
.. figure:: test.png
   :loading: lazy
~~~



---

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: #40 Option to embed images as data uri in rst2html

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

> I don't understand "Smaller image size". Embedding SVG directly
into HTML5 pages makes each page larger, 

I wrote: "Embed SVG images directly, not as **data** URI ."
Encoding an SVG with Base64 usually makes it larger.


---

**[feature-requests:#40] Option to embed images as data uri in rst2html**

**Status:** open
**Group:** Default
**Labels:** rst2html 
**Created:** Wed Dec 03, 2014 09:43 PM UTC by Iiro Laiho
**Last Updated:** Sun Nov 26, 2023 04:04 PM UTC
**Owner:** nobody


It would be nice if rst2html had an option to embed images as base64 data uris in html files. Then you could make a single file html document that could be e.g. easily mailed as an attachment.


---

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:feature-requests] #40 Option to embed images as data uri in rst2html

[Karl O. P. <ko...@ka...>]

On Sun, 26 Nov 2023 16:04:10 -0000
"Günter Milde" via Docutils-develop
<doc...@li...> wrote:

> * Embed SVG images directly, not as data URI .
>    +1 Allows interactive SVG images (cf. [feature-requests:#100]).
>    +1 Smaller image size.

I don't understand "Smaller image size".  Embedding SVG directly
into HTML5 pages makes each page larger, and because the SVG
is not referenced as a URI the browser cannot share the
same SVG between different pages so more RAM is used
and more network bandwidth is consumed re-transferring the same
image, if the image appears on multiple pages.

(FWIW, I poked about trying to get python to wrap the
content of an SVG file's svg element and put the element's
content into a SVG group ("g" tag -- with a unique id attribute),
thereby allowing an SVG "image" tag to reference the re-written
SVG file's content.  This to allow embedded SVG in the HTML5
that uses "image" to reference a URI, thereby avoiding the 
above mentioned issues.   Per feature request #100.

I tried using the DOM parts of the stdlib to get the
xml declaration and the dtd declaration, and then
the xml.etree.ElementTree stdlib, all with a parser that
returns elements "as it goes" to avoid putting the entire
SVG file in RAM.  The idea being to re-write the xml declaration
and whatever DTD exists, then the "svg" element tag and
attributes, then construct a "enclosing group", and write
the closing "svg" tag.  But I never got the DOM part of the
parsing to work.

At this point, a dirt simple xml parser -- the complicated
part being understanding XML comments could be used to
find the point in the file where the first "svg" tag is,
might be the simplest approach.  Pluck the whole "head"
of the SVG file.  And parse backwards from the bottom to
find the closing "svg" tag.  (Even though I'd guess that
in the general case XML won't "parse backwards", how many
SVG files are going to have "unparseable" XML comments or other
"unparseable" trailing stuff that's going to prevent finding
the closing "svg" tag.)  Then write the whole middle of the
SVG to the new file, append the "bottom" part of the original
file, and you're done.

If the above kluge fails, somebody who knows the XML stdlibs
can always step in and do it right.  

Or..., just use xml.etree.ElementTree
with a regular parser, write your own XML declaration,
and be done with it.  Even loading entire SVG files into
RAM can't be that much of a big deal.  All of the above
is (premature?) optimization, undertaken because the response I got
to re-writing the SVG file so the content could be shared
via URI between pages was that the rewrite process would be "too
expensive".  (I forget the exact phrasing.  I'm unclear in 
what sense.  And it only has to be done once, unless the
timestamp on the source SVG changes.)

See also: defusedxml https://pypi.org/project/defusedxml/
)

Regards,

Karl <ko...@ka...>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein

[Docutils-develop] [docutils:feature-requests] #40 Option to embed images as data uri in rst2html

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

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

There is room for improvement:

* Embed SVG images directly, not as data URI .
   +1 Allows interactive SVG images (cf. [feature-requests:#100]).
   +1 Smaller image size.
* an option for the "image" directive overriding the configuration setting for individual images.
   +1 allows fine grained control (exclude large images, include just one image, ...).
   
Similar to the configuration setting, the directive option could also care for the 
"lazy loading" feature (cf. [feature-requests:#78]).
+1 fine grained control of lazy/eager image loading (eager loading of the images "above the fold", lazy lading of large images only, ...)
-1 While embedding/refering may become configurable for the XML and ODT writers some day, HTML5 is the only output format supporting "lazy loading". (OTOH, HTML5 is by far the most used output format...)





---

**[feature-requests:#40] Option to embed images as data uri in rst2html**

**Status:** open
**Group:** Default
**Labels:** rst2html 
**Created:** Wed Dec 03, 2014 09:43 PM UTC by Iiro Laiho
**Last Updated:** Sat Apr 03, 2021 05:11 PM UTC
**Owner:** nobody


It would be nice if rst2html had an option to embed images as base64 data uris in html files. Then you could make a single file html document that could be e.g. easily mailed as an attachment.


---

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] Admonitions and Latex

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

Dear Jérôme,

On 2023-11-24, Jérôme Carretero wrote:

> From an admonition title mytitle and class myclass and body text, the
> latex generator generates:

> \begin{DUclass}{myclass}
> \begin{DUadmonition}
> \DUtitle{mytitle}

> text

> \end{DUadmonition}
> \end{DUclass}

...

> In order to transform this
...
> I've had to do:
...
> Which I find a bit dirty. 

> Is there a better solution?

With::

  .. admonition:: mytitle 
     :class: rappel
   
     body text

I can get a custom title with the LaTeX preamble::

  \newcommand*{\DUCLASSrappel}{
    \renewcommand*{\DUtitle}[1]{\emph{Rappel: ##1}}
  }

* The re-definition is local to the environment, so you don't need to 
  save/restore the original function.

* In the nested function redefinition, the argument placeholder requires
  two hashes, ``#1`` → ``##1``!

This is described in 
https://docutils.sourceforge.io/docs/user/latex.html#titles
Attention: typos. 
   I just added a missing ``}`` and the second ``#`` in the document source.



> I seem to recall that before, the admonition title was included as an
> argument to DUadmonition, and it was easier to process. 

Yes, this change is described in
https://docutils.sourceforge.io/RELEASE-NOTES.html#release-0-18-2021-10-26

  legacy_class_functions setting default changed to "False", admonitions
  are now environments.

So, the quick and dirty fix is ``rst2latex --legacy-class-functions``.

Hope this helps,

Günter

[Docutils-develop] Admonitions and Latex

[Jérôme C. <cJ-...@zo...>]

Hi,



>From an admonition title mytitle and class myclass and body text, the
latex generator generates:

\begin{DUclass}{myclass}
\begin{DUadmonition}
\DUtitle{mytitle}

text

\end{DUadmonition}
\end{DUclass}


In order to transform this into eg:

\begin{admonitionboxmyclass}{mytitle}
text
\end{admonitionboxmyclass}


I've had to do:

\newenvironment{DUCLASSmyclass}
{
\let\oldDUtitle\DUtitle
\let\oldDUadmonition\DUadmonition
\renewenvironment{DUadmonition}{}{
        \end{admonitionboxmyclass}
}
\renewcommand{\DUtitle}[1]{%
    \begin{admonitionboxmyclass}{##1}%
}
}
{
\let\DUtitle\oldDUtitle
\let\DUadmonition\oldDUadmonition
}

Which I find a bit dirty. I seem to recall that before, the admonition
title was included as an argument to DUadmonition, and it was easier to
process. Is there a better solution?



Best regards,

-- 
Jérôme