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...>]

This markdown
~~~
this is a plain paragraph
with four consecutive lines
separated by line breaks
without any blank line in between.

```
this is a fenced code block
with four consecutive lines
separated by line breaks
without any blank line in between.
```
~~~
when entered in ReText (which uses Python-Markdown)
produces this html
~~~
<p>this is a plain paragraph<br>
with four consecutive lines<br>
separated by line breaks<br>
without any blank line in between.</p>
<pre><code>this is a fenced code block
with four consecutive lines
separated by line breaks
without any blank line in between.
</code></pre>
~~~

It puts `<br>\n` in the paragraph, but only `\n` in the`<pre>` block.
 


---

** [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:** Mon Jan 03, 2022 04:25 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] Re: #85 Enable easily-typed hard line-breaks in paragraphs.

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

This rst
~~~
this is a plain paragraph
with four consecutive lines
separated by line breaks
without any blank line in between.

::

	this is a literal block
	with four consecutive lines
	separated by line breaks
	without any blank line in between.
~~~
produces this html
~~~
<p>this is a plain paragraph<br>
with four consecutive lines<br>
separated by line breaks<br>
without any blank line in between.</p>
<pre class="literal-block">this is a literal block<br>
with four consecutive lines<br>
separated by line breaks<br>
without any blank line in between.</pre>
~~~
and of course, `<br>\n` within the `<pre>` block
causes the final render to have double-spaced lines.



---

** [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:** Mon Jan 03, 2022 03:16 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] #87 [FR] Giving type annotations to docutils

[Chris S. <chr...@us...>]

Firstly, definitely +1 in general for "inline" type annotations.

> In my experienece, type annotations are often most useful in private / internal code -- the public API is often well specified

That's an interesting take 😬
As noted in the original post, the major use-case of these type annotations are for third-party extension development, e.g. to allow for programmatic (mypy) type checking against docutils usage.
Third-party extensions should "only" care about the public API


---

** [feature-requests:#87] [FR] Giving type annotations to docutils**

**Status:** open
**Group:** Default
**Created:** Mon Jan 03, 2022 03:49 AM UTC by Adam  Turner
**Last Updated:** Mon Jan 03, 2022 03:49 AM UTC
**Owner:** nobody


*Sorry for reposting this as a feature request, I couldn't work out how to respond to Günter's post [1] through Sourceforge's web interface* 

[1]: https://sourceforge.net/p/docutils/mailman/message/37410168/

> > Hi all,
> 
> > I noticed py2 and py36- support will be dropped in the next release.
> 
> Yes, I am currently working on this, ... soon in the repository.

Günter @milde -- happy to help with this if you'd like?

> > It helps to integrate type annotations in docutils-stub package into
> > upstream.
> > I believe it helps to develop third-party extensions (including Sphinx).
> > Is there any chance to merge it into the docutils?
> 
> In my view, it would make sense to have annotations right in the "master".
> 
> This could also be used as an indicator for the public API: 
> 
> In the Docutils Backwards Compatibility Policy, we could change the
> clause about the "scope of the public API" to an "opt-in" scheme: only
> function/class interfaces with annotations belong to the stable, public
> API while not annotated function interfaces may be changed or removed in
> future versions if this helps to improve or clean up the code base.
> 
> What do other Docutils developers/contributors/users think?

In my experienece, type annotations are often most useful in private / internal code -- the public API is often well specified, and used often enough that you remember the types. Internal methods may be touched less frequently, or the code paths from caller to callee may be less clear, so type hints as a self documenting contract are really useful.

I also think that it would be useful to be explicit about the public API in docs/dev/policies.txt -- currently the scope clause links to CPython's backwards compatability rules -- I think that explicit is better than implicit here, in my opinion.

A


---

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...>]

to crossreference my reply at https://github.com/AA-Turner/docutils/pull/1#issuecomment-1003845954

A


---

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

**Status:** open
**Group:** None
**Created:** Fri Dec 31, 2021 03:16 AM UTC by Adam  Turner
**Last Updated:** Sun Jan 02, 2022 12:02 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] #87 [FR] Giving type annotations to docutils

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

---

** [feature-requests:#87] [FR] Giving type annotations to docutils**

**Status:** open
**Group:** Default
**Created:** Mon Jan 03, 2022 03:49 AM UTC by Adam  Turner
**Last Updated:** Mon Jan 03, 2022 03:49 AM UTC
**Owner:** nobody


*Sorry for reposting this as a feature request, I couldn't work out how to respond to Günter's post [1] through Sourceforge's web interface* 

[1]: https://sourceforge.net/p/docutils/mailman/message/37410168/

> > Hi all,
> 
> > I noticed py2 and py36- support will be dropped in the next release.
> 
> Yes, I am currently working on this, ... soon in the repository.

Günter @milde -- happy to help with this if you'd like?

> > It helps to integrate type annotations in docutils-stub package into
> > upstream.
> > I believe it helps to develop third-party extensions (including Sphinx).
> > Is there any chance to merge it into the docutils?
> 
> In my view, it would make sense to have annotations right in the "master".
> 
> This could also be used as an indicator for the public API: 
> 
> In the Docutils Backwards Compatibility Policy, we could change the
> clause about the "scope of the public API" to an "opt-in" scheme: only
> function/class interfaces with annotations belong to the stable, public
> API while not annotated function interfaces may be changed or removed in
> future versions if this helps to improve or clean up the code base.
> 
> What do other Docutils developers/contributors/users think?

In my experienece, type annotations are often most useful in private / internal code -- the public API is often well specified, and used often enough that you remember the types. Internal methods may be touched less frequently, or the code paths from caller to callee may be less clear, so type hints as a self documenting contract are really useful.

I also think that it would be useful to be explicit about the public API in docs/dev/policies.txt -- currently the scope clause links to CPython's backwards compatability rules -- I think that explicit is better than implicit here, in my opinion.

A


---

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.

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

> It would be ideal though if there was a docutils node class for such hard breaks, with the actual translators handling this, or open to other solutions?

I agree with Chris here -- I've had to hack in manual line breaks via a custom node type a couple of times -- line blocks aren't suitable for example in headings where you want to break over a line. 

`\\` is of course the convention in TeX for a break at any point -- perhaps the same could be adopted for Docutils, instead of just a backslash at the end of the line?


---

** [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:** Mon Jan 03, 2022 03:13 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] Re: #85 Enable easily-typed hard line-breaks in paragraphs.

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

Do you have a minimal reproducer of it not working? I used your introductory post locally to write the above & it worked for me!

A


---

** [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:** Mon Jan 03, 2022 12: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] Re: #85 Enable easily-typed hard line-breaks in paragraphs.

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

>`self.body.append("<br>\n".join(...)`

It adds  `<br>\n` in literal blocks (that get enclosed in `<pre>` tags), making extra blank lines where they're not wanted, as well as doing the right thing in paragraphs.

Would it be a big job to add this functionality to docutils, such that it works only where it's needed, and it could be turned on/off by an option somewhere?

Not in a hurry, so please don't feel pressured. (Am building an app, and the documentation will come later.) Sorry I can't do it myself, but life isn't quite long enough to learn everything ;)



---

** [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:** Sun Jan 02, 2022 11:41 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.

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

Günter Milde wrote:
>I would not like to read a novel with "semantic line breaks".

Neither would I.  :)

Not *everything* I write has semantic breaks,
but in explanatory writing, I think they can help comprehension,
when combined with clear simple sentence structure.

A few lines I wrote yesterday provide a good *example* of how I use them,
as well as being a *description* of how I use them:

>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. 

And of course, as you can see in my messages,
where a semantic break can be made at a reasonable line length,
I make it, rather than make a non-semantic break a few words later.
This is second nature to me now, not much extra thought is required.

I'm not too keen on the idea of "semantic empty lines",
as I hope to be able to write in the way that comes to me naturally,
without thinking about extra artifice to  achieve the desired result.

Very short paragraphs are common in punchy journalistic writing,
but that style doesn't often suit my subject matter.

Thanks anyway.  :)



---

** [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:** Sun Jan 02, 2022 12:19 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...>]

On 2022-01-02, jon via Docutils-develop wrote in gmane.text.docutils.devel:

> [-- Type: text/plain, Encoding: 7bit --]

> I've just re-read it, and realized that he's talking about line breaks
> in the **source**.
> He doesn't suggest line-breaking the rendered output in that way.

I agree with https://sembr.org/, that for the end-user (reader),
block paragraphs provide for a better reading experience.

I would not like to read a novel with "semantic line breaks".

***************************

Besides a custom writer to keep original line-breaks in HTML, you may also
consider "semantic empty lines" in your source:

Place an emty line after each sentence and a transition at the more
prominent breaks.

Use a custom style-sheet to remove the additional vertical space
between paragraphs and to style the "transition" element as
an empty block.

Then, this example would look similar to
two paragraphs with semantic line breaks after each sentence.




---

** [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:** Sun Jan 02, 2022 12:19 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: #86 Replace recommonmark with myst-docutils

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

> I would prefer docutils itself did not override the
> `myst_parser.docutils_.Parser` (as it does for the recommonmark parser)
> and instead any required changes/improvements were implemented directly
> in myst-parser.

Agreed. So we may close the ticket as "open-fixed"?

> For the "markdown"/"commonmark" alias, I would certainly be for it
> using myst-parser, but note that this would currently be equivalent to:
> `docutils-cli.py --parser=myst --myst-commonmark-only=yes`.

This would require a (light) "parser wrapper" for commonmark that sets the
"myst_commonmark_only" setting default to `True`.


---

** [feature-requests:#86] Replace recommonmark with myst-docutils**

**Status:** open
**Group:** Default
**Created:** Sun Jan 02, 2022 01:26 PM UTC by Chris Sewell
**Last Updated:** Sun Jan 02, 2022 04:53 PM UTC
**Owner:** nobody


Hey guys,

As discussed in https://github.com/readthedocs/recommonmark/issues/221, recommonmark has been officially deprecated in favour of https://github.com/executablebooks/MyST-Parser/.

In myst-parser v0.16, I added first-class support for direct docutils use (as opposed to via sphinx) and introduced the parallel https://pypi.org/project/myst-docutils/ distribution, which is myst-parser but without explicit install requirements on docutils or sphinx, i.e. you can install myst-docutils with any version of docutils and it will work without sphinx installed.

receive(see https://github.com/executablebooks/MyST-Parser/blob/master/CHANGELOG.md#0160---2021-12-06, https://github.com/executablebooks/MyST-Parser/issues/347, and https://myst-parser.readthedocs.io/en/latest/docutils.html) 
receive
receiveIn the master branch (and soon to be myst-docutils v0.17) I have also been working to improve the rigour of the behaviour/testing against this parser.
(as an example, I believe your current recommonmark solution does not actually work properly with code fences, because it does not syntax highlight the code, see: https://github.com/executablebooks/MyST-Parser/pull/478)

The fixture test sets, essentially provide a full specification of the Markdown -> docutils AST conversion (pre-docutils-transforms):

- https://raw.githubusercontent.com/executablebooks/MyST-Parser/master/tests/test_renderers/fixtures/docutil_syntax_elements.md
- https://raw.githubusercontent.com/executablebooks/MyST-Parser/master/tests/test_renderers/fixtures/docutil_roles.md
-  https://raw.githubusercontent.com/executablebooks/MyST-Parser/master/tests/test_renderers/fixtures/docutil_directives.md

and are currently tested in the CI for myst-docutils against docutils v0.16, v0.17 and v0.18: https://github.com/executablebooks/MyST-Parser/runs/4670995311?check_suite_focus=true

I'm also happy to recieve any feedback /  improvement suggestions to facilitate this, and have opened a parallel discussion topic here: https://github.com/executablebooks/MyST-Parser/discussions/487

Cheer,
Chris



---

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] #86 Replace recommonmark with myst-docutils

[Clément Pit-C. <cre...@us...>]

Just a note to say congratulations on this, folks.  I'm excited to see MyST become a first-class citizen of the Docutils ecosystem :)


---

** [feature-requests:#86] Replace recommonmark with myst-docutils**

**Status:** open
**Group:** Default
**Created:** Sun Jan 02, 2022 01:26 PM UTC by Chris Sewell
**Last Updated:** Sun Jan 02, 2022 04:12 PM UTC
**Owner:** nobody


Hey guys,

As discussed in https://github.com/readthedocs/recommonmark/issues/221, recommonmark has been officially deprecated in favour of https://github.com/executablebooks/MyST-Parser/.

In myst-parser v0.16, I added first-class support for direct docutils use (as opposed to via sphinx) and introduced the parallel https://pypi.org/project/myst-docutils/ distribution, which is myst-parser but without explicit install requirements on docutils or sphinx, i.e. you can install myst-docutils with any version of docutils and it will work without sphinx installed.

receive(see https://github.com/executablebooks/MyST-Parser/blob/master/CHANGELOG.md#0160---2021-12-06, https://github.com/executablebooks/MyST-Parser/issues/347, and https://myst-parser.readthedocs.io/en/latest/docutils.html) 
receive
receiveIn the master branch (and soon to be myst-docutils v0.17) I have also been working to improve the rigour of the behaviour/testing against this parser.
(as an example, I believe your current recommonmark solution does not actually work properly with code fences, because it does not syntax highlight the code, see: https://github.com/executablebooks/MyST-Parser/pull/478)

The fixture test sets, essentially provide a full specification of the Markdown -> docutils AST conversion (pre-docutils-transforms):

- https://raw.githubusercontent.com/executablebooks/MyST-Parser/master/tests/test_renderers/fixtures/docutil_syntax_elements.md
- https://raw.githubusercontent.com/executablebooks/MyST-Parser/master/tests/test_renderers/fixtures/docutil_roles.md
-  https://raw.githubusercontent.com/executablebooks/MyST-Parser/master/tests/test_renderers/fixtures/docutil_directives.md

and are currently tested in the CI for myst-docutils against docutils v0.16, v0.17 and v0.18: https://github.com/executablebooks/MyST-Parser/runs/4670995311?check_suite_focus=true

I'm also happy to recieve any feedback /  improvement suggestions to facilitate this, and have opened a parallel discussion topic here: https://github.com/executablebooks/MyST-Parser/discussions/487

Cheer,
Chris



---

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] #86 Replace recommonmark with myst-docutils

[Chris S. <chr...@us...>]

That great cheers, indeed the aliases are the main thing here:
I would prefer docutils itself did not override the `myst_parser.docutils_.Parser` (as it does for the recommonmark parser)  and instead any required changes/improvements were implemented directly in myst-parser.

Obviously, I will leave it up to you guys, as to any testing you want to include directly in docutils.

For the "markdown"/"commonmark" alias, I would certainly be for it using myst-parser, but note that this would currently be equivalent to: `docutils-cli.py --parser=myst --myst-commonmark-only=yes`.
This "turns off" any syntax that is not strictly part of https://spec.commonmark.org/0.30/, such as tables and footnotes.
(you can see the implementation logic at: https://github.com/executablebooks/MyST-Parser/blob/0f2902ab5eb6236805ed24dc387b34c00fe41744/myst_parser/main.py#L226)
There could perhaps be a slight override for this.

Similarly, it might be interesting to note that the Github Flavoured Markdown spec: https://github.github.com/gfm/, is roughly equivalent to: `docutils-cli.py --parse=myst --myst-enable-extensions=linkify,tasklist --myst-disable_syntax=footnote_ref,footnote_def`.
The only thing that cannot be replicated from that spec currently is strikethrough: it is available in the markdown-it parser, but docutils does not have any native node class to support it :(



---

** [feature-requests:#86] Replace recommonmark with myst-docutils**

**Status:** open
**Group:** Default
**Created:** Sun Jan 02, 2022 01:26 PM UTC by Chris Sewell
**Last Updated:** Sun Jan 02, 2022 01:29 PM UTC
**Owner:** nobody


Hey guys,

As discussed in https://github.com/readthedocs/recommonmark/issues/221, recommonmark has been officially deprecated in favour of https://github.com/executablebooks/MyST-Parser/.

In myst-parser v0.16, I added first-class support for direct docutils use (as opposed to via sphinx) and introduced the parallel https://pypi.org/project/myst-docutils/ distribution, which is myst-parser but without explicit install requirements on docutils or sphinx, i.e. you can install myst-docutils with any version of docutils and it will work without sphinx installed.

receive(see https://github.com/executablebooks/MyST-Parser/blob/master/CHANGELOG.md#0160---2021-12-06, https://github.com/executablebooks/MyST-Parser/issues/347, and https://myst-parser.readthedocs.io/en/latest/docutils.html) 
receive
receiveIn the master branch (and soon to be myst-docutils v0.17) I have also been working to improve the rigour of the behaviour/testing against this parser.
(as an example, I believe your current recommonmark solution does not actually work properly with code fences, because it does not syntax highlight the code, see: https://github.com/executablebooks/MyST-Parser/pull/478)

The fixture test sets, essentially provide a full specification of the Markdown -> docutils AST conversion (pre-docutils-transforms):

- https://raw.githubusercontent.com/executablebooks/MyST-Parser/master/tests/test_renderers/fixtures/docutil_syntax_elements.md
- https://raw.githubusercontent.com/executablebooks/MyST-Parser/master/tests/test_renderers/fixtures/docutil_roles.md
-  https://raw.githubusercontent.com/executablebooks/MyST-Parser/master/tests/test_renderers/fixtures/docutil_directives.md

and are currently tested in the CI for myst-docutils against docutils v0.16, v0.17 and v0.18: https://github.com/executablebooks/MyST-Parser/runs/4670995311?check_suite_focus=true

I'm also happy to recieve any feedback /  improvement suggestions to facilitate this, and have opened a parallel discussion topic here: https://github.com/executablebooks/MyST-Parser/discussions/487

Cheer,
Chris



---

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: #86 Replace recommonmark with myst-docutils

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

Since [r8916], "myst" is a parser alias that points to the module
`myst_parser.docutils_`. You can use, e.g., 
`docutils-cli.py --parser=myst` to parse MyST Markdown input.

Docutils' config documentation links from the section
https://docutils.sourceforge.io/docs/user/config.html#myst-parser
to the upstream documentation.

I am not in favour of removing "recommonmark" support as long as
"recommonmark" is widely available (e.g. as Debian package).

We may consider changing the "commonmark" and "markdown" parser aliases to
a wrapper module that selects whichever of "myst" or "recommonmark" is
installed at the user's system.

Is there anything else that would be better done on the Docutils side?



---

** [feature-requests:#86] Replace recommonmark with myst-docutils**

**Status:** open
**Group:** Default
**Created:** Sun Jan 02, 2022 01:26 PM UTC by Chris Sewell
**Last Updated:** Sun Jan 02, 2022 01:29 PM UTC
**Owner:** nobody


Hey guys,

As discussed in https://github.com/readthedocs/recommonmark/issues/221, recommonmark has been officially deprecated in favour of https://github.com/executablebooks/MyST-Parser/.

In myst-parser v0.16, I added first-class support for direct docutils use (as opposed to via sphinx) and introduced the parallel https://pypi.org/project/myst-docutils/ distribution, which is myst-parser but without explicit install requirements on docutils or sphinx, i.e. you can install myst-docutils with any version of docutils and it will work without sphinx installed.

receive(see https://github.com/executablebooks/MyST-Parser/blob/master/CHANGELOG.md#0160---2021-12-06, https://github.com/executablebooks/MyST-Parser/issues/347, and https://myst-parser.readthedocs.io/en/latest/docutils.html) 
receive
receiveIn the master branch (and soon to be myst-docutils v0.17) I have also been working to improve the rigour of the behaviour/testing against this parser.
(as an example, I believe your current recommonmark solution does not actually work properly with code fences, because it does not syntax highlight the code, see: https://github.com/executablebooks/MyST-Parser/pull/478)

The fixture test sets, essentially provide a full specification of the Markdown -> docutils AST conversion (pre-docutils-transforms):

- https://raw.githubusercontent.com/executablebooks/MyST-Parser/master/tests/test_renderers/fixtures/docutil_syntax_elements.md
- https://raw.githubusercontent.com/executablebooks/MyST-Parser/master/tests/test_renderers/fixtures/docutil_roles.md
-  https://raw.githubusercontent.com/executablebooks/MyST-Parser/master/tests/test_renderers/fixtures/docutil_directives.md

and are currently tested in the CI for myst-docutils against docutils v0.16, v0.17 and v0.18: https://github.com/executablebooks/MyST-Parser/runs/4670995311?check_suite_focus=true

I'm also happy to recieve any feedback /  improvement suggestions to facilitate this, and have opened a parallel discussion topic here: https://github.com/executablebooks/MyST-Parser/discussions/487

Cheer,
Chris



---

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] Giving type annotations to docutils

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

Dear Takeshi KOMIYA, dear Docutils developers,

On 2022-01-02, Komiya Takeshi wrote:
> Hi all,

> I noticed py2 and py36- support will be dropped in the next release.

Yes, I am currently working on this, ... soon in the repository.

> It helps to integrate type annotations in docutils-stub package into
> upstream.
> I believe it helps to develop third-party extensions (including Sphinx).
> Is there any chance to merge it into the docutils?

In my view, it would make sense to have annotations right in the "master".

This could also be used as an indicator for the public API: 

In the `Docutils Backwards Compatibility Policy`__, we could change the
clause about the "scope of the public API" to an "opt-in" scheme: only
function/class interfaces with annotations belong to the stable, public
API while not annotated function interfaces may be changed or removed in
future versions if this helps to improve or clean up the code base.

What do other Docutils developers/contributors/users think?

Thanks,

Günter


__ https://docutils.sourceforge.io/docs/dev/policies.html#backwards-compatibility-policy

[Docutils-develop] [docutils:feature-requests] #86 Replace recommonmark with myst-docutils

[Chris S. <chr...@us...>]

As an aside, I am also working on propagating this first-class docutis support to https://github.com/executablebooks/MyST-NB, so you can do e.g. `mystnb-docutils-pseudoxml --report="info" --nb-execution-mode=cache tests/notebooks/basic_unrun.ipynb`, but more on that at a later date :)


---

** [feature-requests:#86] Replace recommonmark with myst-docutils**

**Status:** open
**Group:** Default
**Created:** Sun Jan 02, 2022 01:26 PM UTC by Chris Sewell
**Last Updated:** Sun Jan 02, 2022 01:26 PM UTC
**Owner:** nobody


Hey guys,

As discussed in https://github.com/readthedocs/recommonmark/issues/221, recommonmark has been officially deprecated in favour of https://github.com/executablebooks/MyST-Parser/.

In myst-parser v0.16, I added first-class support for direct docutils use (as opposed to via sphinx) and introduced the parallel https://pypi.org/project/myst-docutils/ distribution, which is myst-parser but without explicit install requirements on docutils or sphinx, i.e. you can install myst-docutils with any version of docutils and it will work without sphinx installed.

receive(see https://github.com/executablebooks/MyST-Parser/blob/master/CHANGELOG.md#0160---2021-12-06, https://github.com/executablebooks/MyST-Parser/issues/347, and https://myst-parser.readthedocs.io/en/latest/docutils.html) 
receive
receiveIn the master branch (and soon to be myst-docutils v0.17) I have also been working to improve the rigour of the behaviour/testing against this parser.
(as an example, I believe your current recommonmark solution does not actually work properly with code fences, because it does not syntax highlight the code, see: https://github.com/executablebooks/MyST-Parser/pull/478)

The fixture test sets, essentially provide a full specification of the Markdown -> docutils AST conversion (pre-docutils-transforms):

- https://raw.githubusercontent.com/executablebooks/MyST-Parser/master/tests/test_renderers/fixtures/docutil_syntax_elements.md
- https://raw.githubusercontent.com/executablebooks/MyST-Parser/master/tests/test_renderers/fixtures/docutil_roles.md
-  https://raw.githubusercontent.com/executablebooks/MyST-Parser/master/tests/test_renderers/fixtures/docutil_directives.md

and are currently tested in the CI for myst-docutils against docutils v0.16, v0.17 and v0.18: https://github.com/executablebooks/MyST-Parser/runs/4670995311?check_suite_focus=true

I'm also happy to recieve any feedback /  improvement suggestions to facilitate this, and have opened a parallel discussion topic here: https://github.com/executablebooks/MyST-Parser/discussions/487

Cheer,
Chris



---

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] #86 Replace recommonmark with myst-docutils

[Chris S. <chr...@us...>]

---

** [feature-requests:#86] Replace recommonmark with myst-docutils**

**Status:** open
**Group:** Default
**Created:** Sun Jan 02, 2022 01:26 PM UTC by Chris Sewell
**Last Updated:** Sun Jan 02, 2022 01:26 PM UTC
**Owner:** nobody


Hey guys,

As discussed in https://github.com/readthedocs/recommonmark/issues/221, recommonmark has been officially deprecated in favour of https://github.com/executablebooks/MyST-Parser/.

In myst-parser v0.16, I added first-class support for direct docutils use (as opposed to via sphinx) and introduced the parallel https://pypi.org/project/myst-docutils/ distribution, which is myst-parser but without explicit install requirements on docutils or sphinx, i.e. you can install myst-docutils with any version of docutils and it will work without sphinx installed.

receive(see https://github.com/executablebooks/MyST-Parser/blob/master/CHANGELOG.md#0160---2021-12-06, https://github.com/executablebooks/MyST-Parser/issues/347, and https://myst-parser.readthedocs.io/en/latest/docutils.html) 
receive
receiveIn the master branch (and soon to be myst-docutils v0.17) I have also been working to improve the rigour of the behaviour/testing against this parser.
(as an example, I believe your current recommonmark solution does not actually work properly with code fences, because it does not syntax highlight the code, see: https://github.com/executablebooks/MyST-Parser/pull/478)

The fixture test sets, essentially provide a full specification of the Markdown -> docutils AST conversion (pre-docutils-transforms):

- https://raw.githubusercontent.com/executablebooks/MyST-Parser/master/tests/test_renderers/fixtures/docutil_syntax_elements.md
- https://raw.githubusercontent.com/executablebooks/MyST-Parser/master/tests/test_renderers/fixtures/docutil_roles.md
-  https://raw.githubusercontent.com/executablebooks/MyST-Parser/master/tests/test_renderers/fixtures/docutil_directives.md

and are currently tested in the CI for myst-docutils against docutils v0.16, v0.17 and v0.18: https://github.com/executablebooks/MyST-Parser/runs/4670995311?check_suite_focus=true

I'm also happy to recieve any feedback /  improvement suggestions to facilitate this, and have opened a parallel discussion topic here: https://github.com/executablebooks/MyST-Parser/discussions/487

Cheer,
Chris



---

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.

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

i think i use similar structure which results in hanging indents on longer sentences that would have no line break before the paper margin. mainly i make bullet lists without bullets.
i would suggest not using <br> but putting each line in a <div> ... 


---

** [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:** Sun Jan 02, 2022 12:16 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] #85 Enable easily-typed hard line-breaks in paragraphs.

[Chris S. <chr...@us...>]

I would note that myst-parser (Markdown to docutils parser), uses markdown-it which captures soft and hard break tokens (hard-breaks are denoted by a backslash, see: https://spec.commonmark.org/0.17/#hard-line-breaks, and you can test it out in https://markdown-it.github.io).
At present, it turns hard breaks into "raw" `<br>` for HTML and `\\n` for latex: https://github.com/executablebooks/MyST-Parser/blob/885651fc4e25dbac414c20cfe8fe3232ba4e833b/myst_parser/docutils_renderer.py#L403-L408, since I didn't see a better way
It would be ideal though if there was a docutils node class for such hard breaks, with the actual translators handling this, or open to other solutions?


---

** [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:** Sun Jan 02, 2022 10:11 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...>]

strictly speaking : this patch changes the command line API, removing commands, so it can only be applied in a major version change, really ?
Removing commands will break a lot of scripts.
I understand https://blog.ganssle.io/articles/2021/10/setup-py-deprecated.html sees the same problem

> When you move away from direct setup.py invocations (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)

So my plan is to apply this piecewise, leave commands (the work to keep setup.* and pyproject.toml is mine anyway) AND keep the discussion assume to be nudged now and then.
 



---

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

**Status:** open
**Group:** None
**Created:** Fri Dec 31, 2021 03:16 AM UTC by Adam  Turner
**Last Updated:** Sun Jan 02, 2022 12:07 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...>]

Wow, that's great. Thanks Adam.
I had been playing with srt in [ReText](https://github.com/retext-project/retext), and didn't think to look in the HTML source.


---

** [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:** Sun Jan 02, 2022 08:53 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.

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

Hi Jon,

Docutils preserves line breaks throughout the processing pipeline. You can see this if you view the source of generated HTML documents. To turn them into rendered documents in html, you can use a custom writer that replaces `\n` characters with `<br>` elements, as the below sketch illustrates.

```python
from pathlib import Path

from docutils.core import publish_string
from docutils.writers import html5_polyglot


class Writer(html5_polyglot.Writer):
    def __init__(self):
        super().__init__()
        self.translator_class = LineBreakTranslator


class LineBreakTranslator(html5_polyglot.HTMLTranslator):
    def visit_Text(self, node):
        self.body.append("<br>\n".join(self.encode(node.astext()).splitlines()))


def publish_preserving_line_breaks(path: Path):
    out_text = publish_string(
        path.read_text(encoding="utf-8"),
        writer=Writer(),
        settings_overrides={"output_encoding": "unicode"})
    path.with_suffix(".html").write_text(out_text, encoding="utf-8")


if __name__ == '__main__':
    publish_preserving_line_breaks(Path("line-breaks.rst"))
```

A


---

** [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:** Sun Jan 02, 2022 01:49 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.

Re: [Docutils-develop] Giving type annotations to docutils

[Komiya T. <i.t...@gm...>]

Hi all,

I noticed py2 and py36- support will be dropped in the next release.
It helps to integrate type annotations in docutils-stub package into
upstream.
I believe it helps to develop third-party extensions (including Sphinx).
Is there any chance to merge it into the docutils?

Thanks,
Takeshi KOMIYA

2018年10月13日(土) 13:50 Komiya Takeshi <i.t...@gm...>:
>
> Hi all,
>
> After a half year, finally, I and @cocoatomo finished to give type
> annotations to docutils.
> I'd like to publish them ASAP. I think it is better if docutils
> package contains them because
> the synchronize of code and annotation is important. So they should be
> maintained at same place.
> But, if you're not interested in, I'd like to maintain it from myside.
>
> What do you think?
>
> Thanks,
> Takeshi KOMIYA
>
> 2018年3月14日(水) 23:10 Komiya Takeshi <i.t...@gm...>:
> >
> > Hi developers,
> >
> > Now I and @cocoatomo started to make type stubs for docutils on
> > typeshed project. typeshed is a collection of type annotations (type
> > hints) for many libraries.
> > https://github.com/tk0miya/typeshed
> >
> > At present, typeshed library contains type annotations for docutils.
> > But it is broken. As a result, mypy, a well known type checker, fails
> > to inspect typing source codes using docutils.
> > https://github.com/python/typeshed/issues/1269
> >
> > Our goal is to provide correct type annotations to docutils. I think
> > there are two ways to do that. The first one is update type stubs on
> > typeshed project. Another one is add type annotations into docutils
> > itself. What do you think?
> >
> > Thanks,
> > Takeshi KOMIYA

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

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

Hi, Engelbert suggested I open a PR for another patch so I'm doing the same here. 

Please see https://github.com/AA-Turner/docutils/pull/2 for referenece, or https://github.com/AA-Turner/docutils/pull/2.diff for the full diff to apply locally.

A


---

** [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:** Thu Dec 30, 2021 11:29 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:feature-requests] Re: #85 Enable easily-typed hard line-breaks in paragraphs.

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

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

I've just re-read it, and realized that he's talking about line breaks in the **source**.
He doesn't suggest line-breaking the rendered output in that way.
So it looks like I'm on my own with this ...  :)



---

** [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:** Sun Jan 02, 2022 01:31 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.