Images, file-naming conventions, and cross-referencing in Docbook

RE: Images, file-naming conventions, and cross-referencing in Docbook

1. Can you provide me some information about the final output of your
html transformation, e.g. by posting the html code around the generated
img tag? That might help. Are you sure the html file and the image are
in the same directory? 

2. I did the same using processing instructions. Insert the following
text as a child element of your chunks (e.g., section): <?dbhtml
filename="myfilename.html">
There's also the possibility to use the element's id as filename. Set
the param <xsl:param name="use.id.as.filename" select="1"/> and the
element's id="myfilename"

Ludger

________________________________

From: Christine Doyle [mailto:christine.doyle <at> gmail.com] 
Sent: Freitag, 17. Februar 2006 12:01
To: docbook-apps <at> lists.oasis-open.org
Subject: [docbook-apps] Images, file-naming conventions, and
cross-referencing in Docbook

Hi,
I'm new to Docbook and am investigating converting our RoboHelp files to
Docbook format to enable TOC generation for Eclipse plugin help. If we
move to Docbook we can automate our help into the build process. 

I'm now using the Oxygen eclipse plugin on Windows to author my
documents in Docbook 4.4 format. It provides very good validation and
content assistance and a Docbook framework. I tried running the
eclipse.xsl transform on one of my sample books using the Oxygen plugin
in Eclipse, but found that although the transform omits a successful
message, no output was produced. I have now succeeded in running the
eclipse.xsl transform using the command line for the saxon xslt
processor:

java  -jar dir/saxon.jar   [options]   source-document   stylesheet   [
params...]

For example:
java -jar c:/eclipse/plugins/com.oxygenxml.editor_7.0.0/lib/saxon.jar
concepts/concepts.xml
c:/eclipse/plugins/com.oxygenxml.editor_7.0.0/frame
works/docbook/xsl/eclipse/eclipse.xsl base.dir="html/concepts/"

I have two main questions:

1. My images are not displaying. Here is an example of one that is not
displaying:

 <figure><title>blah...</title>
    <mediaobject>
        <imageobject role="html">
          <imagedata fileref="blah_2b.png" format="PNG"></imagedata> 
        </imageobject>
    </mediaobject>
  </figure>

Can anyone suggest why this image would not display? It is in the same
folder as the XML file that references it. Note that I am working from
within an Eclipse project directory. Could this be an issue? Or is there
a problem with the syntax? Do I need to declare blah_2b.png as an entity
somewhere or place it in a different location? 

2. When I run eclipse.xsl, the Docbook HTML files that are produced have
automatically generated file names, using a numeric convention, for
example: 

Writing pr01s02.html for section
Writing pr01s03.html for section
Writing pr01s04.html for section
Writing pr01s05.html for section
Writing pr01s06.html for section
Writing pr01.html for preface
Writing ch01s02.html for sect1
Writing ch01.html for chapter
Writing ch02s02.html for sect1
Writing ch02s03.html for sect1
Writing ch02.html for chapter
Writing index.html for book
Writing toc.xml
Writing plugin.xml

These file names do not match my source XML file names, which are
mnemonic, based on the content. This means that all of my original
Robohelp cross-references are broken. How can I customize the file
naming generation process? Also, what is the best way to create
cross-references between files? There seem to be several Docbook
elements for cross-referencing, and as I'm new to Docbook, it's quite
confusing. I'm using Docbook 4.4. 

<link> seems to be the easiest way to do internal references but what
about between chapters? Should I provide an id for every section and
link to sections using <ulink>? 

I'd appreciate any advice.

Regards

Christine Doyle

Re: Q&A sets within an article: How to insert QandASet title to the article TOC

profile-docbook Snapshot Problems

Re: Images, file-naming conventions, and cross-referencing in Docbook

RE: Images, file-naming conventions, and cross-referencing in Docbook

Re: profile-docbook Snapshot Problems

Ray Miller wrote:

> Docbook-rng-5.0b3, xsl-snapshot (current), saxon-6.5.3, oxygen-7.0.0
> (eclipse 3.1 plugin)
> 
> Following errors generated when utilizing profile-docbook.xsl from snapshots
> (current and previous).

I don't think that profiling was working with DocBook V5 documents 
before. You can convert DocBook V5 to intermediate format using 
stylesheet db5strip.xsl and then process this intermediate format by 
profile-docbook.xsl. Or alternative use 2 pass profiling -- it also 
should work on DocBook V5 documents.

Supporting profiling and namespace stripping at the same time would add 
complexity to stylesheet. Please file it as RFE on SourceForge. If it 
wouldn't be so complex, I can try to mix these two features together.

				Jirka

--

-- 
------------------------------------------------------------------
   Jirka Kosek     e-mail: jirka <at> kosek.cz     http://www.kosek.cz
------------------------------------------------------------------
   Profesionální školení a poradenství v oblasti technologií XML.
      Podívejte se na náš nově spuštěný web http://DocBook.cz
        Podrobný přehled školení http://xmlguru.cz/skoleni/
------------------------------------------------------------------
                    Nejbližší termíny školení:
      ** XSLT 13.-16.3.2006 ** XML schémata 24.-26.4.2006 **
        ** DocBook 15.-17.5.2006 ** XSL-FO 12.-13.6.2006 **
------------------------------------------------------------------

Re: Q&A sets within an article: How to insert QandASet title to the article TOC

Ah, the solution I posted was for FO output.

HTML tables of contents call a template named 'subtoc' to generate a line.
Take a look at the template with match="sect1" mode="toc" in
html/autotoc.xsl, and make one like it for qandaset.

Bob Stayton
Sagehill Enterprises
DocBook Consulting
bobs <at> sagehill.net

----- Original Message ----- 
From: "Zbyszek Cybulski" <z.cybulski <at> gmail.com>
To: "Bob Stayton" <bobs <at> sagehill.net>
Cc: "DocBook Apps" <docbook-apps <at> lists.oasis-open.org>
Sent: Friday, February 17, 2006 4:36 AM
Subject: Re: [docbook-apps] Q&A sets within an article: How to insert
QandASet title to the article TOC

Seems to be much better but the TOC entries are listed inline, not one
entry
per line. This is because the HTML source code seems to be incomplete.

Here is the sample:

<div class="toc">
            <p><b>Table of Contents</b></p>
            <dl>
              <span class="qandaset"><a
href="#general_security">General and security issues</a></span>
              <span class="qandaset"><a
href="#nda_report_troubleshooting">Report troubleshooting</a></span>
              <span class="qandaset"><a href="#d0e712">Special
reports</a></span>
            </dl>
</div>

I can hack the appearance of this code with CSS, but a correct code, that
is, at least <dl><dt> per each toc entry, as it is for the qandaset toc,
would be welcome.

-Zbyszek

On 2/17/06, Bob Stayton <bobs <at> sagehill.net> wrote:
>
> Oops, incomplete solution.  You also need to add this:
>
> <xsl:template match="qandaset" mode="toc">
>   <xsl:call-template name="toc.line"/>
> </xsl:template>
>
> This mode is what processes an element for a TOC.  I thought there was
one
> for qandaset, but there wasn't.
>
> If you were also wanting to list questions under the set title in the
TOC,
> you would expand this template to select the questions and process them
in
> mode="toc" too.
>
> Bob Stayton
> Sagehill Enterprises
> DocBook Consulting
> bobs <at> sagehill.net
>
>
> ----- Original Message -----
> From: "Zbyszek Cybulski" <z.cybulski <at> gmail.com>
> To: "Bob Stayton" <bobs <at> sagehill.net>
> Cc: "DocBook Apps" <docbook-apps <at> lists.oasis-open.org>
> Sent: Wednesday, February 15, 2006 11:27 AM
> Subject: Re: [docbook-apps] Q&A sets within an article: How to insert
> QandASet title to the article TOC
>
>
> Hi,
>
> I have tried the solution you suggested, Bob, and found it not
> satisfactory.
> The problem is that QandASet titles are listed inline along with the
> questions within each qandaset. QandASet titles were not listed one per
> line
> in the article TOC. I can send a sample off the list, if necessary.
>
> -Zbyszek
>
> On 1/26/06, Bob Stayton <bobs <at> sagehill.net> wrote:
> >
> > Hi,
> > You can customize the template named 'component.toc' from
> > html/autotoc.xsl.  It calls a template named 'make.toc' with a
parameter
> > named 'nodes', which selects what elements to include in the toc.  If
> you
> > add qandaset to the selection for 'nodes', you should get them in your
> > article toc.
> >
> > Bob Stayton
> > Sagehill Enterprises
> > DocBook Consulting
> > bobs <at> sagehill.net
> >
> >
> >
> > ----- Original Message -----
> > *From:* Zbyszek Cybulski <z.cybulski <at> gmail.com>
> > *To:* DocBook Apps <docbook-apps <at> lists.oasis-open.org>
> > *Sent:* Wednesday, January 25, 2006 3:41 AM
> > *Subject:* [docbook-apps] Q&A sets within an article: How to insert
> > QandASet title to the article TOC
> >
> > Hi list,
> >
> > my problem is as in the message subject.
> >
> > I have an article, like below:
> >
> > <article class="faq">
> >     <articleinfo>
> >         <title>FAQ</title>
> >         <subtitle>something</subtitle>
> >         <releaseinfo>Release number</releaseinfo>
> >     </articleinfo>
> >     <xi:include href="qa1.xml"/>
> >     <xi:include href="qa2.xml"/>
> >     <xi:include href=" qa3.xml"/>
> > </article>
> >
> > Each XIncluded file is a QandASet, like the following:
> >
> > <qandaset id="general_security">
> >     <title>Security issues</title>
> >     <qandaentry id="forgot_pwd">
> >         <question>
> >             <para>I forgot my password. How can I retrieve it?</para>
> >         </question>
> >         <answer><para>The answer is...</para>
> >         </answer>
> >     </qandaentry>
> > </qandaset>
> >
> >
> > How do I define my customization layer to have the HTML output similar
> to
> > the following?
> >
> > FAQ
> > something
> > Release number
> > -------------------------------
> > Table of Contents
> >
> > Security issues
> > QASet2 title
> > QASet3 title
> >
> > --------------------------------
> > Security issues
> > 1. I forgot my password. How can I retrieve it?
> > 2. Q2
> >
> >
> > QASet2 title
> > 1. Q1
> > 2. Q2
> >
> > QASet3 title
> > 1. Q1
> > 2. Q2
> >
> >
> > I have set <xsl:param name="generate.toc">article toc,title qandaset
> > toc</xsl:param>, but it does not work. That is, questions are listed
> within
> > each Q&ASet but I do not see article's ToC.
> >
> > I can accept the following output or any combination of it that will
> > provide the article ToC:
> >
> > FAQ
> > something
> > Release number
> > -------------------------------
> > Table of Contents
> >
> > Security issues
> >     1. I forgot my password. How can I retrieve it?
> >     2. Q2
> > QASet2 title
> >     1. Q1
> >     2. Q2
> > QASet3 title
> >     1. Q1
> >     2. Q2
> > --------------------------------
> > Security issues
> > 1. I forgot my password. How can I retrieve it?
> > 2. Q2
> >
> >
> > QASet2 title
> > 1. Q1
> > 2. Q2
> >
> > QASet3 title
> > 1. Q1
> > 2. Q2
> >
> >
> > Thanks in advance,
> >
> > -Zbyszek
> >
> >
>
>
>

Re: profile-docbook Snapshot Problems

Hi Ray,
It works for me with that setup (using 2005-02-16_snapshot), except I'm
using DocBook 4.* not v5.  Does it work when you use profile-docbook.xsl
directly instead of from your customization?

Is this HTML or FO?

Bob Stayton
Sagehill Enterprises
DocBook Consulting
bobs <at> sagehill.net

----- Original Message ----- 
From: "Ray Miller" <millerr <at> centechgroup.com>
To: "'Docbook-Apps'" <docbook-apps <at> lists.oasis-open.org>
Sent: Friday, February 17, 2006 6:32 AM
Subject: [docbook-apps] profile-docbook Snapshot Problems

> Docbook-rng-5.0b3, xsl-snapshot (current), saxon-6.5.3, oxygen-7.0.0
> (eclipse 3.1 plugin)
>
>
>
> Following errors generated when utilizing profile-docbook.xsl from
snapshots
> (current and previous).
>
> Profile-docbook is called from a customization.
>
> Problem does not occur with snapshot versions of docbook.xsl or
> profile-docbook-1.69.1
>
>
>
> Severity Description        Resource          In Folder
Location
> Creation Time    Id
>
> 1          No template matches abbrev in emphasis.
> profile-docbook.xsl         foo/xsl/html                   February 17,
2006
> 9:06:54 AM       34272
>
> 1          No template matches attribution in blockquote.
> profile-docbook.xsl         foo/xsl/html                   February 17,
2006
> 9:06:54 AM       34283
>
> 1          No template matches author in info.
profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34238
>
> 1          No template matches authorinitials in revision.
> profile-docbook.xsl         foo/xsl/html                   February 17,
2006
> 9:06:54 AM       34245
>
> 1          No template matches blockquote in dedication.
> profile-docbook.xsl         foo/xsl/html                   February 17,
2006
> 9:06:54 AM       34280
>
> 1          No template matches blockquote in para. profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34282
>
> 1          No template matches book.        profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM
34234
>
> 1          No template matches chapter in part.      profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34287
>
> 1          No template matches colspec in tgroup.  profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34251
>
> 1          No template matches colspec in tgroup.  profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34252
>
> 1          No template matches date in revision.      profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34244
>
> 1          No template matches dedication in book. profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34247
>
> 1          No template matches dedication in book. profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34278
>
> 1          No template matches emphasis in entry. profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34265
>
> 1          No template matches emphasis in entry. profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34268
>
> 1          No template matches emphasis in entry. profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34271
>
> 1          No template matches emphasis in entry. profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34275
>
> 1          No template matches entry in row.          profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34256
>
> 1          No template matches entry in row.          profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34257
>
> 1          No template matches entry in row.          profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34262
>
> 1          No template matches entry in row.          profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34264
>
> 1          No template matches entry in row.          profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34267
>
> 1          No template matches entry in row.          profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34270
>
> 1          No template matches entry in row.          profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34274
>
> 1          No template matches entry in row.          profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34277
>
> 1          No template matches imagedata in imageobject.
> profile-docbook.xsl         foo/xsl/html                   February 17,
2006
> 9:06:54 AM       34260
>
> 1          No template matches imageobject in mediaobject.
> profile-docbook.xsl         foo/xsl/html                   February 17,
2006
> 9:06:54 AM           34259
>
> 1          No template matches info in book.
profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34237
>
> 1          No template matches informaltable in dedication.
> profile-docbook.xsl         foo/xsl/html                   February 17,
2006
> 9:06:54 AM       34249
>
> 1          No template matches mediaobject in entry.
> profile-docbook.xsl         foo/xsl/html                   February 17,
2006
> 9:06:54 AM       34258
>
> 1          No template matches orgdiv in author.     profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34240
>
> 1          No template matches orgname in author. profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34239
>
> 1          No template matches para in blockquote. profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34281
>
> 1          No template matches para in blockquote. profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34284
>
> 1          No template matches para in chapter.      profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34289
>
> 1          No template matches part in book.          profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34285
>
> 1          No template matches revhistory in info.    profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34241
>
> 1          No template matches revision in revhistory.
> profile-docbook.xsl         foo/xsl/html                   February 17,
2006
> 9:06:54 AM       34242
>
> 1          No template matches revnumber in revision.
> profile-docbook.xsl         foo/xsl/html                   February 17,
2006
> 9:06:54 AM       34243
>
> 1          No template matches revremark in revision.
> profile-docbook.xsl         foo/xsl/html                   February 17,
2006
> 9:06:54 AM       34246
>
> 1          No template matches row in tbody.          profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34255
>
> 1          No template matches row in tbody.          profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34261
>
> 1          No template matches row in tbody.          profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34263
>
> 1          No template matches row in tbody.          profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34266
>
> 1          No template matches row in tbody.          profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34269
>
> 1          No template matches row in tbody.          profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34273
>
> 1          No template matches row in tbody.          profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34276
>
> 1          No template matches spanspec in tgroup.
> profile-docbook.xsl         foo/xsl/html                   February 17,
2006
> 9:06:54 AM       34253
>
> 1          No template matches subtitle in book.     profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34236
>
> 1          No template matches tbody in tgroup.      profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34254
>
> 1          No template matches tgroup in informaltable.
> profile-docbook.xsl         foo/xsl/html                   February 17,
2006
> 9:06:54 AM       34250
>
> 1          No template matches title in book.
profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34235
>
> 1          No template matches title in chapter.
profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34288
>
> 1          No template matches title in dedication.   profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34248
>
> 1          No template matches title in dedication.   profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34279
>
> 1          No template matches title in part.
profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM       34286
>
> 1          Processing stripped document.   profile-docbook.xsl
> foo/xsl/html                   February 17, 2006 9:06:54 AM
34232
>
> 1          Request for title of element with no title: book
> profile-docbook.xsl         foo/xsl/html                   February 17,
2006
> 9:06:54 AM       34233
>
> 1          Stripping NS from DocBook 5/NG document.
> profile-docbook.xsl         foo/xsl/html                   February 17,
2006
> 9:06:54 AM       34231
>
>

Re: Centering a table on a page with FO

As you discovered, this is much harder than it should be.  Yes, in XSL-FO
1.0, centering a table requires you to put the table in another layout
table that centers it.  However, you don't have to do this in your XML
files.  Rather, the stylesheet could respond to the align attribute and
place the table in another fo:table to center it.

I started to add that at one point, but found that the different FO
processors behaved differently, and didn't get around to sorting out the
conditional code required to make it work reliably.  If you are using
Antenna House or XEP, I believe each of their FAQs has an entry on how to
center a table.

Oddly enough, the original Cals table spec did not include an align
attribute on the table element, so the stylesheets didn't support it.  It
was introduced into DocBook 4.3 when the HTML table model was added to the
DTD.

Bob Stayton
Sagehill Enterprises
DocBook Consulting
bobs <at> sagehill.net

----- Original Message ----- 
From: "Mike Broschinsky" <mbroschi <at> utah.gov>
To: <docbook-apps <at> lists.oasis-open.org>
Sent: Thursday, February 16, 2006 12:18 PM
Subject: [docbook-apps] Centering a table on a page with FO

I have a number of tables in a manual that our office produces. You can see
the HTML output from the DocBook source at:

http://www.rules.utah.gov/manual-rw/index.html

(I'm actually quite proud of this, having talked my boss into letting me
use DocBook, and yet having few XML/XSLT/HTML/CSS skills.)

You can see that the tables on the various HTML pages are horizontally
centered in the viewport. See, for example:

http://www.rules.utah.gov/manual-rw/ch01s01.html

I want to be able to do the same for the print output, i.e. center a table
horizontally on the page, if possible.

So, I'm pretty sure this question has been asked before, but because I am
new to DocBook and XSLT, the answers that I found subsequent to a Google
search seemed pretty complicated and involved using another table as a
wrapper around the table I want to center.

Extraneous elements bother me more than a table aligned on the left margin.
Is there a way to center a table on a page using the stock DocBook
stylesheets and a customization layer, but not adding extra columns to a
table or wrapping the table in another table? If not, I'm happy to live
with the left-aligned table until the happy day when I *can* center it.

Thanks!

Mike

----------------------------

Mike Broschinsky
Administrative Code Editor
Utah State Division of Administrative Rules
801-538-3003
mbroschi <at> utah.gov

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-apps-unsubscribe <at> lists.oasis-open.org
For additional commands, e-mail: docbook-apps-help <at> lists.oasis-open.org