olink examples

[Tony]

Are there any examples of how to setup target.db creation per file
processed in the pom? My goal is to have it generate the individual
target.db files then use my olinkdb.xml when generating the output.

Thanks,
Tony.

[Mimil Mimil]

Hello,

I never played with olink things even with docbook without docbkx-tools plugin. Could you tell us what need to be done in plain docbook and I will try to help to acheive it with docbks-tolls plugin.

Regards,
Cédric,

[Tony]

For instance I have 4 documents that I want to be able to reference
from within any of the documents. The files may move around as more
documents are added and a site structure begins to develop. The ids
of the documents and the ids within the documents do not change but
may be added to. Using olink I can create a map of my site using the
target database document(olinkdb.xml) which resolve the ids of
documents to targets.db. The targets.db for the document will then
further resolve any ids within the document.

The targets.db for each document is generated using the option
"collect.xref.targets" and optionally "targets.filename" to override
the file name. The olinkdb.xml file is manually created. When
performing the transform from docbook to your chosen output format you
reference the olinkdb.xml using "target.database.document" for olink
resolution.

If in one document I declare:
<article id="art1">
<section id="sec1">
...

Then in another document I say:
<olink targetdoc="art1" targetptr="sec1">Article 1, section 1</olink>

The result in the final output for html would look something like:
<a href="article1.html#sec1">Article 1, section 1</a>

I hope I didn't miss anything, any help is greatly appreciated.

Thanks,
Tony.

[Mimil Mimil]

Hello,

If you are still interested I tried the olink stuff with docbkx plugin and I got it working: I tried HTML Olinking with two standalone documents and another one linking the two others.

1) The *.targets.db generation is working without any modification of the plugin. In the current state of the plugin we have a problem of "targets.filename" in case we want a single plugin execution for many docbook files (which simplifies the pom.xml) as the stylesheet will use the same filename for all docbook files.
So you must use one execution per docbook file in order to avoid this problem:

              <execution>
                <id>olinkdb</id>
                <goals>
                  <goal>generate-html</goal>
                </goals>
                <phase>generate-resources</phase>
                <configuration>
                  <includes>article.xml</includes>
                  <collectXrefTargets>yes</collectXrefTargets> <!-- you can use 'only' value if you don't want the html generation -->
                  <targetsFilename>${project.build.directory}/article.target.db</targetsFilename>
                  <olinkBaseUri>article.html</olinkBaseUri> <!-- this parameter can be avoided if this information is recorded in the olinkdb.xml -->
                </configuration>
              </execution>
              <execution>
                <id>olinkdb2</id>
                <goals>
                  <goal>generate-html</goal>
                </goals>
                <phase>generate-resources</phase>
                <configuration>
                  <includes>sample2.xml</includes>
                  <collectXrefTargets>yes</collectXrefTargets> <!-- you can use 'only' value if you don't want the html generation -->
                  <targetsFilename>${project.build.directory}/sample2.target.db</targetsFilename>
                  <olinkBaseUri>sample2.html</olinkBaseUri> <!-- this parameter can be avoided if this information is recorded in the olinkdb.xml -->
                </configuration>
              </execution>

2) Concerning the olinkdb.xml we have nothing to generate it in the current state of the plugin (we should create a new mojo for that) so I created one manually:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE targetset
       SYSTEM "./targetdatabase.dtd" [
<!ENTITY article SYSTEM "../../../target/article.target.db">
<!ENTITY sample2 SYSTEM "../../../target/sample2.target.db">
]>

<targetset>
  <targetsetinfo>test</targetsetinfo>

  <sitemap>
    <dir name="root">
      <document targetdoc="article1">
        <!--xi:include href="../../../target/article.target.db"
                    xmlns:xi="http://www.w3.org/2001/XInclude"/-->
         &article;
      </document>
      <document targetdoc="book1">
        <!--xi:include href="../../../target/sample2.target.db"
                    xmlns:xi="http://www.w3.org/2001/XInclude"/-->
         &sample2;
      </document>
    </dir>
  </sitemap>
</targetset>

XInclude is commented because I haven't been able to make it working.

3) The pom part for the last execution

             <execution>
                <id>gen</id>
                <goals>
                  <goal>generate-html</goal>
                </goals>
                <phase>pre-site</phase>
                <configuration>
                  <sourceDirectory>src/docbkx/olink</sourceDirectory>
                  <includes>olinkarticle.xml</includes>
                  <targetDatabaseDocument>${basedir}/src/docbkx/olink/olinkdb.xml</targetDatabaseDocument>
                  <xincludeSupported>true</xincludeSupported>
                </configuration>
              </execution>

4) mvn clean generate-resources pre-site

Regards,
Cedric,

[Nat]

Is it possible to generate multiple olink db files in one execution?

e.g. I have:

           <execution>

              <id>xrefdb-html-single</id>

              <goals>

                <goal>generate-html</goal>

              </goals>

              <configuration>

                <includes>Book1.xml</includes>

                <collectXrefTargets>only</collectXrefTargets>

                <targetsFilename>${project.build.directory}/../targetXref/docbkx/xref/html.db</targetsFilename>

              </configuration>

            </execution>

Is it possible to add Book2.xml to the includes and have a separate target db file be generated?

(Given the way the parameters are specified, I'm guessing the answer is no, but this would mean adding 3 more executions, one for each of HTML single & chunked + PDF, which doesn't seem very modular or maintainable.)

[David Cramer]

That's why I ended up creating this:

https://github.com/rackerlabs/olink-maven-plugin

It's focused on the way we use it (so it doesn't support all
olink-related functionality), but perhaps it could be a starting point
for your needs.

Regards,
David

> --
> You received this message because you are subscribed to the Google
> Groups "Docbkx Tools Users" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to docbkx-tools-us...@googlegroups.com.
> To post to this group, send email to docbkx-to...@googlegroups.com.
> Visit this group at http://groups.google.com/group/docbkx-tools-users.
> For more options, visit https://groups.google.com/groups/opt_out.

[Nat]

Thanks, I'll have a look. 

How do you specify which format you want the xrefs for? (Single HTML, chunked HTML, PDF etc)

Any plans to put this on a central maven repository?

Nat 

> an email to docbkx-tools-users+unsub...@googlegroups.com.

[Mimil]

Hello,

I think since http://code.google.com/p/docbkx-tools/issues/detail?id=106 it should work out of the box. You just have to specify a wildcard to select multiple input files.

Regards,

Cédric 

To unsubscribe from this group and stop receiving emails from it, send an email to docbkx-tools-us...@googlegroups.com.

[Nat]

Does it then product multiple db files? How do you specify their names?

[Mimil]

They should be auto nammed, just put *.xml in <includes>.

But you Will have to compile your docbkx version as it is not yet released. I Will soon make a release.

To unsubscribe from this group and stop receiving emails from it, send an email to docbkx-tools-us...@googlegroups.com.

[natk]

Can I put them in a different directory? (I guess if not, I could use the postProcess step to do this)

I currently have a different target directory for my xrefs (so that they don't get deleted when I do a clean for the actual docbook build profile).

Any idea of timing for the release? :)

Nat 

--
You received this message because you are subscribed to a topic in the Google Groups "Docbkx Tools Users" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/docbkx-tools-users/JS8MpaArJZA/unsubscribe.
To unsubscribe from this group and all its topics, send an email to docbkx-tools-us...@googlegroups.com.

[Mimil Mimil]

Hello,

I think you can override <targetDirectory>target/site/</targetDirectory> to point to your directory.

Regards,

Cedric,

[Mimil Mimil]

Concerning the release, I have to wait for oss.sonatype.org hosting because I have some troubles with the way we were publishing in the past. It is a mater of a few days, everything is ready.

Cedric,

[Jason Pickering]

Hi there.

I managed to follow this example, and get the olink db generated. We would like to have links between multiple individual articles, which are assembled into a single book.

The XML source looks like this

<olink targetdoc="dhis2_user_man_data_elements" targetptr="dataElement">corresponding sections</olink>

and when the chunked HTML is generated, we get only get this.

<span class="olink">corresponding sections</span>

I was expecting it to include a link to the olinked section, but seem to be missing something.

Any help would be appreciated.

Best regards, Jason

[Mimil Mimil]

Hello,

I never used olink, I guess you should better ask to the docbook mailing list and come back here if I need to make/configure docbkx to get it working.

Regards,

Cedric,

[Mark Craig]

Hi all,

The fix for issue 106 seems like a good thing.

Resolving the Olinks is quite a mess, though, and I don’t think it’s the fault of docbkx-tools.

In addition to collecting targets, you must also provide a <targetset> wrapper for the files of collected target files.

I don’t see a way of generating the wrapper.

It’s worth reading Bob Stayton’s explanation at http://www.sagehill.net/docbookxsl/Olinking.html for background.

Your target set wrapper, which Bob Stayton’s book refers to as a target database document, is a sort of site map for your documentation set, including the collected target files in the location of each document. As Bob’s writing shows, you do this with entities for example, so you need to know where the target.db files are going to end up in order to finish your target set wrapper.

This apparently allows the stylesheets to resolve links when building the output. You point to this wrapper document with <targetDatabaseDocument> in the docbkx-tools configuration.

So for example if you are making chunked HTML from a document where the top-level file is book.xml, you might have something like the following.

  <plugin>

    <groupId>com.agilejava.docbkx</groupId>

    <artifactId>docbkx-maven-plugin</artifactId>

    <version>2.0.15</version>

    <executions>

      <execution>

        <id>chunked-html</id>

        <phase>pre-site</phase>

        <goals>

          <goal>generate-html</goal>

        </goals>

        <configuration>

          <includes>book.xml</includes>

          <xincludeSupported>true</xincludeSupported>

          <chunkedOutput>true</chunkedOutput>

          <chunkBaseDir>${project.build.directory}/docbkx/html/index/</chunkBaseDir>

          <!-- Generate target files -->

          <collectXrefTargets>yes</collectXrefTargets>

          <!-- Point to the wrapper document that references target files. -->

          <targetDatabaseDocument>${basedir}/src/resources/olink.xml</targetDatabaseDocument>

        </configuration>

      </execution>

    </executions>

  </plugin>

I have a small test project at https://github.com/markcraig/DOCS-81, but you might do better trying to follow Bob’s instructions.

By the way, it seems like things have changed since 2.0.14.

At least the stuff I wrote to handle olinks works with 2.0.14 and does not work with 2.0.15.

Regards,

Mark

[Jason Pickering]

Hi Mark,

Thanks for your follow up. I am able to generate the DB file just fine, more or less following your example,  but am stuck at actually being able to use the DB file for anything. Is this perhaps something which would require a custom XSL? It seems the information in the DB file is correct, but it is not reflected in the HTML or PDF output. 

Regards,
Jason

[Mark Craig]

Hi Jason,

The target database document is the one that you pass to docbkx-tools in your execution by using <targetDatabaseDocument>. No additional customization required that I know of.

      <plugin>

        <groupId>com.agilejava.docbkx</groupId>

        <artifactId>docbkx-maven-plugin</artifactId>

        <version>2.0.15</version>

        <executions>

          <execution>

            <id>chunked-html</id>

            <phase>pre-site</phase>

            <goals>

              <goal>generate-html</goal>

            </goals>

            <configuration>

              <includes>book.xml</includes>

              <chunkedOutput>true</chunkedOutput>

              <chunkBaseDir>${project.build.directory}/docbkx/html/index/</chunkBaseDir>

              <collectXrefTargets>yes</collectXrefTargets>

              <targetDatabaseDocument>${basedir}/src/resources/olink.xml</targetDatabaseDocument>

            </configuration>

          </execution>

        </executions>

        <configuration>

          <xincludeSupported>true</xincludeSupported>

        </configuration>

      </plugin>

The target database document wraps the generated file(s) of collected targets.

In my simple example based on the docbkx quick start archetype, there’s only one document (only one book), so only one collected targets file.

$ more src/resources/olink.xml 

<?xml version='1.0' encoding='utf-8'?>

<!DOCTYPE targetset [

...

<!ENTITY book SYSTEM '../../target/docbkx/html/book.html.target.db'>

]>

<targetset>

 <targetsetinfo>Target DB for chunked HTML</targetsetinfo>

 <sitemap>

  <dir name='html'>

   <dir name='index'>

    <document targetdoc='book'

              baseuri='../index/'>

     &book;

    </document>

   </dir>

  </dir>

 </sitemap>

</targetset>

The collected targets file is generated when you tell docbkx-tools to collect xref targets, <collectXrefTargets>yes</collectXrefTargets>. Looks like the filename depends on the document name, e.g. book, and the format, e.g. html.

$ more target/docbkx/html/book.html.target.db 

<div element="book" href="book.html" number=""><ttl>This is a book</ttl><xreftext>This is a book</xreftext><div element="chapter" href="ch01.html" number="1"><ttl>This is a chapter</ttl><xreftext>Chapter 1, <i>This is a chapter</i></xreftext><div element="section" href="ch01.html#d0e18" number=""><ttl>This is a section</ttl><xreftext>the section called “This is a section”</xreftext></div><div element="section" href="ch01s02.html" number=""><ttl>This is an included section</ttl><xreftext>the section called “This is an included section”</xreftext></div></div><div element="chapter" href="ch02.html" number="2" targetptr="included-chapter"><ttl>A Chapter To Link To</ttl><xreftext>Chapter 2, <i>A Chapter To Link To</i></xreftext></div></div>

The target database DTD by the way is available at http://docbook.sourceforge.net/release/xsl/current/common/targetdatabase.dtd.

I have a couple of olinks that point to the location with targetptr=“included-chapter”, and they seem to get resolved okay in the HTML.

Hope that helps clarify how the pieces fit together.

Regards,

Mark

[natk]

I just tried this with version 2.0.15. I do not get all of the target.db files generated - just the first one. The transformer is executed the correct number of times, but something is going wrong with the value of the targetsFilename property (I think). So, for example if I have two files in the source directory, this is a truncated form of the output:

[DEBUG] SourceFile: /dev/project/test/src/main/doc/docbkx/xml/test2.xml

[DEBUG] TargetDirectory: /dev/project/test/targetXref/docbkx/html

[INFO] Processing input file: test2.xml

Writing /dev/project/test/targetXref/docbkx/html/test2.html.target.db for chapter(test2)

[INFO] See /dev/project/test/targetXref/docbkx/html for generated secondary file(s)

[DEBUG] SourceFile: /dev/project/test/src/main/doc/docbkx/xml/test1.xml

[DEBUG] TargetDirectory: /dev/project/test/targetXref/docbkx/html

[INFO] Processing input file: test1.xml

Writing /dev/project/test/targetXref/docbkx/html/test2.html.target.db for chapter(test1)

[INFO] See /dev/project/test/targetXref/docbkx/html for generated secondary file(s)

[INFO] ------------------------------------------------------------------------

[INFO] BUILD SUCCESS

[INFO] ------------------------------------------------------------------------

[INFO] Total time: 9.584s

[INFO] Finished at: Wed May 28 13:20:13 EST 2014

[INFO] Final Memory: 19M/370M

You can see that the target.db file that is written is the same one both times, but the input files are different.

Nat 

--
You received this message because you are subscribed to a topic in the Google Groups "Docbkx Tools Users" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/docbkx-tools-users/JS8MpaArJZA/unsubscribe.
To unsubscribe from this group and all its topics, send an email to docbkx-tools-us...@googlegroups.com.

[Mimil Owns]

Hi,

sorry for the delay in the reply (I was in holidays), I will have a look but it sounds like a bug :(

I stay you informed.

Regards,

Cedric,

For more options, visit https://groups.google.com/d/optout.

[natk]

Ok, thanks.

Nat 

For more options, visit https://groups.google.com/d/optout.