Re: Narrative Docs and DocBook vs. DITA (was How do I pass parameters for PDF output?)
- Eliot's points are good ones. I can get some of what I want when using
bookmap for pdf creation but to get everything, you have to change a
lot of attributes and xsl processing to make it what's provided in the
free plugins to work. In fact, I just finished a test where I took a
book (which is well-represented by the bookmap structure) and all the
metadata and it was onerous to create a 6x9 (trade paperback size)
book with reasonable structures. Things like dl-based elements are
formatted as tables which I don't consider a great model for that sort
of information. Even the table structures were difficult to change and
things like choicetables had too much white space around them. Lots of
stuff to look at to make things work the way I'd like. I should just
be able to specify a page size and there should be a reasonable
readjustment of margins and other objects within the pages with just
that simple adjustment. Branding should not be a difficult change but
it becomes one in the "free" implementation.
Bottom line: free isn't free. While it was an interesting exercise,
outside of some of the other transforms, XHTML, Eclipse Help, maybe
even CHM files, I would probably look towards other solutions for PDF.
This doesn't say that the reference implementation in the OT is a bad
one; it's just a reference so you have an idea of how to get things
done. Depending on your knowledge of XSLT and XSL-FO, you might be
able to transform DITA magically to anything (as long as you
understand the path structures). Personally, I would rather purchase
something from someone that does all this stuff well as long as I can
make any tweaks to the output easily.
Just my 2 cents' worth.
Julio J. Vazquez
--- In firstname.lastname@example.org, Eliot Kimber <ekimber@...> wrote:
> On 10/31/08 3:27 PM, "cybershark5886" <cybershark5886@...> wrote:
> > Hello Eliot,
> >> That is, there is no narrative document that cannot be represented
> >> *directly* in DITA just as easily as it can be in DocBook, for the
> > simple
> >> reason that both have the same level of structural and semantic
> > generality
> >> and both allow the creation of more-or-less monolithic documents that
> > can be
> >> processed directly by existing processing infrastructure.
> > It does appear to be quite similar in structure, but I just tried to
> > impliment tranitionsing my ditamap to a bookmap by pulling my topics
> > over in similar hierarchical fashion and I ran into a few problems.
> Note that I'm *not* talking about using the BookMap specialization
> 1.1--I find BookMap to be pretty unhelpful unless your books just
> conform to that structure (which largely reflects IBM's internal
> rules for structuring manuals). In addition, the Toolkit processing for
> BookMap is not always what you want.
> I'm trying to make the point that *you don't need maps at all* if
> want is a single-file XML document as you might create with DocBook.
> That is, there's nothing about the DITA standard that *requires* the
> Of course, almost every user of DITA will use maps, but that's
> are really useful, not because they are *required*.
> Creating a map that represents a complete book is pretty
> but getting print output, in particular, that meets your specific
> branding requirements is harder, not because it is inherently hard with
> DITA, but because the free tools we currently have at our disposal
> make it harder than it should be--I don't think anyone disputes that the
> current PDF2 plugin is difficult to understand and customize. I'm
> Suite Solutions is doing what they can to fix that, but it's a tall
> and nobody's paying them, as far as I know, which means it's a
> That's why, in this particular case, going to DocBook as an intermediate
> format might be the most productive thing to do--there is already a
> DITA-to-DocBook plugin available for the Toolkit that would be
> to extend as needed (easier than modifying the PDF2 processing to
> is pretty twisty stuff). If I understand correctly, this is what the XPP
> composition system does to format DITA-based content.
> Please don't confuse what DITA *the standard* allows and enables
with what a
> particular tool (DITA Open Toolkit, FrameMaker, etc.) does when talking
> about the value of DITA.
> Eliot Kimber | Senior Solutions Architect | Really Strategies, Inc.
> email: ekimber@... <mailto:ekimber@...>
> office: 610.631.6770 | cell: 512.554.9368
> 2570 Boulevard of the Generals | Suite 213 | Audubon, PA 19403
> www.reallysi.com <http://www.reallysi.com> | http://blog.reallysi.com
> <http://blog.reallysi.com> | www.rsuitecms.com
- I figured out a way to "cheat" in order to pass information like date,
revision, department name, and author. It's so simple I don't know why
I didn't think of it before but it's akin to a hack, and I don't
necessarily like the idea for long term. I simply took advantage of the
<author> tags by using multiple <author> tags to place anything I need
on the cover page. It all looks the same to the end-user in the output
they wont care whether I used <author> or (a custom defined)
tag to display the revision text, so that works for me.
Is it, however, possible in principle to copy the code for displaying
the <author> tags and modify it to display things in a "<revision>"
tag? Earlier Paul Masalsky told me "Regarding 'creating custom tags,'
you don't really 'add tags' in DITA. You extend existing ones." I plan
on looking at the customization video that he linked me too, but is it
possible to extend existing tags to cover a <revision> element entry?
- --- In email@example.com, "cybershark5886"
> I figured out a way to "cheat" [...] I simply took advantage of theI'm glad you're happy. :) (Though admitting to such hacks around here
> <author> tags by using multiple <author> tags to place anything I need
> on the cover page. [...] so that works for me.
is akin to confessing that you don't wash your hands after using the
> Is it, however, possible in principle to copy the code for displayingAbsolutely. You just have to know where in the document structure you
> the <author> tags and modify it to display things in a "<revision>"
(as the author of the document) are allowed to put a <revision> tag.
[Google the terms "XML validation" and "DTD"]. Or if there isn't one,
specialize an appropriate element such as <othermeta> [Google the
terms "DITA domain specialization".] Or use one that's been done
already, such as <revisionid> in bookmap.
- Thanks for the tips.
>I'm glad you're happy. :) (Though admitting to such hacks around hereHa ha. Well I don't exactly professionally smile on this "solution"
>is akin to confessing that you don't wash your hands after using the
but it "holds me over" until I can provide a more permanent solution,
so in that respect it buys me more time.
Thanks for all your time and suggestions. I'm sure to be around on the
forums in the near future asking more nagging and tantalizing
Hello again Deborah,
> The templates that pdf2 calls are named in
> one of the Ant build files in the demo/fo directory. Just grep for .xsl
> and see what it does.
> The pdf2 plugin has several text readme files in its various directories.
> They contain a lot of information about customizing the output. For more
> serious customization, you may have to read the source. (Those are the
> only resources I used, but perhaps someone else knows of a gentler guide.)
I actually recently stumbled upon a fairly helpful introductory tutorial for PDF2 (linked from here: http://www.ditausers.org/tutorials/) called DITA for Solo Writers (how convenient, since I am a 'solo' writer - as I've told you). I also have read the Readme files in the Plugin directory, and perused some of the files. I noticed that the readme said there was up to 67 customizable variables, but I'm unsure as to what those variables are or if there is a list of them somewhere. Thus far though the closest I have gotten to discovering how to pass information in meta tags to the front cover is from looking at two files in the demo\fo\cfg\fo\attrs directory: front-matter-attr.xsl and commons-attr.xsl.
There is a section in the commons-attr.xsl file where it has a series of such entries as below:
Do those refer to tags that I can use, and is this a template you had in mind when you said, "pdf2 already has templates for putting the title, author, and a couple of other bits onto the front cover"? I'm trying to figure out where I can go from here.
Earlier you said:
"If those templates match your corporate style then it's just a matter of putting the metadata into
the right place in your (book)map, and it will be picked up by the build."
So lets say for the time being that I want to use the default template, nothing special, and wanted to pass it this meta data. Could you give me a sample of what metadata you would use (for example) if you were trying to pass the name of the author(s), the organization, and (maybe) the date and/or the revision number?
Currently in my ditamap I have the following metadata:
<topicmeta>Is it as simple as discovering the correct metadata and its tags or do you truely have to customize the code for that?
<author> UAB CIS Department </author>
<author> Josh Nielsen</author>
Thanks for all your help so far.
- Hi Josh,
> I noticed that the readme said there was up to 67 customizableThose are the ones in cfg/common/vars/en_US.xml. They control the
> variables, but I'm unsure as to what those variables are
automatically-generated *content* which might vary from language to
language ("Page" in English is "Seite" in German, and so on). You are
welcome to change those (or, better, change the corresponding file in
a Customization directory).
You mentioned the cfg/fo/attrs/* files too. Those are for *styling*
of text, rather than *content*. Again, you can change those (or,
better, the Customization equivalent) to suit your needs. Most of the
names of the attribute sets are self-explanatory. If one exists, you
can style it. If it doesn't exist, then it's time to dig into the
XSLT (i.e., you can't just invent a new attribute set name without
mentioning it in the XSLT).
> is this a template you had inThe templates I'm referring to are in fo/xsl/fo/front-matter_1.0.xsl
> mind when you said, "pdf2 already has templates for putting the title,
> author, and a couple of other bits onto the front cover"?
(and others in the same directory). These correspond to the program
that generates your PDF, and they refer to both the variable and
attribute files I mentioned earlier in this message.
> So lets say for the time being that I want to use the default template,If you look for strings in fo/xsl/fo/front-matter_1.0.xsl (even if you
> nothing special, and wanted to pass it this meta data. Could you give me
> a sample of what metadata you would use (for example) if you were trying
> to pass the name of the author(s), the organization, and (maybe) the
> date and/or the revision number?
> Currently in my ditamap I have the following metadata:
> <author> UAB CIS Department </author>
> <author> Josh Nielsen</author>
> <copyryear year="2008"/>
> Is it as simple as discovering the correct metadata and its tags or do
> you truely have to customize the code for that?
don't know any XSLT) and fo/xsl/fo/front-matter.xsl you can see
templates that match <bookowner>, <contactnumbers>, <summary>,
<copyryear>, <namedetails>, <author>, and about a dozen other
elements. That means that the plugin has processing for those
elements. Stick them into your bookmap in legal places and see what
output you get. At a guess, I'd say that your sample ditamap will
contain something that the processing can use.
You're hitting the limit of what I know about the fo plugin without
having to resort to reading the code. That means that increasingly I
am going to point at a file and say "read the source". If you have to
customize the output more than the Customization vars and attrs can
do, then you really have no other option than to edit XSLT.