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

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

While I am in favour of revising and updating Docutils' command line
entry points, I don't think we should drop the number down to one.

> 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

Can you elaborate a bit on what would become a lot simpler?

>> the docutils-cli wrapper is not complex, which gives it
>> significant points in favour in my book.

The generic front-end is one order of magnitude more complex because of
the two-stage command line parsing with the set of valid tags depending
on the components selected.
Even help output depends on the "component" tags. Due to the open nature
(allowing for plug-in components), a man page will always need to refer
to external documentation, while, e.g,  `man rst2html` lists all available
command line options (at least on Debian).

>> Most usage of Docutils today is programmatic, and not via the command
>> line tools

We need to care for "command line users" if their number is
non-negligible -- independent of the number of users depending on the
programmatic interface.

The number of users/projects using Docutils via the command line interface
cannot be estimated by looking at Python projects.
Unfortunately, it is rather hard to find out how many non-Python projects
uses "rst2html.py" in their `Makefile` or another form of build tool chain.

The first answer to [Explain Python entry points?](https://stackoverflow.com/questions/774824/explain-python-entry-points)
even cites Doctils as

  ... a great example of entry-point use: it will install something like a
  half-dozen useful commands for converting Python documentation to other
  formats.

(even if Docutils currently does not use the "console-scripts mechanism" to
provide cli entry points).

...

>>  We cannot know how many people would be affected with local random
>>  scripts, but it is a two-second change.

While the actual re-typing (or drag-and-drop) of the command may be that
fast, this is not the case for the complete task of finding out and
approaching the right spot where to apply the change in a complex build
chain.

>> Many users will also run with old or pinned versions of Docutils, and
>> part of updating is seeing the changelog.

A hard learned lesson from Docutils releases is to never underestimate
the number of users/project managers that don't read the changelog (nor
the announcements in the RELEASE-NOTES) yet depend on a stable Docutils
for a stable system.

********

I am pro change for instances where the current
[naming](https://clig.dev/#naming) is unfortunate or may stand in the way.

`buildhtml.py` is too generic, it may stand in the way.
Debian calls it `rst-buildhtml`. I could imagine `docutils-buildhtml` or
leaving it in the tools for individual installing.

`docutils-cli.py` is too long. This name was selected because a naming
the file for the generic front end tool "docutils.py" is misleading.
With "entry points" it is possible to use `docutils` as front-end command
without the need for a file "docutils.py".

`python3 -m docutils` currently results in the error:
`'docutils' is a package and cannot be directly executed`
It could be made more helpful, we know, a user typing `python -m ...` wants
to execute a command line tool (or just wants to know more about docutils).

`rst2` is established as the start of Docutils' front-end names for
conversion from reStructuredText to something. I would like to keep this
prefix as "ours". (After all, Docutils is the reference implementation of the
rST format.) 

Ease of discovery is important. TAB completion is a powerfull means here.
Additional parser or readers may add their own entry points, cf.
https://github.com/executablebooks/MyST-Parser/issues/347#issuecomment-1003717830


Rarely used and diagnostic tools may not need automatic installation into
the binary PATH. Here, it may help to diagnose which tools are installed by
`pip docutils` vs. OS-specific package managers.

Debian installs the following 13:

rst2html
rst2html4
rst2html5
rst2latex
rst2man
rst2odt
rst2odt_prepstyles
rst2pseudoxml
rst2s5
rst2xetex
rst2xml
rst-buildhtml
rstpep2html

Dropping the `.py` from `rst2*.py` commands may be considered.

+1 shorter and more command-like names
-1 backwards incompatible, an unknown number of users need to change their scripts.


---

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