Producing Latex documents from Leo

[dhumphrey]

I've been struggling to get out of the starting gate with Leo for
several days now. I think it's the change in thought patterns, not
the operation of Leo itself, that has been the hurdle. I'm not sure
I've cleared the gate yet, but I think I have done enough due
diligence to start asking questions.

My first question involves producing Latex documents from Leo. Python
is the primary language I use. Is the only path to Latex via noweb?
When I weave (File/Export/Weave) my Leo web, I get a .txt file with @,
@c, and @language python lines included. Is there an option to omit
these lines from the weave output.

Perhaps better questions are these:

1. Is the normal mode of operation to omit the "printed" document in
favor of reading the outline directly?
2. If not, what is the most direct path from a leo web to a Latex
document?

Regards,
DLH

[Terry Brown]

On Thu, 10 Dec 2009 07:29:00 -0800 (PST)
dhumphrey <da...@dlkeh.net> wrote:

> 2. If not, what is the most direct path from a leo web to a Latex
> document?

I've never used Leo's web stuff. Perhaps you don't need to.

What kind of document are you trying to write?

If you're working with python with the documentation embedded in the
source, Sphinx might be a better route.

I've used LaTeX quite a bit, but if I can I prefer to write in rst,
which uses LaTeX for PDF output, so you can use LaTeX math in
particular.

Finally, if you're just trying to write a document using LaTeX, I'd
just use an @shadow node with @others to track sections etc. etc.

Cheers -Terry

[Edward K. Ream]

On Thu, Dec 10, 2009 at 1:59 PM, Terry Brown <terry_...@yahoo.com> wrote:

Thanks for helping with these comments, Terry.

Edward

[TL]

> I've used LaTeX quite a bit, but if I can I prefer to write in rst, ...

rST support within Leo used to be a plugin but is now a part of Leo's
core. However, the documentation is still located in Chapter 14 of
Leo's User Guide (http://webpages.charter.net/edreamleo/
rstplugin3.html). I use rST to create HTML files. Maybe somebody
else can describe what needs to be done to output Latex files.

Note: The following text uses the code/compile analogy to describe the
use of rST. I think it best reflects the operation being performed.
Others disagree.

The rST "code" (actually written in the "docutils" language) is placed
within a Leo node that has an "@rst" directive in the node's header.
For example: @rst MyLatexFile

The rST "code" will be stored inside the leo file. If you prefer to
keep the "code" in a separate file then place the "@rst" node under a
"@thin" node. For example:

@thin MyLatexFile.tex
@rst MyLatexFile

The rST "code" is "compiled" into an HTML or Latex file by issuing the
command: "c.rstCommands.rst3()". The easiest way to do this is to
create a button in Leo by placing the following node structure in the
Leo outline (or better yet, place it in the outline of your
myLeoSettings.leo file). You can open up the myLeoSettings.leo file
from the "Help" menu.

@settings
@button rst3

Place the "c.rstCommands.rst3()" text (without the quotes) in the body
of the "@button rst3 node". Save the myLeoSettings.leo file and re-
open your leo file and you should see the button. Select the @rst
node that you want to "compile" and select the "rst3" button. This
will place the output file in a directory defined by rST's
"default_path" option.

The rst options are defined in the body of the "@rst MyLatexFile" node
or you can put them in an ancestor node. See Chapter 14 of the User
Guide for a list of the options.

@ @rst-options
code_mode=False
show_doc_parts_in_rst_mode = False
generate_rst=True
show_organizer_nodes=False
show_headlines=False
show_leo_directives=True
write_intermediate_file = False
verbose=True
@c

I hope this helps to get you going. Don't hesitate to ask more
questions.

Welcome to Leo,
TL

[Terry Brown]

For making PDFs from rst via LaTeX this page:

http://leo.zwiki.org/RstEmacs

has some useful info. if you skip the first section about emacs.

I just used this approach to make a 33 page report with 40 figures,
worked great.

Cheers -Terry

[dhumphrey]

Thanks to all that replied. The common message is "rst" so I will
pursue that path.

To clarify my original post, I'm writing python code and want to
experiment with Knuth's ideas of "code embedded in the document".
When I write code, I have always found thought processes alternating
between outlines for high level organization and somewhat random notes
to capture details. I think Leo will be a valuable tool in helping me
impose some organization on this process.

Incidentally, I never thought about using Leo to organize a pure Latex
project, so Leo has made me think in a new way.

Regards,
DLH

[Edward K. Ream]

On Fri, Dec 11, 2009 at 11:47 AM, dhumphrey <da...@dlkeh.net> wrote:
> Thanks to all that replied.  The common message is "rst" so I will
> pursue that path.
>
> To clarify my original post, I'm writing python code and want to
> experiment with Knuth's ideas of "code embedded in the document".
> When I write code, I have always found thought processes alternating
> between outlines for high level organization and somewhat random notes
> to capture details.  I think Leo will be a valuable tool in helping me
> impose some organization on this process.

Leo's rst code was designed with this use case in mind. Experience
has shown that the present scheme is more complex and less flexible
than I would like. Indeed, there are several requests for
enhancements at present.

This is a bit frustrating to me, because I put a lot of work into
making Leo recognize @rst-options in each node. Lately, my intuition
has been whispering that something simpler and more general might be
possible. I always pay attention to such whispers, but there are no
guarantees.

As I write this, I am wondering whether a user-defined prepass might
be a way to simplify and generalize the rst code. Of course,
user-defined scripts might not be what every would call a
simplification :-) But it's a starting point for rumination.

Edward

[Edward K. Ream]

On Sat, Dec 12, 2009 at 9:25 AM, Edward K. Ream <edre...@gmail.com> wrote:

> Leo's rst code was designed with this use case in mind.  Experience
> has shown that the present scheme is more complex and less flexible
> than I would like.  Indeed, there are several requests for
> enhancements at present.
>
> This is a bit frustrating to me, because I put a lot of work into
> making Leo recognize @rst-options in each node.

I can also add that I find it impossible to keep all the various
options (and their interactions!) clear in my mind. That is not a
good sign, though perhaps those that actually use Leo's rst3 command
might not have so much trouble making sense of it all. OTOH,
complexity is usually (almost always) a sign of some underlying
weakness in the design, and it is this complexity that is no doubt
behind the whispers.

Edward

[Edward K. Ream]

On Dec 12, 9:25 am, "Edward K. Ream" <edream...@gmail.com> wrote:

> Leo's rst code was designed with this use case in mind.  Experience
> has shown that the present scheme is more complex and less flexible
> than I would like.  Indeed, there are several requests for
> enhancements at present.

Well, I'm not sure this comment is correct. I just reread the rst3
documentation chapter, and the bug list, and my present feeling is
that Leo's rst handling may be about as good as can be expected. As
always, better documentation might clarify various kinds of usage
patterns, but that is not a design issue.

Furthermore, there is already a way of massaging @rst trees with
scripts. See
http://webpages.charter.net/edreamleo/rstplugin3.html#controlling-the-rst3-command-from-scripts

The essence of the problem is that we want to control the rST output
*without* introducing any additional markup. This is a big, big
constraint, but it has one huge advantage: it allows us to format code
with rST *without* changing the code as it appears in Leo.

The essential trick is to embed settings and raw rST code within Leo's
@doc parts. These doc parts provide and "escape hatch" that allows us
to sidestep the "no new markup" requirement. Using @doc parts, and
@settings in headlines, the user can format any node independently of
any other node.

In all probability, this is the most general formatting framework than
can be imagined. Within this framework, however, it might be possible
to add more features, or to streamline features or options. When even
more flexibility is wanted, the user can use
c.rstCommands.writeNodeToString(p)

In short, if the whispers have any validity at all (they are indeed
sometimes just wrong), they are likely to be confined to tweaks around
the edges. I don't see how we can do better than the present general
framework.

Edward

[Juaco]

On 11 Dez., 17:47, dhumphrey <da...@dlkeh.net> wrote:

> Incidentally, I never thought about using Leo to organize a pure Latex
> project, so Leo has made me think in a new way.

Although I somehow late to this discussion, I would like to say
something as a simple user. Some weeks ago I tried to generate my
first LaTeX documents. I had at the very beginning only a partial
success. I received several useful answers from different persons
participate in this group.

One of the difficulties was how to "convince" Leo to write raw code, I
wanted to write some equations and tables, so it was necessary to use
symbols like \, { }, and so on, i. e., what is required by LaTeX. The
problem was that all these symbols were "interpreted" wrongly and
replaced by an unreadable code. The solution was to use the raw
directive. An example is much better to show this. Assume the
following LaTeX code for an equation and a table in a Leo node:

@
.. raw:: latex html

\begin{equation} f(x)=\frac{e^{X\beta}}{1-e^{X\beta}} \end
{equation}

\newline
\begin{tabular}[b]{|r|l||c|r|}
<content deleted ...>
\end{tabular}

@c

Attention: RsT code requires an indentation with respect to the raw
directive. I didn't know it. It is here a leading blank space for all
LaTeX code inside the raw directive. And then it worked fine.

In this way I feel now free to write the LaTeX code. I would recommend
you to see the former contributions in the beginning of december.

I hope this helps you also a little bit.

Juaco

[Edward K. Ream]

On Sun, Dec 13, 2009 at 11:47 AM, Juaco <joaqui...@gmx.de> wrote:
>
> On 11 Dez., 17:47, dhumphrey <da...@dlkeh.net> wrote:
>
>> Incidentally, I never thought about using Leo to organize a pure Latex
>> project, so Leo has made me think in a new way.
>
> Although I somehow late to this discussion, I would like to say
> something as a simple user. Some weeks ago I tried to generate my
> first LaTeX documents. I had at the very beginning only a partial
> success. I received several useful answers from different persons
> participate in this group.
>
> One of the difficulties was how to "convince" Leo to write raw code, I
> wanted to write some equations and tables, so it was necessary to use
> symbols like \, { }, and so on, i. e., what is required by LaTeX. The
> problem was that all these symbols were "interpreted" wrongly and
> replaced by an unreadable code. The solution was to use the raw
> directive.

Thanks for these helpful comments.

I am beginning to think that Leo is quite close to being the ultimate
rST processor, with just a slight change in point of view (and
corresponding docs, of course :-) I'm thinking out loud here.

As I write this, it looks like there are two, no three, no four, no
five, no six, ways to fully integrate rST into Leo.

Part 1: Make @rst trees behave like full-fledged @<file> nodes.

Suppose we make @rst nodes behave like other kinds of @<file> nodes.
@rst trees would then have the following properties:

A. As with any @<file> node, saving a Leo outline will write the file
if any part of the outline is dirty. In effect, Leo automatically
performs the rst3 command in such situations.

B. Like an @nosent file (and present @rst trees), Leo will store the
data in the outline, not in the generated file.

B. The write_intermediate_file rst option might could be expanded so
that it would specify the full path of the intermediate file. This
option would have to appear in the root @rst node.

Continuing this line of thought, an @rst tree without a filename would
still be useful, provided it had an write_intermediate_file option
that specified an intermediate file: saving the outline would write
this file if the @rst tree were dirty.

Part 2: Add @rst capabilities to @<file> trees.

This is kinda a new thought. It may have been inspired by the recent
comments concerning Leo and literate programming. The question is:
can we have the rst3 command do something useful and interesting when
applied to an @<file> tree?

Just as with @rst trees, selecting any node within an @<file> tree
will cause the rst3 command to look up the tree looking for *either*
@rst nodes (as at present) *or* @<file> nodes (the new capability).

If the rst3 command finds an @<file> node, the rst3 command **must
not** write the file--Leo *already* writes the file as needed. But,
depending on @rst options, the rst3 command *could* write one or more
additional files, and these additional files could be considered to be
"weaves" of (all or parts of) the external file specified in the
@<file> node.

Part 3: tagged weaves in any kind of @<file> tree, include @rst trees.

Here is another idea inspired by "tags" like @design-notes that I
discussed earlier today. We could have the something like the
following rst options::

@ @rst-options
rst-tag-file <tag> <tag-file>
@c

This would search for all nodes with headline starting with @tag,
munge those nodes as usual as per the rst3 command, and then send the
output to tag-file. In effect, this "weaves" the outline
automatically into tag-file. Let us use the term **intermediate
file** to mean either the file specified by the (expanded)
write_intermediate_file option or one of these new tag-file files.

For further control, we could allow body text to contain

@ @rst-options
set-tag <tag>

which would be the same as starting the headline with @<tag>. This
scheme would allow a single outline to have arbitrarily many weaves:
one for each tag and corresponding tag file.

Part 4: @rst trees without a file name.

This idea builds on the expanded meaning of intermediate files. If the
@rst node specifies no file, there would be no "official" output file
at all, but saving the Leo outline would create various intermediate
files as side effects. Imo, this is very much like automatic weaving.
For the very first time, Leo could support both automatic tangling
and automatic weaving!

Part 5: Applying scripts to intermediate or woven files.

As long as we are processing an @rst tree (or an @<file> tree??) for
its side effects (intermediate files) we might as well allow an @rst
file to specify a post-processing script. This won't work for all
kinds of @<file> trees, but in an @rst tree we could add support for
@post-processing-script nodes that would contain a script to be run
after creating any kind of intermediate file.

Part 6: leading and trailing blank lines.

Whenever writing any kind of intermediate file, Leo will be in a
position to ensure a blank line before and after the body text of any
node. So the expanded definition of intermediate files instantly
creates a context in which this important detail can be handled.

Conclusions

1. We can considerably expand what can be done in @rst trees by
expanding the notion of an intermediate rst file to include tagged
weaves and named intermediate files.

2. We can scan for rst options within @<file> nodes. These options
could create both kinds of intermediate files too. This expanded
scanning could be very fast: Leo would do it only if the @<file> node
itself contained an rst doc part.

3. Tagged weaves provide a highly flexible way of simulating TLP's
weave operations. As usual, adding outline context significantly
generalizes the notion. Why settle for one weave? A single @rst or
@<file> node could have dozens.

These are just initial thoughts. There may be gotcha's that I haven't
considered. However, it does appear that Leo can do much better than
at present with what appears to me to be very minimal changes to Leo's
rst and file write code.

Your comments, please.

Edward

[Edward K. Ream]

On Mon, Dec 14, 2009 at 1:19 PM, Edward K. Ream <edre...@gmail.com> wrote:

> As I write this, it looks like there are two, no three, no four, no
> five, no six, ways to fully integrate rST into Leo.

This post was way too long for the big picture to jump out, so let me
try to clarify what has just happened. All these ideas were the
result of two very simple ingredients:

1. Tagged nodes.

These are a staple of Leo. Nobody, including me, has any idea how
powerful tags (user types) really are.

2. Intermediate files and side effects.

This is something truly new. The idea is to treat an @<file> tree as a
data structure to be used for its side effects. Named weaves are one
side effect; who knows how many others there might be?

The reason that these simple ideas can create two, no three, no four,
no five, no six new possibilities is that they create a new design
space for invention. This as useful, perhaps even more useful, than a
"big collapse" of complexity. Indeed, this new design space may be
the way to unify various disparate, inchoate ideas relating to rST
processing and literate programming. All these might just collapse
into tagged intermediate files.

Maybe the whispers weren't so wrong after all :-)

Edward

[TL]

> A. As with any @<file> node, saving a Leo outline will write the file
> if any part of the outline is dirty. In effect, Leo automatically
> performs the rst3 command in such situations.

This feature has crossed my mind as I've been using rST to develop
HTML files. My concern is that I don't necessarily want to have a new
HTML file created, which may have a "last modified on <date>" entry,
just because Leo has detected a change to a r
ST option or some other change that doesn't actually change the
visible HTML content.

TL

[TL]

Concerning the tangle and weave issues, can't I accomplish what is
needed by putting the documentation for a given module, function or
whatever in a node that is then cloned and included in the code and
the HTML/Latex document using a <<nodeName>> section name?

For example, if a function's description is placed in a node called
"functionName() description" then I can add it to the node containing
the python code as a comment by specifying:

"""
<<functionName() description>>
"""

and in an @rst node containing the module's documentation under a
header by specifying:

functionName
==========
<<functionName() description>>

Are you trying to achieve something more sophisticated? If so, can
you provide an example showing the code and documentation files you
want to generate and how that would be accomplished within Leo's
outline?

TL

[Edward K. Ream]

That should never be a problem. Iirc, all of Leo's write commands
write to a string first, and write to the actual file only if a real
change was made.

Edward

[Edward K. Ream]

On Mon, Dec 14, 2009 at 8:19 PM, TL <t...@tltools.net> wrote:
> Concerning the tangle and weave issues, can't I accomplish what is
> needed by putting the documentation for a given module, function or

> whatever in a node that is then cloned [snip]

Yes.

> Are you trying to achieve something more sophisticated?

Something simpler and perhaps more general. Suppose Leo supports a
new @tag directive::

@tag tag-name

tag-name can be any string not containing blanks. @tag will be the
way for the user to tag any node. Tags have many uses:

1. Scripts can use tags to select nodes for processing. Leo's
directive code can easily be extended to support user tags.

2. The find command could look only for nodes with a given tag, or
apply an @tag directive to found nodes.

3. Yesterday's Aha was that a single @<file> tree might generate many
intermediate (auxiliary) files, one for each tag. If the root @<file>
node contains::

@ @tag-file tag filename
@c

Leo will write all nodes having the given tag to the file.

This looks like a simpler solution than cloning, because everything is
in the @<file> tree. It's also extends Knuth's idea of weaving. Not
only is outline context important while generating rST, but a single
@<file> tree can produce many different "weaves".

4. Explicit tags might be the way to get the oft-requested
"half-clone" feature. To do this, Leo might support one or both of
the following directives::

@link unl
@gnx gnx

One can think of these as special-purpose tags, telling Leo to keep
the headline and body text of the linked nodes in sync. Such nodes
are not clones: they will typically have different children.

Edward

[TL]

> @tag will be the way for the user to tag any node.

Would the @tag directive be placed as a line in the body text of the
node being tagged?

Can you show what a Leo outline might look like if it were to support
outputting multiple variations of an @file based on the tagging of sub-
nodes?

Thanks,
TL

[Edward K. Ream]

On Tue, Dec 15, 2009 at 8:33 PM, TL <t...@tltools.net> wrote:

> Would the @tag directive be placed as a line in the body text of the
> node being tagged?

Yes. Or as Ville suggests, it could be a uA. Leo's tag support
should handle both.

> Can you show what a Leo outline might look like if it were to support
> outputting multiple variations of an @file based on the tagging of sub-
> nodes?

The root node would contain an rst comment like this::

@ @rst-options
tag-file tag filename
tag-file tag2 filename2
@c

That's all, except for the @tag directives (or uA's) in the nodes that
are "assigned" to the tag files.

Edward

[Terry Brown]

On Wed, 16 Dec 2009 09:23:32 -0500

"Edward K. Ream" <edre...@gmail.com> wrote:

> The root node would contain an rst comment like this::
>
> @ @rst-options
> tag-file tag filename
> tag-file tag2 filename2
> @c

@ @rst-options
tag-file tag filename

tag-file tag2 tag3 tag3 filename2
@c

perhaps?

Assuming that I'm at least partly understanding this proposal, and that
the goal is to build filename from all the nodes tagged 'tag', and
filename2 from all the nodes tagged 'tag2' (or 'tag3' or 'tag4').

Cheers -Terry

[Edward K. Ream]

On Wed, Dec 16, 2009 at 11:39 AM, Terry Brown <terry_...@yahoo.com> wrote:

> tag-file tag2 tag3 tag3 filename2

An excellent suggestion. Thanks.

Edward