Loading ...
Sorry, an error occurred while loading the content.

Re: Narrative Docs and DocBook vs. DITA (was How do I pass parameters for PDF output?)

Expand Messages
  • Julio Vaquez
    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
    Message 1 of 25 , Nov 1, 2008
    • 0 Attachment
      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
      SDI

      --- In dita-users@yahoogroups.com, 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
      in DITA
      > 1.1--I find BookMap to be pretty unhelpful unless your books just
      happen to
      > conform to that structure (which largely reflects IBM's internal
      business
      > 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
      all you
      > 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
      use of
      > maps.
      >
      > Of course, almost every user of DITA will use maps, but that's
      because maps
      > are really useful, not because they are *required*.
      >
      > Creating a map that represents a complete book is pretty
      straightforward,
      > but getting print output, in particular, that meets your specific
      layout and
      > branding requirements is harder, not because it is inherently hard with
      > DITA, but because the free tools we currently have at our disposal
      currently
      > 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
      sure that
      > Suite Solutions is doing what they can to fix that, but it's a tall
      order
      > and nobody's paying them, as far as I know, which means it's a
      "spare time"
      > effort.
      >
      > 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
      simple
      > DITA-to-DocBook plugin available for the Toolkit that would be
      pretty easy
      > to extend as needed (easier than modifying the PDF2 processing to
      FO, which
      > 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.
      >
      > Cheers,
      >
      > Eliot
      >
      > ----
      > 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
      <http://www.rsuitecms.com>
      >
    • cybershark5886
      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
      Message 2 of 25 , Nov 5, 2008
      • 0 Attachment
        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
        and
        they wont care whether I used <author> or (a custom defined)
        "<revision>"
        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?

        Thanks,

        ~Josh
      • Deborah Pickett
        ... I m glad you re happy. :) (Though admitting to such hacks around here is akin to confessing that you don t wash your hands after using the bathroom.) ...
        Message 3 of 25 , Nov 5, 2008
        • 0 Attachment
          --- In dita-users@yahoogroups.com, "cybershark5886"
          <cybershark5886@...> wrote:
          > I figured out a way to "cheat" [...] I simply took advantage of the
          > <author> tags by using multiple <author> tags to place anything I need
          > on the cover page. [...] so that works for me.

          I'm glad you're happy. :) (Though admitting to such hacks around here
          is akin to confessing that you don't wash your hands after using the
          bathroom.)

          > 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?

          Absolutely. You just have to know where in the document structure you
          (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.
        • cybershark5886
          Thanks for the tips. ... Ha ha. Well I don t exactly professionally smile on this solution but it holds me over until I can provide a more permanent
          Message 4 of 25 , Nov 6, 2008
          • 0 Attachment
            Thanks for the tips.

            >I'm glad you're happy. :) (Though admitting to such hacks around here
            >is akin to confessing that you don't wash your hands after using the
            >bathroom.)

            Ha ha. Well I don't exactly professionally smile on this "solution"
            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
            questions. ;-)

            Sincerely,

            ~Josh
          • cybershark5886
            Hello again Deborah, ... .xsl ... directories. ... more ... the ... guide.) I actually recently stumbled upon a fairly helpful introductory tutorial for PDF2
            Message 5 of 25 , Dec 10, 2008
            • 0 Attachment

              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:

              <xsl:attribute-set name="titlealts">
                      <xsl:attribute name="background-color">#f0f0d0</xsl:attribute>
                      <xsl:attribute name="border-style">solid</xsl:attribute>
                      <xsl:attribute name="border-color">black</xsl:attribute>
                      <xsl:attribute name="border-width">thin</xsl:attribute>
                  </xsl:attribute-set>

                  <xsl:attribute-set name="navtitle">
                      <xsl:attribute name="font-family">Sans</xsl:attribute>
                  </xsl:attribute-set>

                  <xsl:attribute-set name="navtitle__label">
                      <xsl:attribute name="font-weight">bold</xsl:attribute>
                  </xsl:attribute-set>

                  <xsl:attribute-set name="searchtitle">
                  </xsl:attribute-set>

                  <xsl:attribute-set name="searchtitle__label">
                      <xsl:attribute name="font-weight">bold</xsl:attribute>
                  </xsl:attribute-set>

              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>
              <author> UAB CIS Department </author>
              <author> Josh Nielsen</author>
              <copyright>
              <copyryear year="2008"/>
              <copyrholder/>
              </copyright>

              Is it as simple as discovering the correct metadata and its tags or do you truely have to customize the code for that?

              Thanks for all your help so far.

              ~Josh Nielsen

               

            • Deborah Pickett
              Hi Josh, ... Those are the ones in cfg/common/vars/en_US.xml. They control the automatically-generated *content* which might vary from language to language
              Message 6 of 25 , Dec 10, 2008
              • 0 Attachment
                Hi Josh,

                > I noticed that the readme said there was up to 67 customizable
                > variables, but I'm unsure as to what those variables are

                Those are the ones in cfg/common/vars/en_US.xml. They control the
                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 in
                > mind when you said, "pdf2 already has templates for putting the title,
                > author, and a couple of other bits onto the front cover"?

                The templates I'm referring to are in fo/xsl/fo/front-matter_1.0.xsl
                (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,
                > 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>
                > <author> UAB CIS Department </author>
                > <author> Josh Nielsen</author>
                > <copyright>
                > <copyryear year="2008"/>
                > <copyrholder/>
                > </copyright>
                >
                > Is it as simple as discovering the correct metadata and its tags or do
                > you truely have to customize the code for that?

                If you look for strings in fo/xsl/fo/front-matter_1.0.xsl (even if you
                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.
              Your message has been successfully submitted and would be delivered to recipients shortly.