docutils-develop — For developer discussions of the implementation.

[Docutils-develop] latex writer section numbering

[engelbert g. <be...@ch...>]

if sections are not numbered (using \section*{this ..} instead of
\section{...}) the sections are not included in the table of contents.

by putting the following lines in the latex header results in \section{}
numbering being invisible, BUT the section title will be indented as if
there were a number. any other tips.

\renewcommand{\thesection}{}
\renewcommand{\thesubsection}{}
\renewcommand{\thesubsubsection}{}


--
engelbert gruber
email: eng...@ss...

[Docutils-develop] latex writer

[engelbert g. <be...@ch...>]

thanks to julien for bringing the writer to this point

--
engelbert gruber
email: eng...@ss...

[Docutils-develop] latex writer

[engelbert g. <be...@ch...>]

as there are many options to latex how should they be settable.

first distinguishing if they are needed in the writer
(when a pdf is generated some the pdf-documentinfo should be populated
otherwise not)

font packages and even the language could be left to a included file.
times is the better font for pdfs but if someone likes cm better ?

one could supply some sample include files.

attached is roundups user_guide converted to pdf.
i would take it as it is. except for the table.
tabular does no line breaking in a l(eft align) column. sould be p{Ncm}
but who knows N.

does anyone know how i get unnumbered sections into the toc ?

cheers
--
engelbert gruber
email: eng...@ss...

Re: [Docutils-develop] Implementation of "raw"-directive?

[Dethe E. <de...@bl...>]

You can grab the raw directive from my sandbox if you want to play now, 
it's under /sandbox/delza.

Mathplayer is a plugin for IE to display MathML.
http://www.dessci.com/webmath/mathplayer

Netscape 7.0 supports MathML on Linux and Windows.

Mozilla 1.1 supports MathML on Linux, Windows, and MacOS.  Not sure if 
this includes OS X yet, but it's enabled in the nightly builds for OS 
X.  I'm running Mozilla 1.2 alpha and it seems to work, but is missing 
some fonts.

As for SVG, I don't think it's going into the standard build because of 
licensing issues with the libart engine used to render it.  There are 
many solutions for viewing SVG, but the 500-pound gorilla is Adobe's 
SVG plugin.

There is also the X-Smiles browser, which is written in Java and 
support MathML, SVG, SMIL, X3D, and lots more.

http://www.xsmiles.org/

Note, with either SVG or MathML, only Mozilla (or another browser with 
native support, like X-Smiles) will allow you to freely mix HTML with 
other markups (AFAIK).  Markup which requires a plugin generally 
requires it be included using an <object> tag or the like.

HTH

--Dethe

On Friday, September 27, 2002, at 02:04 AM, Adam Chodorowski wrote:

> On Thu, 26 Sep 2002 21:58:47 -0400 David Goodger
> <go...@us...> wrote:
>
> [...]
>> I wasn't aware that HTML browsers supported MathML
>> though.  What do you use?
>
> Mozilla supports MathML. Don't know if they got in the Mac-version yet 
> though
> (it was dragging a bit behind, I think).
>
> ---
> Adam Chodorowski <ad...@ch...>
>
> I use OpenBSD 'coz it has a cool blowfish logo. The other BSDs look 
> satanic.
>     -- Anonymous Coward
>
>
> -------------------------------------------------------
> This sf.net email is sponsored by:ThinkGeek
> Welcome to geek heaven.
> http://thinkgeek.com/sf
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
>

Re: [Docutils-develop] Implementation of "raw"-directive?

[Adam C. <ad...@ch...>]

On Thu, 26 Sep 2002 21:58:47 -0400 David Goodger
<go...@us...> wrote:

[...]
> I wasn't aware that HTML browsers supported MathML
> though.  What do you use?

Mozilla supports MathML. Don't know if they got in the Mac-version yet though
(it was dragging a bit behind, I think).
 
---
Adam Chodorowski <ad...@ch...>

I use OpenBSD 'coz it has a cool blowfish logo. The other BSDs look satanic.
    -- Anonymous Coward

Re: [Docutils-develop] Implementation of "raw"-directive?

[David G. <go...@us...>]

Gunnar Schwant wrote:
> However, I became aware that there is a (not yet implemented)
> "raw"-directive which looks very promising to me.

In a few days, a week at most, it will be available in the parser.

> For example, I could use it to pass-through MathML-formulas.
...
> The MathML part should go untouched through the writer and replace
> the formula.
> 
> Is this the way you are planning to implement it?

Yes, precisely.  I wasn't aware that HTML browsers supported MathML
though.  What do you use?

> (It would be a nice way to pass through SVGs as well.)

As long as the receiving end understands the data, anything goes.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Re: [Docutils-develop] Implementation of "raw"-directive?

[Richard J. <rj...@ek...>]

On Thu, 26 Sep 2002 11:53 am, g.s...@gm... wrote:
> Is this the way you are planning to implement it?
> (It would be a nice way to pass through SVGs as well.)

Again I'm reminded of a pet project that's still in the conceptual design 
stage of turning ASCII art into SVG... ;)

What can be used to _view_ SVG though? I understand there's a KPart in KDE 
3.1, but beyond that...


    Richard

[Docutils-develop] Implementation of "raw"-directive?

[<g.s...@gm...>]

Hi Folks,

As a mathematician I have the bad habit to display some formulas in my
documents. Up to now I do this in reStructuredText by inserting
formulas as GIFs. Of course, this becomes very annoying as the number of
formulas increases. On the other hand it is not a goal of reStructuredText
to be a math-authoring-tool ...

However, I became aware that there is a (not yet implemented)
"raw"-directive which looks very promising to me. For example, I could
use it to pass-through MathML-formulas. It would be great if something
like this would work:

Example::

  **Pythagorean triple**: Any set of three integers satisfying
  the DIOPHANTINE EQUATION |formula|. For example, (x,y,z)=(3,4,5)
  is a Pythagorean triple.

  .. |formula| raw:: html

        <m:math>
         <m:mrow>
          <m:msup>
           <m:mi>x</m:mi>
            <m:mn>2</m:mn>
          </m:msup>
          <m:mo>+</m:mo><m:msup>
           <m:mi>y</m:mi>
           <m:mn>2</m:mn>
          </m:msup>
          <m:mo>=</m:mo><m:msup>
           <m:mi>z</m:mi>
           <m:mn>2</m:mn>
          </m:msup>
         </m:mrow>
        </m:math>

The MathML part should go untouched through the writer and replace
the formula.

Is this the way you are planning to implement it? 
(It would be a nice way to pass through SVGs as well.)

Rgds,
Gunnar.

Re: [Docutils-develop] LaTeX writer, again

[<eng...@ss...>]

sorry for the nonsense if i do pdflatex here i get tableofcontents bookmarks
in this version too.

last commit has several dead code removed.

-- 
 BINGO: globally simplify cutting edge leadership
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

Re: [Docutils-develop] LaTeX writer, again

[<eng...@ss...>]

ad subtitle in latex itself i did attach this in smaller font
to the title.

-- 
 BINGO: pining for the fjords.
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

Re: [Docutils-develop] LaTeX writer, again

[<eng...@ss...>]

On Wed, 25 Sep 2002, Julien T. Letessier wrote:

> Hi list,
>
> My version of the LaTeX writer is almost finished; It'll be posted to a
> sandbox (mine, Engelbert's or a fresh new latex-writer sandbox) as soon as
> it produces 'acceptable' output.
>
> There's an issue with tables, though:
> - LaTeX can't handle at all cells that span multiple columns *and* rows;
> - LaTeX can only handle with great difficulty cells that contain 'body
>   elements', or more generally, more than a few words with inline markup.
>
> If anyone has ideas about this, please tell me.
> Otherwise, the LaTeX writer will stay without complex table support for now.
>
> An example of how good the writer currently is is available at
> http://www.mezis.net/docutils/test.pdf -- as good as it gets.
>
> Bonus track:
> - can someone tell me if I can change the default output-encoding (which
>   currently is UTF-8) to ISO-Latin-1 (a.k.a ``latin-1``) for the LaTeX writer?
>   I want to do this because base (pdf)LaTeX can only handle 1-byte encodings
>   (AFAIK)...
> - do you think it is sensible to add a ``stylesheet`` option for the LaTeX
>   writer (implemented with e.g. ``\include{style.tex}``)
should go into docutils.conf IMHO

-- 
 BINGO: Think outside the box
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

Re: [Docutils-develop] LaTeX writer, again

[<pf...@ar...>]

Hi,

David Goodger:
[...]
> In addition, I noticed the "--documentclass" option, default
> "article".  Are there a finite number of different document classes?
> If so, it would be best to add another entry to the dictionary for
> this option::
> 
>     'choices': ('article', ...)
> 
> But if document classes are user-definable, that won't work.

Most TeX/LaTeX distributions come with a set of standard document class
definitions: 'book', 'report', 'article', 'letter' and 'slides' even
found their way into textbooks handling LaTeX.  But the user may define 
her/his own classes where it is possible to inherit from the standard
classes.  I did this once (back in 1995 or so) to define a specific 
coporate design for our company user reference documentation.

The python documentation comes with the classes 'howto' and 'manual'.

> > - do you think it is sensible to add a ``stylesheet`` option for the
> >   LaTeX writer (implemented with e.g. ``\include{style.tex}``)
> 
> I'd say yes from a Docutils point of view, but I'm no TeXpert.

A LaTeX document is usually devided into two parts:

 1. a preamble (header) section containing meta information like 
    the document class to be used, calls to additional style packages 
    or intrinsic TeX commands to define page margins and so on.

 2. the real content of the document, which is introduced with 
    (followed by) a ``\begin{document}`` macro.

IMHO most future users of Juliens LaTeX writer will be also no TeXperts
and won't care at all about documentclass and packages, as long as the
output fits there expectations.  But a real TeXpert should have the 
following optional possibilities:
  
  * Define his own document preamble (including the choice to
    choose his own documentclass.  That would make the ``--documentclass``
    option superfluous).  I suggest to call this option ``--preamble``

  * Use two additional hooks to put additional stuff just behind the 
    ``\begin{document}`` and just before the ``\end{document}`` macros.
    Typical uses would be ``\tableofcontents``, ``\listoffigures`` and
    ``\appendix``, ``\makeindex``, ``\makeglossary`` and some such 
    for larger documents.

    I'm not sure what to suggest as option names for these hooks.  May 
    be these options could be called ``--preface`` and ``--appendix``?

Regards, Peter
-- 
Peter Funk, Oldenburger Str.86, D-27777 Ganderkesee, Germany
office: +49 421 20419-0 (ArtCom GmbH, Grazer Str.8, D-28359 Bremen, Germany)

Re: [Docutils-develop] LaTeX writer, again

[David G. <go...@us...>]

Julien T. Letessier wrote:
> My version of the LaTeX writer is almost finished; It'll be posted
> to a sandbox (mine, Engelbert's or a fresh new latex-writer sandbox)
> as soon as it produces 'acceptable' output.

You might as well leave it in the "grubert" sandbox, especially if
it's nearly complete.  No need to duplicate files.

> There's an issue with tables, though:
> - LaTeX can't handle at all cells that span multiple columns *and*
>   rows;
> - LaTeX can only handle with great difficulty cells that contain
>   'body elements', or more generally, more than a few words with
>   inline markup.
> 
> If anyone has ideas about this, please tell me.  Otherwise, the
> LaTeX writer will stay without complex table support for now.

Was Peter Funk's suggestion of the "tabularx" package useful?  Or
Engelbert's "longtable" or "supertabular"?  (Note that I have no idea
what any of these are; I'd just like to make sure every avenue is
explored.)

Also, please take a look at Alexander Schmolck's code that he posted
and extract anything useful.  Are the mappings there useful to the
LaTeX writer?  If not now, then perhaps later (so best to insert a
comment referring to them).

When I worked with SGML in Japan, we used TeX as our back-end,
processing arbitrarily complex documents in different languages
(including Japanese, Chinese, and Korean).  There were tables with
body elements inside, no problem.  TeX could handle any table we threw
at it.  I don't know the TeX details though; there was probably a lot
of code in the back end to make it all work.  But I know that TeX can
handle almost anything, so there must be a way to get all these things
to work.

Just think of it as expanding your TeX expertise!

> An example of how good the writer currently is is available at
> http://www.mezis.net/docutils/test.pdf -- as good as it gets.

It's looking good.  I hope there's still room for improvement though
(there are lots of issues, as I'm sure you realize).

> Oh, and by the way, forget about what I said about footnotes that
> couldn't be split info references and definitions, like in ReST.

Great!  Many thanks to your girlfriend!

> - can someone tell me if I can change the default output-encoding
>   (which currently is UTF-8) to ISO-Latin-1 (a.k.a ``latin-1``) for
>   the LaTeX writer?

Within the Writer class, add this::

    option_default_overrides = {'output_encoding': 'latin-1'}

Also be sure to explain this change: replace "None" in
"cmdline_options" with text like::

    'The LaTeX "--output-encoding" default is "latin-1".'

In addition, I noticed the "--documentclass" option, default
"article".  Are there a finite number of different document classes?
If so, it would be best to add another entry to the dictionary for
this option::

    'choices': ('article', ...)

But if document classes are user-definable, that won't work.

> - do you think it is sensible to add a ``stylesheet`` option for the
>   LaTeX writer (implemented with e.g. ``\include{style.tex}``)

I'd say yes from a Docutils point of view, but I'm no TeXpert.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Re: [Docutils-develop] Directives Howto (in progress)

[David G. <go...@us...>]

Dethe Elza wrote:
> OK, I've finally got the directives ready for comment and I've
> updated the HOWTO based on Aahz's feedback.

Great!  Thanks again.

> Aahz brings up a good point, which I didn't catch the first time,
> which is the question of whether parse_directive is called by the
> directive implementation, or the directive implementation is called
> by parse_directive.
>
> Right now, the directive calls parse_directive, but this is
> boilerplate code and it could easily be reversed (with some savings
> in repetitive coding).

Good idea.  I agree that "parse_directive" should call the directive
function, not the other way around.

> Currently the directive passes in a dictionary of option handlers to
> parse_directive, but these could just as easily be registered when
> the directive itself is registered.

That kind of registration would require importing each of the
directive modules, which could become expensive.  Better to look up
the settings only when needed.

A neat way to avoid a complex and cumbersome registration system would
be to use function attributes.  Like this::

    def directive_function(args...):
        code...

    directive_function.arguments = None     # or a 2-tuple if possible
    directive_function.options = None       # or a dict if possible
    directive_function.content = None       # or 1/true if allowed

The settings stay local to the directive function, so there's no
setup/registration required.  There's one major ramification here
though: the minimum Python version requirement will become 2.1 (that's
when function attributes were introduced).  I can live with that; any
objections?

> One possible way to make directives even easier to implement
> (besides the above refactoring) would be to allow the
> parse_directive have even more information about the expected result
> (i.e., do we expect a non-empty content block, multiple arguments,
> mandator "options", etc.?), rather than the current state of putting
> the burden of checking values on the directive implementation.

Take another look at the docstring of "parse_directive".  Notice the
"arguments" and "content" parameters already listed?  :-)

> On the other hand, the directive is where this is known, and it's
> possible to make the parse_directive *too* general, spending time
> and creating complexity to what is basically trivial to determine in
> the directive implementation.

I think the "parse_directive" function should be as general as
possible.  It should parse arguments, options, and content.  In other
words, do what the docstring describes. ;-)

Also, I think that "parse_directive" should become a method of class
"Body" in docutils/parsers/rst/states.py.  The current "directive"
method contains::

    if directivefunction:
        return directivefunction(match, type_name, data, self,
                                 self.state_machine, option_presets)

This should change to::

    if directive_function:
        return self.parse_directive(directive_function, match,
                                    type_name, option_presets)

"parse_directive" can call the directive function itself; otherwise,
it would have to return a bunch of extra information (like the initial
line offset of the content block) which has to be passed on.  Note
that the "data" parameter is no longer necessary.  Also,
"option_presets" was dropped from the parameter list, but it's
required.

Please let me know if you'd like to tackle these changes yourself, or
if you'd rather I did them (either way is fine).  It will take some
effort integrating everything to get it working just right.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

[Docutils-develop] LaTeX writer, again

[Julien T. L. <me...@fr...>]

Hi list,

My version of the LaTeX writer is almost finished; It'll be posted to a
sandbox (mine, Engelbert's or a fresh new latex-writer sandbox) as soon as
it produces 'acceptable' output.

There's an issue with tables, though:
- LaTeX can't handle at all cells that span multiple columns *and* rows;
- LaTeX can only handle with great difficulty cells that contain 'body
  elements', or more generally, more than a few words with inline markup.

If anyone has ideas about this, please tell me.
Otherwise, the LaTeX writer will stay without complex table support for now.

An example of how good the writer currently is is available at
http://www.mezis.net/docutils/test.pdf -- as good as it gets.

Oh, and by the way, forget about what I said about footnotes that couldn't be
split info references and definitions, like in ReST. In fact they can, even in
base LaTeX (using \footnotemark[num] and \footnotetext[num]{text}).

.. troll::
	Hopefully, my girlfriend is a good TeXnician and pointed this out...
	...she could probably be called a geek-ette as well ;P

Bonus track:
- can someone tell me if I can change the default output-encoding (which
  currently is UTF-8) to ISO-Latin-1 (a.k.a ``latin-1``) for the LaTeX writer?
  I want to do this because base (pdf)LaTeX can only handle 1-byte encodings
  (AFAIK)...
- do you think it is sensible to add a ``stylesheet`` option for the LaTeX
  writer (implemented with e.g. ``\include{style.tex}``)

Cheers,
-- 
Julien T. Letessier     email: co...@me...
ENSIMAG Student         web: http://www.mezis.net

Re: [Docutils-develop] Directives Howto (in progress)

[Dethe E. <Dad...@li...>]

OK, I've finally got the directives ready for comment and I've updated
the HOWTO based on Aahz's feedback.  Aahz brings up a good point, which
I didn't catch the first time, which is the question of whether
parse_directive is called by the directive implementation, or the
directive implementation is called by parse_directive.

Right now, the directive calls parse_directive, but this is boilerplate
code and it could easily be reversed (with some savings in repetitive
coding).  Currently the directive passes in a dictionary of option
handlers to parse_directive, but these could just as easily be
registered when the directive itself is registered.

One possible way to make directives even easier to implement (besides
the above refactoring) would be to allow the parse_directive have even
more information about the expected result (i.e., do we expect a
non-empty content block, multiple arguments, mandator "options",
etc.?), rather than the current state of putting the burden of checking
values on the directive implementation.  On the other hand, the
directive is where this is known, and it's possible to make the
parse_directive *too* general, spending time and creating complexity to
what is basically trivial to determine in the directive implementation.

Other opinions?

--Dethe

On Tuesday, September 17, 2002, at 11:47 AM, Aahz wrote:

> On Thu, Aug 29, 2002, Dethe Elza wrote:
>>
>> Define Directive
>> ----------------
>>
>> The directive signature itself should follow this template:
>
> Shouldn't that be "template::"?
>
> Also, you should explain that a directive is a plain function (a
> callback), not a method.
>
>>     def my_directive(match, type_name, data, state, state_machine,
>> option_presets):
>
> Reformat to shorter lines?
>
>> Define Options
>> --------------
>>
>> You will have to define the options your directive requires.  This is
>> a
>> dictionary of name, conversion pairs which are applied to each option
>> value to
>> convert it to an expected type.  Python's built-in conversion are
>> often usable
>> for this, for example, str, int, float.  Other useful types would be
>> bool
>> (included in python 1.3) and exists (to test for existence of an
>> option when
>> you don't care about the value or the option has no value).
>
> Python 2.3, right?
>
> Again shorter lines would be better, I think.
>
>> Parse Directive
>> ---------------
>>
>> You'll want to use the parse_directive method, which has returns a
>> 4-tuple
>> (arguments, options, content, blank_finish) and has the following
>> signature:
>
> Method of what?  What does "use" mean?  (I.e., I believe the writer of
> a
> directive doesn't actually call parse_directive(); parse_directive()
> calls the my_directive() callback.  Whether I'm right or wrong, clarity
> is needed.)
>
> (Yes, examples will help, but the text should also be correct and
> complete.)
> -- 
> Aahz (aa...@py...)           <*>
> http://www.pythoncraft.com/
>
> Project Vote Smart: http://www.vote-smart.org/
>

Re: [Docutils-develop] Functionnal LaTeX writer

[David G. <go...@us...>]

Adam Chodorowski wrote:
> There is a similar problem with link targets. Say for example that
> you have a collection of documents, that link each other. If you
> want to call your output files descriptively, like .html, .pdf, etc
> based on filetype, link targets will break.

This is definitely an interesting issue.  There's this item from the
spec/notes.txt file:

    Support generic hyperlink references to targets in other
    documents?  Not in an HTML-centric way, though (it's trivial to
    say ``http://www.example.com/doc#name``, and useless in non-HTML
    contexts).  XLink/XPointer?  ``.. baseref::``?  See Doc-SIG
    2001-08-10.

Any ideas would be appreciated.  Has this already been solved elsewhere?

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Re: [Docutils-develop] Functionnal LaTeX writer

[David G. <go...@us...>]

Alexander Schmolck wrote:
> One bit that I think could be lifted easily from my sources and that
> might be quite useful are the unicode to tex-command mappings as
> well as the selection of the right babyl package for
> internationalization (depending on the language code).

Yes, those do look useful.  Thanks!

> However, I had the impression that a few things about
[Docutils?]
> limit its potential scope. As an example many things seemed a bit
> html-centric to me.

As I wrote yesterday, this is only true as long as HTML is the only
major practical writer component available.  Already that's not true
though, since there is an XML writer (although it's trivial).

> Take pictures, for example. You have to supply a file extension (which
> I think is a bad idea) and can only specify height and width in pixels
> (which is not meaningful for e.g. latex documents and might even
> become less relevant for web development with a shift of emphasis to
> vector based formats).

As I've said before, when the need arises, we'll adapt.  I've been
following the Extreme Programming "continuous evolution" approach:
"always do the simplest thing that could possibly work" and "never add
functionality before it's needed."  The only reason Docutils doesn't
support a TeX-frienly model is because it hasn't been needed yet.

It is assumed and expected that the document model will adapt and
evolve to meet new requirements.  Patches are welcome (and necessary)!

> I think it would be better if the extension were left unspecified as
> a default, so that the same document could be processed by different
> writers that include the most suitable image with the specified name
> for the given output format. As an example, the html writer might
> include the file 'flower.png', whereas the latex writer would
> presumably be better of with 'flower.eps' if that also existed.

Sounds OK in theory, but what if the picture file isn't actually
available when the document is being processed by Docutils?  I'm sure
that TeX is smart enough to get the right file, but an HTML browser
isn't.

Thanks for your input, and please do join us when you have time!

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Re: [Docutils-develop] XML output

[David G. <go...@us...>]

Adam Chodorowski wrote:
> Hmmm, the DOCTYPE declaration is causing some problems for us.
> Using Internet Explorer or XMLmind XML Editor, the first error is
> about "SYSTEM" in the DOCTYPE::

I keep forgetting that the "SYSTEM" is not necessary.  There are
subtle differences between SGML and XML.

> This works better, but when it then tries to parse the DTD it also
> complains::
> 
>    Invalid character in content model. Error processing resource \
>    'http://docutils.sourceforge.net/spec/docutils.dtd'. Line 433,
>    Position 56
>    <!ELEMENT figure (image, ((caption, legend?) | legend) >

A missing close-parenthesis, now fixed.  I also fixed some "%number;"
parameter entities that were mistakenly written "&number;".  I've been
using the DTD as a convenient notation, but I've never validated it or
actually used the XML produced, so I'm not surprised there were bugs.

> I tried running the generated XML file through the XML validator at
> http://www.stg.brown.edu/service/xmlvalid/, and it resulted in a
> *lot* of errors and warnings. :-(

I wasn't aware of that resource.  I'll try it on Docutils output and
see what it says.  Of course, patches & fixes are always welcome!

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Re: [Docutils-develop] reorganize the sandbox?

[David G. <go...@us...>]

Tony J Ibbs (Tibs) wrote:
> What about documentation/papers/slides? At the moment, I suspect
> it's easiest to stay with the sandbox/person organisation for
> them...

Sure.  We can use the "sandbox" for experimental/temporary files,
which can be more-or-less ignored by everyone except their owner, and
"projects" for group efforts.  Whatever fits the situation.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Re: [Docutils-develop] Functionnal LaTeX writer

[Adam C. <ad...@ch...>]

On 24 Sep 2002 12:00:55 +0100 Alexander Schmolck <a.s...@gm...> wrote:

[...]
> Take pictures, for example. You have to supply a file extension (which I
> think is a bad idea) and can only specify height and width in pixels (which
> is not meaningful for e.g. latex documents and might even become less
> relevant for web development with a shift of emphasis to vector based
> formats). I think it would be better if the extension were left unspecified
> as a default, so that the same document could be processed by different
> writers that include the most suitable image with the specified name for the
> given output format. As an example, the html writer might include the file
> 'flower.png', whereas the latex writer would presumably be better of with
> 'flower.eps' if that also existed.

There is a similar problem with link targets. Say for example that you have a
collection of documents, that link each other. If you want to call your output
files descriptively, like .html, .pdf, etc based on filetype, link targets
will break.

__ path/to/foo.html

You need to call it foo.html, since otherwise it won't find the file. But if
you output something else than html, this will break the link. This means that
the input files are dependant on the output, which is bad...

The nicest solution would IMHO be if you could somehow only write:

__ path/to/foo

And docutils would add the .html extension automatically if you're generating
HTML, but ,pdf if you're generating PDF. The problem is ofcourse that
sometimes you really want to link to a file of a different type...

---
Adam Chodorowski <ad...@ch...>

The dotcom dream - where young, talentless egotists could pretend they 
knew more about the world than everyone else and VCs indulged their 
fantasies for 18 months - has died. Thank god.
    -- Kieren McCarthy / The Register

Re: [Docutils-develop] Re: Footnotes in LaTeX Writer

[<gr...@us...>]

On Tue, 24 Sep 2002, Peter Funk wrote:

> The LaTeX writer should also pay attention to the fact, that
> standard LaTeX does not allow to construct footnotes inside tabular
> material.  I advise to use the tabularx environment and to add a
> \usepackage{tabularx} into the header section.  This shouldn't be a
> problem, since tabularx may be considered as Standard LaTeX today:
> It was even documented in LaTeX companion from 1994.
>
how about using longtable and supertabular so that tables can span
pages ?

> Using the LaTeX writer and pdflatex would offer a decent
> reST to PDF converter.
right it does
>

-- 
 BINGO: professionally create virtual services
 --- Engelbert Gruber -------+
 SSG Fintl,Gruber,Lassnig   /
 A6410 Telfs Untermarkt 9  /
 Tel. ++43-5262-64727 ----+

Re: [Docutils-develop] XML output

[Adam C. <ad...@ch...>]

On Mon, 23 Sep 2002 22:37:04 -0400 David Goodger
<go...@us...> wrote:

[...]
> I've added an encoding attribute to the XML declaration (``<?xml
> version="1.0" encoding="utf-8"?>``) and a ``<!DOCTYPE document ...``
> declaration.  It would be easy enough to add an XSL stylesheet
> declaration as well; I'll wait for the need to arise.

Hmmm, the DOCTYPE declaration is causing some problems for us. 
Using Internet Explorer or XMLmind XML Editor, the first error is about
"SYSTEM" in the DOCTYPE::

    A string literal was expected, but no opening quote character was found.

Removing the SYSTEM, so you have::

   <!DOCTYPE document PUBLIC "+//IDN docutils.sourceforge.net//DTD Docutils \
   Generic//EN//XML" "http://docutils.sourceforge.net/spec/docutils.dtd">

This works better, but when it then tries to parse the DTD it also complains::

   Invalid character in content model. Error processing resource \
   'http://docutils.sourceforge.net/spec/docutils.dtd'. Line 433, Position 56 
   <!ELEMENT figure (image, ((caption, legend?) | legend) >

I tried running the generated XML file through the XML validator at
http://www.stg.brown.edu/service/xmlvalid/, and it resulted in a *lot* of
errors and warnings. :-(

---
Adam Chodorowski <ad...@ch...>

There are two major products that come from Berkeley: LSD and UNIX.
We don't believe this to be a coincidence.
    -- Jeremy S. Anderson

RE: [Docutils-develop] reorganize the sandbox?

[Tony J I. (Tibs) <to...@ls...>]

David Goodger wrote:
> I think projects ought to be emphasized, rather than people.  Perhaps
> we should create a new top-level "projects" directory, open to
> participation.  A README.txt file at the top of each project could
> identify the project coordinator and outline any requirements (like
> "please run patches by me before checking them in").

I think this is a good idea as well (but then, I would, wouldn't I?).

> Some of the material in the sandbox is not project-oriented though,
> and should remain in the sandbox.

Subject to later decisions otherwise, just like this one, of course.

What about documentation/papers/slides? At the moment, I suspect it's
easiest to stay with the sandbox/person organisation for them...

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)

Re: [Docutils-develop] XML output

[Adam C. <ad...@ch...>]

On Mon, 23 Sep 2002 22:37:04 -0400 David Goodger
<go...@us...> wrote:

[...]
> > What's the best way to fix these issues? Perhaps a dedicated XML
> > writer is necessary (I hope not...)?
> 
> One already exists: docutils-xml.py.  Try it instead of quicktest.py.

For some weird reason I managed to miss that one. :-) Sorry about that...

> I just tried running it on tools/test.txt and had some trouble.  Fell
> victim to a bug in Python 2.2's StringIO.py.  Moral: upgrade to 2.2.1!
> With 2.2.1 in place, it worked without problem.

Good thing to know.
 
> I've added an encoding attribute to the XML declaration (``<?xml
> version="1.0" encoding="utf-8"?>``) and a ``<!DOCTYPE document ...``
> declaration.  

Thanks. 

> It would be easy enough to add an XSL stylesheet
> declaration as well; I'll wait for the need to arise.

AFAIK, we currently don't have any such need. We won't be serving the XML
files dynamically or such, but rather do the transformation at "build time".

[...]
> Patches are welcome, but I suspect that once you try docutils-xml.py
> you'll forget all about quicktest.py.

Yes, docutils-xml.py works much better. :-)

> > 2. The "xml:space" attribute is used incorrectly. In the output one
> >    can find "xml:space=1"; the only valid values from xml:space are
> >    "default" and "preserved".
> 
> An oversight, now fixed ("preserve", actually).  Thanks.  The snapshot
> has been updated: http://docutils.sf.net/docutils-snapshot.tgz

Great!

---
Adam Chodorowski <ad...@ch...>

BTW, I made the statistics up. I read somewhere that 60% of statistics are
made up on the spot :-)
    -- Phill Wooller