Re: [Docutils-develop] Re: Building the Docutils community

[<bb...@ma...>]

On Friday, Jan 10, 2003, at 20:32 US/Eastern, David Goodger wrote:
> So please take notes of the stumbling blocks you encounter and feed
> them back to the project, in whatever form.

Will do -- I'm going to do a code review of my writer to jog my 
memory....

>>      The current set of tools is relatively hard to use to someone
>> new to DocUtils.  The module doesn't self install into a directly
>> usable state [previous post covered that].  Easily fixed;
>
> I agree that a tool or the tools should be installed.  But what should
> it (or they) be called?  What form should it/they take?  If we go the
> "rst2html.py" route, there may be many tools.  The other extreme would
> be a "docutils rst standalone html" tool.  See
> <http://docutils.sf.net/spec/notes.html#front-end-tools>.

I like the idea of a 'docutils' command that encapsulates the 
functionality.

But I would do something like:

     docutils [options] output [options] <format> [options]

Where each [options] is specific to the noun/verb preceding it.

In the end, it doesn't really matter what is installed as long as it 
provides relatively easy access to the different outputs along with 
some decent debugging / structure analysis tools (like pseudoxml -- 
which is really just a writer?).

>>      - more conversion modules that "just work" (i.e. can handle all
>> of test.txt)
>
> I hope these will come with time & volunteers.  A how-to for Writer
> modules would be useful too.  Engelbert Gruber has some notes at
> <http://docutils.sf.net/sandbox/grubert/making_a_writer.html>.

Except that the 'The Simplest Writer' section is empty. :-)

Seriously -- that document has the potential to be very useful.

Engelbert:  If you don't mind, I would be willing to add some 
information to the document based on my experiences.

>> - an example that shows using a custom writer to produce a document
>> with a custom look-n-feel will help convince people that ReST is not
>> just for producing docs w/our look-n-feel, but they can do it
>> themselves
>
> Care to volunteer?

I wish I had more time.   But, the PyObjC project is quickly moving to 
using ReST for everything.   Including the web site.   We have a fairly 
nice look and feel for the site right now -- see pyobjc.sf.net -- but 
it is implemented in PHP [recycling at its best -- compare it to 
fink.sf.net].   We would like to move the site content-- at least, the 
documentation and examples sections (which haven't been implemented 
yet) to ReST.

At this point, it is just an idea and may be a bad one.

>> - some GUI tools.   I'll eventually build a ReST tool for OS X using
>> PyObjC and Cocoa...
>
> Have you looked at DocFactory yet (sandbox/gschwant/docfactory/)?  It
> has great promise.  It uses wxWindows, which I believe now works under
> OS X.

Will check it out....

b.bum