Newbie trying to set up a splitted document

[chrisTS]

Hi all,

First of all: I am a newbie to docbook and to oxygen so please be patient with me if I am asking stupid questions.

What I am trying to do:
I want to create a book-type document with docbook 5 and I want each chapter to be in a separate file.
I want to be able to use the Oxygen Author mode which means that each file must be "full featured" and not just an included fragment.
I need a set of variables (entities) which can be used and replaced in any of the files.
I must be able to create links between the chapter files
Output formats are PDF and Webhelp

I managed to split up the documents and to handle the variables but I can not figure out how to get the links working.

The following setup is working except for the links:
The variables file variables.ent:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>



<!ENTITY programname "The program">          

<!ENTITY programversion "4.1">       

The main document file:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE chapter [

<!ENTITY % variables SYSTEM "variables.ent">

%variables;

]>



<?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbookxi.rng" 

    schematypens="http://relaxng.org/ns/structure/1.0"?>

    

<book xmlns="http://docbook.org/ns/docbook" 

        xmlns:xi="http://www.w3.org/2001/XInclude"

        xmlns:xlink="http://www.w3.org/1999/xlink" 

        version="5.0" xml:lang="en" >

    <info>

        <title>&programname; Manual</title>

    </info>

    

    <part>        

        <xi:include  href="GettingStarted.xml" 

          xmlns:xi="http://www.w3.org/2001/XInclude"/>

    </part>    

</book>

The chapter file GettingStarted.xml:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE chapter [

<!ENTITY % variables SYSTEM "variables.ent">

%variables;

]>



<chapter xmlns="http://docbook.org/ns/docbook" 

           version="5.0" xml:id="chapterGettingStarted">

	<title>

          Getting Started

        </title>

	<para> 

	  &programname; must have been installed properly.

	  Please refer to 

	  <olink targetdoc="Installation" 

	    targetptr="installation">Installation</olink>

	  for more information on the installation procedure. 

	</para>

</chapter>

The chapter file Installation.xml:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE chapter [

<!ENTITY % variables SYSTEM "variables.ent">

%variables;

]>

		

<chapter xmlns="http://docbook.org/ns/docbook" 

    version="5.0" xml:id="installation">



	<title>

	  Installation

	</title>

	<section>

		<title>

		  Program Setup Procedure

		</title>

		<para>

		  &programname;	comes with an installation program. 

		</para>

	</section>

</chapter>		

As I said everything is working fine except the olink thing in GettingStarted.xml. I have been searching the web and trying for hours but I just can not figure out how to get it working. The recommended way is to use a target database like the following:

Target DataBase olinkdb.xml with entities:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE targetset SYSTEM 

  "file:frameworks/docbook/xsl/common/targetdatabase.dtd" [

<!ENTITY chapterInstallation SYSTEM "Installation.xml"> 

<!ENTITY chapterGettingStarted SYSTEM "GettingStarted.xml"> 

]>



<targetset> 

    <targetsetinfo> 

        Description of this target database document,

        which is for the olinks.

    </targetsetinfo>

    

    <sitemap> 

      <dir name="manual"> 

        <document targetdoc="GettingStarted"> 

          &chapterGettingStarted;

        </document>

        <document targetdoc="Installation"> 

          &chapterInstallation;

        </document>

      </dir>

    </sitemap>

</targetset>

However this does not work as the linked document must not have a DOCTYPE in this case (but I need the DOCTYPE to enable my variables file).

So I tried to use XIncludes instead:
Target DataBase olinkdb.xml with XIncludes:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE targetset SYSTEM 

  "file:frameworks/docbook/xsl/common/targetdatabase.dtd" [

<!ENTITY chapterInstallation SYSTEM "Installation.xml"> 

]>



<targetset> 

    <targetsetinfo> 

        Description of this target database document,

        which is for the olinks.

    </targetsetinfo>

    

    <sitemap> 

      <dir name="manual"> 

        <document targetdoc="GettingStarted"> 

          <xi:include href="GettingStarted.xml"  

            xmlns:xi="http://www.w3.org/2001/XInclude"/>                

        </document>

        <document targetdoc="Installation"> 

          <xi:include href="Installation.xml"  

            xmlns:xi="http://www.w3.org/2001/XInclude"/>                

        </document>

      </dir>

    </sitemap>

</targetset>

Then I get an error that xi:include must be declared.

If I try to declare it as follows:

Code: Select all

<targetset xmlns:xi="http://www.w3.org/2001/XInclude"

    xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"

    xml:lang="en"> 

Then I get an error that xmlns:xi must be declared.

Can anyone out there help me with this before I am going crazy?

[sorin_ristache]

Hi,

Olink links are maintained in a separate document called target database as you already discovered but this type of links is usually reserved for inter-document linking, that is links between distinct documents which are transformed to PDF, WebHelp, etc. in distinct transformations, for example two distinct book documents. For intra-document linking as in your case I suggest the xref and link elements which work across XInclude boundaries, which means GettingStarted.xml can link directly to Installation.xml using an xref element while both GettingStarted.xml and Installation.xml are included in the master document (the one with the book root element) using XInclude. Please take a look at the following files. The action Validate (Ctrl+Shift+V) applied to main.xml reports no validation errors.

• main.xml

  Code: Select all

  
  <?xml version="1.0" encoding="UTF-8"?>
  
  <?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbookxi.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
  
  <!DOCTYPE book [
  
      <!ENTITY % variables SYSTEM "variables.ent">
  
      %variables;
  
  ]>
  
  <book xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
  
      xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
  
      <info>
  
          <title>&programname; Manual</title>
  
      </info>
  
      <part>
  
          <info>
  
              <title>Part 1</title>
  
          </info>
  
          <xi:include href="GettingStarted.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
  
          <xi:include href="Installation.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
  
      </part>
  
  </book>
  

• GettingStarted.xml

  Code: Select all

  
  <?xml version="1.0" encoding="UTF-8"?>
  
  <!DOCTYPE chapter [
  
  <!ENTITY % variables SYSTEM "variables.ent">
  
  %variables;
  
  ]>
  
  <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="chapterGettingStarted">
  
      <title>Getting Started</title>
  
      <para>&programname; must have been installed properly. Please refer to 
  
          <xref linkend="installation"/> for more information on the installation procedure.
  
      </para>
  
  </chapter>
  

• Installation.xml

  Code: Select all

  
  <?xml version="1.0" encoding="UTF-8"?>
  
  <!DOCTYPE chapter [
  
  <!ENTITY % variables SYSTEM "variables.ent">
  
  %variables;
  
  ]>
  
  <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="installation">
  
      <title>Installation</title>
  
      <section>
  
          <title>Program Setup Procedure</title>
  
          <para> &programname; comes with an installation program. </para>
  
      </section>
  
  </chapter>
  

Regards,
Sorin

[chrisTS]

Thanks for your quick answer Sorin

I have missed the information that olinks and the target database is only required if I want to link across multiple generated documents. I understood that I need them to link between the individual generated parts of a single document.
So this really helps a lot.

I tried your solution and the document is generated correctly without errors.

However I get the following error in Installation.xml when I run the validation:
Jing error: element "chapter" not allowed yet; expected element "info", "subtitle", "title" or "titleabbrev"
I wonder why the generation works if the validation reports an error?
I also wonder why this error occurs. In my oppinion there is nothing wrong with the chapter there ...

Additionally the editor underlines the link in GettingStarted.xml in red and the mouse over tooltip says:
Jing error: "installation" without matching id
Although the link is functional in the generated pdf document.
Actually I tried this version before and did not even try to execute the conversion because of this error.
I suppose that the error occurs as the link can not be resolved inside GettingStarted.xml. Is there any chance to fix this?

[sorin_ristache]

Hi,

However I get the following error in Installation.xml when I run the validation:
Jing error: element "chapter" not allowed yet; expected element "info", "subtitle", "title" or "titleabbrev"
I wonder why the generation works if the validation reports an error?
I also wonder why this error occurs. In my oppinion there is nothing wrong with the chapter there ...

I get no validation error in the Installation.xml file that I posted above which is a DocBook 5 chapter file. Did you get the validation error with the action Validate (Ctrl+Shift+V) that is available on the toolbar? What Oxygen version and build number do you use (available in the Help -> About dialog box)?

Additionally the editor underlines the link in GettingStarted.xml in red and the mouse over tooltip says:
Jing error: "installation" without matching id
Although the link is functional in the generated pdf document.
Actually I tried this version before and did not even try to execute the conversion because of this error.
I suppose that the error occurs as the link can not be resolved inside GettingStarted.xml. Is there any chance to fix this?

You can fix this by creating a validation scenario with main.xml as the main file of the scenario and associate the scenario with Installation.xml, with GettingStarted.xml and with main.xml. After you set this association the validation action applies the validation scenario, that is the validation starts with the main file from the scenario (main.xml).


Regards,
Sorin

[chrisTS]

Hi Sorin,

Everything is working as desired now

I created a validation scenario as you proposed which removed the "missing link" error.

Removing <part> </part> around the inclusion of the 2 chapter files in "Manual.xml" removed the "chapter not expected here" - error.
Seems like a chapter nedds some info before the chapters.

Thank you very much for your support!

chris