Menu
▾
▴
jython-dev
|
From: Samuele P. <pe...@in...> - 2001-06-07 19:36:16
|
Hi. > > -> I'm not convinced there's a better, stable, cross-platform > -> answer out there today, but probably *soon* there will be > -> a stable enough xml-based system (that can even generate > -> the old latex if needs be). There are such systems today, > -> but I don't think they fit all of the criteria one might > -> want: () > > What about DocBook? I've heard good things about it, although I've not > gotten around to using it personally. > If I remember well, using DocBook is an idea that is haunting around also for CPython doc but refrained for the moment because of stable, usable, cross-platform, free issues for tools. For the moment, in order to get started and gather things the wiki should be ok. I think that asking directly on doc-sig list or to Fred Drake on the format, tools issue in relation with CPython doc and its future would be very useful. A marginal note: latex, tex exists and works under win but for the other tools I don't know either. regards, Samuele Pedroni. |
|
From: <bc...@wo...> - 2001-06-07 16:26:42
|
[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? 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. regards, finn |
|
From: Robert W. B. <rb...@di...> - 2001-06-07 17:51:15
|
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 |
|
From: Mats W. <ma...@la...> - 2001-06-07 18:17:42
|
>> 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. TeX itself (and thus Latex) is available for Windows platforms and works fine. I've used it (rarely, however) in that environment for many years. Where we probably get into trouble is all the conversion tools that turn the base docs into different output styles, esp. the webpages we know and love... >> 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 The advantage in starting from the existing CPython docs is that there's a lot that's reusable, and it's cleaner to fold in the changes as the Python languages itself evolves, always consiering that CPython continues to be the reference implementation (maybe it will be Python.net instead :-) (no, really, that was a joke). I agree with Finn: I also find the Latex stuff old and clunky, and I say that from the viewpoint of someone who used to *like* troff. The real irritant, to me, is that to use it effectively you almost have to use emacs, and I loathe and detest emacs. So there. There's also the problem that the CPython docs depend on tools that are a little fragile - they're not that well understood and when stuff breaks, tweaking them breaks other things. The hyperlinks in the html output, for example, are not generating correctly all the time. There was big head scratching over the 2.0 tutorial where they were completely broken, and I just ran across some in the 2.1 docs that are also busted. Someone might ask Fred Drake for an opinion, my view is just that of an outside observer, he's working with this stuff all the time. I'm not convinced there's a better, stable, cross-platform answer out there today, but probably *soon* there will be a stable enough xml-based system (that can even generate the old latex if needs be). There are such systems today, but I don't think they fit all of the criteria one might want: (stable, usable, cross-platform, free) So I guess I endorse the concept of gathering information someplace where at least it's recorded and discussed, and then hash out the production details. Mats |
|
From: <ti...@ca...> - 2001-06-07 18:35:04
|
-> I'm not convinced there's a better, stable, cross-platform -> answer out there today, but probably *soon* there will be -> a stable enough xml-based system (that can even generate -> the old latex if needs be). There are such systems today, -> but I don't think they fit all of the criteria one might -> want: (stable, usable, cross-platform, free) What about DocBook? I've heard good things about it, although I've not gotten around to using it personally. --t |
|
From: Robert W. B. <rb...@di...> - 2001-06-07 20:56:14
|
On Thu, 7 Jun 2001, Samuele Pedroni wrote: > Hi. > > > > > -> I'm not convinced there's a better, stable, cross-platform > > -> answer out there today, but probably *soon* there will be > > -> a stable enough xml-based system (that can even generate > > -> the old latex if needs be). There are such systems today, > > -> but I don't think they fit all of the criteria one might > > -> want: () > > > > What about DocBook? I've heard good things about it, although I've not > > gotten around to using it personally. > > > If I remember well, using DocBook is an idea that is haunting around also > for CPython doc but refrained for the moment because of > stable, usable, cross-platform, free issues for tools. Mats suggestion motivated me to dive into docbook this afternoon. I had terrific luck, especially with Cees de Groot's Python package "SGML-lite"- http://sourceforge.net/projects/sgmltools-lite/ There's also quite a few editors and editor modes that should accomodate most people. > For the moment, in order to get started and gather things the wiki should > be ok. Agreed. Spread the word, "Go fill the wiki!" When some sizable content collects in the wiki, I'll plug it into docbook and see what people think. > I think that asking directly on doc-sig list or to Fred Drake on the format, > tools issue in relation with CPython doc and its future would be very useful. Good idea. Will do > A marginal note: latex, tex exists and works under win but for the other > tools I don't know either. > > regards, Samuele Pedroni. rb |
