docutils-users Mailing List for Docutils: Documentation Utilities

On 2011-06-28, <mic...@di...> wrote:
> From: Guenter Milde [mailto:mi...@us...]

...
>> > +\DeclareMathSymbol{\amalg}{\mathbin}{cmsymbols}{"71}
...

>> What is the intention of these re-definitions? Are these fixes or
>> defining variants?

> These are fixes.  The problem is that mathptmx doesn't define \amalg,
> \coprod or \jmath, or more precisely defines them to generate errors. 
> These lines are a fudge to pull in alternative (and perfectly workable)
> definitions directly from the original computer modern files.  These
> lines are required because latex_math.txt uses \amalg and \coprod.

> The issue, presumably, is that these symbols don't have postscript
> forms, and for whatever reason the writers of mathptmx didn't want to
> do the fudge I'm doing here (despite the fact it works perfectly well,
> as far as I can tell).

While it works well, it might be too scary for font experts like the
mathptmx author(s).

But more generally: mathptmx is not suited for serious/heavy math use:

-1 mix of Times letters with non-matching CM nonalphanumerical symbols.
-2 no bold.

`mathptmx` was chosen as default font package following feature requests
because it provides a well known "Base Postscript/PDF font" without
further dependencies (LaTeX core package).

At this time, there was no math support in Docutils.
Anyone using more than just very basic math should also use a different
font package. (A survey of free math typesetting packages (in German)
with example pages is available at
http://milde.users.sourceforge.net/Matheschriften/matheschriften.html.)

Best consistency is achieved with --stylesheet=lmodern,amssymb.
Times can be used with e.g. --stylesheet=txfonts or
--stylesheet=qtxmath. Another recommended choice is Utopia with
--stylesheet=fourier.

Of course the stylesheet can be defined in a config file for a more
permanent setting. Then, overwriting the "latex_preamble" is
recommended, too.

>> Dont, use the development version of Docutils (SVN checkout or daily
>> snapshot).

> Gosh, must be pretty recent: I only checked out my docutils build
> literally a month ago!

Strange: the first version was added 2010-10-25 with the commit
``Support mathematics with a "math" role and directive``. Since then,
math is documented in the local documentation.

However, the documentation at Sourceforge seems to be far behind the
current state.

From: Guenter Milde [mailto:mi...@us...]
> > +\let\amalg=\undefined
> > +\let\coprod=\undefined
> > +\DeclareSymbolFont{cmsymbols}{OMS}{cmsy}{m}{n}
> > +\DeclareSymbolFont{cmlargesymbols}{OMX}{cmex}{m}{n}
> > +\DeclareMathSymbol{\amalg}{\mathbin}{cmsymbols}{"71}
> > +\DeclareMathSymbol{\coprod}{\mathop}{cmlargesymbols}{"60}
> 
> What is the intention of these re-definitions? Are these fixes or
> defining variants?

These are fixes.  The problem is that mathptmx doesn't define \amalg, \coprod or \jmath, or more precisely defines them to generate errors.  These lines are a fudge to pull in alternative (and perfectly workable) definitions directly from the original computer modern files.  These lines are required because latex_math.txt uses \amalg and \coprod.

The issue, presumably, is that these symbols don't have postscript forms, and for whatever reason the writers of mathptmx didn't want to do the fudge I'm doing here (despite the fact it works perfectly well, as far as I can tell).

For reference, the third symbol \jmath requires these lines:

\let\jmath=\undefined
\DeclareSymbolFont{cmletters}{OML}{cmm}{m}{it}
\DeclareMathSymbol{\jmath}{\mathord}{cmletters}{"7C}


> Dont, use the development version of Docutils (SVN checkout or daily
> snapshot).

Gosh, must be pretty recent: I only checked out my docutils build literally a month ago!

> >    to itex2MML?  Or am I missing more recent work?
> Yes.

:)  Guess I need to do more reading...

> > I'm not subscribed to this list, so *please* CC me.
> I am not sure whether this works via the Gmane usenet interface...

Yes, seemed to get through just fine.

-- 
Please disregard stuff below.

> From: m h

> Sent: Mon, June 6, 2011 5:57:04 AM
> 
> 
> Hello-
> 
> I'm trying to insert code under the .. tip:: construct like  so:
> 
> .. tip::
> 
>   Here's some code to show it::
> 
>      >>> foo = "test"
> 
> With the odtwriter, the embedded code is  not indented relative to the
> tip section but to the page. Any ideas on how to  fix, or should I file
> a  bug?
> 

Matt -

Thanks for letting me know.  I believe I've fixed it.  I checked the
code into the SVN repository last night.  Please let me know
if it works the way you'd expect.

- Dave


 -- 

Dave Kuhlman
http://www.rexx.com/~dkuhlman

On 2011-06-27, <mic...@di...> wrote:
> I'm trying to figure out the options for writing equations in reST, and
> the possibilities appear to be to use either itex2MML or the latex-math
> plugin from http://docutils.sourceforge.net/sandbox/jensj/latex_math/

You can also use a recent snapshot of the upcoming release 0.8 that
includes math support into the core (incorporating and extending Jens
Jörgens latex_math).

> However, it seems that the latex generated by rst2latexmath.py (in the
> tools directory of the link above) is incomplete.  For example, running
> the commands (latex_math.txt from the docs directory):

> 	rst2latexmath.py latex_math.txt latex_math.tex
> 	pdflatex latex_math.tex

> complains about undefined symbols.  To get latex_math.tex to build I
> have to apply this patch:


> --- latex_math.tex.original	2011-06-27 09:18:18.000000000 +0100
> +++ latex_math.tex	2011-06-27 09:18:43.000000000 +0100
> @@ -14,9 +14,19 @@
>  %%% Custom LaTeX preamble
>  % PDF Standard Fonts
>  \usepackage{mathptmx} % Times
> +\usepackage{amsmath}
> +\usepackage{amsfonts}
> +\usepackage{amssymb}
>  \usepackage[scaled=.90]{helvet}
>  \usepackage{courier}

I suppose it is documented somewhere that you need to add amsmath and
amssymb to the list of stylesheets.

The built-in "math" directive and role will automatically load the
amsmath package but still requires you to specify amssymb (or an
alternative like txfonts) in the stylesheet argument, say ::

  rst2latex --stylesheet=amssymb math-example.txt math-example.tex

> +\let\amalg=\undefined
> +\let\coprod=\undefined
> +\DeclareSymbolFont{cmsymbols}{OMS}{cmsy}{m}{n}
> +\DeclareSymbolFont{cmlargesymbols}{OMX}{cmex}{m}{n}
> +\DeclareMathSymbol{\amalg}{\mathbin}{cmsymbols}{"71}
> +\DeclareMathSymbol{\coprod}{\mathop}{cmlargesymbols}{"60}

What is the intention of these re-definitions? Are these fixes or
defining variants?


> Unfortunately, of course, I'm patching completely the wrong file here!

> So two questions:

> 1. How do I modify rst2latexmath.py so that the changes above occur in
>    the generated .tex file?  I'm wholly unfamiliar with the docutils
>    plugin mechanism, so pointers to relevant documents will be
>    gratefully received.

Dont, use the development version of Docutils (SVN checkout or daily
snapshot).

> 2. What's the state of play with equation support in reST, in
>    particular, should I pay more attention to the latex-math plugin or
>    to itex2MML?  Or am I missing more recent work?

Yes.

> I'm not subscribed to this list, so *please* CC me.

I am not sure whether this works via the Gmane usenet interface...

Günter

I'm trying to figure out the options for writing equations in reST, and the possibilities appear to be to use either itex2MML or the latex-math plugin from http://docutils.sourceforge.net/sandbox/jensj/latex_math/

However, it seems that the latex generated by rst2latexmath.py (in the tools directory of the link above) is incomplete.  For example, running the commands (latex_math.txt from the docs directory):

	rst2latexmath.py latex_math.txt latex_math.tex
	pdflatex latex_math.tex

complains about undefined symbols.  To get latex_math.tex to build I have to apply this patch:


--- latex_math.tex.original	2011-06-27 09:18:18.000000000 +0100
+++ latex_math.tex	2011-06-27 09:18:43.000000000 +0100
@@ -14,9 +14,19 @@
 %%% Custom LaTeX preamble
 % PDF Standard Fonts
 \usepackage{mathptmx} % Times
+\usepackage{amsmath}
+\usepackage{amsfonts}
+\usepackage{amssymb}
 \usepackage[scaled=.90]{helvet}
 \usepackage{courier}
 
+\let\amalg=\undefined
+\let\coprod=\undefined
+\DeclareSymbolFont{cmsymbols}{OMS}{cmsy}{m}{n}
+\DeclareSymbolFont{cmlargesymbols}{OMX}{cmex}{m}{n}
+\DeclareMathSymbol{\amalg}{\mathbin}{cmsymbols}{"71}
+\DeclareMathSymbol{\coprod}{\mathop}{cmlargesymbols}{"60}
+
 %%% User specified packages and stylesheets
 
 %%% Fallback definitions for Docutils-specific commands


Unfortunately, of course, I'm patching completely the wrong file here!

So two questions:

1. How do I modify rst2latexmath.py so that the changes above occur in the generated .tex file?  I'm wholly unfamiliar with the docutils plugin mechanism, so pointers to relevant documents will be gratefully received.

2. What's the state of play with equation support in reST, in particular, should I pay more attention to the latex-math plugin or to itex2MML?  Or am I missing more recent work?


I'm not subscribed to this list, so *please* CC me.


-- 
I'm very very sorry, but I can do nothing about the garbage added by my employer below this e-mail :( 



-- 
This e-mail and any attachments may contain confidential, copyright and or privileged material, and are for the use of the intended addressee only. If you are not the intended addressee or an authorised recipient of the addressee please notify us of receipt by returning the e-mail and do not use, copy, retain, distribute or disclose the information in or attached to the e-mail.
Any opinions expressed within this e-mail are those of the individual and not necessarily of Diamond Light Source Ltd. 
Diamond Light Source Ltd. cannot guarantee that this e-mail or any attachments are free from viruses and we cannot accept liability for any damage which you may sustain as a result of software viruses which may be transmitted in or with the message.
Diamond Light Source Limited (company no. 4375679). Registered in England and Wales with its registered office at Diamond House, Harwell Science and Innovation Campus, Didcot, Oxfordshire, OX11 0DE, United Kingdom
 

On 2011-06-22, Attila Tajti wrote:
> Hello,

> I would like to know if it is possible make definitions in definition 
> lists implicit hyperlink targets automatically somehow. Eg. instead of:

> ---------------------------------------------------------------------------
> _`considerWarningAsError`
>      When set to non-zero, show error message instead of confirmation 
> dialog.

> chechEntryMaximumValue
>      Together with considerWarningAsError_ blah.
> ---------------------------------------------------------------------------

> I would like to write this

> ---------------------------------------------------------------------------
> considerWarningAsError
>      When set to non-zero, show error message instead of confirmation 
> dialog.

> chechEntryMaximumValue
>      Together with considerWarningAsError_ blah.
> ---------------------------------------------------------------------------

> i.e. without explicit markup in the first line (definition) for 
> "considerWarningAsError".

> Is this possible? If not, how should I make it possible?

This is currently not supported.

To achieve it, there are several ways, amongst them:

a) write and use a pre-processor script that adds the explicit markup
   before passing the result to Docutils.
  
b) write a "transform" that traverses the doctree after parsing and
   adds the hypertargets to the node.

Method a) is the quick and dirty one - giving fast results without the
need to understand all of the Docutils interna. Together with a custom
"front-end", it could be used with the same ease as the standard
front-ends.

Method b) is "the right way", which, when done well, might even be added
to Docutils. However, it requires reading and understanding the Doctutils
developer documentation, looking at the source of other "transforms" and
at the places where these transforms are called.

Günter

Hello,

I would like to know if it is possible make definitions in definition 
lists implicit hyperlink targets automatically somehow. Eg. instead of:

---------------------------------------------------------------------------
_`considerWarningAsError`
     When set to non-zero, show error message instead of confirmation 
dialog.

chechEntryMaximumValue
     Together with considerWarningAsError_ blah.
---------------------------------------------------------------------------

I would like to write this

---------------------------------------------------------------------------
considerWarningAsError
     When set to non-zero, show error message instead of confirmation 
dialog.

chechEntryMaximumValue
     Together with considerWarningAsError_ blah.
---------------------------------------------------------------------------

i.e. without explicit markup in the first line (definition) for 
"considerWarningAsError".

Is this possible? If not, how should I make it possible?

Thanks

--
Attila

Hi all,

I have a problem with the otherwise excellent (thanks!) rst2beamer tool.
After a recent system upgrade to Xubuntu Natty (11.4), it doesn't render
the slide title correctly. Instead, the title is output immediately *after*
the maketitle command, as the attached test file shows. Strangely,
rst2beamer does recognize the title correctly (as the "\hypersetup{
pdftitle={..." setting shows), but it doesn't render it correctly.

I use rst2beamer v0.6.6 with originally Docutils 0.8 [snapshot 2010-09-01,
r6395]. After the problem I tried downgrading Docutils to 0.7 [release],
but that didn't change anything. I also tried re-installing rst2beamer, but
without any success. The only real change was that Python is now at
v2.7.1+, while before it was v2.6.something.

Does anybody have any idea what's going wrong there? I'll be grateful for
any hints...

Christian

-- 
|------- Dr. Christian Siefkes ------- chr...@si... -------
| Homepage: http://www.siefkes.net/ | Blog: http://www.keimform.de/
|    Peer Production Everywhere:       http://peerconomy.org/wiki/
|---------------------------------- OpenPGP Key ID: 0x346452D8 --
The first 90% of the code accounts for the first 90% of the development
time. The remaining 10% of the code accounts for the other 90% of the
development time.

Hello-

I'm trying to insert code under the .. tip:: construct like so:

.. tip::

  Here's some code to show it::

    >>> foo = "test"

With the odtwriter, the embedded code is not indented relative to the
tip section but to the page. Any ideas on how to fix, or should I file
a bug?

cheers,
-matt

Hi,

I'm not sure it's a bug (even if it looks like one), and if not I'm looking for
a workaround.

I need to do a group option list with special characters, and the dot '.' seems
to break the layout (a ``.sp`` is added). Can be reproduced with:

$
    bla bla bla

#
    bla bla bla

.
    bla bla bla

[
    bla bla bla

]
    bla bla bla

It does not seem to affect other tools, so I guess it's a bug from rst2man.
Escaping the dot does not help getting the correct output.

On 2011-05-31, Sih Iok-Jin wrote:

> I would like to use rst2latex to generate *.tex file , and show the
> section name on the right top of result PDF file. 

> So, I use the fancyhdr Latex package to accomplish my goal.

> But the result PDF file doesn't show the section name on the right top.

By default, headings are only automatically updated when a new numbered
section starts.

Hence, there can be several reasons:

a) You do not use numbered headings
b) You do not use "latex numbering"

Fix for b):

> docutils.conf
> -----------------

> [latex2e writer]
> documentclass: article
> documentoptions: 12pt,a4paper,dvipdfmx
> output-encoding: utf-8
> stylesheet: docutils.tex
  # section numbering by LaTeX instead of Docutils:
  sectnum-xform: False 
  
or command line arg: --no-section-numbering
  

Otherwise, you would need to update the headers via raw latex...
(see the fancyhdr documentation).

Günter