Beefy Boxes and Bandwidth Generously Provided by pair Networks
Your skill will accomplish
what the force of many cannot
 
PerlMonks  

Re: Re: XML documentation formatting and transformations

by John M. Dlugosz (Monsignor)
on Nov 01, 2001 at 23:39 UTC ( [id://122645]=note: print w/replies, xml ) Need Help??


in reply to Re: XML documentation formatting and transformations
in thread XML documentation formatting and transformations

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

Replies are listed 'Best First'.
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…

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: note [id://122645]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others surveying the Monastery: (7)
As of 2024-03-28 21:57 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found