docutils-develop — For developer discussions of the implementation.

[Docutils-develop] [docutils:feature-requests] Re: #85 Enable easily-typed hard line-breaks in paragraphs.

[jon <j7...@us...>]

Thanks for the awk tip.

> paragraphs and sentences

I break lines on sentence breaks, 
sometimes on phrase breaks within sentences,
and sometimes just to make line lengths close to equal.

I don't like to let line-breaking be *semantically* random,
as it is when allowed to wrap to whatever the page width is. 

Have you seen https://bobheadxi.dev/semantic-line-breaks/ ?
It provides another reason to accept line breaks as intentional, and preserve them.

> justified paragraphs

I'd forgotten about them.   ;-)
As to ***why*** reST and Markdown remove line-breaks from paragraphs,
I guess they assume the breaks were inserted to conform to the editor's page width,
and remove them to let the paragraph soft-wrap to the width of any target.
I can't think of any other reason.

> chicago manual of style

(off topic)
It's a guide for writing **academic** works for Chicago university.
In the USA, many people think it should be applied to all English writing,
but I believe that's a mistaken view, as it's not suitable for other kinds of writing.



---

** [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:** Sat Jan 01, 2022 12:51 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:patches] Re: #186 Modernise packaging

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

OK I have created a PR at https://github.com/AA-Turner/docutils/pull/1

You can see the unified diff by putting `.diff` or `.patch` on the end of the PR url, e.g. 
https://github.com/AA-Turner/docutils/pull/1.diff

I pinged `@grubert` on GitHub which seems to be you!

A


---

** [patches:#186] Modernise packaging**

**Status:** open
**Group:** None
**Created:** Fri Dec 31, 2021 03:16 AM UTC by Adam  Turner
**Last Updated:** Sat Jan 01, 2022 11:54 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Use-flit-and-pyproject.toml.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0001-Use-flit-and-pyproject.toml.patch) (12.2 kB; application/octet-stream)
- [0002-Use-entry-points.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0002-Use-entry-points.patch) (20.7 kB; application/octet-stream)
- [0003-update-docs-etc-after-packaging-changes.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0003-update-docs-etc-after-packaging-changes.patch) (49.3 kB; application/octet-stream)


Hi,

I had a go at modernising the packaging stack. `setup.py` based invocations have been deprecated (https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html), and setuptools may remove them in the future. 

This takes the opportunity to move to a PEP 621 based declarative config, and also fixes a longstanding TODO item about providing script wappers for the frontend tools on windows, by migrating them to entry points.

I've updated install and development docs with the new guidance, and updated references to the frontend tools to remove `.py`, given they are now installed as proper scripts.

Hope this is appreciated -- happy to make revisions etc to help getting this merged.

A


---

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

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

[Docutils-develop] [docutils:patches] #186 Modernise packaging

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

> I just want to ponder and assume your patch will be applied.

No worries, I appreciate python packaging isn't the easiest thing (or the most fun!).

You're right that removing `setup.py` is not mandatory. However it only makes sense to keep it if the "build backend" is kept as setuptools. One of the advantages of flit is that it does a lot less (only pacakges pure python projects like Docutils, no C complier integration etc), so there's less to go wrong. It is also an official Python Packaging Authority project (https://github.com/pypa/flit/), and has been recommended by python  core developers. 

A


---

** [patches:#186] Modernise packaging**

**Status:** open
**Group:** None
**Created:** Fri Dec 31, 2021 03:16 AM UTC by Adam  Turner
**Last Updated:** Sat Jan 01, 2022 05:20 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Use-flit-and-pyproject.toml.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0001-Use-flit-and-pyproject.toml.patch) (12.2 kB; application/octet-stream)
- [0002-Use-entry-points.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0002-Use-entry-points.patch) (20.7 kB; application/octet-stream)
- [0003-update-docs-etc-after-packaging-changes.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0003-update-docs-etc-after-packaging-changes.patch) (49.3 kB; application/octet-stream)


Hi,

I had a go at modernising the packaging stack. `setup.py` based invocations have been deprecated (https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html), and setuptools may remove them in the future. 

This takes the opportunity to move to a PEP 621 based declarative config, and also fixes a longstanding TODO item about providing script wappers for the frontend tools on windows, by migrating them to entry points.

I've updated install and development docs with the new guidance, and updated references to the frontend tools to remove `.py`, given they are now installed as proper scripts.

Hope this is appreciated -- happy to make revisions etc to help getting this merged.

A


---

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

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

[Docutils-develop] [docutils:patches] Re: #186 Modernise packaging

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

I just want to ponder and assume your patch will be applied. But as docutils is older than setuptools we might have to consider things they do not ... somewhere in the blogpost linux distribution packagers are mentioned and then there is the sentence 
> note: this does not mean removing setup.py entirely or switching away from setuptools, it just means that you change all your scripts and documentation to tell people not to do this

I like it :-) 


---

** [patches:#186] Modernise packaging**

**Status:** open
**Group:** None
**Created:** Fri Dec 31, 2021 03:16 AM UTC by Adam  Turner
**Last Updated:** Sat Jan 01, 2022 05:16 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Use-flit-and-pyproject.toml.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0001-Use-flit-and-pyproject.toml.patch) (12.2 kB; application/octet-stream)
- [0002-Use-entry-points.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0002-Use-entry-points.patch) (20.7 kB; application/octet-stream)
- [0003-update-docs-etc-after-packaging-changes.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0003-update-docs-etc-after-packaging-changes.patch) (49.3 kB; application/octet-stream)


Hi,

I had a go at modernising the packaging stack. `setup.py` based invocations have been deprecated (https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html), and setuptools may remove them in the future. 

This takes the opportunity to move to a PEP 621 based declarative config, and also fixes a longstanding TODO item about providing script wappers for the frontend tools on windows, by migrating them to entry points.

I've updated install and development docs with the new guidance, and updated references to the frontend tools to remove `.py`, given they are now installed as proper scripts.

Hope this is appreciated -- happy to make revisions etc to help getting this merged.

A


---

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

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

[Docutils-develop] [docutils:patches] Re: #186 Modernise packaging

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

yes I would like to try it from a git mirror, what could go wrong :-)


---

** [patches:#186] Modernise packaging**

**Status:** open
**Group:** None
**Created:** Fri Dec 31, 2021 03:16 AM UTC by Adam  Turner
**Last Updated:** Sat Jan 01, 2022 01:22 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Use-flit-and-pyproject.toml.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0001-Use-flit-and-pyproject.toml.patch) (12.2 kB; application/octet-stream)
- [0002-Use-entry-points.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0002-Use-entry-points.patch) (20.7 kB; application/octet-stream)
- [0003-update-docs-etc-after-packaging-changes.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0003-update-docs-etc-after-packaging-changes.patch) (49.3 kB; application/octet-stream)


Hi,

I had a go at modernising the packaging stack. `setup.py` based invocations have been deprecated (https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html), and setuptools may remove them in the future. 

This takes the opportunity to move to a PEP 621 based declarative config, and also fixes a longstanding TODO item about providing script wappers for the frontend tools on windows, by migrating them to entry points.

I've updated install and development docs with the new guidance, and updated references to the frontend tools to remove `.py`, given they are now installed as proper scripts.

Hope this is appreciated -- happy to make revisions etc to help getting this merged.

A


---

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

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

[Docutils-develop] [docutils:patches] #186 Modernise packaging

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

> who might get in trouble if setup.py and install.py is missing

`install.py` is noted in the docs as just a hack for windows -- I'm writing this on a windows PC & have done all my testing on one, so no issues there!

As noted in Paul Ganssle's blog[1], `python -m build` is the recommended method for the future. Distribution packagers are working to these standards now -- for example `typing_extensions`has had ~100mm downloads in the last month, and uses `flit`, as I'm proposing here. (`python-rsa` is another such example also at around 100mm per month).

The maintainers of `setuptools` (see the blog post) have indicated that they want to (intend to) deprecate usage of `setup.py install`, `setup.py build`, et cetera. I updated all the user documentation to make it clear how to build and install Docutils in the proposed build system, which hopefully eases the transition.

A

[1] https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html#summary 


---

** [patches:#186] Modernise packaging**

**Status:** open
**Group:** None
**Created:** Fri Dec 31, 2021 03:16 AM UTC by Adam  Turner
**Last Updated:** Sat Jan 01, 2022 12:30 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Use-flit-and-pyproject.toml.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0001-Use-flit-and-pyproject.toml.patch) (12.2 kB; application/octet-stream)
- [0002-Use-entry-points.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0002-Use-entry-points.patch) (20.7 kB; application/octet-stream)
- [0003-update-docs-etc-after-packaging-changes.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0003-update-docs-etc-after-packaging-changes.patch) (49.3 kB; application/octet-stream)


Hi,

I had a go at modernising the packaging stack. `setup.py` based invocations have been deprecated (https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html), and setuptools may remove them in the future. 

This takes the opportunity to move to a PEP 621 based declarative config, and also fixes a longstanding TODO item about providing script wappers for the frontend tools on windows, by migrating them to entry points.

I've updated install and development docs with the new guidance, and updated references to the frontend tools to remove `.py`, given they are now installed as proper scripts.

Hope this is appreciated -- happy to make revisions etc to help getting this merged.

A


---

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

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

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

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

IMHO. 
It is not arbitrary line breaks, other people call it paragraphs and sentences.
The non-justified paragraphs only took on because modern word processors are bad at aligning left and right.
Sorry I can not tell the depth this is ingrained in docutils.
But your request sounds unusual, we have people referencing the chicago manual of style ... now you have your own, which I consider cool, which I think is structured Text

for a start, so you can use your style, I would use awk as a preprocessor to insert double linebreaks
or add a line block character 
~~~
cat 0001-Use-flit-and-pyproject.toml.patch | awk '{print $0 "\n"}' | rst2man.py > out.man
~~~

cheers


---

** [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:** Sat Jan 01, 2022 08:41 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:patches] #186 Modernise packaging

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

and we have to think who might get in trouble if setup.py and install.py is missing.


---

** [patches:#186] Modernise packaging**

**Status:** open
**Group:** None
**Created:** Fri Dec 31, 2021 03:16 AM UTC by Adam  Turner
**Last Updated:** Sat Jan 01, 2022 12:25 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Use-flit-and-pyproject.toml.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0001-Use-flit-and-pyproject.toml.patch) (12.2 kB; application/octet-stream)
- [0002-Use-entry-points.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0002-Use-entry-points.patch) (20.7 kB; application/octet-stream)
- [0003-update-docs-etc-after-packaging-changes.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0003-update-docs-etc-after-packaging-changes.patch) (49.3 kB; application/octet-stream)


Hi,

I had a go at modernising the packaging stack. `setup.py` based invocations have been deprecated (https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html), and setuptools may remove them in the future. 

This takes the opportunity to move to a PEP 621 based declarative config, and also fixes a longstanding TODO item about providing script wappers for the frontend tools on windows, by migrating them to entry points.

I've updated install and development docs with the new guidance, and updated references to the frontend tools to remove `.py`, given they are now installed as proper scripts.

Hope this is appreciated -- happy to make revisions etc to help getting this merged.

A


---

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

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

[Docutils-develop] [docutils:patches] #186 Modernise packaging

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

No worries! 

How do I make a pull request  on sourceforge? or are you talking about via one of the git mirrors? Sorry for the confusion!

A


---

** [patches:#186] Modernise packaging**

**Status:** open
**Group:** None
**Created:** Fri Dec 31, 2021 03:16 AM UTC by Adam  Turner
**Last Updated:** Sat Jan 01, 2022 12:23 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Use-flit-and-pyproject.toml.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0001-Use-flit-and-pyproject.toml.patch) (12.2 kB; application/octet-stream)
- [0002-Use-entry-points.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0002-Use-entry-points.patch) (20.7 kB; application/octet-stream)
- [0003-update-docs-etc-after-packaging-changes.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0003-update-docs-etc-after-packaging-changes.patch) (49.3 kB; application/octet-stream)


Hi,

I had a go at modernising the packaging stack. `setup.py` based invocations have been deprecated (https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html), and setuptools may remove them in the future. 

This takes the opportunity to move to a PEP 621 based declarative config, and also fixes a longstanding TODO item about providing script wappers for the frontend tools on windows, by migrating them to entry points.

I've updated install and development docs with the new guidance, and updated references to the frontend tools to remove `.py`, given they are now installed as proper scripts.

Hope this is appreciated -- happy to make revisions etc to help getting this merged.

A


---

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

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

[Docutils-develop] [docutils:patches] #186 Modernise packaging

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

Good morning Adam,

You have the same problem as i have, unsure about future command line tools.
I am waiting  (a little) on Günter's comment, he made the new cli interface.
and am waiting (a more) on me slow thinking 

many thanks to you 
P.S. if you send me a pull request I think it is a diff in the end so I should be able to decipher


---

** [patches:#186] Modernise packaging**

**Status:** open
**Group:** None
**Created:** Fri Dec 31, 2021 03:16 AM UTC by Adam  Turner
**Last Updated:** Sat Jan 01, 2022 05:42 AM UTC
**Owner:** nobody
**Attachments:**

- [0001-Use-flit-and-pyproject.toml.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0001-Use-flit-and-pyproject.toml.patch) (12.2 kB; application/octet-stream)
- [0002-Use-entry-points.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0002-Use-entry-points.patch) (20.7 kB; application/octet-stream)
- [0003-update-docs-etc-after-packaging-changes.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0003-update-docs-etc-after-packaging-changes.patch) (49.3 kB; application/octet-stream)


Hi,

I had a go at modernising the packaging stack. `setup.py` based invocations have been deprecated (https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html), and setuptools may remove them in the future. 

This takes the opportunity to move to a PEP 621 based declarative config, and also fixes a longstanding TODO item about providing script wappers for the frontend tools on windows, by migrating them to entry points.

I've updated install and development docs with the new guidance, and updated references to the frontend tools to remove `.py`, given they are now installed as proper scripts.

Hope this is appreciated -- happy to make revisions etc to help getting this merged.

A


---

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

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

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

[jon <j7...@us...>]

Not only in paragraphs, of course, but also in list-items and definitions and anywhere else where line-breaks are usually discarded.


---

** [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:** Sat Jan 01, 2022 08:21 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] #85 Enable easily-typed hard line-breaks in paragraphs.

[jon <j7...@us...>]

---

** [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:** Sat Jan 01, 2022 08:21 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:patches] #186 Modernise packaging

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

(I can't find any way to update my patches/edit the message above similar to how one would on a pull request in GitHub or similar, so apologies for posting an entirely new message.)

I've updated the patch into what I think is a cleaner implementation, somewhat segregated into three parts.

Patches 1 and 2 now set up the minimum for a standards compliant packaging solution, and solve the issue of automatically creating executables on both unix and windows through `entry points`.

Patches 3 and 4 move the `rst*` frontends into the new `entry points` based setup (in the new `_cli` module, and update documentation to reflect both that the frontends should no longer be called with `.py`, and that the commands for building/installing Docutils have changed.

Patches 5 and 6 subsequentley deprecate the `rst*` based frontends (printing a message to the console on invocation noting what the user should run instead) and update documentation to prefer `docutils-cli` throughout as the canonical front-end tool. 

I have intentionally kept 3/4 and 5/6 distinct, as I am not sure of your opinions on deprecating the other front-end tools.

As before, all tests pass & all commands etc are usable.

(Please let me know if there's anything else that would be useful to help on -- I proposed a patch for FR#61, but I don't know what your priorities are as maintainers. Thanks!)

A


Attachments:

- [0001-Use-flit-and-pyproject.toml.patch](https://sourceforge.net/p/docutils/patches/_discuss/thread/e3c9702768/5b45/attachment/0001-Use-flit-and-pyproject.toml.patch) (11.7 kB; application/octet-stream)
- [0002-Add-docutils-cli-entry-point.patch](https://sourceforge.net/p/docutils/patches/_discuss/thread/e3c9702768/5b45/attachment/0002-Add-docutils-cli-entry-point.patch) (6.8 kB; application/octet-stream)
- [0003-Use-entry-points-for-rst-tools.patch](https://sourceforge.net/p/docutils/patches/_discuss/thread/e3c9702768/5b45/attachment/0003-Use-entry-points-for-rst-tools.patch) (24.2 kB; application/octet-stream)
- [0004-Update-docs-for-packaging-changes.patch](https://sourceforge.net/p/docutils/patches/_discuss/thread/e3c9702768/5b45/attachment/0004-Update-docs-for-packaging-changes.patch) (53.1 kB; application/octet-stream)
- [0005-Deprecate-rst-entry-points-in-favour-of-docutils-cli.patch](https://sourceforge.net/p/docutils/patches/_discuss/thread/e3c9702768/5b45/attachment/0005-Deprecate-rst-entry-points-in-favour-of-docutils-cli.patch) (4.2 kB; application/octet-stream)
- [0006-Update-documentation-to-focus-on-docutils-cli.patch](https://sourceforge.net/p/docutils/patches/_discuss/thread/e3c9702768/5b45/attachment/0006-Update-documentation-to-focus-on-docutils-cli.patch) (26.1 kB; application/octet-stream)


---

** [patches:#186] Modernise packaging**

**Status:** open
**Group:** None
**Created:** Fri Dec 31, 2021 03:16 AM UTC by Adam  Turner
**Last Updated:** Sat Jan 01, 2022 03:45 AM UTC
**Owner:** nobody
**Attachments:**

- [0001-Use-flit-and-pyproject.toml.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0001-Use-flit-and-pyproject.toml.patch) (12.2 kB; application/octet-stream)
- [0002-Use-entry-points.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0002-Use-entry-points.patch) (20.7 kB; application/octet-stream)
- [0003-update-docs-etc-after-packaging-changes.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0003-update-docs-etc-after-packaging-changes.patch) (49.3 kB; application/octet-stream)


Hi,

I had a go at modernising the packaging stack. `setup.py` based invocations have been deprecated (https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html), and setuptools may remove them in the future. 

This takes the opportunity to move to a PEP 621 based declarative config, and also fixes a longstanding TODO item about providing script wappers for the frontend tools on windows, by migrating them to entry points.

I've updated install and development docs with the new guidance, and updated references to the frontend tools to remove `.py`, given they are now installed as proper scripts.

Hope this is appreciated -- happy to make revisions etc to help getting this merged.

A


---

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

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

[Docutils-develop] [docutils:patches] #186 Modernise packaging

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

Meant to add as well -- I noticed you intend to drop support for 2.7 in a future release (https://sourceforge.net/p/docutils/code/8921/tree/trunk/docutils/RELEASE-NOTES.txt#l23). 

Is there a tracking issue for this? I'd love to help in any way I can if possible @grubert -- please do let me know!

A


---

** [patches:#186] Modernise packaging**

**Status:** open
**Group:** None
**Created:** Fri Dec 31, 2021 03:16 AM UTC by Adam  Turner
**Last Updated:** Fri Dec 31, 2021 06:36 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Use-flit-and-pyproject.toml.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0001-Use-flit-and-pyproject.toml.patch) (12.2 kB; application/octet-stream)
- [0002-Use-entry-points.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0002-Use-entry-points.patch) (20.7 kB; application/octet-stream)
- [0003-update-docs-etc-after-packaging-changes.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0003-update-docs-etc-after-packaging-changes.patch) (49.3 kB; application/octet-stream)


Hi,

I had a go at modernising the packaging stack. `setup.py` based invocations have been deprecated (https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html), and setuptools may remove them in the future. 

This takes the opportunity to move to a PEP 621 based declarative config, and also fixes a longstanding TODO item about providing script wappers for the frontend tools on windows, by migrating them to entry points.

I've updated install and development docs with the new guidance, and updated references to the frontend tools to remove `.py`, given they are now installed as proper scripts.

Hope this is appreciated -- happy to make revisions etc to help getting this merged.

A


---

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

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

[Docutils-develop] [docutils:patches] #186 Modernise packaging

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

> we are still supporting python2.7

I checked and the build system proposed generates universal wheels still -- you can tell by the `-py2.py3-` tags in the filename.

A


---

** [patches:#186] Modernise packaging**

**Status:** open
**Group:** None
**Created:** Fri Dec 31, 2021 03:16 AM UTC by Adam  Turner
**Last Updated:** Fri Dec 31, 2021 03:53 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Use-flit-and-pyproject.toml.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0001-Use-flit-and-pyproject.toml.patch) (12.2 kB; application/octet-stream)
- [0002-Use-entry-points.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0002-Use-entry-points.patch) (20.7 kB; application/octet-stream)
- [0003-update-docs-etc-after-packaging-changes.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0003-update-docs-etc-after-packaging-changes.patch) (49.3 kB; application/octet-stream)


Hi,

I had a go at modernising the packaging stack. `setup.py` based invocations have been deprecated (https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html), and setuptools may remove them in the future. 

This takes the opportunity to move to a PEP 621 based declarative config, and also fixes a longstanding TODO item about providing script wappers for the frontend tools on windows, by migrating them to entry points.

I've updated install and development docs with the new guidance, and updated references to the frontend tools to remove `.py`, given they are now installed as proper scripts.

Hope this is appreciated -- happy to make revisions etc to help getting this merged.

A


---

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

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

[Docutils-develop] [docutils:patches] #186 Modernise packaging

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

contributions very welcome

please bear with us, currently we are still supporting python2.7. trying to avoid breakage needs some checking.
nag me if you think i am to slow which i am usually

thanks again



---

** [patches:#186] Modernise packaging**

**Status:** open
**Group:** None
**Created:** Fri Dec 31, 2021 03:16 AM UTC by Adam  Turner
**Last Updated:** Fri Dec 31, 2021 03:40 AM UTC
**Owner:** nobody
**Attachments:**

- [0001-Use-flit-and-pyproject.toml.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0001-Use-flit-and-pyproject.toml.patch) (12.2 kB; application/octet-stream)
- [0002-Use-entry-points.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0002-Use-entry-points.patch) (20.7 kB; application/octet-stream)
- [0003-update-docs-etc-after-packaging-changes.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0003-update-docs-etc-after-packaging-changes.patch) (49.3 kB; application/octet-stream)


Hi,

I had a go at modernising the packaging stack. `setup.py` based invocations have been deprecated (https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html), and setuptools may remove them in the future. 

This takes the opportunity to move to a PEP 621 based declarative config, and also fixes a longstanding TODO item about providing script wappers for the frontend tools on windows, by migrating them to entry points.

I've updated install and development docs with the new guidance, and updated references to the frontend tools to remove `.py`, given they are now installed as proper scripts.

Hope this is appreciated -- happy to make revisions etc to help getting this merged.

A


---

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

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

[Docutils-develop] [docutils:patches] #186 Modernise packaging

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

A further change could be to deprecate/remove the `rst2*` tools in favour of the unified `docutils-cli` tool that was added a couple of versions ago -- this would simplifiy the command line usage space and perhaps enable further simplifications in the logic for using doctuils as a library.

If you'd like me to do this more than happy to -- I think it would be pretty simple.

A


---

** [patches:#186] Modernise packaging**

**Status:** open
**Group:** None
**Created:** Fri Dec 31, 2021 03:16 AM UTC by Adam  Turner
**Last Updated:** Fri Dec 31, 2021 03:20 AM UTC
**Owner:** nobody
**Attachments:**

- [0001-Use-flit-and-pyproject.toml.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0001-Use-flit-and-pyproject.toml.patch) (12.2 kB; application/octet-stream)
- [0002-Use-entry-points.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0002-Use-entry-points.patch) (20.7 kB; application/octet-stream)
- [0003-update-docs-etc-after-packaging-changes.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0003-update-docs-etc-after-packaging-changes.patch) (49.3 kB; application/octet-stream)


Hi,

I had a go at modernising the packaging stack. `setup.py` based invocations have been deprecated (https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html), and setuptools may remove them in the future. 

This takes the opportunity to move to a PEP 621 based declarative config, and also fixes a longstanding TODO item about providing script wappers for the frontend tools on windows, by migrating them to entry points.

I've updated install and development docs with the new guidance, and updated references to the frontend tools to remove `.py`, given they are now installed as proper scripts.

Hope this is appreciated -- happy to make revisions etc to help getting this merged.

A


---

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

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

[Docutils-develop] [docutils:patches] #186 Modernise packaging

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

The patches merged together as a full diff is also attached on this comment


Attachments:

- [packaging-update.diff](https://sourceforge.net/p/docutils/patches/_discuss/thread/e3c9702768/4dbc/attachment/packaging-update.diff) (76.3 kB; application/octet-stream)


---

** [patches:#186] Modernise packaging**

**Status:** open
**Group:** None
**Created:** Fri Dec 31, 2021 03:16 AM UTC by Adam  Turner
**Last Updated:** Fri Dec 31, 2021 03:16 AM UTC
**Owner:** nobody
**Attachments:**

- [0001-Use-flit-and-pyproject.toml.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0001-Use-flit-and-pyproject.toml.patch) (12.2 kB; application/octet-stream)
- [0002-Use-entry-points.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0002-Use-entry-points.patch) (20.7 kB; application/octet-stream)
- [0003-update-docs-etc-after-packaging-changes.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0003-update-docs-etc-after-packaging-changes.patch) (49.3 kB; application/octet-stream)


Hi,

I had a go at modernising the packaging stack. `setup.py` based invocations have been deprecated (https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html), and setuptools may remove them in the future. 

This takes the opportunity to move to a PEP 621 based declarative config, and also fixes a longstanding TODO item about providing script wappers for the frontend tools on windows, by migrating them to entry points.

I've updated install and development docs with the new guidance, and updated references to the frontend tools to remove `.py`, given they are now installed as proper scripts.

Hope this is appreciated -- happy to make revisions etc to help getting this merged.

A


---

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

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

[Docutils-develop] [docutils:patches] #186 Modernise packaging

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

---

** [patches:#186] Modernise packaging**

**Status:** open
**Group:** None
**Created:** Fri Dec 31, 2021 03:16 AM UTC by Adam  Turner
**Last Updated:** Fri Dec 31, 2021 03:16 AM UTC
**Owner:** nobody
**Attachments:**

- [0001-Use-flit-and-pyproject.toml.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0001-Use-flit-and-pyproject.toml.patch) (12.2 kB; application/octet-stream)
- [0002-Use-entry-points.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0002-Use-entry-points.patch) (20.7 kB; application/octet-stream)
- [0003-update-docs-etc-after-packaging-changes.patch](https://sourceforge.net/p/docutils/patches/186/attachment/0003-update-docs-etc-after-packaging-changes.patch) (49.3 kB; application/octet-stream)


Hi,

I had a go at modernising the packaging stack. `setup.py` based invocations have been deprecated (https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html), and setuptools may remove them in the future. 

This takes the opportunity to move to a PEP 621 based declarative config, and also fixes a longstanding TODO item about providing script wappers for the frontend tools on windows, by migrating them to entry points.

I've updated install and development docs with the new guidance, and updated references to the frontend tools to remove `.py`, given they are now installed as proper scripts.

Hope this is appreciated -- happy to make revisions etc to help getting this merged.

A


---

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

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

[Docutils-develop] [docutils:feature-requests] #61 Support for :BCP: role, similar

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

Hi Günter @milde
I'm not sure how to convert a git patch into svn, but I've attached said git diff below.

This adds an explicit ``bcp`` role, tests, and documentation.

I can also add a commit-by-commit patch, broadly I added the role, and then updated the RFC base URL, hence the larger number of files touched.

A



Attachments:

- [add-bcp.diff](https://sourceforge.net/p/docutils/feature-requests/_discuss/thread/131c6d5cc8/4bcf/attachment/add-bcp.diff) (42.2 kB; application/octet-stream)


---

** [feature-requests:#61] Support for :BCP: role, similar**

**Status:** open
**Group:** Default
**Created:** Tue Apr 09, 2019 08:46 AM UTC by Roberto Polli
**Last Updated:** Mon Aug 24, 2020 04:18 PM UTC
**Owner:** nobody


## I wish

- support for referencing IETF Best Current Practices, eg:  :BCP:`47`role 
- the processing is similar to :RFC:

## Notes

- sphinx people suggests that goes in docutils. see  https://github.com/sphinx-doc/sphinx/issues/6255 


---

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] #440 longtable labels in the wrong place

[Erik H. <eri...@us...>]

I've attached the sample table I've used. See `tables.rst`. I did use the `--reference-label ref` option to get table numbers in the references. The attached `run.sh` shows how I've run the tools.

The standard named references work fine with the `\label` after the `\end{longtable}`.  When using `\ref{}` to refer to tables however, no number shows. This only seems possible when the `\label{}` is moved near the caption or inside table body. See `tables_edited.tex` for how I'v manually edited the tex file to make it work. That is, if the table has a caption it works. For some reason I haven't been able to place a `\label{}` inside a table without a caption.

Haven't run the docutils test suite.

I guess this whole ticket boils down to how can we get numbered tables references to work?


Attachments:

- [run.sh](https://sourceforge.net/p/docutils/bugs/_discuss/thread/0d2d55e26b/d622/attachment/run.sh) (96 Bytes; application/x-shellscript)
- [tables.rst](https://sourceforge.net/p/docutils/bugs/_discuss/thread/0d2d55e26b/d622/attachment/tables.rst) (417 Bytes; text/x-rst)
- [tables.tex](https://sourceforge.net/p/docutils/bugs/_discuss/thread/0d2d55e26b/d622/attachment/tables.tex) (1.8 kB; text/x-tex)
- [tables_edited.tex](https://sourceforge.net/p/docutils/bugs/_discuss/thread/0d2d55e26b/d622/attachment/tables_edited.tex) (1.8 kB; text/x-tex)


---

** [bugs:#440] longtable labels in the wrong place**

**Status:** pending-remind
**Created:** Tue Dec 21, 2021 11:39 PM UTC by Erik Hansen
**Last Updated:** Wed Dec 29, 2021 12:46 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Move-longtable-labels-to-table-body.patch](https://sourceforge.net/p/docutils/bugs/440/attachment/0001-Move-longtable-labels-to-table-body.patch) (1.7 kB; text/x-patch)


The latex2e writer outputs `\label{}` for tables after `\end{longtable}`. This is incorrect causing the table referencing to end up with empty reference text rather than the table number. The author of the `longtable` latex package suggest putting the `\label{}` inside the caption itself  `\caption{My caption \label{mylabel}}` or inside the table body. The latter option has the added benefit of working for tables without  a caption. I've attached a proposed fix.

`longtable` package documentation can be found at https://mirror.ox.ac.uk/sites/ctan.org/macros/latex/required/tools/longtable.pdf. See page 4 and 5 about the discussion on labeling.


---

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] #440 longtable labels in the wrong place

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

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

Thank you for the report and patch.
The warning in the source (introduced 2010-02-05 in [r6255])
 
     other places (beginning, caption) result in LaTeX errors.
     
makes me hesitating to change the current behaviour. OTOH, it may be outdated.

Currently standard Docutils does not write `\ref` macros. How do you get a table number in the document?  Can you provide your test file (and info about how it is converted)?

Did you try your patch with the Docutils test suite? Here, I get `FAILED (failures=4, errors=21, skipped=1)` and a lot of  additional (spurious) labels **after** longtables.


    



---

** [bugs:#440] longtable labels in the wrong place**

**Status:** pending-remind
**Created:** Tue Dec 21, 2021 11:39 PM UTC by Erik Hansen
**Last Updated:** Wed Dec 22, 2021 04:10 AM UTC
**Owner:** nobody
**Attachments:**

- [0001-Move-longtable-labels-to-table-body.patch](https://sourceforge.net/p/docutils/bugs/440/attachment/0001-Move-longtable-labels-to-table-body.patch) (1.7 kB; text/x-patch)


The latex2e writer outputs `\label{}` for tables after `\end{longtable}`. This is incorrect causing the table referencing to end up with empty reference text rather than the table number. The author of the `longtable` latex package suggest putting the `\label{}` inside the caption itself  `\caption{My caption \label{mylabel}}` or inside the table body. The latter option has the added benefit of working for tables without  a caption. I've attached a proposed fix.

`longtable` package documentation can be found at https://mirror.ox.ac.uk/sites/ctan.org/macros/latex/required/tools/longtable.pdf. See page 4 and 5 about the discussion on labeling.


---

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

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

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

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

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

Fised in [r8919]. Thank you for the report.



---

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

**Status:** open-fixed
**Labels:** rst parser 
**Created:** Mon Oct 25, 2021 09:53 AM UTC by Dimitri Papadopoulos
**Last Updated:** Fri Nov 05, 2021 11:24 AM UTC
**Owner:** Günter Milde


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

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

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

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


---

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

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

[Docutils-develop] [docutils:bugs] #440 longtable labels in the wrong place

[Erik H. <eri...@us...>]

Btw, I'm a beginner when it comes to Latex.  Even though the proposed patch works for my test case, please double check it to ensure it produces valid Latex.


---

** [bugs:#440] longtable labels in the wrong place**

**Status:** open
**Created:** Tue Dec 21, 2021 11:39 PM UTC by Erik Hansen
**Last Updated:** Tue Dec 21, 2021 11:39 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Move-longtable-labels-to-table-body.patch](https://sourceforge.net/p/docutils/bugs/440/attachment/0001-Move-longtable-labels-to-table-body.patch) (1.7 kB; text/x-patch)


The latex2e writer outputs `\label{}` for tables after `\end{longtable}`. This is incorrect causing the table referencing to end up with empty reference text rather than the table number. The author of the `longtable` latex package suggest putting the `\label{}` inside the caption itself  `\caption{My caption \label{mylabel}}` or inside the table body. The latter option has the added benefit of working for tables without  a caption. I've attached a proposed fix.

`longtable` package documentation can be found at https://mirror.ox.ac.uk/sites/ctan.org/macros/latex/required/tools/longtable.pdf. See page 4 and 5 about the discussion on labeling.


---

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] #440 longtable labels in the wrong place

[Erik H. <eri...@us...>]

---

** [bugs:#440] longtable labels in the wrong place**

**Status:** open
**Created:** Tue Dec 21, 2021 11:39 PM UTC by Erik Hansen
**Last Updated:** Tue Dec 21, 2021 11:39 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Move-longtable-labels-to-table-body.patch](https://sourceforge.net/p/docutils/bugs/440/attachment/0001-Move-longtable-labels-to-table-body.patch) (1.7 kB; text/x-patch)


The latex2e writer outputs `\label{}` for tables after `\end{longtable}`. This is incorrect causing the table referencing to end up with empty reference text rather than the table number. The author of the `longtable` latex package suggest putting the `\label{}` inside the caption itself  `\caption{My caption \label{mylabel}}` or inside the table body. The latter option has the added benefit of working for tables without  a caption. I've attached a proposed fix.

`longtable` package documentation can be found at https://mirror.ox.ac.uk/sites/ctan.org/macros/latex/required/tools/longtable.pdf. See page 4 and 5 about the discussion on labeling.


---

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.