Hi Cameron & Stuart, I want to make sure that I haven't misunderstood either of you or missed a post.
@Cameron, I went back and checked again what you said and by talking about having a .tpl file for every entity and showing examples of trivial h1 I understood you to be talking about a complete replacement of the backend. @Stuart, You seem to be talking about the tpl mechanism as an extra which can override the existing backend mechanism with arbitrary Python, but only for entities that need it. To me the latter seems a less intrusive approach and it allows the extra facility to be turned off if required (Stuart, my security concerns and Murphys law both require the ability to turn it off, no matter how transparent the changes are :-) @Cameron, what was your reason for choosing having a directory with a file per entity rather than a single file with a section per entity? The latter would make it much easier to keep the cascading configuration that asciidoc has at the moment, only one file is needed per level rather than a directory per level. Cheers Lex On 13 March 2010 14:58, Stuart Rackham <[email protected]> wrote: > Hi Cameron > > I like your concept, it's elegant, and you are correct, it does involve a > major change in output generation. Using Python as the template language is > the ultimate in flexibility and doesn't introduce yet another templating > language. > > Since the changes only affect outputs there should be no impact on AsciiDoc > source compatibility. > > The major design decisions relate to how the rendering parameters are > passed from asciidoc to .tpl files and how the .tpl files are named and > organized. Getting this interface right would be key. > Currently we have an internal document attributes dictionary plus INI style > .conf files containing template and tag entries (actually there's really no > difference between asciidoc template sections and tag entries, the different > implementations are historical). The only missing attribute is the > template/tag content, but that's easy to add. > > Theoretically the implementation should be straight-forward: > > - After loading asciidoc .conf files (templates and tags) load .tpl files. > - When rendering, .tpl templates take precedence over .conf file templates > and tags. > > The new templates could be switched on with a command-line option to > preserve backward compatibility (though in theory this should not be > necessary, provided care is taken to give any customized .conf file > templates and tags precedence over distributed .tpl files). > > As always the devil is in the details and I suspect it won't be trivial > (asciidoc has been under development for more than seven years and there's a > fair amount of evolution related cruft buried in the code). > > @all Asciidoc users: > I would very much like to see some concrete use cases i.e. AsciiDoc > solutions that would not be possible without the proposed templating system > -- irrespective of elegance, I don't see a lot of point in solutions that > don't solve real and existing problems. So if this system rings your bell > please post your use case. > > @Cameron: > So where to from here? > > 1. Define specs for the asciidoc to .tpl file API and the .tpl naming and > organization conventions. Posting this spec for public comments before > getting to far down the implementation track would be a good idea. > > 2. Clone the Hg repo and create a separate development branch for your > templating system. > > 3. Implement it. > > I'm very happy to answer any questions and advise re asciidoc internals > (but as you've probably guessed by now, I don't always operate in real > time). As far as coding goes you would be largely on your own. > > > Cheers, Stuart > > > > cweagans wrote: > >> Below is a paste of a conversation I had with Stuart via email. Any >> input on this topic would be appreciated, as my company is wanting to >> move forward on this. If the Asciidoc community is interested, we'll >> build it on Asciidoc. Else, we'll go with another solution that >> supports what we need (we want to contribute to an open source >> project, hence my post. If the contribution just doesn't really fit >> any projects, we'll either create our own or use Open Office or >> something) >> >> >> +-------------------------------------------------------- >> from: [email protected] >> to: [email protected] >> date: March 8, 2010 >> +-------------------------------------------------------- >> Hi Stuart, >> >> First off, I'd like to thank you for all the work you've put into >> asciidoc. We're using it internally for documentation and customer >> manuals and such, and it's working really well! >> >> We've been having some difficulty with asciidoc, in that it's >> difficult to do some of the things that we'd like to do (sorry for the >> vagueness...I'm not really allowed to say too much about our >> documentation, due to a super-strict NDA). I'm a programmer and I'd >> like to implement our needed features, but I don't want to put a bunch >> of time into it if it won't be accepted as a contribution to asciidoc. >> >> So, my question is, how would you feel about a major rewrite of how >> asciidoc outputs formatted data? Existing documents will be >> unaffected, as the modifications would only affect the output logic. >> These changes would allow for more output formats, as well as the >> ability for end-users to tweak how asciidoc outputs data (for example, >> it would be a very very trivial matter to make asciidoc output <h1 >> class="class1 class2 class3" id="header_123"> rather than just <h1>. >> >> Essentially, I'm talking about building an easily extensible output >> layer for asciidoc. >> >> Interested? >> >> -Cameron Eagans >> >> >> +-------------------------------------------------------- >> from: [email protected] >> to: [email protected] >> date: March 8, 2010 >> +-------------------------------------------------------- >> Hi Cameron, >> >> You will need to be a bit more specific, some examples (input and >> output) would be nice, any text is fine, no need to include any NDA >> related stuff. Also the rationale and the advantages of you proposed >> changes would be good. >> >> I suggest that you post it to the AsciiDoc discussion list (http:// >> groups.google.com/group/asciidoc) to get input from other users. >> >> >> Cheers, Stuart >> >> >> +-------------------------------------------------------- >> from: [email protected] >> to: [email protected] >> date: March 8, 2010 >> +-------------------------------------------------------- >> >> Basically, what I'd like to do is this (I'll use the XHTML output >> format for my examples): >> >> There is a set of entities that asciidoc supports for rendering. A non- >> exhaustive list: headers (1 through 6), bold, italic, underline, >> normal text, and code listings. >> >> Every output document has a set of entities that it requires. In my >> vision for this implementation, you'd have a directory for every >> output format that contains template files for each asciidoc supported >> entity. >> >> /home/cweagans/asciidoc/output/xhtml: >> document.tpl >> h1.tpl >> h2.tpl >> h3.tpl >> h4.tpl >> h5.tpl >> h6.tpl >> bold.tpl >> italic.tpl >> underline.tpl >> text.tpl >> code_listing.tpl >> xhtml.conf >> >> Each .tpl file is simply a python script that prints the appropriate >> markup (or uses a python library to generate PDFs or to generate ODT >> or....you get the idea). >> >> document.tpl might contain: >> >> print """ >> <html> >> <head> >> <title>%(title)s</title> >> </head> >> <body class='%(body_classes)s''> >> %(content)s >> </body> >> </html> >> """ % variables >> >> variables would be created when the file is loaded and populated with >> the needed information to build the document. >> >> Smaller entities are trivial: >> >> h1.tpl might contain: >> >> print """ >> <h1>%(content)s</h1> >> """ % variables >> >> >> The .conf file might contain some information about what order to load >> the entities, or maybe a reference to a pre-build or post-build script >> that would get executed before or after the initial compile on the >> document (for example, a .odt post-build script might write all the >> needed files and compress them into the archive format needed for >> opendocument) >> >> Since all of the entity templates would be standard python, there's no >> reason why asciidoc couldn't support, for example, .odt output or even >> (if you are feeling -really- daring) voice files or microsoft word >> documents. >> >> I haven't fully fleshed out the idea because I haven't actually >> started implementation, but that's the basic idea. >> >> What do you think? >> >> -Cameron >> >> > -- > You received this message because you are subscribed to the Google Groups > "asciidoc" group. > To post to this group, send email to [email protected]. > To unsubscribe from this group, send email to > [email protected]<asciidoc%[email protected]> > . > For more options, visit this group at > http://groups.google.com/group/asciidoc?hl=en. > > -- You received this message because you are subscribed to the Google Groups "asciidoc" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/asciidoc?hl=en.
