From: G. M. <mi...@us...> - 2008-05-19 13:34:32
|
On 16.05.08, David Goodger wrote: > [G. Milde - 2008-05-16 02:33] >> On 15.05.08, David Goodger wrote: >>> On Thu, May 15, 2008 at 11:54 AM, G. Milde wrote: >> :literal: would explicitly ask for the literal block (or string, >> in case of a math role), while >> :raw: would pass-through the content and insert like a raw node. > Why have "raw" math at all? We already have a "raw" directive. Wouldn't > they do exactly the same thing? While using the "raw" directive is used to mark a part of the the document, the math-output-format "raw" would not be specified in the document but in either the Writer configuration or a command line option. It can be used to pass-through content in a specific math format in a specific case while using the fall-back solution (literal) in all others without the need to make this format known to Docutils. Mind that I don not plan a restriction on the value of the math ``input-format``. However, only a restricted set of input formats (starting with just "latex") will be handled by the Transform. All other formats will be included literal (with a message like:: """math input-format ``%s`` cannot be converted to ``%s``. (Specify a supported output format, e.g. ``--output-format=verbatim``, to turn of this message)."""%(input-format, output-format) >>> Better to require that the format be specified. Explicit is better >>> than implicit. >> Then, math-input-format == "auto" could be used to explicitly ask >> for auto-determination by the Transform. > If we ever have more than one supported math input format, we can revisit > this issue. It is premature now, as we have none and someone may be > working on one. While I agree that it makes sense to start with just one math input format, I would like to set up the framework for multiple input formats to facilitate later extension. My proposal should enable the power user to pass-through arbitrary math formats without fear of later incompatibilites. >> BTW: how would I specify the math-input-format in case of a role >> (i.e. for inline math)? > Again, if this ever becomes necessary, we'll revisit it. Possibilities: > * :math-latex:`...`, :math-ml:`...`, etc. > * .. math-input-format:: ... > followed by :math:`...` I prefer the second variant. >> Would it help, if I started writing a specification (in the line of >> ref/rst/directives.txt)? > Yes. Done. >> Should this be a sandbox project (math-directive) or modify the >> main documentation? > I suggest a branch, since it touches the entire codebase. > /branches/mathsupport or /branches/math would be fine. IMO, the specification could be done to the docs/ref/ tree of the trunk with proper marking of the additions as NOT YET IMPLEMENTED. I'll attach my additions to the reference documents as a diff between my working copy and the docutils SVN version. I hope that I did meet the style and conventions of the docutils documentation and would like to see comments etc. Up to now, I only committed to the sandbox and I am not sure whether I am allowed to commit to trunk (and whether my idea to keep the specification in the trunk will be agreed upon). Therefore I will not commit unto I receive a get-ahead note but I am happy with someone else taking the diff and doing the commit (either as-is or modified). Günter |