[Jython-dev] Re: [Jython-users] Jython documentation

[Robert W. B. <rb...@di...>]

On Thu, 7 Jun 2001, Finn Bock wrote:
> [moving the discussion to jython-dev]
> 
> [finn]
> > Is the SF DocManager usefull for this?
> >
> >   http://sourceforge.net/docman/?group_id=12867
> 
> [Robert]
> 
> >This may be a good start, but it seems unclear what format limitation
> >there is on SF.  A limitation to html might not be ideal? 
> 
> I tend to agree.
> 
> >I'm
> >curious what people think about sticking closer to the latex documentation
> >Fred Drake details here:
> >
> >    http://python.sourceforge.net/devel-docs/doc/doc.html
> 
> Copying the use of latex from CPython might be a good idea. That way we
> get both Fred's documentation on latex use and lots of examples.
> 
> >CVS + latex and converting to format-specific output seems a better
> >investment. How can you do this on SF? Would this mean a separate
> >'project' for documentation where only the html output is committed to the
> >jython project?  What are others thoughts?  My cvs+emacs+latex
> >bias may be another's bane, so speak up.
> 
> Well, latex does seems somewhat old and dusty (just IMHO). The list of
> tools also seems quite intimidating. I haven't searched for them yet,
> but some look very unix centric. Obviously I will prefer an enviroment
> where I too can generate the output files on my win2k. Does the latex
> tools also exists on windows?

After surfing a bit, it does seem latex is more *nix-centric and
not nearly as ubiquitous as I had thought. I'm terribly uninformed 
about win/mac tools, so I'd better get things working on Windows
before suggesting ;)  All hints are welcome from other win/mac
latex users.

> We may also require some additions to the latex macros. Perhaps
> something that can pretty print static and instance java methods.
>
> >It seems a quick consesus may be most useful, so I'll cast my
> >inconsequential vote for what seems most likely to allow latex source...
> >If authors can have rw to only a /doc subdirectory of Jython's cvs- do
> >that.
> 
> I don't think that is technically doable (please correct me if anyone
> knows how) but it may not be a major problem. If write-access to the CVS
> is mis-used it is easily revoked.
> 
> If we pick a CVS based route, I think we should add a new CVS module (we
> already have "jython" and "htdocs") that contains only the doc sources.

Agreed.  And better saved for when "formal" layout is figured
out (i.e. will latex+win/mac be a nuissance).

The idea of generating content in a wiki before
formalizing docs might allow quick start despite the
unknowns in formal layout.

I put up a couple wiki pages for those anxious to get started (I
hope this was ok):

http://www.jython.org/cgi-bin/moin.cgi/JythonDevelDocs