2 Nov 04:27 2011

### Re: Separate html file for each chapter

On Mon, Oct 31, 2011 at 7:21 AM, Bob Plantz <rgplantz <at> gmail.com> wrote:
> My book is already written in LaTeX, which is sort of at the opposite end of
> the toolchain path from rst. Converting it to epub is turning out to be a
> real chore, but an interesting learning experience. It's teaching me that my
> source should be as simple as possible, which allows for more diverse paths
> to the final outputs.

BTW, sphinx already does "experimental" output to epub. See
http://sphinx.pocoo.org/config.html#options-for-epub-output and

You can use MathJax (http://www.mathjax.org/) with sphinx now
(http://sphinx.pocoo.org/ext/math.html#module-sphinx.ext.mathjax).
This lets you use latex within rst files.

However, epub support of Mathjax is still in the future. The thread
"MathJax and epub3"
will show you the relevant current discussions.

------------------------------------------------------------------------------
RSA&#174; Conference 2012
Save $700 by Nov 18 Register now&#33; http://p.sf.net/sfu/rsa-sfdev2dev1  9 Nov 11:12 2011 ### newpage in restructuredtext Dear List, i use restructuredtext to sweave my statistical analysis from R into html, odt and pdf (via latex). However, to improve readability I would like to start a section on a new page. Is there any kind of a “newpage” command in restructuredtext? Best, Felix Dr. rer. nat. Dipl.-Psych. Felix Fischer Institut für Sozialmedizin, Epidemiologie und Gesundheitsökonomie Charité - Universitätsmedizin Berlin Luisenstrasse 57 10117 Berlin Tel: 030 450 529 104 Fax: 030 450 529 902 http://epidemiologie.charite.de ------------------------------------------------------------------------------ RSA(R) Conference 2012 Save$700 by Nov 18
Register now
http://p.sf.net/sfu/rsa-sfdev2dev1
------------------------------------------------------------------------------
RSA(R) Conference 2012
Save $700 by Nov 18 Register now http://p.sf.net/sfu/rsa-sfdev2dev1 9 Nov 11:38 2011 ### Re: newpage in restructuredtext Hello, Fischer, Felix (Mittwoch, den 09.11.2011 um 11:12): > Dear List, > > > > i use restructuredtext to sweave my statistical analysis from R into html, odt > and pdf (via latex). However, to improve readability I would like to start a > section on a new page. Is there any kind of a “newpage” command in > restructuredtext? There is already a way to force a page break in LaTeX described in the docutils Documentation: Commands directly to LaTeX ========================== By means of the reST-raw directive one can give commands directly to LaTeX, e.g. forcing a page break:: .. raw:: LaTeX \newpage But I can't decide, whether this already what you are looking for. What do you want to achieve? A new page in your LaTeX generated .pdfs or also in .odt? Or should each section start on new page automatically? Viele Grüße nach Berlin, Peter Funk -- -- Peter Funk, home: ✉Oldenburger Str.86, D-27777 Ganderkesee mobile:+49-179-640-8878 phone:+49-421-20419-0 <http://www.artcom-gmbh.de/> office: ArtCom GmbH, ✉Haferwende 2, D-28357 Bremen, Germany DRUPA 3.5.-16.5.2012: Besuchen Sie uns in Halle 4 auf Stand B02 ------------------------------------------------------------------------------ RSA(R) Conference 2012 Save$700 by Nov 18
Register now
http://p.sf.net/sfu/rsa-sfdev2dev1
_______________________________________________
Docutils-users mailing list
Docutils-users <at> lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/docutils-users


9 Nov 15:00 2011

### Re: newpage in restructuredtext


Dear Peter,

> But I can't decide, whether this already what you are looking for.
>
> What do you want to achieve?
> A new page in your LaTeX generated .pdfs or also in .odt?
> Or should each section start on new page automatically?

I would be glad, if newpage would also work in odt. I guess, each section/subsection on a new page would be the
best solution!

Best,
Felix

-----Ursprüngliche Nachricht-----
Von: Peter Funk [mailto:pf <at> artcom-gmbh.de]
Gesendet: Mittwoch, 9. November 2011 11:39
An: docutils-users <at> lists.sourceforge.net
Betreff: Re: [Docutils-users] newpage in restructuredtext

Hello,

Fischer, Felix (Mittwoch, den 09.11.2011 um 11:12):
> Dear List,
>
>
>
> i use restructuredtext to sweave my statistical analysis from R into html, odt
> and pdf (via latex). However, to improve readability I would like to start a
> section on a new page. Is there any kind of a “newpage” command in
> restructuredtext?

There is already a way to force a page break in LaTeX described
in the docutils Documentation:

Commands directly to LaTeX
==========================

By means of the reST-raw directive one can give commands directly to
LaTeX, e.g. forcing a page break::

.. raw:: LaTeX

\newpage

But I can't decide, whether this already what you are looking for.

What do you want to achieve?
A new page in your LaTeX generated .pdfs or also in .odt?
Or should each section start on new page automatically?

------------------------------------------------------------------------------
RSA(R) Conference 2012
Save $700 by Nov 18 Register now http://p.sf.net/sfu/rsa-sfdev2dev1 _______________________________________________ Docutils-users mailing list Docutils-users <at> lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/docutils-users Please use "Reply All" to reply to the list.  9 Nov 23:33 2011 ### Re: newpage in restructuredtext On 2011-11-09, Fischer, Felix wrote: >> What do you want to achieve? >> A new page in your LaTeX generated .pdfs or also in .odt? >> Or should each section start on new page automatically? > I would be glad, if newpage would also work in odt. I guess, each > section/subsection on a new page would be the best solution! This looks very much like a task for a custom style sheet. I don't know whether/how this can be achieved in ODT. I know that it is possible with a custom style or just LaTeX preamble code with LaTeX. However, I don't know the details so you will need to search the web or ask the TeXperts about "LaTeX, start every section on a new page". Günter ------------------------------------------------------------------------------ RSA(R) Conference 2012 Save$700 by Nov 18
Register now
http://p.sf.net/sfu/rsa-sfdev2dev1
_______________________________________________
Docutils-users mailing list
Docutils-users <at> lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/docutils-users


11 Nov 00:27 2011

### Two ideas for implementation

Hello everyone,
I'm a regular user and a great fan of docutils and ReST; I use it to
write reports and other documents and I even wrote my bachelor thesis
in it. Thank you all for the hard work you put in the project!

This year at school I signed up for an open-source programming class
which includes participating in an actual project; I'd like to
contribute something to Docutils. There are two ideas I have and I
need to decide between. My concern is mostly about how long would each
idea take to implement and how complicated it would be; I'm fluent in
Python and I wrote some custom extensions for docutils before, but I'm
still no expert on how docutils work internally.

First idea is inspired by a recent post [1] in this list asking about
the "field-list-table" directive. Is there still interest in this? Is
someone working on it at the moment? As far as I can tell this seems
like a rather easy thing to do, basically just transforming the field
list into a table in the internal tree representation. Am I missing
something (apart from correct terminology)?

The second idea is a much more complex one. I'm not a huge LaTeX fan;
it does the job for me most of the time, but without rst2latex I'd be
lost. Adjusting stuff by hand typically takes too much tweaking and
I'm not very satisfied with the documentation.

On the other hand, the documentation of ConTeXt [2] is very nice and
well organized and I like the system more in general. So I thought
about creating a ConTeXt writer, to have a rst2context tool in the
end. Again, if I understand correctly, that woul mean taking some of
the existing *tex writers and modifying it accordingly. Is there a
sample document using all directives, where I would be able to test
how far I progressed? What are the standards for creating new writers
and for accepting them into upstream?

What are your thoughts? Is there some other feature/bug that is more
important, yet easy enough for me to work on? Something from the
docutils ToDo [3] perhaps :) ?

al-Quaknaa

P.S.: I'm away for the weekend so I may not respond immediately, but I
will eventually.

[1] http://article.gmane.org/gmane.text.docutils.user/6456
[2] http://wiki.contextgarden.net/Main_Page
[3] http://docutils.sourceforge.net/docs/dev/todo.html

------------------------------------------------------------------------------
RSA(R) Conference 2012
Save $700 by Nov 18 Register now http://p.sf.net/sfu/rsa-sfdev2dev1  11 Nov 10:37 2011 ### Re: Two ideas for implementation [Alli Quaknaa] wrote & schrieb: (1) >First idea is inspired by a recent post [1] in this list asking about >the "field-list-table" directive. Is there still interest in this? Is >someone working on it at the moment? Yes, yes. I'am the one who asked. We still need it. And I'm working on that at the moment. And, your're right: It's not that very difficult. I've got a first version doing the basic stuff ready and working here already. So you could leave this "field-list-table" topic up to me. I will continue that work when there's a next time slot free. Currently my code isn't written well and I want to add "rowspan" and "colspan" capabilities. That's a bit more tricky. And I'm not sure yet what kind of :options: should be possible. So I've switched to improving an existing 'html2rst' converter to also handle tables. I am dreaming of roundtrip capabilities: html -> rst -> html -> rst -> ... with table structure being maintained. I will be glad to present the stuff here or come back for help. (2) >The second idea is a much more complex one. Yes, do that As I wrote already the http://typo3.org community has decided to switch to ReST documentation format lately. And others of us are trying to care about the LaTeX stuff. I am not in that and cannot help with suggestions here. But I know there is much need in that area. So I'd love to see you following your idea (2)! Cool, cool, cool, I'm feeling excited! Martin -- -- http://mbless.de ------------------------------------------------------------------------------ RSA(R) Conference 2012 Save$700 by Nov 18
Register now
http://p.sf.net/sfu/rsa-sfdev2dev1

12 Nov 00:28 2011

### why docutils should reject Alan's proposal

Docutils mailing list:

David Goodger has suggested that the two major reasons why
reStrucuredText is not used for scientific documentation is that it
cannot mange bibliographic references and it cannot include math.
Recently, there have been some good steps forward in implementing math
support (through converting LaTeX to MathML, for example).

There have been no steps forward to handle bibliographic management.

Alan Isaac has put forward some type of proposal, but I suggest docutils
reject this proposal.

In order for a proposal to be adopted, it must meet 2 criteria:

(1) It must thoroughly explore the problem. The proposal must not only
consider the actual reStructuredText syntax, but the needs of a
different users. For example, the developers have considered the problem
with tables and have realized that many users needed CSV tables, and
then implemented this feature. Thought was given to the needs of users
and the different scenarios.

(2) A proposal must include examples of reStructuredText syntax and
examples of how that syntax should be rendered in a tree. For example,
the reSructuredText pattern

Title
===

Gets rendered in the docutils tree as

<section>

<title>Title</title>

Imagine if docutils did not have the heading element, and someone
proposed that there should be a title just like in MS Word. What exactly
does that mean? Does the user want to create a section, for example?

Alan's proposal fails to meet either criteria.

(1) First, he has not thoroughly considered the problem at hand.
Bibliographic references can be quite complex. Consider:

As Bergonzi notes (*Anatomy of Rome*, p33)

As Bergonzi notes (*Anatomy of Rome*, p33-66)

As Bergonzi notes (*Anatomy of Rome*, p33, p66)

As Begonzi notes (*Anatomy of Rome*, p33-66, Vol1, p45, Vol 2)

As Bergonzi and Jensen note (*Anatomy of Rome*, p33-66, Vol1, p45;
*History of Italy*, p33)

And so fourth. I have done some work in the past on just this issue,
painstakingly going through style manuals gleaning examples. That is how
I know about the complexity of the issue.

Alan's proposal has not considered any of these issues. Instead of
presenting the full problem and then showing how his proposal would
handle them, he has merely given one or two examples, and then in a very
vague way. He has not presented proposed syntax for these examples.
Instead, he has presented rambling discourse on the need to accept his
proposal, and how it works in bibtex. Such a proposal neither addresses
the specific problem nor gives a solution. A serious proposal includes
specific syntax for all the potential situations. Alan either seems
unaware of the complexity of the problem, or does not care to address it.

(2) Alan proposes no idea of how the docutils tree should render his
proposal. As it stands now, the following syntax:

a refernece [foo]_

.. [foo] reference

Gets rendered as

<paragraph>a refernece <citation_reference ids="id1"
refid="foo">foo</citation_reference>
</paragraph>
<citation backrefs="id1" ids="foo" names="foo">
<label>foo</label>
<paragraph>reference</paragraph>
</citation>

No spaces are allowed, and brackets are not allowed. The text inside the
brackets gets assigned an ID, which should match a the backrefs
attribute in the citation element.

Alan suggests:

[mycite{mytext}]_

From here, he does not suggest how he wants the new tree to look.
Presumably, he wants the text "mycite" to link to the full citation, and
the string "mytext" to somehow be extra. But from here, his proposal is
too vague to be taken seriously. Does he want the "mytext" dumped as a
string in its own element? If so, then how about when there are multiple
references? For example:

As Bergonzi and Jensen note [Anatomy{p33-66Vol1,p45;Vol2p33-44}]_

Becomes:

<citation backrefs="id1" ids="Anatomy"
names="Anatomy"><other>p33-66Vol1,p45;Vol2p33-44</other></citation>

But what use is that? The other element now contains a string of text
that is almost useless to an external writer or parser. Perhaps he wants:

As Bergonzi and Jensen note [Anatomy{p33-66}{Vol1}{p45}{Vol2}{p33-44}]_

.. [Anatomy] *Anatomy of Rome*, etc

to become:

<citation backrefs="id1" ids="Anatomy" names="Anatomy">
<p>33-66</p>
<vol>1</vol>
<p>45</p>
<vol>2</vol>
<p>33-44</p>
</citation>

It is hard to say, because Alan's proposal does not contain any
specifics. He keeps  insisting that it is not important how the rest of
the text that is not the ID gets handled, but that seems unworkable,
namely because his solution does not put fourth a solution to
bibliographic management. It basically requires a partial solution that
does not further the goals of reStructredText. Developers would have to
develop code only to have to go back later and develop more code, or
switch the code they have.

Alan seems unaware that a reStructuredText document gets rendered to a
tree before it gets rendered to a LaTeX document, and hence his proposal
remains too vague to be workable.

I suggest that Alan do 3 things in order for his proposal to go forward:

not talking past each other

2. Provide the syntax for complex citation references, not just simple
references that have one page.

3. Provide specifics on how he wants these citations parsed, preferably
in a tree, or, if he does not feel comfortable with that, something
equivalent.

I don't think implementing poorly thought-out proposals further
reStructuredText

Paul

------------------------------------------------------------------------------
RSA(R) Conference 2012
Save $700 by Nov 18 Register now http://p.sf.net/sfu/rsa-sfdev2dev1  12 Nov 02:06 2011 ### Re: why docutils should reject Alan's proposal Paul, I cannot tell from your post whether you actually understand how BibTeX's optional text works. Do you? Millions of users have found BibTeX pretty darn useful. I ask yet again, what part of your critique would *not* apply to BibTeX's handling of optional text? Can you please respond to this question? (It provides important context for the conversation.) I'm just asking we take a small step by adding functionality that millions of BibTeX users have proved is useful. It would be one thing if you were proposing some better way to move forward, but instead you seem to insist that optional text not just be arbitrary optional text but come with a grammar. As I explained multiple times, this is exactly what my proposal intentionally does not do. My only proposal is that docutils support optional text for citation references, instance by instance. Yes: a single string. You ask "what use is that?"; well, ask millions of BibTeX users. It is useful! Finally, you seem to think I am putting forward an implementation proposal. I am putting forward only a proposal that developers agree in principle to allow optional text, and find a syntax to support it. I've proposed one at the document level, one that is easily parsed and backward compatible. Here is another: use the vertical bar. [mycite|optional text]_ I am not in any way attached to this. I have also urged that docutils treat the optional text as a simple string and not commit to parsing it in any way, because otherwise we need agreement on many things whereas getting agreement even on allowing any extra information at all will be hard to get. Note too that you offer an example where the citation is changed by the optional text. That is not what I proposed: the citation is what it is. The optional text for the citation reference only affects that particular instance of the citation reference. (Again, compare with BibTeX.) E.g., [mycite{p.10}]_ would become e.g. :: <citation_reference ids="id1" refid="mycite">mycite <crtext>p.10</crtext></citation_reference> and then [mycite{vol.3,p.10}]_ would become e.g. :: <citation_reference ids="i2" refid="mycite">mycite <crtext>vol.3,p.10</crtext></citation_reference> I am not proposing the details! The important thing is that the citation would be unchanged. Both references would be to the same citation. That is the only goal: to allow optional text in the citation references, instance by instance. Finally, you can have what you would like even if my wishes are accommodated. For example, suppose there were agreement to allow optional text as I request, perhaps using the vertical bar as above. Then when you persuade everyone of a useful and meaningful grammar for additional text, you could introduce it using braces. If it is superior -- and honestly I imagine it will be in every way aside from date of implementation -- then use of the other syntax will slowly die out. Alan ------------------------------------------------------------------------------ RSA(R) Conference 2012 Save$700 by Nov 18
Register now
http://p.sf.net/sfu/rsa-sfdev2dev1

12 Nov 03:45 2011

### Re: why docutils should reject Alan's proposal

On 11/11/11 8:06 PM, Alan G Isaac wrote:

It would be more helpful if Alan had actually included examples of
syntax markup and the resulting tree. Since he didn't, let me do that so
everyone is clear on the intentions.

Alan proposes that this syntax:

a refernce [mycite{p33}]_

.. [mycite] reference

Becomes this tree:

<paragraph>a refernece
<citation_reference ids="id1" refid="mycite">
mycite
<cite_arg>p33</cite_arg>
^^^^^^^^^^^^^^^^^^^^
</citation_reference>
</paragraph>
<citation backrefs="id1" ids="mycite" names="mycite">
<label>mycite</label>
<paragraph>reference</paragraph>
</citation>

Note the addition of the cite_arg element.

This suggestion ignores the fundamental idea behind docutils, that it
processes text to form a tree. This tree can then be converted into
other forms, such as LaTeX (a non-tree structure) or XML, HTML, or
OpenOffice (all trees).

Alan proposes that docutils implement something for one type of writer
(LaTeX) that will not work with other types of writers (OpenOffice,
HTML, XML). So one could write a scientific paper intended for the web
in reStructuredText, and still not have any bibliographic management.

Such an approach is short-sighted.

None-the-less, Alan makes a valid point. He at least wants the ability
to post process the string created in the hypothetical cite_arg above.
The above tree fragment:

<citation_reference ids="id1" refid="mycite">
mycite
<cite_arg>p33</cite_arg>
</citation_reference>

Can be processed by a further transform, depending on the writer, just
before the text is actually written. The transform could be written
later. For now, one has the option of either including literal text (for
example "a reference [mycite{page 33}]_"), or of not using any optional
arguments.

To make this truly useful, however, I think we need to agree that there
be more than one argument. If we are going to change the syntax of the
reference citation, it makes more sense to make it flexible and logical.
So, going with Alan's initial proposal (from a few weeks ago), the text
could look like this:

[mycite {page: 33}{vol: 2}]_

Note the difference here: there are now more than one argument. Each
argument has a keyword that helps define the argument. The resulting
tree would be:

<citation_reference ids="id1" refid="mycite">
mycite
<cite_arg name="page">33</cite_arg>
<cite_arg name="vol">2</cite_arg>
</citation>

Let be clear here that I am not proposing that the arguments be
constricted by any specific grammar. For example, this syntax would be
also valid:

[mycite {page: 33}{vol: 2}{spaghetti_monster: like speghatti}]_

<citation_reference ids="id1" refid="mycite">
mycite
<cite_arg name="page">33</cite_arg>
<cite_arg name="vol">2</cite_arg>
<cite_arg name="spaghetti_monster">like spaghetti</cite_arg>
</citation>

Such a syntax would make post processing much easier and more sensible.

In addition, I propose that an optional, simplified syntax with an
implied argument be allowed.

[mycite 33]_

<citation_reference ids="id1" refid="mycite">
<cite_arg name="page">33</cite_arg>
</citation>

And:

[mycite 33-44]_

<citation_reference ids="id1" refid="mycite">
<cite_arg name="page-range" start="33" end="44">33-44</cite_arg>
</citation>

Other implied arguments could also be implemented, such as pages
separated by commas.

The obstacle to this implementation at this point are the normal obstacles:

(1) Does everyone agree on the usefulness of the syntax?

(2) Can the parser parse the syntax?

Paul
> Paul,
>
> I cannot tell from your post whether you actually
> understand how BibTeX's optional text works.  Do you?
> Millions of users have found BibTeX pretty darn useful.
> I ask yet again, what part of your critique would *not* apply
> to BibTeX's handling of optional text?  Can you please
> respond to this question? (It provides important
> context for the conversation.)
>
> I'm just asking we take a small step by adding functionality
> that millions of BibTeX users have proved is useful.
>
> It would be one thing if you were proposing some better
> way to move forward, but instead you seem to insist that optional
> text not just be arbitrary optional text but come with a grammar.
> As I explained multiple times, this is exactly what my
> proposal intentionally does not do.
>
> My only proposal is that docutils support optional text
> for citation references, instance by instance.
> Yes: a single string. You ask "what use is that?"; well,
> ask millions of BibTeX users.  It is useful!
>
> Finally, you seem to think I am putting forward an
> implementation proposal.  I am putting forward only
> a proposal that developers agree in principle to allow
> optional text, and find a syntax to support it.
> I've proposed one at the document level, one that
> is easily parsed and backward compatible.  Here is
> another: use the vertical bar.
>
>      [mycite|optional text]_
>
> I am not in any way attached to this.  I have also
> urged that docutils treat the optional text as a simple
> string and not commit to parsing it in any way, because
> otherwise we need agreement on many things whereas
> getting agreement even on allowing any extra information
> at all will be hard to get.
>
> Note too that you offer an example where the citation
> is changed by the optional text.  That is not what
> I proposed: the citation is what it is. The optional
> text for the citation reference only affects that
> particular instance of the citation reference.
> (Again, compare with BibTeX.)  E.g., [mycite{p.10}]_
> would become e.g. ::
>
>     <citation_reference ids="id1"
>     refid="mycite">mycite<crtext>p.10</crtext></citation_reference>
>
> and then [mycite{vol.3,p.10}]_ would become e.g. ::
>
>     <citation_reference ids="i2"
>     refid="mycite">mycite<crtext>vol.3,p.10</crtext></citation_reference>
>
> I am not proposing the details! The important thing is that the citation
> would be unchanged. Both references would be to the same citation.
> That is the only goal: to allow optional text in the citation references,
> instance by instance.
>
> Finally, you can have what you would like even if
> my wishes are accommodated. For example, suppose there
> were agreement to allow optional text as I request,
> perhaps using the vertical bar as above.  Then when
> you persuade everyone of a useful and meaningful
> grammar for additional text, you could introduce
> it using braces.  If it is superior -- and honestly
> I imagine it will be in every way aside from date
> of implementation -- then use of the other syntax
> will slowly die out.
>
> Alan
>
>
> ------------------------------------------------------------------------------
> RSA(R) Conference 2012
> Save $700 by Nov 18 > Register now > http://p.sf.net/sfu/rsa-sfdev2dev1 > _______________________________________________ > Docutils-users mailing list > Docutils-users <at> lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/docutils-users > > Please use "Reply All" to reply to the list. ------------------------------------------------------------------------------ RSA(R) Conference 2012 Save$700 by Nov 18
Register now
http://p.sf.net/sfu/rsa-sfdev2dev1


Gmane