From: Lea W. <lew...@gm...> - 2008-03-30 08:30:33
|
[When replying, please exclude the Docutils-users list.] Hi everyone, and David in particular, For those uninitiated, Google Summer of Code (SoC) is a program that offers 4500 USD stipends for students to work on open source software during the summer. If you're a student, you should consider applying (feel free to make use of my ideas below); the mentoring umbrellla organization is the Python Software Foundation. Application deadline is Monday 3/31 5pm PDT (4/1 00:00 UTC). I'd like to apply again to SoC this year. David, are you willing to mentor me? Here are some project ideas -- I'd be happy to do any of them. Any suggestions which idea I should choose? (Docutils users, which one would be most helpful for you?) Any comments? Any other project ideas? * Image support: - Render images in different format depending on writer. - Useful for images that are easily representable in text, in particular formulas (LaTeX), graphs (Graphviz), plots (gnuplot, R). - Support "embedding" of images in document tree; render on demand to file format (PDF, PS, PNG). - Automatically convert images if necessary. - Shift file handling and referencing from plugins to framework. - Existing implementations exist for formulas, ASCII art, graphviz, and perhaps some more; make at least some of those work with the new image support framework. * Extension/plugin support: - Support for adding components (parsers/writers). Requires generic frontend: http://docutils.sf.net/docs/dev/todo.html#front-end-tools - Support for modifying existing writers and parsers; e.g. we need a clean way for adding directives and roles to the reST parser. - Support for adding doctree nodes. - Too small in scope for SoC? Design-work-to-code ratio too high? * Clean up LaTeX writer: - The standard LaTeX writer is quite messy in a few places (and lacks support or edge-case workarounds for quite a few things), and I'm not convinced that the "new" LaTeX writer I started is well-designed. - Need to research and document how many shortcomings the existing writer really has before applying for or starting this project to avoid unnecessary work. - Refactor the standard LaTeX writer (or base a rewrite on both writers) to turn the Docutils tree into a LaTeX tree structure, then dump that tree structure to LaTeX code. - Lots of work required to deal with edge cases where LaTeX fails. - Will probably end up doing a lot of research on third-party packages that all do the same job and fail in slightly different ways. - Uncertain how many problem's I'll run into; some features may be unimplementable. - Update the writer to use the TeX Live distribution (the standard LaTeX writer seems to work fine with it, the "new" one doesn't). - Not fun (LaTeX is a mess), but may be practically useful (I still write my papers in LaTeX rather than reST because it allows for greater control; that should change). Best wishes, Lea |
From: Georg B. <g.b...@gm...> - 2008-03-30 08:38:50
|
Lea Wiemann schrieb: > [When replying, please exclude the Docutils-users list.] > > Hi everyone, and David in particular, > > For those uninitiated, Google Summer of Code (SoC) is a program that > offers 4500 USD stipends for students to work on open source software > during the summer. If you're a student, you should consider applying > (feel free to make use of my ideas below); the mentoring umbrellla > organization is the Python Software Foundation. Application deadline is > Monday 3/31 5pm PDT (4/1 00:00 UTC). > > I'd like to apply again to SoC this year. David, are you willing to > mentor me? > > Here are some project ideas -- I'd be happy to do any of them. Any > suggestions which idea I should choose? (Docutils users, which one > would be most helpful for you?) Any comments? Any other project ideas? If I might suggest "Doing a release"? :) Many people are getting anxious about the state of docutils since there hasn't been a release for a long time, and they are referred to install SVN snapshots. How complete is the trunk in terms of release goals? Georg -- Thus spake the Lord: Thou shalt indent with four spaces. No more, no less. Four shall be the number of spaces thou shalt indent, and the number of thy indenting shall be four. Eight shalt thou not indent, nor either indent thou two, excepting that thou then proceed to four. Tabs are right out. |
From: Lea W. <lew...@gm...> - 2008-03-30 08:42:27
|
Georg Brandl wrote: > If I might suggest "Doing a release"? :) Good idea. Not for Google SoC since it takes ~2h rather than 400h, but still a good idea. :) I'll put it on my list; expect email on Docutils-develop in ~7 days or so. -- Lea |
From: Georg B. <g.b...@gm...> - 2008-05-06 16:19:54
|
Lea Wiemann schrieb: > Georg Brandl wrote: >> If I might suggest "Doing a release"? :) > > Good idea. Not for Google SoC since it takes ~2h rather than 400h, but > still a good idea. :) I'll put it on my list; expect email on > Docutils-develop in ~7 days or so. Don't want to seem impatient or something, but I wanted to ask what the status of your list is :) Georg |
From: engelbert g. <gr...@us...> - 2008-03-30 09:14:24
|
as i do th emaintenance on the latexwriter i am for cleaning up and would apply for this myself if i would be a student . either way i would like to give a hand or two. cheers |
From: Lea W. <lew...@gm...> - 2008-03-30 09:35:39
|
engelbert gruber wrote: > as i do th emaintenance on the latexwriter i am for cleaning up > and would apply for this myself if i would be a student . > > either way i would like to give a hand or two. Cool, thanks a lot for the offer! -- Lea |
From: Alan G I. <ai...@am...> - 2008-03-30 14:36:36
|
On Sun, 30 Mar 2008, Lea Wiemann apparently wrote: > * Image support: > * Extension/plugin support: > * Clean up LaTeX writer: Please consider taking on the issue of better citation support. I just had someone contact me off-list again to ask if there had been any movement on this. I think top priority on such a project would be a mechanism for providing substitution text for the citation reference. I recently completed a journal article in reST. Submission required not only that the citations be correctly formatted, which can easily be done with bibstuff, but also that the citation references be correctly formatted. This requires some formatting hints that reST does not currently provide. The result is that anyone using reST to write academic papers must do substantial post processing. So the big request is to allow a formatting hint. So for example [lea-2006-jar|p] might be written as:: \citep{lea-2006-jar} OR <a class="citation-reference" href="#lea-2006-jar" id="id38">(Wiemann 1959)</a> whereas [lea-2006-jar|t] might be written as:: \citep{lea-2006-jar} OR <a class="citation-reference" href="#lea-2006-jar" id="id39">Wiemann (1959)</a> (By a LaTeX writer or HTML writer.) Note that it is important that the citation reference text continue to allow easy access by processors (such as bibstuff) to BibTeX style keys. This allows extracting the references from a BibTeX database. (This need gets in the way of some workarounds that have been proposed in the past.) Thank you, Alan Isaac |
From: Toni A. <an...@an...> - 2008-03-30 18:47:36
|
Alan G Isaac kirjoitti: >> * Extension/plugin support: >> * Clean up LaTeX writer: > Please consider taking on the issue of better citation > support. I just had someone contact me off-list again to > ask if there had been any movement on this. i have often looked at the state of that too, as have been writing academic stuff in rst. > The result is that anyone using reST to write academic > papers must do substantial post processing. indeed. i hacked my own for this recently, did manually for my master thesis earlier :p (that is http://www.an.org/gradu2/gradu2.rst to make http://www.an.org/gradu2/gradu2.pdf, via http://www.an.org/gradu2/gradu2.latex) the recent ugly hack for an article just replaces stuff: #citations text = text.replace('[', ':raw-latex:`\cite{') text = text.replace(']', '}`') #citation arguments (page nums) #- these are inside the citation brackets, and hence the raw-latex text = text.replace('__', '}{') #hyphens (ajatusviiva) text = text.replace('---', ':raw-latex:`---`') #footnotes .. this is now a bit stupidly different from ReST, but oh well. text = text.replace('(#)', '[#]') #only relatively positioned supported now out.write(text) > So the big request is to allow a formatting hint. So for example > [lea-2006-jar|p] might be written as:: > \citep{lea-2006-jar} OR > <a class="citation-reference" href="#lea-2006-jar" id="id38">(Wiemann 1959)</a> > whereas [lea-2006-jar|t] might be written as:: > \citep{lea-2006-jar} OR > <a class="citation-reference" href="#lea-2006-jar" id="id39">Wiemann (1959)</a> hm. seems interesting, and without completely understanding it now i guess something like that could do it :o > Note that it is important that the citation reference text > continue to allow easy access by processors (such as > bibstuff) to BibTeX style keys. This allows extracting the > references from a BibTeX database. (This need gets in the > way of some workarounds that have been proposed in the past.) ok .. i've only done postprocessing, but in a project earlier other guys iirc hacked docutils so that you could do .. bibliography:: i don't remember now whether/when/how/where that kind of stuff has been discussed before, that project is http://www.fenfire.org/ .. they also integrated a textual uml syntax to their documentation system back then (http://tuukka.iki.fi/2003/navidoc/navidoc-poster.pdf), but used rst for articles and implemented such a way to use bibtex bibliographys. anyway, this post it basically just a +1 for 'something nice for this would be nice' :) although it's not afwul for me now at all with the postprocessing that i have, certainly like just writing (pretty) normal rst and 'just getting' the correctly formatted pdf out, knowing the ways in which that stupid little "postprocessor" sucks -- so thanks a lot you guys. > Thank you, > Alan Isaac ~Toni |
From: Alan G I. <ai...@am...> - 2008-03-30 19:01:51
|
A couple responses to your post, which may be off base. It was unclear to me if you realized that the LaTeX writer now has support for LaTeX citations and footnotes. This has really made life easier! It was unclear to me if you realized that you can use bibstuff to process an reST document and a BibTeX database into reST-formatted citations. (Please get from SVN if possible.) Cheers, Alan Isaac |
From: Lea W. <lew...@gm...> - 2008-03-31 02:37:34
|
Alan G Isaac wrote: > Please consider taking on the issue of better citation support. As much as I'd like to, I don't think I'm the right person for this -- I'm a an undergrad majoring in math, so with the handful of papers I have to write during my college career, I just hack in citations the way my professors tell me to and forget about them. I don't really understand the variety of citation styles out there, nor can I claim to have more than superficial understanding of BibTeX. That said, the implementation of what you're talking about seems to *relatively* easy; perhaps something is required to allow the HTML writer to use BibTeX sources (LaTeX-only solutions would be pretty much unacceptable for Docutils), but beyond that I don't see much difficulty. So I suggest you come up with a spec for the new citation syntax (talking about rationale, syntax, implementation, compatibility [no breakage and no fundamentally new syntax, if possible]) post it on Docutils-develop, and implement it. I don't recommend you do this if you're not willing to implement it or at least pay someone for it -- David didn't work in academia either last time we talked, so I suspect you won't be able to expect too much coding power from either of us. Best wishes, Lea |
From: Alan G I. <ai...@am...> - 2008-03-31 06:52:57
|
On Sun, 30 Mar 2008, Lea Wiemann apparently wrote: > That said, the implementation of what you're talking about > seems to relatively easy; perhaps something is required to > allow the HTML writer to use BibTeX sources (LaTeX-only > solutions would be pretty much unacceptable for Docutils), > but beyond that I don't see much difficulty. Note that bibstuff already extracts the citation references from an reST document and produces reST formatted citations based on entries in a BibTeX database. My request was not about that. The problem is the need to be able to parameterize citation references. I do not really care how this is done, but I hope the docutils developers will take this need seriously, since it has been expressed by many people. My first pass at a proposal was to allow [citereftext|params] so that the parameter information could be easily split out by writers that choose to recognize it. Then "citereftext|params".split("|")[0] would always work fine to produce "citereftext". Thank you, Alan Isaac PS Note that as a bibstuff developer, I feel that I am already making my contribution to citation support for reST. I am not prepared to become a docutils developer as well. |
From: <gr...@us...> - 2008-03-31 10:26:44
|
On Mon, 31 Mar 2008, Alan G Isaac wrote: > On Sun, 30 Mar 2008, Lea Wiemann apparently wrote: >> That said, the implementation of what you're talking about >> seems to relatively easy; perhaps something is required to >> allow the HTML writer to use BibTeX sources (LaTeX-only >> solutions would be pretty much unacceptable for Docutils), >> but beyond that I don't see much difficulty. > > Note that bibstuff already extracts the citation references > from an reST document and produces reST formatted citations > based on entries in a BibTeX database. > > My request was not about that. > > The problem is the need to be able to parameterize citation > references. I do not really care how this is done, but > I hope the docutils developers will take this need > seriously, since it has been expressed by many people. > > My first pass at a proposal was to allow > [citereftext|params] > so that the parameter information could be easily split out > by writers that choose to recognize it. Then > "citereftext|params".split("|")[0] would always work fine > to produce "citereftext". does this http://ocoins.info/ apply to the htmlwriter or ? -- |
From: Alan G I. <ai...@am...> - 2008-03-31 16:49:38
|
On Mon, 31 Mar 2008, (CEST) gr...@us... apparently wrote: > http://ocoins.info/ That involves ambitions beyond anything I have in mind! The proposal on the table is extremely simple: allow paramterizing the citation reference. I have not even proposed that the writers do anything with the parameterization: for now that might be left to post-processors. Suppose the proposed syntax were accepted. I believe the implementation steps involved would be: 1. allow the bar ``|`` as a citation reference character. 2. docutils would have to be slightly changes to extract the citation reference (since those are used by the target). So from ``[citeref|p]_`` docutils would want to extract "citeref|p".split('|')[0] as the citation reference. Cheers, Alan Isaac |
From: Toni A. <an...@an...> - 2008-03-31 17:22:12
|
Alan G Isaac kirjoitti: > The proposal on the table is extremely simple: > allow paramterizing the citation reference. iirc i had to hack parameters back earlier in somehow too .. seems that did a very ugly thing: "Bogost goes on to suggest that the notion of a supposedly sharp division between game and not-game should be revised [bogost2006unitops__(p. 134)]." which translate to latex as: \cite{bogost2006unitops}{(p. 134)} > Suppose the proposed syntax were accepted. > I believe the implementation steps involved would be: > 1. allow the bar ``|`` as a citation reference character. > 2. docutils would have to be slightly changes to extract > the citation reference (since those are used by the > target). So from ``[citeref|p]_`` docutils would want to > extract "citeref|p".split('|')[0] as the citation seems like a well possible solution to me. but i'm no docutils/syntax expert really. > Alan Isaac ~Toni |
From: Torsten B. <br...@ph...> - 2008-03-31 07:00:14
|
Hallöchen! Lea Wiemann writes: > [...] > > That said, the implementation of what you're talking about seems > to *relatively* easy; perhaps something is required to allow the > HTML writer to use BibTeX sources (LaTeX-only solutions would be > pretty much unacceptable for Docutils), but beyond that I don't > see much difficulty. With custombib, it is possible to configure BibTeX in a way that it produces HTML excerpts. Maybe a little bit of postprocessing is necessary. Then, there is biblatex, a relatively new but exciting development. It reduces BibTeX to the mere sorting machine. All markup is done on the LaTeX level which makes the use and creation of styles much much easier. Tschö, Torsten. -- Torsten Bronger, aquisgrana, europa vetus Jabber ID: br...@ja... (See http://ime.webhop.org for further contact info.) |
From: Alan G I. <ai...@am...> - 2008-03-31 16:49:36
|
On Mon, 31 Mar 2008, Torsten Bronger apparently wrote: > With custombib, it is possible to configure BibTeX in a way that it > produces HTML excerpts. Maybe a little bit of postprocessing is > necessary. > Then, there is biblatex, a relatively new but exciting development. > It reduces BibTeX to the mere sorting machine. All markup is done > on the LaTeX level which makes the use and creation of styles much > much easier. Unless I am missing something, none of this addresses the problem at hand: inadequate citation support for reST documents. To repeat. 1. Users of the LaTeX writer are in OK shape. They have been allowed to turn citation handling over to LaTeX. They face a single problem: reST does not currently allow parameterization of citation references. **This is the change I have requested.** With this change, a tiny change in the LaTeX writer will put users in great shape for citation handling. Indeed, unless I am overlooking something, this is really the last step need to provide users of the LaTeX writer with full blown citation facilities. LaTeX users could use bibstuff (see below), but (many!) thanks to Engelbert, they can stick with LaTeX instead. 2. Users of the HTML writers are in a bit less good shape. The availability of bibstuff really helps here: bibstuff uses the citation references in an reST document to output reST **formatted** citations based on any standard BibTeX database, so the output can simply be included in the reST document. But unlike LaTeX users, those who need HTML have no nice way to substitute for citation references. Allowing parameterized citation references would be an important step toward improving this too. (E.g., I could make bibstuff use the parameters, or a writer could provide parameterized substitutions for the citation references.) So for all reST users with serious citation needs, this would be an important step in the right direction. And for LaTeX users, it provides the immediate possibility of full citation support. Hope that clarifies the situation. Cheers, Alan Isaac |
From: Lea W. <lew...@gm...> - 2008-03-31 16:29:54
|
[When replying, please exclude the Docutils-users list.] Lea Wiemann wrote: > Application deadline is Monday 3/31 5pm PDT (4/1 00:00 UTC). From the SoC announcement list, "The new [extended] deadline for student applications is Monday, April 7, 2008." Presumably at 5pm PDT. If there are any other students here: go apply! :) -- Lea |
From: Lea W. <lew...@gm...> - 2008-04-08 00:18:36
|
I've just submitted a proposal for adding embedded formula/plot/graph support to Docutils/reStructuredText. Here's the abstract: ------------------------------------------------------------------------ I propose to add image embedding support to the Docutils framework, including getting LaTeX formula, graphviz graph and gnuplot plot support, so that you can embed LaTeX/graphviz/gnuplot code in reStructuredText documents, and any of these programs can be automatically called to generate images that are then embedded into the output document. This is especially helpful for the scientic Python community, since they frequently need to include formulas and plots. Also, graphviz is *really* handy for creating graphs, which would improve our ability to quickly create graphical illustrations for software. ------------------------------------------------------------------------ Proposal text: ------------------------------------------------------------------------ I propose to add image embedding support to the Docutils framework. This means that it should be easy to write plugins that generate images, and the framework takes care of writing those images to disk and referencing them appropriately. Currently, images are only supported by URI reference, which is awkward and does not work reliably across writers. Timeline (I have ~9 weeks due to being on vacation with my family): * 1st-3rd week: Design and implement a framework that allows plugins to generate images and let Docutils take care of embedding them into the document. * 4th-6th week: Port the existing (not widely used) LaTeX formula, graphviz, and ASCII-art-to-PNG support to the new framework. Fill in implementations where necessary, so rendering to HTML documents (requiring PNG images) and to PDF documents through LaTeX (requiring PDF or EPS images) works transparently. (For instance, there are different LaTeX formula plugins, for either LaTeX or HTML, but there is no existing output-format-independent support.) Clean up code, where necessary. Have a discussion on the mailing list about how to make the syntax for embedding LaTeX/graphviz/gnuplot code in reStructuredText consistent, and implement the reStructuredText syntax. * 7th week: Design and implement gnuplot support. * 8th week: Documentation. * 9th week: Buffer time. Perhaps try to merge the LaTeX, graphviz, gnuplot, and ASCII art support into the core, so no plugins have to be installed. (But I cannot promise that this will be possible at this time -- it will require discussion on the mailing list.) David Goodger is willing to mentor me, like last year -- thanks, David! ------------------------------------------------------------------------ Best wishes, Lea |
From: Gael V. <gae...@no...> - 2008-04-08 00:23:09
|
On Mon, Apr 07, 2008 at 08:18:29PM -0400, Lea Wiemann wrote: > I've just submitted a proposal for adding embedded formula/plot/graph > support to Docutils/reStructuredText. > Here's the abstract: > ------------------------------------------------------------------------ > I propose to add image embedding support to the Docutils framework, > including getting LaTeX formula, graphviz graph and gnuplot plot > support, so that you can embed LaTeX/graphviz/gnuplot code in > reStructuredText documents, and any of these programs can be > automatically called to generate images that are then embedded into the > output document. Why Gnuplot and not Matplotlib? Matplotlib is Python, and thereforr much easier to integrate. The Python scientific community strongly encourages users to use MatPlotLib. By the way, the SVN version of MatPlotLib as a LaTeX-like renderer that does an amzing job of maching LaTeX's output. That might come in handy to provide LaTeX functionnality without requiring LaTeX. My 2 cents, Gaël |
From: Alan G I. <ai...@am...> - 2008-04-08 01:15:24
|
On Tue, 8 Apr 2008, Gael Varoquaux apparently wrote: > Why Gnuplot and not Matplotlib? Matplotlib is Python, and > thereforr much easier to integrate. The Python scientific > community strongly encourages users to use MatPlotLib. I strongly agree!! I would add that since discovering Matplotlib, I almost never use gnuplot. However, note that Gnuplot.py allows cross-platform control of gnuplot binaries. Cheers, Alan Isaac |
From: Aahz <aa...@py...> - 2008-04-08 00:36:00
|
On Mon, Apr 07, 2008, Lea Wiemann wrote: > > I've just submitted a proposal for adding embedded formula/plot/graph > support to Docutils/reStructuredText. Congrats! Looks good! -- Aahz (aa...@py...) <*> http://www.pythoncraft.com/ "It is easier to optimize correct code than to correct optimized code." --Bill Harlan |
From: Lea W. <lew...@gm...> - 2008-05-25 22:22:57
|
Lea Wiemann wrote: > I'd like to apply again to SoC this year. Hi everyone, Apologies for the delay -- I just wanted to let everyone know that another of my Google Summer of Code applications (for git, the VCS) has been accepted, so I won't be working on Docutils this summer. :( Best, Lea |
From: David G. <go...@py...> - 2008-05-26 01:01:55
Attachments:
signature.asc
|
[Lea Wiemann - 2008-05-25 18:22] > Apologies for the delay -- I just wanted to let everyone know that > another of my Google Summer of Code applications (for git, the VCS) has > been accepted, so I won't be working on Docutils this summer. :( Lea's Docutils application probably would have been accepted, but Git was really keen, and the Python side had many more applications than available slots. Good luck Lea! -- David Goodger <http://python.net/~goodger> |