[Docutils-develop] [docutils:feature-requests] #88 Unify Docutils CLI tools into `docutils-cli`

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

Proposal

* Provide entry point `docutils` (done in 0.19).
* In Docutils 0.20, announce the move from `rst2*.py` scripts to `rst2*` entry points for 0.21 or later.
* For the transition, we already provide `docutils --writer=*` as stable alternative to `rst2*.py` (documented in RELEASE-NOTES since Docutils 0.20). 
* Keep the "rst2*.py" scripts, "rstpep2html.py", and "buildhtml.py" in the `tools/` directory of the repository and source package.

Rationale:

*  installing both, `rst2html` and `rst2html.py` in the binary path would complicate command line use,
*  in scripts, the increased verbosity of the stable command is no problem.
*  changing interactive usage patterns is easy
*  in Windows, it would be bad to first introduce the new "rst2*.py" entry points and then removing them again.
* users installing from the source may install selected front-ends "manually", cf. [docs/dev/repository.txt]( https://docutils.sourceforge.io/docs/dev/repository.html#editable-installs).

The attached patch provides a set of functions that are required for the `rst2*` entry points.
It could go into Docutils 0.20.


Attachments:

- [0001-New-functions-for-use-as-rst2-console_scripts-entry-.patch](https://sourceforge.net/p/docutils/feature-requests/_discuss/thread/bb8ab9be49/9314/attachment/0001-New-functions-for-use-as-rst2-console_scripts-entry-.patch) (34.7 kB; text/x-patch)


---

** [feature-requests:#88] Unify Docutils CLI tools into `docutils-cli`**

**Status:** open
**Group:** Default
**Created:** Sat Jan 15, 2022 10:11 PM UTC by Adam  Turner
**Last Updated:** Fri May 20, 2022 05:53 PM UTC
**Owner:** nobody


As noted at https://sourceforge.net/p/docutils/patches/186/?page=1#897a/547e/ef2d by @milde, 
> we should open a new ticket for the command line tool review

This is a tracker issue for this, and to allow discussion. 

I'll briefly re-outline my argument to (eventually) drop the `rst*` front-end tools, and only export `docutils-cli` (or `python -m docutils`). 

> I think a single front-end tool significantly simplifies a lot of things -- the docutils-cli wrapper is not complex, which gives it significant points in favour in my book.

> Most usage of Docutils today is programmatic, and not via the command line tools (see the table at the bottom of this post - it shows all the projects that have a full dependency on Docutils with over 500k downloads in the last month. Of those 8, none use the command line tools)

> I also suspect (although the data does not exist) that most command line uses of the Docutils tools will be rst2html(5). This is already the default in docutils-cli, so it is a drop-in replacement.

> ...

>  My proposal isn't to remove them *\[the rst2 front-end tools\]* with no recourse, but to deprecate over a period of time, clearly marking identical drop-in commands at runtime to affected users. ... We cannot know how many people would be affected with local random scripts, but it is a two-second change.

> Many users will also run with old or pinned versions of Docutils, and part of updating is seeing the changelog. If Debian or other redistributors already make changes, they could decide to keep shell aliases from rst2* to the new docutils-cli based invocations. 

(quotes taken from https://sourceforge.net/p/docutils/patches/186/#897a and https://sourceforge.net/p/docutils/patches/186/?page=1#897a/547e )

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.