Re: XML documentation formatting and transformations

Here are some links that might lead you where you want to go:

There are more out there, but not yet a lot. The key here is to combine your search on XML with a search on Literate Programming. Because that is pretty much what you describe- literate programming that is. In fact, excepting the small matter of coding (SMOC tm), you not only should get every thing on your list (index, master table ofcontents, etc.), but you also get your source code out of the same black box. If you extend your schema, you also get a cross reference for all parameters used and if you want, all variables cross referenced with scoping information etc. Point of fact, if you tag it, you can manipulate it! Again, this is what LP is all about.

Having said that, there are two problems that come to mind. The first problem is that most of the magic involved around LP typically revolves around translating some initial form into LaTeX, and you've already indicated that, that wouldn't be desirable. Second problem, is tied to XML. While the idea of LP is comparative old (20 years comes to mind), expressing this in XML is pretty much a new thing. New enough that there aren't a lot of ready made tools that spring to mind. Most of them have been mentioned already in either this thread or the earlier one.

All of that leads me to this:

Q. XLS, will it fall down?
A. Nope. XLS can do pretty much everything you've mentioned, it's just SMOC again.
Q. What technology and approach should you take?
A. Well either lose your hang-up over LaTex and use well featured, tested, off of the shelf software…or do it your self. This last will give you the most control over the output- I'd still keep the LP approach (it's sound and it works), but a combination of XSL and Perl should take you to you destination. Keep in mind that you would have to pay the 'early adopter' penalty no matter what approach you choose.

I've given this topic quite some thought, since it is pretty much what I'm getting paid for at the moment! I've looked at virtually every solution to this problem out there, where 'looked at' means actually tried. To be truthful, I haven't found a single solution yet. Which same implies that I'm currently leaning in the direction of 'roll your own'. My general idea is to write a filter that uses a hybrid approach, i.e. part XML, part LP, part target language (Perl at the moment) to generate source, reference and help documents in html, and pdf. And of course, I'd write this in Perl- as a module, in the usual form of a 'something' 2 'something' app (pod2html, pod2pdf, and similar).

To grok the LP thing here is the single best pointer that I know:

http://www.literateprogramming.com/farticles.html

hsm

Comment on Re: XML documentation formatting and transformations

Replies are listed 'Best First'.
Re: Re: XML documentation formatting and transformations by John M. Dlugosz (Monsignor) on Nov 01, 2001 at 23:39 UTC
The whole idea behind Literate Programming is that someone can read the single source like a book. That is, it has the approachability of a "whitepaper" explaining it, but can spit out the real source code as opposed to referencing it in seperatly-maintained files. Obviously, that's not XML. What I really want is a simple markup that's easy to type, but I'll process that into XML as a stand-alone component. Then the real work transforms XML into my formatted documentation. As far as mixing the code and docs in the same file, I like the idea for some types of work, especially the code I write as part of a magazine article! That would be utterly perfect, if the LP file were a readable tutorial as it was. —John	[reply]
Re: Re: Re: XML documentation formatting and transformations by hsmyers (Canon) on Nov 02, 2001 at 00:55 UTC
Obviously, that's not XML. If this is based on experience, please relate the details. Point of fact, no has ever said that the raw source to LP has to be readable. Nor is the output limited to 'Whitepaper' style prose— I use it for normal day to day library documentation. To paraphrase, the whole point of XML is information tagging…once that is done, you transform it into whatever you want. And there is nothing in that concept that precludes LP or for that matter XML-LP. Have you actually looked at approaches like CWEB and NUWEB? If “What I really want is a simple markup that's easy to type…” then you are talking about a wheel that has already been invented, tested and used to a fare-thee-well. All of that aside, the reason I keep harping on the combination of XML and LP is that regardless of how you get there, XML is a stronger base for transformation than the original LP concept. So if you take the LP idea of starting with a simple markup language and combine that with conversion into XML, then I believe the sky is the limit on the possible transformations. Further, if you embrace the perlish 'Lazy is good!', then using a hybrid system makes good sense. For those things that LP already does, use an existing setup, typically a language non-specific LP, like NUWEB or one of the others (there are many.) For output not anticipated by LP, slap a Perl filter on your easy markup and let it rip! The posted comments about XSL being obviated by CSS is arguable…actual textual transformations can't be done in CSS, but are the bread and butter of XSL. I hadn't thought of it as an example before, but I actually use of form of this hybrid every time I post a bibliography on one of my web pages. The source is kept in a text file formatted in what is called BibTeX. It can be used in LP (gets converted into either html, pdf, or LaTeX) as is. For the web, I perl-filter it to XML and display using XSLT. This leverages 'working' code written by others with my own efforts, and is an open ended solution too boot! Obviously all of this babble is based on my idea of a good time, and at a guess, your mileage probably would vary. Not important, what is important is your goal. The more people that make this journey, the more choices we will all have, simply because there will be more solutions! *Good luck,and let the monastery follow along. hsm p.s. Source into whatever form your editors want shouldn't be a problem…*	[reply]


Keep It Simple, Stupid
	PerlMonks