RE: [docbook-apps] Compact DocBook ?
>On topic though, so why not! Thanks for the help on what is appropriate etiquette. >By the looks of it, Leo is GUI ? Leo is a GUI in the sense that it displays nodes hierarchically just like Windows explorer displays folders/directories hierarchically. I am a novice at DocBook, Leo, literate programming and the like. The best thing would be to look at the Leo doco "Chapter 6: Leo and Literate Programming" at http://webpages.charter.net/edreamleo/design.html#chapter-6-leo-and-literate -programming -Original Message- From: Dave Pawson [mailto:da...@dpawson.co.uk] Sent: Monday, July 12, 2010 7:38 AM To: Robert Lucente Subject: Re: [docbook-apps] Compact DocBook ? On Mon, 12 Jul 2010 06:11:46 -0400 "Robert Lucente" wrote: > >Think of it the other way round? > >Embed java code in Docbook? > Nice ! > > >Tangle and weave are the ideas, > >Literate Programming the background. > > At one point, I started using Leo to do "literate programming". The > thing that I like about Leo is that it is an outliner w/ hoist and > node cloning. The downside is that it has a steep learning curve. > > http://webpages.charter.net/edreamleo/front.html > > I still use an old versio of Leo but don't do full Literate > programming. So far, the price of the learning curve is not worth it. > > I did not post this in the docbook group because it did not seem > appropriate. If I am wrong, please correct me. Some are interested in literate programming in general, so there may be some interest, but I guess it's low. On topic though, so why not! By the looks of it, Leo is GUI? I'm not sure how that helps for litprog? I use emacs, or (a java environment, then paste/include into emacs for the Docbook) regards -- regards -- Dave Pawson XSLT XSL-FO FAQ. http://www.dpawson.co.uk - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
Re: [docbook-apps] Compact DocBook ?
+-- | I'm hoping to embed DocBook within some Java code (as | comments). Along with some support utilities, this should | allow embedding of documentation next to the code it describes. | This is somewhat similar to JavaDoc, but: | | a. using DocBook vocabulary, | | b. to be included within end-user documentation. | | The thought of writing DocBook XML inside Java comments isn't appealing. +-- Why not turn the whole process inside out? http://www.nmt.edu/~shipman/soft/litprog/ For several years now, all my serious coding is done in "lightweight literate programming" (LLP) style. The idea is to have the documentation contain the program, not vice versa. Here's how I develop code nowadays. 1. Write up the external interface in DocBook. 2. Document the "big picture" parts of the design, also in DocBook. For a small project, this can be the same document as the external spec; for substantial projects, I'll start a separate "Internal Maintenance Specification". 3. Write the program as a continuous narrative with embedded code blocks contained within DocBook elements. To distinguish example code blocks from live code blocks, I used the extension 'role' attribute to route the code into the files from which it will be run or compiled. Here's an example: The first lines make this script self-executing, and point back to this documentation: #!/usr/bin/env python # myscript.py: This script... # For documentation, see http://... <- HTML output from DocBook import sys ... Writing a script to extract the source code files took me about an hour, including all documentation. It's trivial in any language with a decent XML toolset; I used Python and lxml. Note that you can include any number of files in any number of languages. One drawback of JavaDocs is that it works only with Java. Sometimes the project includes non-Java files, such as CSS stylesheets; why not include them in literate form as well? See the URL above for the code extractor and several dozen complete projects done in this style. The originator of Lightweight Literate Programming is my colleague Dr. Allan Stavely, based on the classic 1980s-era literate programming idea from Dr. Don Knuth. Best regards, John Shipman (j...@nmt.edu), Applications Specialist, NM Tech Computer Center, Speare 119, Socorro, NM 87801, (575) 835-5735, http://www.nmt.edu/~john ``Let's go outside and commiserate with nature.'' --Dave Farber - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
Re: [docbook-apps] Compact DocBook ?
Remko Tronçon wrote: > Unfortunately, this way of working works if the main thing you're > writing is documentation with some toy examples in them (and even > then, I personally just write scripts that embed pure source code into > DocBook includes). It doesn't work for real development. Of couse it is not mainstream, but this method of writing software was successfully used on very complex software projects like TeX. So I would not just straightly deny this idea. -- -- Jirka Kosek e-mail: ji...@kosek.cz http://xmlguru.cz -- Professional XML consulting and training services DocBook customization, custom XSLT/XSL-FO document processing -- OASIS DocBook TC member, W3C Invited Expert, ISO JTC1/SC34 member -- signature.asc Description: OpenPGP digital signature
Re: [docbook-apps] Compact DocBook ?
On Mon, 12 Jul 2010 13:19:31 +0200 Remko Tronçon wrote: > > then you have a perfectly normal docbook document, > > ... and you lose the ability to use of development tools like IDEs, > you have to regenerate the sources every time you make a tiny change > (which happens much more often than regenerating documentation), > debuggers get confused, you need to set up a way to name your sources > and map this to the filesystem, ... > > Unfortunately, this way of working works if the main thing you're > writing is documentation with some toy examples in them (and even > then, I personally just write scripts that embed pure source code into > DocBook includes). It doesn't work for real development. Doesn't work for you? yet you use xInclude... which could include files from your IDE? Odd, that sounds like a reasonable litprog way of doing it. Be assured, it does work for non trivial examples. regards -- regards -- Dave Pawson XSLT XSL-FO FAQ. http://www.dpawson.co.uk - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
Re: [docbook-apps] Compact DocBook ?
> then you have a perfectly normal docbook document, ... and you lose the ability to use of development tools like IDEs, you have to regenerate the sources every time you make a tiny change (which happens much more often than regenerating documentation), debuggers get confused, you need to set up a way to name your sources and map this to the filesystem, ... Unfortunately, this way of working works if the main thing you're writing is documentation with some toy examples in them (and even then, I personally just write scripts that embed pure source code into DocBook includes). It doesn't work for real development. cheers, Remko - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
Re: [docbook-apps] Compact DocBook ?
On Mon, 12 Jul 2010 10:36:36 +0200 Paul Millar wrote: > Dear all, > > [I hope this is on-topic for this list] > > I'm hoping to embed DocBook within some Java code (as comments). Think of it the other way round? Embed java code in Docbook? then you have a perfectly normal docbook document, from which you can extract java code to execute it and process into fully documented code! Tangle and weave are the ideas, Literate Programming the background. http://www.dpawson.co.uk/litprog/ may help. HTH -- regards -- Dave Pawson XSLT XSL-FO FAQ. http://www.dpawson.co.uk - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
