matplotlib-devel Mailing List for matplotlib

As of revision 6718, the usetex part of the pdf backend has support for
font effects (SlantFont and ExtendFont) specified in TeX's mapping
files. Together with the recent encoding fixes, this should make the
output visually identical to what pdftex would produce, assuming that
all fonts are Type-1 -- pdftex also supports the original type of TeX
fonts by encoding bitmaps as Type-3 fonts, but these should be rare in
modern TeX installations. The major missing feature is Type-1 font
subsetting to reduce output file sizes.
I would be especially interested in hearing reports from users of other
TeX distributions -- I use TeX Live 2008, but I have no idea how
distributions work on Windows.
I added the dviread and type1font modules in the backend API part of the
documentation tree, since these modules are likely only useful for
backend developers. This is my first foray into Sphinx documentation, so
please feel free to tell me if I got anything wrong.
-- 
Jouni K. Seppänen
http://www.iki.fi/jks

On Fri, Dec 26, 2008 at 8:40 AM, Michiel de Hoon <mjl...@ya...> wrote:
> I have written such a function for the qt4 backend; see patch #2468809 at
>
> https://sourceforge.net/tracker/index.php?func=detail&aid=2468809&group_id=80706&atid=560722
>
> I am not a big qt4 user, so it would be good if somebody else could look at this patch before adding it to the trunk.
I would like to apply this patch, but I am not a qt user either, so if
someone could test this and get back to us, that would be great.
JDH

On Mon, Dec 29, 2008 at 8:20 AM, Michael Droettboom <md...@st...> wrote:
> I've refactored hatching support to move the hatch design itself to the
> core, added support for them in the Agg and SVG backends, and simplified
> their usage in the PDF and PS backends. It should now be easier to add
> new hatch styles if anyone ever feels artistic.
Hey Michael, this is really great. Did you get all this done this
morning or was this a holiday project :-) The only problem I see is
that it looks like you forgot to fix the title in the hatch_demo.py!
The last major piece for patches is now gradient fills.
JDH

I've refactored hatching support to move the hatch design itself to the 
core, added support for them in the Agg and SVG backends, and simplified 
their usage in the PDF and PS backends. It should now be easier to add 
new hatch styles if anyone ever feels artistic.
In order to use the same general approach in all backends, the PS 
backend now uses the makepattern command rather than a loop to draw each 
hatch line. That may be a regression in certain situations (eg., old PS 
printers without enough memory). So those who were using the old PS 
backend with hatches should test the new approach and report any problems.
Mike
-- 
Michael Droettboom
Science Software Branch
Operations and Engineering Division
Space Telescope Science Institute
Operated by AURA for NASA

> This seems like a reasonable change and I have added it to
> the trunk.
> It would be nice to get a canvas.draw_idle on the qt
> backend, so
> perhaps Darren you can add this to your list if you get
> some free
> time.
> 
I have written such a function for the qt4 backend; see patch #2468809 at
https://sourceforge.net/tracker/index.php?func=detail&aid=2468809&group_id=80706&atid=560722
I am not a big qt4 user, so it would be good if somebody else could look at this patch before adding it to the trunk.
--Michiel.
 

On Wed, Dec 24, 2008 at 3:34 AM, Sandro Tosi <mo...@de...> wrote:
> Hi!
>
> On Wed, Dec 17, 2008 at 22:16, Michael Droettboom <md...@st...> wrote:
>> Ok. Based on your success report, I'll go ahead and merge this to trunk.
>>
>> Sandro: please let me know if these changes break anything in your package
>> build scripts.
>
> I don't know if you're waiting for an input from me, but: John made me
> test 0.98.5.2 preliminary version and doc build was great! the whole
> set of packages (included the original tarball) is not ~62M, much
> better :)
>
> After the off-list email exchange with John, I saw no official
> announce of 0.98.5.2, so maybe you're planning to do it as xmas gift,
> just to be sure I didn't miss anything :)
I'll let you know, don't worry. After all the pain, I want to make
sure we have a stable build, and there is at least one fix (legend
dpi) that I will push out into 98.5.3 before I ask you to upload for
debian. After Christmas, though.
JDH

Hi!
On Wed, Dec 17, 2008 at 22:16, Michael Droettboom <md...@st...> wrote:
> Ok. Based on your success report, I'll go ahead and merge this to trunk.
>
> Sandro: please let me know if these changes break anything in your package
> build scripts.
I don't know if you're waiting for an input from me, but: John made me
test 0.98.5.2 preliminary version and doc build was great! the whole
set of packages (included the original tarball) is not ~62M, much
better :)
After the off-list email exchange with John, I saw no official
announce of 0.98.5.2, so maybe you're planning to do it as xmas gift,
just to be sure I didn't miss anything :)
Cheers and Merry Xmas guys :)
-- 
Sandro Tosi (aka morph, Morpheus, matrixhasu)
My website: http://matrixhasu.altervista.org/
Me at Debian: http://wiki.debian.org/SandroTosi

On Fri, Dec 19, 2008 at 9:07 AM, Paul Kienzle <pau...@ni...> wrote:
>> Interactive is not the best word, but it is the rc parameter meaning
>> "you are using mpl from the interactive prompt and want every pyplot
>> command to update the plot". If the macosx backend is not doing this
>> it should. If tkagg is issuing draw commands on pyplot commands when
>> interactive is False, it is a bug that we should be able to fix.
>
> The interactive backends (wx, tk, gtk) all handle draw_idle in a way
> which delays the drawing until there are no more commands to run.
This seems like a reasonable change and I have added it to the trunk.
It would be nice to get a canvas.draw_idle on the qt backend, so
perhaps Darren you can add this to your list if you get some free
time.
JDH

> The interactive backends (wx, tk, gtk) all handle draw_idle
> in a way which delays the drawing until there are no
> more commands to run.
> 
> By changing draw_if_interactive to use draw_idle instead of
> draw,
> wouldn't this automatically smooth over the performance
> issues without
> the user having to toggle interactive in their scripts?
I just tried this approach with the tkagg and gtk backends, and indeed, this does solve the performance issue in interactive mode.
--Michiel.
 

> Could you post the script you are using to do the
> profiling?
This is the code that I was using
from pylab import *
import numpy
figure()
x=numpy.arange(20)
y=1+x**2
n = 4
for i in range(n*n):
 subplot(n,n,i+1)
 bar(x,y,log=True)
 xlim(-5,25)
 ylim(1,1e4)
> The call to subplot/plot/bar should not trigger a draw, unless
> "interactive" is set to True
I was doing the profiling with "interactive" set to True (both for the Agg backends and for the Mac OS X native backend). With "interactive" set to False, I don't see any significant speed difference between Agg and the native backend.
> Interactive is not the best word, but it is the rc
> parameter meaning
> "you are using mpl from the interactive prompt and
> want every pyplot
> command to update the plot". If the macosx backend is
> not doing this it should. 
In its current form, the MacOSX backend assumes that mpl is being used from the interactive prompt and the plot is updated whenever there are no further Python commands (in other words, when Python is waiting for the user to type in the next Python command). Maybe this is a naive question, but why would a user want every pyplot command to update the plot? 
--Michiel.
 

John,
Sometime in January, we are going to spend some time fixing a few minor MPL bugs we've hit and a probably work on a few enhancements (I'll send you a list in Jan before we start anything - it's nothing major). We're also going to work on writing a set of tests that try various plots w/ units. I was thinking this would be a good time to introduce a standard test harness into the MPL CM tree.
I think we should:
1) Select a standard test harness. The two big hitters seem to be unittest and nose. unittest has the advantage that it's shipped w/ Python. nose seems to do better with automatic discovery of test cases.
2) Establish a set of testing requirements. Naming conventions, usage conventions, etc. Things like tests should never print anything to the screen (i.e. correct behavior is encoded in the test case) or rely on a GUI unless that's what is being tested (allows tests to be run w/o an X-server). Basically write some documentation for the test system that includes how to use it and what's required of people when they add tests.
3) Write a test 'template' for people to use. This would define a test case and put TODO statements or something like it in place for people to fill in. More than one might be good for various classes of tests (maybe an image comparison template for testing agg drawing and a non-plot template for testing basic computations like transforms?).
Some things we do on my project for our Python test systems:
We put all unit tests in a 'test' directory inside the python package being tested. The disadvantage of this is that potentially large tests are inside the code to be delivered (though a nice delivery script can easily strip them out). The advantage of this is that it makes coverage checking easier. You can run the test case for a package and then check the coverage in the module w/o trying to figure out which things should be coverage checked or not. If you put the test cases in a different directory tree, then it's much harder to identify coverage sources. Though in our case we have 100's of python modules - in MPL's case, there is really just MPL, projections, backends, and numerix so maybe that's not too much of a problem.
Automatic coverage isn't something that is must have, but it is really nice. I've found that it actually causes developers to write more tests because they can run the coverage and get a "score" that other people will see. It's also a good way to check a new submission to see if the developer has done basic testing of the code.
For our tests, we require that the test never print anything to the screen, clean up any of its output files (i.e. leave the directory in the same state it was before), and only report that the test passed or failed and if it failed, add some error message. The key thing is that the conditions for correctness are encoded into the test itself. We have a command line option that gets passed to the test cases to say "don't clean up" so that you can examine the output from a failing test case w/o modifying the test code. This option is really useful when an image comparison fails.
We've wrapped the basic python unittest package. It's pretty simple and reasonably powerful. I doubt there is anything MPL would be doing that it can't handle. The auto-discovery of nose is nice but unnecessary in my opinion. As long as people follow a standard way of doing things, auto-discovery is fairly easy. Of course if you prefer nose and don't mind the additional tool requirement, that's fine too. Some things that are probably needed:
- command line executable that runs the tests.
 - support flags for running only some tests
 - support flags for running only tests that don't need a GUI backend
 (require Agg?). This allows automated testing and visual testing to be
 combined. GUI tests could be placed in identified directories and then
 only run when requested since by their nature they require specific backends
 and user interaction.
 - nice report on test pass/fail status
 - hooks to add coverage checking and reporting in the future
- test utilities
 - image comparison tools
 - ??? basically anything that helps w/ testing and could be common across
 test cases
As a first cut, I would suggest is something like this:
.../test/run.py
 mplTest/
 test_unit/
 test_transform/
 test_...
The run script would execute all/some of the tests. Any common test code would be put in the mplTest directory. Any directory named 'test_XXX' is for test cases where 'XXX' is some category name that can be used in the run script to run a subset of cases. Inside each test_XXX directory, one unittest class per file. The run script would find the .py files in the test_XXX directories, import them, find all the unittest classes, and run them. The run script also sets up sys.path so that the mplTest package is available.
Links:
http://docs.python.org/library/unittest.html
http://somethingaboutorange.com/mrl/projects/nose/
http://kbyanc.blogspot.com/2007/06/pythons-unittest-module-aint-that-bad.html
coverage checking:
http://nedbatchelder.com/code/modules/coverage.html
http://darcs.idyll.org/~t/projects/figleaf/doc/
Thoughts?
Ted
ps: looking at the current unit directory, it looks like at least one test (nose_tests) is using nose even though it's not supplied w/ MPL. Most of the tests do something and show a plot but the correct behavior is never written into the test.

As there was no explicit objection, I just submit this to the trunk.
The change in Axes class is rather minor, and I hope others don't
mind.
I added two examples. The examples are rather lengthy, because they
are actually helper classes that I have been playing with (and it is
not well documented).
Here is screenshots.
http://dl.getdropbox.com/u/178748/mpl_aux/axes_divider.png
http://dl.getdropbox.com/u/178748/mpl_aux/axes_grid.png
I hope others find this useful.
Regards,
-JJ
On Wed, Dec 17, 2008 at 1:06 AM, Jae-Joon Lee <lee...@gm...> wrote:
> Hello,
>
> I'm thinking about slightly modifying the draw() method of the Axes
> class, so that user can optionally
> calculate the position of the axes at drawing time. It may be
> considered as a general version of the apply_aspect() method.
>
> For example, instead of "self.apply_aspect()" call in the draw
> function, we may put something like below.
>
> if self._axes_locator:
> self._axes_locator(self, renderer)
> else:
> self.apply_aspect()
>
> where self._axes_locator is a (user-supplied) callable object which
> takes the axes itself and the renderer as arguments.
> I have been running a similar version of this, and I found it quite
> helpful especially when drawing images. Here are a few of my use
> cases.
>
> * colorbar (or any kind of axes) whose location is adjusted to match
> the image location (which is calculated on the fly with apply_aspect).
> * grid of images (of same size) with fixed space between them.
>
> I guess the needed change is not significant and I don't think it will
> interfere with other things of Axes class.
> So, how do others think?
>
> Regards,
>
> -JJ
>

On Fri, Dec 19, 2008 at 6:50 PM, Sandro Tosi <mo...@de...> wrote:
> On Fri, Dec 19, 2008 at 18:47, Ondrej Certik <on...@ce...> wrote:
>> On Fri, Dec 19, 2008 at 6:34 PM, Sandro Tosi <mo...@de...> wrote:
>>> This is fixed in the latest release (0.98.4 or in 0.98.5); I'm working
>>> on uploading it Debian, together with John and Michael (and all dev
>>> team), to have a feasable release.
>>
>> Ah, I didn't know you are on the mpl dev team as well. That's great.
>
> Oh no no: I bother them for something, and they (to force me to
> silence) release a fix :D
Ah I see. The next level is that they'll force you to fix it yourself. :)
Ondrej

On Fri, Dec 19, 2008 at 18:47, Ondrej Certik <on...@ce...> wrote:
> On Fri, Dec 19, 2008 at 6:34 PM, Sandro Tosi <mo...@de...> wrote:
>> This is fixed in the latest release (0.98.4 or in 0.98.5); I'm working
>> on uploading it Debian, together with John and Michael (and all dev
>> team), to have a feasable release.
>
> Ah, I didn't know you are on the mpl dev team as well. That's great.
Oh no no: I bother them for something, and they (to force me to
silence) release a fix :D
Cheers,
-- 
Sandro Tosi (aka morph, Morpheus, matrixhasu)
My website: http://matrixhasu.altervista.org/
Me at Debian: http://wiki.debian.org/SandroTosi

On Dec 19, 2008, at 7:52 AM, John Hunter wrote:
> Could you post the script you are using to do the profiling? The call
> to subplot/plot/bar should not trigger a draw, unless "interactive" is
> set to True
>
> http://matplotlib.sourceforge.net/users/shell.html
>
> Interactive is not the best word, but it is the rc parameter meaning
> "you are using mpl from the interactive prompt and want every pyplot
> command to update the plot". If the macosx backend is not doing this
> it should. If tkagg is issuing draw commands on pyplot commands when
> interactive is False, it is a bug that we should be able to fix.
The interactive backends (wx, tk, gtk) all handle draw_idle in a way
which delays the drawing until there are no more commands to run.
By changing draw_if_interactive to use draw_idle instead of draw,
wouldn't this automatically smooth over the performance issues without
the user having to toggle interactive in their scripts?
 - Paul

On Fri, Dec 19, 2008 at 2:20 AM, Michiel de Hoon <mjl...@ya...> wrote:
>> This looks great -- in particular I am intrigued by the
>> final timing results which show your backend 12 times
>> faster than tkagg. I am not sure where this speedup is
>> coming from -- do you have some ideas?
>
> In this example, I am drawing 16 subplots in a 4x4 grid. With Tkagg, I am noticing that the first few subplots appear quickly, but subsequent subplots get slower and slower. I think that this is due to how the event loop works. In my understanding, tkagg redraws the window when a subplot is added. So to draw subplot 16, tkagg also needs to redraw subplots 1..15, causing the progressive slowdown. The native backend draws all 16 at once, and draws each of them only once. Using plot() instead of bar() doesn't really make a difference; the same slowdown happens there with the agg backends.
Could you post the script you are using to do the profiling? The call
to subplot/plot/bar should not trigger a draw, unless "interactive" is
set to True
 http://matplotlib.sourceforge.net/users/shell.html
Interactive is not the best word, but it is the rc parameter meaning
"you are using mpl from the interactive prompt and want every pyplot
command to update the plot". If the macosx backend is not doing this
it should. If tkagg is issuing draw commands on pyplot commands when
interactive is False, it is a bug that we should be able to fix.
Thanks,
JDH

On Fri, Dec 19, 2008 at 1:49 AM, Michiel de Hoon <mjl...@ya...> wrote:
> It appears that the 98.5.2 tarball is missing one file for the native Mac OS X backend: src/_macosx.m is missing. The other file (lib/matplotlib/backends/backend_macosx.py) is present.
Yep, I forgot to modify the MNIFEST.in to include *.m files from src.
This is fixed and new files have been uploaded. Thanks for catching
this.
JDH

> This looks great -- in particular I am intrigued by the
> final timing results which show your backend 12 times
> faster than tkagg. I am not sure where this speedup is
> coming from -- do you have some ideas?
In this example, I am drawing 16 subplots in a 4x4 grid. With Tkagg, I am noticing that the first few subplots appear quickly, but subsequent subplots get slower and slower. I think that this is due to how the event loop works. In my understanding, tkagg redraws the window when a subplot is added. So to draw subplot 16, tkagg also needs to redraw subplots 1..15, causing the progressive slowdown. The native backend draws all 16 at once, and draws each of them only once. Using plot() instead of bar() doesn't really make a difference; the same slowdown happens there with the agg backends.
In principle, it should be possible to avoid these redraws with the agg and other backends, but it depends on how much of the underlying event loop is exposed by Tkinter/gtk/wx. Basically, instead of calling figManager.show() from draw_if_interactive(), we'd have to call it from inside the Tkinter/gtk/wx event loop just before the event loop starts waiting for events. However, it depends on whether the functionality to insert calls into the event loop is available on Tkinter/gtk/wx.
> Since the new macosx backend was released in 0.98.5, I also
> need to decide whether this patch belongs on the branch, and hence
> will get pushed out as early as today in a bugfix release when some
> changes JJ and Michael are working on are ready, or the trunk, in
> which case it could be months.
> .... I'm in favor of branch, ...
Me too. :-).
--Michiel
> 
> JDH
> 
> 
> On Tue, Dec 16, 2008 at 6:08 PM, Michiel de Hoon
> <mjl...@ya...> wrote:
> > Dear all,
> >
> > I have now implemented the draw_path_collection,
> draw_quad_mesh, and draw_markers methods in the Mac OS X
> native backend (see patch 2179017 at
> >
> http://sourceforge.net/tracker/?func=detail&atid=560722&aid=2179017&group_id=80706).
> Some timings are below. In terms of raw drawing speed, the
> native backend can be either faster or slower than agg. On
> the other hand, the native backend can be considerably
> faster if the agg backend uses many calls to draw(); the
> native backend can avoid these superfluous because it has
> complete control over the event loop (see the third example
> below).
> > # Timings in seconds
> > # n Mac OS X TkAgg
> > # 2 2 6
> > # 3 3 23
> > # 4 5 66
> >
> >
 

It appears that the 98.5.2 tarball is missing one file for the native Mac OS X backend: src/_macosx.m is missing. The other file (lib/matplotlib/backends/backend_macosx.py) is present.
--Michiel.
--- On Thu, 12/18/08, John Hunter <jd...@gm...> wrote:
> From: John Hunter <jd...@gm...>
> Subject: [matplotlib-devel] 98.5.2 tarball and OS X binaries up
> To: "matplotlib development list" <mat...@li...>
> Date: Thursday, December 18, 2008, 12:26 PM
> Just wanted to let you know that I posted the 0.98.5.2
> tarball and OS
> X binaries at
> 
> https://sourceforge.net/project/showfiles.php?group_id=80706&package_id=278194&release_id=646644
> 
> I'm going to hold off an announcement to the users list
> until Charlie
> gets the win32 binaries up.
> 
> JDH
> 
> ------------------------------------------------------------------------------
> SF.Net email is Sponsored by MIX09, March 18-20, 2009 in
> Las Vegas, Nevada.
> The future of the web can't happen without you. Join
> us at MIX09 to help
> pave the way to the Next Web now. Learn more and register
> at
> http://ad.doubleclick.net/clk;208669438;13503038;i?http://2009.visitmix.com/
> _______________________________________________
> Matplotlib-devel mailing list
> Mat...@li...
> https://lists.sourceforge.net/lists/listinfo/matplotlib-devel
 

This post is related with a bug reported in
http://sourceforge.net/tracker/index.php?func=detail&aid=2430751&group_id=80706&atid=560720
John assigned this to me, and I thought it is better to discuss with others.
First of all, I actually don't know much about the svg, so others
(someone who wrote the svg backend?) may give much better answer than
me.
Anyhow, I guess there are two issues related.
1) As Jacob said, all the text in MPL is actually left-aligned. MPL
internally calculates the needed offset according to the alignment,
and make all the text left-aligned.
2) The resulting texts have wrong alignment If svg renderer picks up
different font than what MPL used to calculate the offset. This does
not happen if embed_char_paths=True.
I'm not sure whether we need to concern about the first issue. We may
delegate alignment of text to svg renderer as Jacob suggested. This
may be useful when one wants to edit the output svg file using tools
like inkscape. MPL still need to calculate the offset due to different
alignment to support things like (fancy)box around the text. I'm
personally happy with the way it is, though.
The second issue may need some work. The best way I can think of is to
embed the font inside the svg file (but this has a license issue,
although we're doing it now anyway). As of now, when embed_char_paths
is True, the glyphs of each character are embedded as paths, not as a
font. It will be relatively easy to change the current code to make
the embed path as a font, although handling of kerning and such will
be quite difficult. We may include svg font with kerning information
in the mpl distribution (as we do for some ttf and other fonts now)
and embed these fonts to the ouput file.
I guess, it all depends on how strongly we want to support the
post-editing of the output svg file.
So, how others think?
Regards,
-JJ

John Hunter skrev:
> 
> That would be nice, because it would make it easier for users and
> developers to contribute to the docs and test their changes. Right
> now there is something of a barrier to entry for people who want to
> contribute to the docs.
> 
> JDH
What about building the docs on windows? The mpl_examples, mpl_data 
links don't work on windows, I get a file that contains:
link ../mpl_examples
Is it possible to convince sphinx to follow the path that is inside this 
file?
Today I saw that the new legend options are missing in the docs. At 
least in the docs on the front page.
/Jörgen

Just wanted to let you know that I posted the 0.98.5.2 tarball and OS
X binaries at
https://sourceforge.net/project/showfiles.php?group_id=80706&package_id=278194&release_id=646644
I'm going to hold off an announcement to the users list until Charlie
gets the win32 binaries up.
JDH

On Wed, Dec 17, 2008 at 3:57 PM, Gael Varoquaux
<gae...@no...> wrote:
> On Wed, Dec 17, 2008 at 12:25:12PM -0600, John Hunter wrote:
> Talking about that, last time I looked, the plot directive, and the other
> MPL sphinx extension were not in the matplotlib namespace, and thus not
> importable by other programs. This is a pity, because they can be useful
> for other projects (I wrote for instance some lecture notes using sphinx
> to doctest them, and I wanted to use the plot directive).
>
> It seems it would be very easy to put them in a matplotlib submodule, and
> have the sphinx conf.py import from there. Nothing urgent, but if there
> is no reason no to, I would make me a happy man.
We have provided the sphinx_template2 to serve as a starting point for
sphinx projects that want to use the plot, mathmpl, etc, extensions.
Unfortunately, we are not doing the best job of keeping the two in
sync. Fernando and I have talked of the need to have standard,
reusable components for these kinds of things. Perhaps it would be
possible to move the guts of some of these into a matplotlib.sphinxext
module.
Here is the pointer to the sphinx template:
http://matplotlib.svn.sourceforge.net/viewvc/matplotlib/trunk/py4science/examples/sphinx_template2/

On Wed, Dec 17, 2008 at 12:25:12PM -0600, John Hunter wrote:
> Thanks again, sorry that was such a bear. Hopefully the plot
> directive emerges stronger from the carnage.
Talking about that, last time I looked, the plot directive, and the other
MPL sphinx extension were not in the matplotlib namespace, and thus not
importable by other programs. This is a pity, because they can be useful
for other projects (I wrote for instance some lecture notes using sphinx
to doctest them, and I wanted to use the plot directive).
It seems it would be very easy to put them in a matplotlib submodule, and
have the sphinx conf.py import from there. Nothing urgent, but if there
is no reason no to, I would make me a happy man.
Cheers,
Gaël

On Wed, Dec 17, 2008 at 22:25, John Hunter <jd...@gm...> wrote:
> Sandro -- do you distribute something like a matplotlib-devel, so that
> people who want to compile mpl, and build the docs, could do so
> themselves with a simple
do you mean something like the source package + debianization? of
course we do! :) you need a "source" line in the /etc/apt/sources.list
(something like deb-src <url>) and then
apt-get source <source_package_name>
in this case matplotlib.
> > apt-get install python-matplotlib-devel
> > cd ~/path/to/mpl/docs
> > python make.py html latex
>
> That would be nice, because it would make it easier for users and
> developers to contribute to the docs and test their changes. Right
> now there is something of a barrier to entry for people who want to
> contribute to the docs.
once you issued that "apt-get source" you'll have a nice "<pkg
nam>-<version>" dir in . with the upstream tarball uncompress and with
the debianization applied. With that, you can do all you can with the
upstream source code, or use debian tools to compile the package.
I hope I answered your question,
-- 
Sandro Tosi (aka morph, Morpheus, matrixhasu)
My website: http://matrixhasu.altervista.org/
Me at Debian: http://wiki.debian.org/SandroTosi