rst3 and section names
Theo Ruys
Only recently I discovered Leo and I am very happy with it. Leo seems
very powerful and offers many possibilities of which I have only
scratched and understand the surface.
I come from a 'pure' literate programming world (i.e. noweb), and I
would like to do similar things with the rst3 plugin. That is, have a
single leo source file and let leo generate three different files from
it:
- a source program for some programming language
- a LaTeX file (describing the source)
- a HTML file (describing the source)
To have as less redundancy as possible, I want to use clones for the
program fragments, using noweb-style section names (e.g. <<macros>>).
Unfortunately, it seems that I cannot use section names in combination
with the rst3 plugin. The plugin does not expand the section names. Is
there a rst3 setting, that I have overlooked?
Theo Ruys
Edward K. Ream
> I come from a 'pure' literate programming world (i.e. noweb), and I
> would like to do similar things with the rst3 plugin. That is, have a
> single leo source file and let leo generate three different files from
> it:
> - a source program for some programming language
> - a LaTeX file (describing the source)
> - a HTML file (describing the source)
Hmm. I am a bit unsure how to answer. Please don't take the
following as authoritative: I often forget the implications of all the
rst options.
My *guess* is that the easiest way forward for you is to create an
@button (or @command) script to create the input to the rst3 plugin.
That script can set up the rst3 options as convenient.
The script would create @rst x.html or @rst x.tex depending on the
kind of output desired. (Or you could use two scripts.
The input to the scripts would be either a noweb file, or one of Leo's
@file, @thin (etc) nodes.
BTW, I have only limited experience with generating LaTeX using
docutils. You might want to do a quick prototype to see how well the
rst3 plugin generates .tex files.
Anyone else have advice?
Writing the scripts themselves should not be too difficult. The
script would simply traverse a Leo outline looking for section
references. For the logic required, look at leoPy.leo, the node:
Code-->Core classes-->@thin leoAtFile.py-->at.Writing-->Writing 4.x-->putBody
Edward
Theo Ruys
> My *guess* is that the easiest way forward for you is to create an
> @button (or @command) script to create the input to the rst3 plugin.
> That script can set up the rst3 options as convenient.
I want to write the documentation for the source program in a @rst3
subtree.
In this @rst3 subtree I want to refer to fragments of the program,
like:
In the following code fragment::
<<code fragment>>
Unfortunately, <<code fragment>> will not be expanded.
Furthermore, in order to get to this work, I should have <<code
fragment>> under
the @rst3 subtree as well, but this is then also treated as @rst3
input (which
in this case, is not what I want).
> BTW, I have only limited experience with generating LaTeX using
> docutils. You might want to do a quick prototype to see how well the
> rst3 plugin generates .tex files.
also
input "default.css", which they shouldn't of course.
> Writing the scripts themselves should not be too difficult. The
> script would simply traverse a Leo outline looking for section
> references. For the logic required, look at leoPy.leo, the node:
>
> Code-->Core classes-->@thin leoAtFile.py-->at.Writing-->Writing 4.x-->putBody
in Python and Leo to make this work, though.
Theo Ruys
Edward K. Ream
> Hmm, that is not exactly what I want.
> I want to write the documentation for the source program in a @rst3
> subtree.
> In this @rst3 subtree I want to refer to fragments of the program,
> like:
>
> In the following code fragment::
>
> <<code fragment>>
>
> Unfortunately, <<code fragment>> will not be expanded.
> Furthermore, in order to get to this work, I should have <<code
> fragment>> under
> the @rst3 subtree as well, but this is then also treated as @rst3
> input (which
> in this case, is not what I want).
Let's assume that the @rst tree is in the same .leo file as the
sources. In this case, cloning nodes is possible.
The problem with traditional litprog is that, just as you say, << code
fragment >> isn't expanded, but instead the reader must somehow find
it. Imo, this makes litprog listings *much* harder to understand than
a Leo outline. Indeed, I say at
http://webpages.charter.net/edreamleo/design.html:
"Experience with the Weave command shows that an outline can easily
become unintelligible when printed, no matter how "beautiful" the
typeset printout is. No printed listing can be as clear as Leo's
outline view."
I don't think there is anything that the rst3 plugin can do to alter
this stark fact.
However, let's move on. I assume you want to do essentially what
weave does. That is, you want to present the *list* (not outline!) of
all the noweb fragments.
I don't know how suited the rst3 plugin is to this task, but it's
quite flexible, so given almost any kind of formatting it should be
possible to write a script that produces an @rst tree that, when
processed by the rst3 plugin (and docutils) will produce a decent
result. In particular, your script will create an @rst tree that
(presumably) contains clones.
> I do not know whether I am yet fluent enough in Python and Leo to make this work, though.
The Leo part should not be a problem, and if it is, I'll be glad to
ask questions. Ditto for the rst3 plugin. I suggest doing *hand
simulations* of what you want the script to produce before writing too
much code. That is, pretend you are the script, and create the @rst
tree by hand. You should start writing the script only *after* you
know what kind of @rst tree you want to create. This was the approach
I took with the m2c (more to c) script, the initial prototype of Leo.
Now this is important: this script will teach you Python. It's not,
in fact, very complicated, but it's big enough for you to learn lots.
My first Python program was much more ambitious: see scripts.leo, the
node:
Scripts-->@file leoScripts.txt-->Important-->c2py Convert C code to
Python syntax
This was the source of all my initial Aha's about Python. See the white paper:
http://webpages.charter.net/edreamleo/whitepapers.html#why-i-like-python
In other words, by *far* the best way to learn python is to write a
script that is important to you.
Edward
Theo Ruys
Thanks for the extensive reply.
And thanks for all the pointers and encouragement for diving
into Python and Leo. I will certainly do so in the coming weeks.
And I guess that the script way is a sensible way to go.
But that is not exactly what I want (at this moment).
Let me try to explain what I want to do in more detail.
Suppose I have a source program that I have written in leo.
The source program is defined in a leo subtree (either @thin,
@nosent, @shadow) and I let leo generate the source file.
So leo tangles the source program.
At a certain point I want to describe (parts) of this program
in a @rst tree. This means that I want to (re)use certain
named sections (i.e. clones) of the original program
in this @rst tree. For example,
----- example of body text under the @rst sub tree -----
Below we define some macros::
<<macros>>
----- end of example -----
Note that I have indented <<macros>> to make it a code block.
What I want is that the body of the named section <<macros>>
of the original program is inserted here. I do not want to see
the name <<macros>> appear in the generated file (either
.html or .tex). So it is not exactly the way as weaving.
With noweb, you still would see the section names in the
output; here I just want to have the plain code.
So in retrospect, I do not want to use the @rst plugin in pure
noweb style. With noweb, you would use tangle to get the
source code. Here, I use leo to my advantage to generate
the source file. In a separate @rst subtree, I now build a new
subtree to generate (i.e. weave) the documentation.
What would work for me is if named sections in a @rst subtree
would work exactly as they work for other derived files: they
get inserted at the place where they are referenced.
Or am I trying to misuse leo in this way?
Theo Ruys
Edward K. Ream
> At a certain point I want to describe (parts) of this program
> in a @rst tree. This means that I want to (re)use certain
> named sections (i.e. clones) of the original program
> in this @rst tree. For example,
>
> ----- example of body text under the @rst sub tree -----
>
> Below we define some macros::
>
> <<macros>>
>
> ----- end of example -----
>
> Note that I have indented <<macros>> to make it a code block.
> What I want is that the body of the named section <<macros>>
> of the original program is inserted here. I do not want to see
> the name <<macros>> appear in the generated file (either
> .html or .tex).
...
> What would work for me is if named sections in a @rst subtree
> would work exactly as they work for other derived files: they
> get inserted at the place where they are referenced.
>
> Or am I trying to misuse leo in this way?
This is certainly not a misuse of Leo--it's an extension of the rst3 plugin.
Clearly, a script could expand these section references, creating a
temporary @rst tree which then gets processed as usual. As usual,
scripts give complete control over what is happening.
But other people might like have the rst3 plugin work in this way, so
an expand_noweb_references option would be good. For compatibility,
the default for this option would be False.
I don't want to change the rst3 plugin until after Leo 4.5.1 is
released, but feel free to experiment with these ideas before then.
Edward
Edward K. Ream
On Sep 8, 6:52 am, "Edward K. Ream" <edream...@gmail.com> wrote:
> I don't want to change the rst3 plugin until after Leo 4.5.1 is
> released, but feel free to experiment with these ideas before then.
work needed to support the expand_noweb_references option. A simple
test file in test.leo shows the expected traces.
However, we come now to an interesting choice, namely, how to find
referenced clones. There are at least two possibilities, each with
drawbacks:
1. Require clones to be descendants of the referencing node (in the
@rst tree). This is unambiguous, but would seem to require and
@rst_ignore_node directive to suppress the definition that would
otherwise be shown twice (once for the reference and once when the
definition node is printed.
2. Look for definitions throughout the entire outline. This requires
that section used in @rst trees have unique names.
It's about the same amount of work either way. What are your
preferences?
Edward
Johannes Wrehde
> It seems to work. The only annoying thing is that the LaTeX files
> also
> input "default.css", which they shouldn't of course.
if you use such like this
@ @rst-options
publish_argv_for_missing_stylesheets =
--language=de,--documentclass=scrbook,--use-latex-toc,--documentoptions=12pt,--stylesheet=PREAMBLE.tex,
--use-latex-footnotes,--hyperlink-color=0
@c
in the first node of your @rst-tree you will avoid "default.css" in LaTeX.
Look at
http://docutils.sourceforge.net/docs/user/config.html#latex2e-writer
and
http://webpages.charter.net/edreamleo/rstplugin3.html#options
Johannes
Theo Ruys
> This morning I created an rst3 branch. I now contains the preliminary
> work needed to support the expand_noweb_references option. A simple
> test file in test.leo shows the expected traces.
trunk.
> 1. Require clones to be descendants of the referencing node (in the
> @rst tree). This is unambiguous, but would seem to require and
> @rst_ignore_node directive to suppress the definition that would
> otherwise be shown twice (once for the reference and once when the
> definition node is printed.
would be
to ignore noweb style named sections within a @rst tree. This would
make it
easier to just use clones within a @rst subtree. This is also more in
line with
the behaviour of named sections in 'normal' (non-@rst) subtrees.
BTW, does the explicit @rst_ignore_node directive also apply to the
children
of the particular @rst_ignore_node node? In that case an explicit
@rst_ignore_node parent node would suffice to shield all named
sections
to be expanded. But this is less nice than simply ignoring named
sections,
as we now have to "declare" all named sections under a
@rst_ignore_node
parent.
> 2. Look for definitions throughout the entire outline. This requires
> that section used in @rst trees have unique names.
unique
in the complete leo file, it also makes the @rst tree not longer self-
contained.
IMO, this seems to be against leo-philosophy. It feels like using
global
variables in a program.
> It's about the same amount of work either way. What are your
> preferences?
Theo Ruys
Theo Ruys
> @ @rst-options
> publish_argv_for_missing_stylesheets =
> --language=de,--documentclass=scrbook,--use-latex-toc,--documentoptions=12p t,--stylesheet=PREAMBLE.tex,
> @c
>
> in the first node of your @rst-tree you will avoid "default.css" in LaTeX.
I had not understand this from Leo's User's Guide on rst3.
Very much appreciated.
Theo Ruys
Edward K. Ream
>> 1. Require clones to be descendants of the referencing node (in the
>> @rst tree). This is unambiguous, but would seem to require and
>> @rst_ignore_node directive to suppress the definition that would
>> otherwise be shown twice (once for the reference and once when the
>> definition node is printed.
>
> Instead of using a @rst_ignore_node directive, another possibility
> would be to ignore noweb style named sections within a @rst tree.
We can't do this by default, because that would change how the rst3
plugin might handle existing @rst3 trees. But this could be (yet
another) option, say ignore_section_definition_nodes. I think this is
the proper way. The default for this option must be False for
compatibility with existing @rst trees.
> BTW, does the explicit @rst_ignore_node directive also apply to the
> children of the particular @rst_ignore_node node?
Here is what the docs say (I think they are accurate):
QQQ
@rst-ignore-node TEXT
Suppress all output from a single node. TEXT is ignored.
Has no effect on descendant nodes and does not change any rst3 option.
@rst-ignore-tree TEXT and @rst-ignore TEXT
Suppress all output from the node and its descendants.
TEXT is ignored. Does not change any rst3 formatting option.
QQQ
> A solution in the style of option 1 would be very much appreciated.
All right. That is what I shall do. I'll add the
ignore_section_definition_nodes option. In most cases, you should be
able to put that option in the root node and everything will "just
work".
Edward