Sunday, October 19, 2008

docpicture + svg generation: first prototype working

As outlined in a previous post, I have decided to use svg to embed pictures in html pages generated from docstrings. Of course, this could be generalized to other cases than docstrings; for example, this could be implemented as a reStructuredText directive. In the course of playing with generating such pages with inline svg code, I observed the following:
  1. If a file is saved locally and loaded within Firefox, it should be saved with a ".xml" (or possibly ".xhtml") extension.
  2. If a file is served dynamically from a server, all that is needed is that its content be identified as "application/xhtml+xml" [as I had mentioned previously].
  3. If the file is put on a "generic webserver" that can't be configured by the user, Firefox will ignore the svg code if the extension of the file is ".xml" or ".html". However, I did find a workaround: use a ".xhtml" extension and, when prompted by Firefox as to what application to use to open such file, select Firefox itself. The file will be downloaded locally and displayed correctly. At least, this is what happens on a Mac with Firefox 3.
There might be another way to do this; if so, I would be interested in knowing how. In the meantime, for those interested, here is the output of a first working test case.

Update: The test case has been improved with styling.

Update 2: A new picture perhaps gives a better idea of a more realistic use case.

6 comments:

David Goodger said...

The .xhtml link doesn't work for me in either Firefox 2 or Safari on Mac OS X 10.5.5. They both download a file instead of serving a page. Perhaps rename it to .html?

André said...

If I rename it to .html, then the svg graphics is not displayed. This is a minor annoyance for what I want to do, since the files are going to be displayed dynamically by a local server with the proper configuration.

However, if this is going to be adapted/incorporated by programs like docutils to produce normal (x)html files by a server with no specific configuration, it is going to be an annoyance...

Doug Napoleone said...

It sort of works for me in Safari and Firefox on OSX (after forcing them to open the file after downloading).

But, when I do view it I see the following error:

Unknown parser dummy_name.

for the first example.

(The red circle is fine... very excited about this...)

André said...

The error message is intentional! I just wanted to provide an easy to see error message when a docpicture directive was given with an unknown parser. This makes it easy to spot a typo when embedding code in a docstring.

I'm still trying go get more familiar with svg graphics before working some more on parsers. In the meantime, you can try the following link ...
http://andre.roberge.googlepages.com/turtle_test.xhtml

It is likely going to form the basis for the first parser: one that could be used with docstrings for the turtle module. ;-)

swheatley said...

Cool stuff! Will you be posting the code as well?

André said...

Yes, I will be posting the code as well, as soon as I can automatically generate pictures for a fictitious turtle module, and after I clean it up a bit.