Webware for Python

The documentation format discussion kind of died down, but I'd like to
do some documenting, and that's one of those fleeting motivations you
really have to grab onto ;)  Anyway, after looking some at the XML
produced by reST, I think the format doesn't imply any great lock-in. 
And I like writing it, so I'd like to use it.  But this effects all the
developers who might write documentation, since one of the first things
I want to do is rewrite the current WebKit documentation, expanding and
checking for accuracy.  I'm not planning to do anything too exciting at
this point (no doc strings or literate programming or new tools or
anything), just trying to get the basic documentation in good shape.

Shall I go forward or do we need more discussion about this?

  Ian

Re: [Webware-discuss] Documentation format From: Roger Haase <crosseyedpenguin@ya...> - 2002-10-30 15:09 --- Ian Bicking <ianb@...> wrote: > The documentation format discussion kind of died down, but I'd like > to > do some documenting, and that's one of those fleeting motivations you > really have to grab onto ;) Anyway, after looking some at the XML > produced by reST, I think the format doesn't imply any great lock-in. > > And I like writing it, so I'd like to use it. But this effects all > the > developers who might write documentation, since one of the first > things > I want to do is rewrite the current WebKit documentation, expanding > and > checking for accuracy. I'm not planning to do anything too exciting > at > this point (no doc strings or literate programming or new tools or > anything), just trying to get the basic documentation in good shape. > > Shall I go forward or do we need more discussion about this? > > Ian > At the risk of making the documentation project even harder, it seems to me the best place to create Webware documentation is in a TWiki-like environment because mass participation would be so easy. Having looked over the reStructuredText specs a bit, I rather like it because it seems pretty simple. There has been talk now and then of a Webware based Wiki (a WikiKiti? ;). How difficult/feasible it would be modify your Wikiware code to utilize reStructuredText? Roger __________________________________________________ Do you Yahoo!? HotJobs - Search new jobs daily now http://hotjobs.yahoo.com/

Re: [Webware-discuss] Documentation format From: Aaron Held <aaron@Me...> - 2002-10-30 15:15 Go w/ reSt, and let me know what bits you need help on. Ian Bicking wrote: > The documentation format discussion kind of died down, but I'd like to > do some documenting, and that's one of those fleeting motivations you > really have to grab onto ;) Anyway, after looking some at the XML > produced by reST, I think the format doesn't imply any great lock-in. > And I like writing it, so I'd like to use it. But this effects all the > developers who might write documentation, since one of the first things > I want to do is rewrite the current WebKit documentation, expanding and > checking for accuracy. I'm not planning to do anything too exciting at > this point (no doc strings or literate programming or new tools or > anything), just trying to get the basic documentation in good shape. > > Shall I go forward or do we need more discussion about this? > > Ian > > > > ------------------------------------------------------- > This sf.net email is sponsored by:ThinkGeek > Welcome to geek heaven. > http://thinkgeek.com/sf > _______________________________________________ > Webware-discuss mailing list > Webware-discuss@... > https://lists.sourceforge.net/lists/listinfo/webware-discuss

Re: [Webware-discuss] Documentation format From: Matt Feifarek <matt@da...> - 2002-10-30 15:37 Ian Bicking wrote: >The documentation format discussion kind of died down, but I'd like to > I know that I'm late to this discussion, but something has occurred to me. As I understand it, OpenOffice stores all of its docs in pure XML format. What if we had someone design a SIMPLE template, then all used it to write in. One of the XML gurus in this list could then surely devise a transform on the written data into whatever output we would like. OpenOffice has GOT to be easier for people to write in than any of these documentation generators. If anyone who understands these things (XML) better than I, the Open-Office file formats are just zip files with xml and dtd files inside of them. Just a thought...

Re: [Webware-discuss] Documentation format From: Aaron Held <aaron@Me...> - 2002-10-30 16:05 Enought writing about how to write, just write! The format DOES NOT MATTER as long as it has some logic. reStruct, XML, docbook, gentoo, OpenOffice ... all can be CONVERTED to something. Here is a deal. Once we have written 30 new pages of documentation we will revisit this topic and see what format will fit our needs. I'll work on another tutorial, probably a simple database pull. Ian is revisiting the code docs. If anyone else has a desire to write, just post a message to let everyone else know and then upload a draft for review. -Aaron

Re: [Webware-discuss] Documentation format From: Ray Leyva <maillist@es...> - 2002-10-30 16:25 I've already done some heavy work in transforming the OO-Xml files to other things. It's definitely do-able, but from my perspective I'd rather go with something that VIM, or Emacs, or heck even nano can open. reST seems to be amazingly easy. I say go with reST, and we'll work out the translations later. reST just seems like a much much better way to "write" content, and from a cursory overview of the site I think there's a tool to turn reST to html ... so not to very much of a leap to create xml. So Ian, go with reST, but please let us know the conventions you're using for the docs. From what I read (quick glimpse) there's no formal spec on the grammar. So it's kinda open ended in that respect. If you have some basic definitions for special characters / conventions that you would like to use for delimitting code-snippets, bookmarks / references to bookmarks, emphasis ( bold / italic / underline / crossed-out ). I think that would be enough to get started. Of course I could be wrong about the whole thing, but after having worked with the xml in the OpenOffice docs I think it's simpler / easier for writers to write in plain text, with just tabs / spacing to worry about. Ray On Wed, 30 Oct 2002 10:37:56 -0500 Matt Feifarek <matt@...> wrote: > Ian Bicking wrote: > > >The documentation format discussion kind of died down, but I'd like to > > > I know that I'm late to this discussion, but something has occurred to me. > > As I understand it, OpenOffice stores all of its docs in pure XML > format. What if we had someone design a SIMPLE template, then all used > it to write in. One of the XML gurus in this list could then surely > devise a transform on the written data into whatever output we would like. > > OpenOffice has GOT to be easier for people to write in than any of these > documentation generators. > > If anyone who understands these things (XML) better than I, the > Open-Office file formats are just zip files with xml and dtd files > inside of them. > > Just a thought... > > > > ------------------------------------------------------- > This sf.net email is sponsored by:ThinkGeek > Welcome to geek heaven. > http://thinkgeek.com/sf > _______________________________________________ > Webware-discuss mailing list > Webware-discuss@... > https://lists.sourceforge.net/lists/listinfo/webware-discuss

Re: [Webware-discuss] Documentation format From: Ian Bicking <ianb@co...> - 2002-10-30 17:37 On Wed, 2002-10-30 at 09:09, Roger Haase wrote: > At the risk of making the documentation project even harder, it seems > to me the best place to create Webware documentation is in a TWiki-like > environment because mass participation would be so easy. Having looked > over the reStructuredText specs a bit, I rather like it because it > seems pretty simple. > > There has been talk now and then of a Webware based Wiki (a WikiKiti? > ;). How difficult/feasible it would be modify your Wikiware code to > utilize reStructuredText? As a matter of fact I was working on just this last night -- it was only a matter of taking reST text and changing all dangling links to Wiki references. I can give those code snippets to anyone who's interested. Ian

Re: [Webware-discuss] Documentation format From: Ian Bicking <ianb@co...> - 2002-10-30 17:45 I know... it's only because I'm planning on ripping out old markup and replacing it with new markup that I'm reluctant to dive in without feedback. But now that I have that feedback I'll move forward on that. On Wed, 2002-10-30 at 10:04, Aaron Held wrote: > Enought writing about how to write, just write! > > The format DOES NOT MATTER as long as it has some logic. reStruct, XML, > docbook, gentoo, OpenOffice ... all can be CONVERTED to something. > > Here is a deal. > Once we have written 30 new pages of documentation we will revisit this > topic and see what format will fit our needs. > > I'll work on another tutorial, probably a simple database pull. > Ian is revisiting the code docs. > > If anyone else has a desire to write, just post a message to let > everyone else know and then upload a draft for review. > > -Aaron

1 message has been excluded from this view by a project administrator.