Re: [Docutils-develop] Re: Writer for .ht (HTML Template?) files

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

I think this effort (and I, personally!) could benefit greatly from a
short README or quick-start guide, giving straightforward instructions
how to set up HT2HTML and how to use the HT2HTML and Docutils tools to
build a web page or site.  HT2HTML comes with a bunch of "generators";
which one to use at first?  Or do we have to customize our own?  A
quick-start guide answering these questions could also be fed back to
the HT2HTML project.

Could someone write one?

Oliver Rutherford wrote:
> As far as the bulletproof part goes, I might have sent a broken
> version :-(.  When I tried it this morning I got an error.

It happens.  No biggie.

> I've fixed the break and added stylesheet handling and will upload
> an updated version into the sandbox

Having taken a look at the code, I noticed that the ``settings_spec``
attribute is being partially duplicated.  With the addition of
stylesheet handling, the duplication is complete (or close).  Perhaps
it would be best to make the generation of .ht files (and
body-contents-only files, as Julien proposed) part of the html4css1.py
writer.  Something like "--form=ht" or "--partial-ht" (can't think of
anything good today; brain's a bit fuzzy).  The "HTTranslator" class
could live in the same module as "HTMLTranslator", and the option
would trigger its use (the visitor/translator class is already
parameterized in the "Writer" class).

Or should they be separate writers, but inherit most or all settings?
See writers/pep_html.py for an example.

>>> On an unrelated note, what do you think of adding the front end
>>> scripts in "tools" as scripts in docutils setup.py file?
>>
>> Good idea.  But how would that work?  Does Distutils put scripts on
>> the shell's path?  Is it cross-platform?  (Where does it put
>> scripts on my ancient Mac?)
> 
> Good question, so after suggesting it I'm embarrased to say that it
> might not.  I could have sworn that 'Scripts' was in my PATH, but I
> just checked and it's not.

That's not really *our* problem though.  We can ask users to add to
their PATH, and petition PythonLabs to fix their installer (if it's a
bug).  Any user competent enough to use the command line ought to be
able to set their PATH.  For those not competent to use the command
line, there's DocFactory, a Docutils GUI front end using wxPython
(http://docutils.sf.net/sandbox/gschwant/docfactory/README.html;
anybody interested, *please* help out with this -- could be great).

I experimented on different OSes:

* On Win2K, scripts are installed into the "Scripts" subdirectory of
  the Python install directory (``sys.prefix``).

* On GNU/Linux (I agree with RMS's views on naming :-), scripts are
  installed into the "bin" subdirectory of the installation prefix
  (``sys.prefix``), typically /usr/bin or /usr/local/bin.  These
  should be on every user's PATH.

* On MacOS 8.6 (my home machine; hardware contributions welcome! :-)
  it's the same as Windows: scripts are installed into the "Scripts"
  subdirectory of the Python install directory (``sys.prefix``).  On
  my machine, that subdirectory didn't exist -- Distutils created it.
  There is no PATH on MacOS (pre-X), only Python's ``sys.path``.  But
  there's also no command line, so any Docutils use would have to be
  programmatic or have a GUI.

  Don't know where scripts get installed on MacOS X, but since it's
  FreeBSD-based, it's probably the same as GNU/Linux.

Distutils (setup.py) has an option for the scripts install directory:
"--install-scripts".  See all the options with::

    python setup.py install --help

-- 
David Goodger  <go...@us...>  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/