[Docutils-develop] Re: [ docutils-Feature Requests-654826 ] install command line tools via setup.py

[David G. <go...@py...>]

http://sf.net/tracker/?func=detail&atid=422033&aid=654826&group_id=38414

> Submitted By: Bill Bumgarner (bbum)
> 
> Setup.py should be augmented to install some/all of the
> tools into the appropriate install directory when
> 'python setup.py install' is invoked.
> 
> The tools are very useful as is and this would make
> them even more accessible.
> 
> One issue:  some of the tools should either be renamed
> or not installed.  For example, 'html.py' should be
> renamed such that it is associated more strongly with
> docutils when installed into a relatively cluttered
> spot such as /usr/local/bin/

These issues have come up before.  I'm inclined to agree.  What should the
tools be called?  Here are my initial thoughts:

===============  ======================================================
Current Name     Proposed New Name & Comments
===============  ======================================================
buildhtml.py     ? -- Builds HTML for all .txt files in a directory;
                 handles standalone RST, old-style PEPs & RST PEPs.
                 Kind of like a mini-make util.  Was a proof of concept
                 which may not be generally useful.  Install?

docutils-xml.py  rst2xml.py -- Produces Docutils-native XML.

html.py          rst2html.py

pep2html.py      no change -- Handles plaintext and RST PEPs.  This is
                 a copy of the tool that lives in Python's CVS.
                 Non-standard interface (different from other Docutils
                 tools).  Specialized tool; perhaps it shouldn't be
                 installed (anyone who needs it should get it from
                 Python's CVS).

pep.py           rstpep2html.py? -- Handles RST PEPs only, but with a
                 different command-line interface than pep2html.py;
                 this one has a standard Docutils front end interface.
                 Don't install?  No longer useful since pep2html.py
                 is the standard tool?

publish.py       rst2pseudoxml.py? -- Produces pseudo-XML, used mainly
                 for testing.  Install?

quicktest.py     quickrst.py? -- Produces various output, for testing.
                 This was the first front-end tool, before Docutils
                 existed.  Non-standard interface.  Should it be
                 installed?
===============  ======================================================

Input is welcome: alternative names, thoughts on the questions raised.

Should the .py suffix be kept?  On Linux/Unix it probably doesn't
matter, given a proper #! line, but on Windows it's significant.

See <http://docutils.sf.net/docs/tools.html> for tool details.

> Thanks -- awesome tool --

You're welcome, and thanks for the compliment.

> I have started using docutils
> for everything, including non-python things (and will
> likely have a bunch of bug reports, feature requests
> and patches related to non-Python support).

All input is welcome.

-- 
David Goodger  <go...@py...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/