# Just Launched: You can now import projects and releases from Google Code onto SourceForge

We are excited to release new functionality to enable a 1-click import from Google Code onto the Allura platform on SourceForge. You can import tickets, wikis, source, releases, and more with a few simple steps.

## docutils-develop

 [Docutils-develop] plan to add math support From: Guenter Milde - 2010-10-18 13:08:47 Dear Docutils developers, after import this, I read Simple is better than complex. There should be one-- and preferably only one --obvious way to do it. Now is better than never. and want to start implementing math support *now*. Plan: 1. stage: Basic support * "math" role and directive * input language "LaTeX math" * output as literal in the non-latex writers 2. stage: Improvements * support other writers (see todo.txt for existing work that we can build upon). * accept Unicode input. Directive --------- +++ rst/directives.txt (Arbeitskopie) @@ -492,6 +492,55 @@ +.. _math: + +Math Block +========== + +**NOT IMPLEMENTED YET** + +:Directive Type: "math" +:Doctree Element: math-block +:Directive Arguments: None. +:Directive Options: Possible. +:Directive Content: Becomes the body of the math block (display formula). + +The "math" directive inserts a block with mathematical content (display +formula) into the document. + +The default input format is "latex" (LaTeX math syntax without surrounding +). + +If the writer does not support math typesetting, the content will be +inserted verbatim. + +The following options are recognized: + +class : text + Set a "classes" attribute value on the block element. See the + class_ directive. Role ---- +++ rst/roles.txt (Arbeitskopie) @@ -256,6 +256,36 @@ +:math: +========== + +**NOT IMPLEMENTED YET** + +:Aliases: :inline-math:, :m: +:DTD Element: math +:Customization: + :Options: class_, input-format + :Content: None. + +The math role marks its content as mathematical notation (inline formula). + +The default input format is LaTeX math syntax without +the surrounding  ("latex"). + +See the math directive_ (producing display formulas) for more info on +mathematical notation in restructuredText. Doctree additions ----------------- +++ docutils/docs/ref/doctree.txt (Arbeitskopie) @@ -2861,7 +2862,129 @@ +math +======== + +The math element contains text in LaTeX format that will be +typeset as mathematical notation (inline formula). + +Details +------- + +:Category: + Inline Elements_ + +:Parents: + All elements employing the %inline.elements;_ parameter entities in + their content models may contain math. + +:Children: + math elements may contain text data. + +:Analogues: + math is analogous to a XHTML "math" element or + the LaTeX ($math$) mode. + +:Processing: + Rendered as mathematical notation. + +Content Model +------------- + +.. parsed-literal:: + + %text.model;_ + +:Attributes: + The math element contains the common attributes_ + (ids_, names_, dupnames_, source_, and classes_). + +To be completed_. + + +math_block +============== + +The math_block element contains a block of text in +LaTeX format that will be typeset as block of mathematical notation +(display formula). + +The math_block element is generated during the initial parse from a +"math" directive. + +If the writer does not support math typesetting, the content will be +inserted verbatim (i.e. as LaTeX source code). + +Details +------- + +:Category: + Simple Body Elements_ + +:Parents: + All elements employing the %body.elements;_ or + %structure.model;_ parameter entities in their content models + may contain math_block. + +:Children: + math_block elements may contain text data. + +:Analogues: + math_block is analogous to a LaTeX "equation*" environment or a XHTML + "math" element displayed as block-level element. + +:Processing: + Rendered in a block as mathematical notation, typically centered or with + indentation + +Content Model +------------- + +.. parsed-literal:: + + %text.model;_ + +:Attributes: + The math element contains the common attributes_ + (ids_, names_, dupnames_, source_, and classes_). Objections, Comments? Günter 
 Re: [Docutils-develop] plan to add math support From: David Goodger - 2010-10-18 13:45:22 On Mon, Oct 18, 2010 at 09:08, Guenter Milde wrote: > Dear Docutils developers, > > after import this, I read > >  Simple is better than complex. > >  There should be one-- and preferably only one --obvious way to do it. > >  Now is better than never. > > and want to start implementing math support *now*. If you can include reasonable HTML output, +1. If not (and you seem to indicate not), -1. If we can't improve the status quo, what's the point? LaTeX math support exists already, via the "raw" directive at least. It's not ideal, but it's explicit. IOW, HTML output is IMO a necessary precondition for core inclusion. ISTM that this is a case of "never is often better than *right* now." (And the Zen of Python applies best to the Python language itself. Its application to Python *code* is questionable.) -- David Goodger ; 
 Re: [Docutils-develop] plan to add math support From: Roberto Alsina - 2010-10-18 13:53:19 David Goodger writes: > On Mon, Oct 18, 2010 at 09:08, Guenter Milde wrote: >> Dear Docutils developers, >> >> after import this, I read >> >>  Simple is better than complex. >> >>  There should be one-- and preferably only one --obvious way to do it. >> >>  Now is better than never. >> >> and want to start implementing math support *now*. > > If you can include reasonable HTML output, +1. > If not (and you seem to indicate not), -1. > > If we can't improve the status quo, what's the point? LaTeX math > support exists already, via the "raw" directive at least. It's not > ideal, but it's explicit. Not only is it not ideal, it's broken. rst2pdf has math support. sphinx has math support (also in HTML, and yes, jsMath is a pain) The idea that the raw latex directive is enough means that every writer that wants to provide it has two paths: 1) Implement math directive by themselves, which means the document doesn't work with other writers 2) Implement a raw directive that handles this, but then you have to duplicate, triplicate, etc. if you want to use more than one writer that supports math, HTML support via images and matplotlib should not be terribly hard to implement, I am even willing to reluctantly offer to do it ;-) The same thing happens with the code-block directive. I have in rst2pdf a nice code-block that only requires pygments and works for every writer that supports inline text roles with colors and fonts, in case someone wants it, too ;-) 
 Re: [Docutils-develop] plan to add math support From: David Goodger - 2010-10-18 14:02:18 On Mon, Oct 18, 2010 at 10:16, Roberto Alsina wrote: > David Goodger writes: > >> On Mon, Oct 18, 2010 at 09:08, Guenter Milde wrote: >>> Dear Docutils developers, >>> >>> after import this, I read >>> >>>  Simple is better than complex. >>> >>>  There should be one-- and preferably only one --obvious way to do it. >>> >>>  Now is better than never. >>> >>> and want to start implementing math support *now*. >> >> If you can include reasonable HTML output, +1. >> If not (and you seem to indicate not), -1. >> >> If we can't improve the status quo, what's the point? LaTeX math >> support exists already, via the "raw" directive at least. It's not >> ideal, but it's explicit. > > Not only is it not ideal, it's broken. Agreed. But without HTML support the proposed alternative is no less broken. > rst2pdf has math support. > sphinx has math support (also in HTML, and yes, jsMath is a pain) Can these approaches be ported for generalized support? I don't like the situation with Sphinx fragmentation/incompatibility. Core functionality should be moved into core Docutils. Unfortunately I don't have the time to drive this. I've said it before and I'll say it again: the Docutils "commit bit" is widely available to anyone willing to take the responsibility to do the job right. (See http://docutils.sourceforge.net/docs/dev/policies.html -- and that's open to modification too.) If you don't already have the commit bit, just ask! > HTML support via images and matplotlib should not be terribly hard to > implement, I am even willing to reluctantly offer to do it ;-) Great! > The same thing happens with the code-block directive. I have in rst2pdf a > nice code-block that only requires pygments and works for every writer that > supports inline text roles with colors and fonts, in case someone wants it, > too ;-) Sure, please! -- David Goodger ; 
 [Docutils-develop] Adding code-block to docutils From: Roberto Alsina - 2010-11-19 13:27:58 On Monday 18 October 2010 11:01:41 David Goodger wrote: > > The same thing happens with the code-block directive. I have in rst2pdf a > > nice code-block that only requires pygments and works for every writer > > that supports inline text roles with colors and fonts, in case someone > > wants it, too ;-) > > Sure, please! After being very busy for a month, I now have some time for this. I see the math situation has improved, so this leaves the code-block part. Today I committed some new features to rst2pdf's code block implementation. It's based on code by Felix Wiemann and Guenter Milde I found somewhere, with lots of changes. Basically, it now supports everything pygments provides. It is generic enough to work with any writer that can apply inline classes supporting bold/italic/colors, so I know it works with the following writers: * HTML (you need to link a pygments CSS) * Latex (the one from docutils, not the one from sphinx which is earlier) * rst2pdf (of course ;-) I haven't tested it with the Openoffice writer, and I suppose the man writer should work well as far as it goes. I would like to get it into docutils, but I am not terribly happy with the code quality, and I know I am not following docutils conventions. Could anyone give me a hand and look at it? It's here, and it's just one file, self-contained: http://code.google.com/p/rst2pdf/source/browse/trunk/rst2pdf/pygments_code_block_directive.py 
 Re: [Docutils-develop] plan to add math support From: Alan G Isaac - 2010-10-18 14:07:13 On 10/18/2010 9:45 AM, David Goodger wrote: > If you can include reasonable HTML output, +1. > If not (and you seem to indicate not), -1. Even outputting the math in a PRE element would be better than the current situation. This could be offered as an option. But in fact Jens's rst2mathml produces very nice output in a broad set of circumstances. Not all browsers offer good MathML support, but why not let the user decide if that is a problem! PLEASE go forward with this. Alan Isaac 
 Re: [Docutils-develop] plan to add math support From: David Goodger - 2010-10-18 14:18:13 On Mon, Oct 18, 2010 at 10:06, Alan G Isaac wrote: > On 10/18/2010 9:45 AM, David Goodger wrote: >> If you can include reasonable HTML output, +1. >> If not (and you seem to indicate not), -1. > > Even outputting the math in a PRE element would > be better than the current situation. No, it wouldn't. That would be a mis-feature, horribly broken. -1 > But in fact Jens's rst2mathml produces very nice > output in a broad set of circumstances. Does it support LaTeX output? What's the input? If it's general-purpose, it's a viable candidate. Single-purpose is not. > Not all browsers offer good MathML support, Which ones do? Which don't? > but why not let the user decide if that is a problem! Because broken web pages don't help anybody. They'd just generate noise and siphon off the already limited resources we have (like this discussion). > PLEASE go forward with this. Not until it works. I'd like to see this implemented, if only so these discussions go away. But we need a **general-purpose** solution. I'm sorry for your frustration. Please stop pushing for anything but general-purpose solutions. -- David Goodger ; 
 Re: [Docutils-develop] plan to add math support From: Guenter Milde - 2010-10-18 18:52:54 On 2010-10-18, David Goodger wrote: > On Mon, Oct 18, 2010 at 09:08, Guenter Milde wrote: >> I [...] want to start implementing math support *now*. > If you can include reasonable HTML output, +1. Fine. > If not (and you seem to indicate not), -1. This depends on what you consider reasonable. Unfortunately, HTML has no math support. The W3C recommends MathML (http://www.w3.org/Math/), which we can support via Jens' LaTeX -> MathML converter. Browser support for MathML is mixed: * Firefox 1.0 renders PersentationMathML in HTML pages natively. See the MathML project page. (Open source, all major platforms). Since MathML rendering is part of Mozilla's layout engine, all derived browsers (Netscape 7, Galeon, Kmeleon, etc.) include it. * Although IE doesn't directly support MathML, it has the hooks that allow plug-in support, enabling the full MathML experience through plug-ins such as Mathplayer or techexplorer. http://www.w3.org/Math/Software/mathml_software_cat_browsers.html http://en.wikipedia.org/wiki/MathML#Web_browsers Could you try the examples in sandbox/jensj/latex_math/ and tell whether you would consider this reasonable? Alternatives are conversion to images (PNG or SVG) or MathJax_. As almost all math symbols are nowadays available as Unicode characters, simple formulas can also be converted to pure HTML+CSS. .. _MathJax: http://www.mathjax.org/ > If we can't improve the status quo, what's the point? LaTeX math > support exists already, via the "raw" directive at least. It's not > ideal, but it's explicit. The point is to get this started and to get a supported common RST syntax for math instead of a variety of add-ons. Even supporting all output formats that support math (LaTeX, PDF(reportlab), ODF) with a consistent input would be an advantage. > IOW, HTML output is IMO a necessary precondition for core inclusion. I agree that all standard writers should be supported. Günter 
 Re: [Docutils-develop] plan to add math support From: Guenter Milde - 2010-10-18 19:12:28 On 2010-10-18, David Goodger wrote: > On Mon, Oct 18, 2010 at 10:16, Roberto Alsina > wrote: >> David Goodger writes: >>> On Mon, Oct 18, 2010 at 09:08, Guenter Milde wrote: >> rst2pdf has math support. >> sphinx has math support (also in HTML, and yes, jsMath is a pain) > Can these approaches be ported for generalized support? Yes. >> HTML support via images and matplotlib should not be terribly hard to >> implement, I am even willing to reluctantly offer to do it ;-) > Great! This would add to the available choice of HTML output options. So we have for math in HTML: LaTeX2MathML: Jens' latex_math in the sandbox, MathJax: (HTML + JavaScript) Sphinx math extension PNGMath: (images via LaTeX) Sphinx mathplotlib: images via mathplotlib (also SVG?) Not all of them need to be supported in core Docutils, though. My preference for HTML output is LaTeX2MathML. >> The same thing happens with the code-block directive. I have in rst2pdf a >> nice code-block that only requires pygments and works for every writer that >> supports inline text roles with colors and fonts, in case someone wants it, >> too ;-) > Sure, please! There is also a generic implementation in sandbox/code-block-directive. Günter 
 Re: [Docutils-develop] plan to add math support From: Guenter Milde - 2010-10-18 19:36:50 On 2010-10-18, David Goodger wrote: > On Mon, Oct 18, 2010 at 10:06, Alan G Isaac wrote: >> On 10/18/2010 9:45 AM, David Goodger wrote: >> But in fact Jens's rst2mathml produces very nice >> output in a broad set of circumstances. > Does it support LaTeX output? What's the input? The input is LaTeX, so it's not needed for LaTeX output. > If it's general-purpose, it's a viable candidate. Single-purpose is not. The proposed general-purpose math support uses the LaTeX math syntax for input and internal storage. LaTeX math syntax is powerfull and widely supported/used for human-edited presentational math. > I'd like to see this implemented, if only so these discussions go > away. But we need a **general-purpose** solution. I'm sorry for your > frustration. Please stop pushing for anything but general-purpose > solutions. With a LaTeX2MathML converter, we can support all Docutils standard output formats + PDF(rst2pdf_reportlab). The proposed "math" directive/role provides the framework for input and internal storage, and supports the standard output formats. However, it will not overcome intrinsic limitations of the output formats. By this, it is as *general purpose* as the "image" directive: It is up to the user to provide image files in a format understood by the presentation software. The "image" directive does no automatic image conversion, nor automatic selection of a supported graphics format. Günter 
 Re: [Docutils-develop] Adding code-block to docutils From: Guenter Milde - 2010-11-29 09:41:36 On 2010-11-19, Roberto Alsina wrote: > Today I committed some new features to rst2pdf's code block > implementation. It's based on code by Felix Wiemann and Guenter Milde > I found somewhere, with lots of changes. It looks like coming from the code-block-directive sandbox project. http://docutils.sourceforge.net/sandbox/code-block-directive/ > Basically, it now supports everything pygments provides. > It is generic enough to work with any writer that can apply inline classes > supporting bold/italic/colors, so I know it works with the following writers: > * HTML (you need to link a pygments CSS) > * Latex (the one from docutils, not the one from sphinx which is earlier) > * rst2pdf (of course ;-) > I haven't tested it with the Openoffice writer, and I suppose the man writer > should work well as far as it goes. the odp writer has its own implementation already. We must make sure it does not break. > I would like to get it into docutils, but I am not terribly happy with the > code quality, and I know I am not following docutils conventions. To get this into Docutils core, it needs to be moved "to the right places" and included in the documentation. Also, we need style sheets or style sheet extensions for at least HTML and LaTeX. I'd like to change the name of the directive to "code" instead of "code-block" and also add a "code" role for in-line code snippets. This would bring it in line with "math" role and directive. > Could anyone give me a hand and look at it? > It's here, and it's just one file, self-contained: > http://code.google.com/p/rst2pdf/source/browse/trunk/rst2pdf/pygments_code_block_directive.py I had a look. Let me discuss the diff: --- /home/milde/Code/Python/docutils-svn/sandbox/code-block-directive/pygments_code_block_directive.py 2010-11-27 01:35:43.000000000 +0100 +++ /home/milde/Code/Python/docutils-svn/sandbox/code-block-directive/pygments_code_block_directive-roberto.py 2010-11-26 23:52:58.000000000 +0100 There are not-yet-committed changes in my version: -# 2010-11-27 Rename directive and class from "code-block" to "code". -# Fix fallback if pygments not found. ... +from log import log Reporting will be done via the Docutils reporter. ... - lexer = get_lexer_by_name(self.language) + if self.language and unicode(self.language).lower() <> 'none': + lexer = get_lexer_by_name(self.language.lower()) + else: + lexer = get_lexer_by_name('text') What is the use case for this change? ... + if 'include' in options: I would prefer to have "code" as an option to the "include" directive:: .. include:: myfile.py :code: instead of vice versa:: .. code:: :include: myfile.py This would remove the need for duplicating options and leave of +code_block_directive.options = {'include': directives.unchanged_required, + 'start-at': directives.unchanged_required, + 'end-at': directives.unchanged_required, + 'start-after': directives.unchanged_required, + 'end-before': directives.unchanged_required, + 'linenos': directives.unchanged, + 'linenos_offset': directives.unchanged, + 'tab-width': directives.unchanged, + } just code_block_directive.options = {'linenos': directives.unchanged, 'linenos_offset': directives.unchanged, } or, if we implement the line-number offset as an optional argument to 'linenos' with just one additional option. The options 'start-at', 'end-at' and 'linenos' should added to the "include" directive (but this can be discussed and done separately). I am working on an implementation of the "number-lines" option... Thanks for your work, Günter 
 Re: [Docutils-develop] Adding code-block to docutils From: Guenter Milde - 2010-11-30 20:19:07 On 2010-11-29, Guenter Milde wrote: > On 2010-11-19, Roberto Alsina wrote: >> I would like to get it into docutils, but I am not terribly happy with the >> code quality, and I know I am not following docutils conventions. > To get this into Docutils core, it needs to be moved "to the right > places" and included in the documentation. > Also, we need style sheets or style sheet extensions for at least HTML > and LaTeX. ... and tests. > I'd like to change the name of the directive to "code" instead of > "code-block" and also add a "code" role for in-line code snippets. > This would bring it in line with "math" role and directive. The updated "pygments_code_block_directive.py" is at the sandbox, available via SVN checkout and via http://svn.berlios.de/viewvc/docutils/trunk/sandbox/code-block-directive/ New in this version: # 2010-11-27 Rename directive from "code-block" to "code". # Fix fallback if pygments not found. # Use class-based interface. # Add "number-lines" option. Please test and comment. Open questions: * how to call the option to number lines? :number-lines: makes clear what it does :linenos: is the name used by Sphinx. * Include highlight rules in the default stylesheet(s)? +1 makes the document self contained with least effort -1 lot of redundancy for documents without code snippets -1 a set of separate higlight-styles allows easier choice of the highligth-style by the user. If adding separate code-highligthing style sheets, it might be an idea to put them (as well as other Docutils-provided stylesheets)\ #_ in a "stylesheet library directory" and use the syntax from "include" to specify files from this standard library like --stylesheet-path= .. _# examples are * the s5 styles, * html4css2.css (for the html_strict writer (still) in the sandbox) * math styles, * style variants from the sandbox style repository. Günter