Mailman 3 April 2003 - Doc-SIG

Re: PythonPoint front-end
by Aahz April 26, 2003

April 26, 2003

On Fri, Apr 25, 2003, Kevin Altis wrote: > > Hey Aahz, > I couldn't get the script to run. > > ImportError: No module named style Oops. I've only run this as part of the PythonPoint toolchain, so I forgot about that. I've long since had to run PythonPoint only with a style file, so my stx2xml partly relies on that. I'm attaching the style.py that I used. > What are the module/package requirements? Do you have a URL to the PDF > output so I can just look at that? Real Soon Now. ;-) (It's part of my full PyCon package.) > The thing I was thinking of doing would be pretty darn simple, so it would > be interesting to get your requirements for the presentation tool/output > since I haven't done many presentations. I'm sort of leaning towards wiki > pages with some special CSS style sheets. Well, I don't like web pages much, so that doesn't work for me. I chose this route because I needed the fine-grained control. (Just like PowerPoint.) -- Aahz (aahz(a)pythoncraft.com) <*> http://www.pythoncraft.com/ "In many ways, it's a dull language, borrowing solid old concepts from many other languages & styles: boring syntax, unsurprising semantics, few automatic coercions, etc etc. But that's one of the things I like about it." --Tim Peters on Python, 16 Sep 93

1 0

Re: [marketing-python] 2.3 release - proposed plan
by Aahz April 25, 2003

April 25, 2003

[cc'ing doc-sig in case anyone is interested] On Fri, Apr 25, 2003, Patrick K. O'Brien wrote: > > When I gave my presentation to the ACM I just created an html page, > increased the font size in the browser, and scrolled through the > items. I've done my share of PowerPoint slides, but I'd rather have a > way to generate slides using reST. Kevin Altis said he's toying > around with something to do this. If you'd like, you can have my front-end to PythonPoint. (I created a dead-simple half-reSTed syntax to avoid the drudgery of writing XML.) Once Kevin does his work, it should be simple to modify my front-end to write out reST. -- Aahz (aahz(a)pythoncraft.com) <*> http://www.pythoncraft.com/ "In many ways, it's a dull language, borrowing solid old concepts from many other languages & styles: boring syntax, unsurprising semantics, few automatic coercions, etc etc. But that's one of the things I like about it." --Tim Peters on Python, 16 Sep 93

4 4

Greetings
by Jordan McCoy April 19, 2003

April 19, 2003

Greetings and good day. Having just joined the DOC-sig, I wanted to introduce myself and determine the status of the work the SIG is doing, perhaps see what I could contribute. I've been working with Python (and programming in general) for quite a while, but only recently starting to involve myself with the community. I'm going to review the archives of the list, but would appreciate a quick summary of the current work of the SIG and what contributions the group is currently seeking. Thanks. Jordan McCoy jordanm(a)uts.cc.utexas.edu

2 1

Python book ideas
by Aahz April 15, 2003

April 15, 2003

[Cross-posted to both doc-sig and marketing-python] Last week I went to the Waterside Conference, which is a conference for writers and publishers put on by my agent's company. I picked up some good leads for book ideas, some of which I'm holding to myself for a bit while I talk with my agent, but I'd like to throw out one idea that's been mentioned before as a joke: _Python for VB6 Programmers_ According to a presentation I saw, one survey claims that more than 50% of VB6 programmers currently refuse to consider upgrading to VB.net. That's a huge market for us even if we only get a tiny slice of it. I'll be glad to assist someone else to find a publisher. Any takers? Another idea that I and others have been kicking around for a while is a data structures and algorithms book using Python. Based on what I saw at the conference, I think now would be a good time to start working on that, possibly beginning it as an Open Source project of some kind. -- Aahz (aahz(a)pythoncraft.com) <*> http://www.pythoncraft.com/ This is Python. We don't care much about theory, except where it intersects with useful practice. --Aahz, c.l.py, 2/4/2002

4 4

Re: Wikis using reST
by Ian Bicking April 5, 2003

April 5, 2003

Someone pointed this thread out to me. I thought I'd note that the example application for the Web Framework Shootout is a Wiki using reST: http://colorstudy.com/docs/shootout.html It uses a generic Wiki module that is in the docutils sandbox CVS repository. It is certainly fairly primitive -- I wanted an example that could fit in a paper (actually fit in many times over) -- but the core Wiki concepts are delightfully simple, and it lives up to that at least. I'm interested in extending the module, as I like the basic architecture with a firm separation of content from interface. But there's lots of things I'm interested in extending... Ian

1 0

Using docutils on source code
by Juergen Hermann April 4, 2003

April 4, 2003

Hi! Maybe I'm thick here, but from a more than cursory look at the docs I got the impression that docutils is still "just" a document processor, and that there is no front-end to extract docstrings from source and format them. Can somebody enlighten me, and shove me in the right direction? Ciao, Jürgen

2 1

reStructuredText: What a cool idea!!
by Stefan Merten April 2, 2003

April 2, 2003

-----BEGIN PGP SIGNED MESSAGE----- Hi hackers and others, first of all I'd like to apologize if this is off-topic on this list. If so it would be nice if someone could tell me, where this belongs to. I don't know whether you already know, but reStructuredText is mentioned on http://www.ibm.com/developerworks/library/x-matters24/ I saw it there, read the specification and some more - and I'm absolutely delighted :-) !! First, I'd like to tell you a bit about my background. I love the Perl idea of embedding documentation in the source code using POD. To me it became a habit documenting everything while or often even before coding something. I guess that was, what Larry had in mind when inventing POD :-) . Another nice aspect of POD is, that it's ASCII based and thus it is useful to use CVS on it and/or the miracles of the Emacs' ediff package. And of course you do not need any special editor to work with this format. Instead every editor supporting plain ASCII works. And nonetheless you can produce lots of output formats. By a simple `make' call if you like. All in all POD allowed for a lot of nice features with a high degree if automatization, versioning and so on. So I started to write all my documents in POD. However, POD is a rather limited markup format. If you want to write something different from a manual page you'll immediately run into a number of limitations. So I looked for an alternative. I found SDF [http://search.cpan.org/author/IANC/sdf-2.001/, the original site doesn't exist any more but it is embedded in the package]. SDF is a rather great tool very much in the spirit of reStructuredText. One feature I particularly like is, that it is possible to embed (Perl) code in your text document to do some very specific job. Anyway it is easy to combine SDF with Perl to create really great stuff. The most elaborated thing I did with SDF were some filters which take a high level interface description for an API and produce include files for C, C++, Sicstus Prolog, and Java. Well, since I discovered SDF I'm using SDF for nearly everything. In particular the web sites I'm maintaining are all created by SDF and `make'. However, SDF has a number of drawbacks: * The code is based on Perl 4 (before references were invented in Perl) and it's - ummm - somewhat ugly. I thought about rewriting it from scratch but I've got no time for such a task. * There is a great number of nice ideas but there is not much of an overall concept. * No community developed - at least no community visible to me. This may be partly because the maintainer Ian Clatworthy (thanks Ian for all of your efforts) seemingly gave up the project shortly after I discovered it (in 1999). (I never contacted him, so I could not have been the reason ;-) .) * It did not reach a wide distribution and thus virtually nobody is used to using it. So though personally I'm rather happy with SDF I don't like the thought of being trapped in a evolutionary dead end. And now I found reStructuredText. I read the specification and though today reStructuredText misses some things of what SDF has, I see that there is a potential for reStructuredText for being a very powerful tool - much more than SDF ever was. Particularly because there seems to be an active maintainer (thanks David Goodger and all for the *great* web site, I particularly like that the discussion of alternatives is listed) and seemingly a very interested community. Personally I think it would be a great gift to the world to establish a text format which is easy to write but yet powerful. In short: I fully support all the goals listed for reStructuredText. I think over time I'll reformat all my sources to use reStructuredText. Ahmm - as you may have noted I'm coming from the Perl community and I don't know Python yet and at the moment I'm not planning to change that. But when talking about a format this is of little importance of course. Well, now you know why I'm here :-) . Now for the question part of this mail. Indeed I have a number of questions about reStructuredText and it's implementation. I'm sorry if any of these questions is already answered on one some web page. I did not read all of the pages yet. * Is there a Perl implementation already? Does anybody plan such a beast? Admittedly I thought of doing it - but my time is *very* limited :-( . However, that's a itch I'd like to scratch. * Is there a Emacs mode already? Particularly it there `font-lock' support for reStructuredText documents available? Personally I got used so much to font-locking I find it an unbearable pain to read text containing formal syntax without appropriate coloring. If no such thing is available I could give it a try. * Are there transformation tools from OpenOffice format to reStructuredText? This question may need some explanation. I have the problem, that sometimes I receive M$ `.doc's and `.ppt's or `.rtf's I'd like to transform to SDF to embed them in a web site. Before OpenOffice and it's XML based document format this was a difficult task needing a lot of unautomatable work. I wrote a tool for RTF but Powerpoint was beyond automatization. For SDF lately I created a suite of XSLT style sheets which transform the `styles.xml' and `content.xml' contained in `.sxw' and `.sxc' to SDF. Though this involves some post processing by hand it is *much* easier than anything I did before. In effect by (ab)using the input filters of OpenOffice I now have a whole lot of formats I can transform to SDF with reasonable effort. Of course I'd like to see this for reStructuredText as well. If no-one did this until know, I could rewrite my XSLT scripts a bit to support reStructuredText. * Is there a transformation for Docutils Document Tree documents in XML to a reStructuredText source form? Or following PEP 258: Is there a writer for reStructuredText? If so the Docutils Document Tree could be used as an XML based representation and all the nice things of XML are available. For instance one could write an XSLT transformation from an OpenOffice format to Docutils Document Tree format and transformations in all thinkable directions are possible. * Are there plans to support embedded code in reStructuredText documents? The embedded code needs access to the embedding document of course. May be this is similar to JavaScript embedded in HTML pages. Of course I'd prefer support for Perl ;-) . * Are there writers for plain text and/or manual pages? Finally I'd like to draw your attention to http://template-toolkit.org/ It's a very cool tool which allows for a wide range of automation. It virtually adds a powerful macro language to every ASCII based format. One thing I particularly liked with SDF is the feature to embed SDF or other stuff in anything which supports comments. This way you were able to embed for instance POD documentation in a C++ file. One of the nice features is, that it rearranges the embedded code allowing you to write your documentation at the place of the definition and nonetheless get every piece of documentation at the right place in the final document. However, as SDF is usually not available this feature is of limited use if you're going to share your source with others :-( . In the free software project I started lately [http://savannah.nongnu.org/projects/mamo/] I created a plug-in for the Template Toolkit which exactly does this sort of gathering of snippets of documentation from an arbitrary source file [http://savannah.nongnu.org/cgi-bin/viewcvs/mamo/mamo/lib/perl5/Mamo/Templat…]. Thinking reStructuredText and Docutils it might qualify as the input part of a reader. Mit Freien Grüßen Stefan -----BEGIN PGP SIGNATURE----- Version: 2.6.3in Charset: noconv Comment: Processed by Mailcrypt 3.5.7, an Emacs/PGP interface iQCVAwUBPlqjdAnTZgC3zSk5AQGjVgQArL3NYg0OThGf7Xi++LJPUgKnS0HyRfT6 bek6sjLiYOSfDLQPFAfWjeVhRKaMt4P+nKhIqVPuT/Jfe3nj/LgxTOMdWspjE7gU CT6VA2qKNpuAAvoIc9BoW9nL4bQE3fgnETENtdZROlg4kiQLwGKzTr1VWs+uLvqt nSzPi3EddpI= =alwL -----END PGP SIGNATURE-----

3 6