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

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

> Note I'm not proposing getting rid of the config, just loosening the
> direct relationship between the CLI-parsing part of Docutils and the
> settings/config part of Docutils. 

> > We already have the docutils.core.publish_* "convenience functions" as
> > a high-level API for custom front-ends (both command-line and programmatic).
> 
> Hmm, perhaps we are talking at cross purposes. I'm talking about utility
> functions such as "take some RST and turn in into docutils nodes"

> ...

I agree that it would be an improvement to implement config-file
processing without dependency on "optparse" or "argparse" (cf. [bugs:#441]). 
Well documented utility functions are helpful, too.

However, getting rid of the `rst*` front-end tools does not simplify this task:
it does not matter if `docutils.core.publish_cmdline()` is called by one
or several command line front-end scripts.

> end-user simplicity is what counts.

For end-user convenience, I see benefits in both, a generic, flexible CLI
and simple scripts for the common tasks (rst2html, rst2latex, ...).

Proposal:

Keep the "*.py" scripts in `tools/` for backwards compatibility and as
examples for users wanting to create their own front-ends.

Use "entry points" [patches:#186] to install front-end scripts in
the binary PATH:

`docutils`: generic front end
(as "docutils-cli.py" is not installed in 0.18 [bugs:#447],
we can change to a shorter name already in 0.19). 

`rst2*`: drop the `.py` suffix (after a transition period).
> Note I'm not proposing getting rid of the config, just loosening the
> direct relationship between the CLI-parsing part of Docutils and the
> settings/config part of Docutils. 

> > We already have the docutils.core.publish_* "convenience functions" as
> > a high-level API for custom front-ends (both command-line and programmatic).
> 
> Hmm, perhaps we are talking at cross purposes. I'm talking about utility
> functions such as "take some RST and turn in into docutils nodes"

> ...

I agree that it would be an improvement to implement config-file
processing without dependency on "optparse" or "argparse" (cf. [bugs:#441]). 
Well documented utility functions are helpful, too.

However, getting rid of the `rst*` front-end tools does not simplify this task:
it does not matter if `docutils.core.publish_cmdline()` is called by one
or several command line front-end scripts.

> end-user simplicity is what counts.

For end-user convenience, I see benefits in both, a generic, flexible CLI
and simple scripts for the common tasks (rst2html, rst2latex, ...).

Proposal:

Keep the "*.py" scripts in `tools/` for backwards compatibility and as
examples for users wanting to create their own front-ends.

Use "entry points" [patches:#186] to install front-end scripts in
the binary PATH:

`docutils`: generic front end
(as "docutils-cli.py" is not installed in 0.18 [bugs:#447],
we can change to a shorter name already in 0.19). 

`rst2*`: drop the `.py` suffix (after a transition period).

> Note I'm not proposing getting rid of the config, just loosening the
> direct relationship between the CLI-parsing part of Docutils and the
> settings/config part of Docutils. 

> > We already have the docutils.core.publish_* "convenience functions" as
> > a high-level API for custom front-ends (both command-line and programmatic).
> 
> Hmm, perhaps we are talking at cross purposes. I'm talking about utility
> functions such as "take some RST and turn in into docutils nodes"

> ...

I agree that it would be an improvement to implement config-file
processing without dependency on "optparse" or "argparse" (cf. [bugs:#441]). 
Well documented utility functions are helpful, too.

However, getting rid of the `rst*` front-end tools does not simplify this task:
it does not matter if `docutils.core.publish_cmdline()` is called by one
or several command line front-end scripts.

> end-user simplicity is what counts.

For end-user convenience, I see benefits in both, a generic, flexible CLI
and simple scripts for the common tasks (rst2html, rst2latex, ...).

Proposal:

Keep the "*.py" scripts in `tools/` for backwards compatibility and as
examples for users wanting to create their own front-ends.

Use "entry points" [patches:#186] to install front-end scripts in
the binary PATH:

`docutils`: generic front end
(as "docutils-cli.py" is not installed in 0.18 [bugs:#447],
we can change to a shorter name already in 0.19). 

`rst2*`: drop the `.py` suffix (after a transition period).
Eventually stop installing rarely used tools.

---

** [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:** Mon Jan 24, 2022 11:17 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.