On Mon, Apr 28, 2014 at 10:12 AM, <[email protected]> wrote: > Dear Edward, > > Thanks for providing your impressive Leo tool. I currently try to understand > its full potential.
Haha. So am I :-) > short story > =========== > I struggle to understand how to use Leo for creating code and docs from one > common project outline. > I tried to create code chunks as sections: expanding those in code files > works but I fail to expand them in documentation files (see attached .leo > file). What am I doing wrong? I'm not sure you are doing anything wrong. > full story > ========== > I got interested in Leo because it was mentioned under > http://www.literateprogramming.com/tools.html. I need a tool that I can use > across programming languages for maintaining code and documentation in one > place. I want something that goes beyond pure documentation generation from > code (such as javadoc or doxygen) because documentation needs to include > more that that (requirements, design, top down introduction from coarse to > fine grain etc). I want something that goes beyond traditional literate > programming in that I don't want to be forced to write all of my code as an > essay, because sometimes it is sufficient to just cite some important pieces > of code and because clear code needs its own structure different from > documentation structure. > > So what I want is a tool that allows to > - define named code chunks that can be re-used in multiple views such as > code files and documentation files > - GUI navigate code structure, docu structure and jump from one to the other > (inside Leo as well as between exported code and docs) > - define reusable modules that encapsulate code and documentation You are not alone in your desires. However, this is a surprisingly difficult ask. In general, the idea would be to convert (by hand, or with a script), an original (source) tree to another (target) tree representing exactly the output you want. Typically, nodes in the target tree would be clones of nodes in the source tree. That way, you don't have to reconvert the tree when source nodes change. Depending on node structure, you may have to reconvert the target tree when adding or deleting nodes in the source tree. > I understand that Leo is great in structuring either code or documentation. > I understand that Leo allows to define two types of chunks (nodes and > sections) and reusing them in multiple views (nodes via cloning and sections > via expanding references). > However, I don't see how to expand references in rst files, which would be > the natural way to talk about multiple chunks in one docu chapter (cloned > nodes force new chapters in the documentation)? > I also don't see how to create reusable modules of code and documentation. > This would require a tree structure like this > - root > - - module 1 > - - - module chunk tree 1 > - - - - elements of chunk tree 1 > - - - module code tree 1 > - - - - elements of code tree 1 reusing chunks > - - - module docu tree 1 > - - - - elements of docu tree 1 reusing chunks > - - module 2 > - - - module chunk tree 2 > - - - - elements of chunk tree 2 > - - - module code tree 2 > - - - - elements of code tree 2 reusing chunks > - - - module docu tree 2 > - - - - elements of docu tree 2 reusing chunks > - - main code tree (here the code export happens) > - - - elements of main code tree reusing modules > - - main docu tree (here the docu generation happens) > - - - elements of main docu tree reusing modules > > Can I do that with Leo? If not, would it be difficult to modify Leo to do > this (it seems Leo is at least already very close to such *extremely* useful > tool)? All your questions are intelligent. I said earlier that I am still, after more than 20 years experience with Leo outlines, exploring the answers to this and similar questions. By the way, Leo's developers (a.k.a the usual suspects) are actively discussing such questions on #Leo. You are welcome to join. See http://webchat.freenode.net/?channels=%23leo&uio=d4 The short answer is, you can do *anything* in Leo, provided you are willing to write a script to do exactly what you want to do. Especially if you use clones to "inject" code and/or comments into your documents. This is the most general, but least convenient approach. The rst3 command has some very complex capabilities that are (on purpose) not documented on Leo's web site. These involve code mode and rst mode. They are only documented in LeoDocs.leo. See the node:: LeoDocs.leo#Leo's Documentation-->Users Guide--> Creating documents with the rst3 Command--> @rst html\rstplugin3.html-->@rst-ignore-->Advanced topics I can never remember all the complexities myself, but the documentation will show you the kinds of options (hacks) that may be useful to you. In short, you *might* be able to make the rst3 command do exactly what you want. The great advantage of the rst3 command is that you can set options in each node: see the online docs. The code to handle per-node options is very complicated and tricky, as is the code that interfaces with docutils. Otoh, writing your own script will allow you to organize your data in exactly the way you want, and to process your data exactly as you want. Perhaps your script will create a tree that (say) the viewrendered.py or viewrendered2.py plugins can handle. There are many possibilities. HTH. Edward -- You received this message because you are subscribed to the Google Groups "leo-editor" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at http://groups.google.com/group/leo-editor. For more options, visit https://groups.google.com/d/optout.
