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].
For more options, visit this group at
http://groups.google.com/group/asciidoc?hl=en.
