[oXygen-user] How to include smaller files into a "master document" in Oxygen?

Mon Dec 7 10:29:41 CST 2015

Hi,

The video demonstration you found about working with XML modules uses 
external (system) entities to link the files together. This is a 
different, older method for working with XML modules. I would not 
recommend using it now, if you have the possibility of using XInclude 
instead. The link I gave you regarding XInclude describes it as a 
replacement for external entities and explains the advantages:
> XInclude is targeted as the replacement for External Entities. The 
> advantage of using XInclude is that, unlike the entities method, each 
> of the assembled documents is permitted to contain a Document Type 
> Declaration (DOCTYPE). This means that each file is a valid XML 
> instance and can be independently validated. It also means that the 
> main document to which smaller instances are included can be validated 
> without having to remove or comment out the DOCTYPE. as is the case 
> with External Entities. This makes XInclude a more convenient and 
> effective method for managing XML instances that need to be 
> stand-alone documents and part of a much larger project.

You can read more about the differences between external entities and 
XInclude here:
http://www.xml.com/lpt/a/1009

Regarding your questions:
- for XInclude the links between files are the XInclude statements found 
within the files.
e.g. <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
href="introduction.xml">

- for external entities (the other method) there's an external (system) 
entity declaration in the DOCTYPE section of the XML document and an 
entity reference where the content is wanted.
e.g. Declaration in the DOCTYPE
<!ENTITY chapter1 SYSTEM "my/file/chapter1.xml">
And the reference in the XML content:
&chapter1;

So there are no "auxiliary files" for either of these two linking methods.

Regards,
Adrian

On 07.12.2015 17:57, Jean-Luc Chevillard wrote:
> Hello Adrian,
> (resent, with copy to the mailing list)
>
> thanks for your explanations.
>
> My XML files are "custom"
> and I have defined a DTD and a CSS myself,
> which I am progressively enriching,
> as my understanding of the complexity of that particular thesaurus grows.
>
> In my creation of the Thesaurus
> I alternate between "Text Mode" for certain (complex) tasks
> and "Author Mode" for (easy) tasks.
>
> I had not realized until now that the RLT file size constraints are 
> not that stringent in Author Mode.
> (BTW, Tamil is not a "RTL language" but rather a script with complex 
> rendering ...)
>
> Since I asked the question,
> I have discovered the following video on the Oxygen Web site,
> "http://oxygenxml.com/demo/Working_With_XML_Modules.html"
>
> Using your answer and the video,
> I should (hopefully) have no difficulty trying to use that method.
>
> I have however a remaining question:
> -- I expect the linkage between the "master document" and the 
> "included documents" to be described in some auxiliary file, which 
> will tell Oxygen where to look for the DTD, etc. when it does "content 
> completion"
> -- WHERE will those auxiliary files be located? (will they be in a 
> hidden location) How can I do backup for them?
> -- WHAT HAPPENS when I upgrade to the next version of Oxygen? Will the 
> auxiliary files be destroyed?
>
> Thanks for clarifying those points
>
> Best wishes
>
> -- Jean-Luc Chevillard (Paris)
>
>
> "https://univ-paris-diderot.academia.edu/JeanLucChevillard"
>
> "https://plus.google.com/u/0/113653379205101980081/posts/p/pub"
>
> "https://twitter.com/JLC1956"
>
>
> On 07/12/2015 15:32, Oxygen XML Editor Support (Adrian Buza) wrote:
>> Hello,
>>
>> What type of XML files are these (DITA, DocBook, TEI or custom)?
>>
>> The "support for RTL languages" is problematic for large files in Text
>> mode. But Author mode (Document > Edit Mode > Author) can handle RTL
>> content a lot better, so that's a possible solution if you want to
>> work with larger files.
>> However, if you have a custom type of document thhat Oxuygen doesn't
>> support out-of-the-box, you'll have to create a custom CSS, so that
>> the document is represented properly in Author mode:
>> http://www.oxygenxml.com/doc/versions/17.1/ug-editor/index.html#concepts/dg-css-stylesheet.html 
>>
>>
>>
>>> Can I create a MASTER document in Oxygen
>>> in which the chapters are INCLUDED
>>> (by mentionning their names)
>>> for the sake of processing the sum of the chapters?
>> Yes, you can use XInclude to bind all documents together in a single
>> master file. This way you can transform the master that includes all
>> other documents as if it's a single document.
>> http://www.oxygenxml.com/doc/versions/17.1/ug-editor/index.html#topics/including-document-parts-with-XInclude.html 
>>
>>
>> The examples from this section are for DocBook, but XInclude is
>> supported by Oxygen independent from the XML format.
>> Check your XInclude options from Oxygen (Options > Preferences, XML >
>> "XML Parser", "XInclude Options"), they should be enabled by default.
>>
>>> (I currently run XSLT transformations on separate chapters for making
>>> indices? How to do that for the sum of the chapters?)
>> It's simpler to use the master file and runt the transformation just
>> once on it.
>>
>> Regards,
>> Adrian
>>
>> Adrian Buza
>> oXygen XML Editor and Author Support
>>
>> Tel: +1-650-352-1250 ext.2020
>> Fax: +40-251-461482
>> 
>>
>>
>> On 04.12.2015 15:40, Jean-Luc Chevillard wrote:
>>> Greetings!
>>>
>>> I am currently editing several XML files
>>> which are the chapters of a Tamil thesaurus,
>>> and each file is dangerously close to the size limit
>>> connected with the script specificity.
>>> ("support for RTL languages" has to be activated,
>>> for proper display,
>>> and I have already increased the default size
>>> beyond which RTL language support is automatically deactivated)
>>>
>>> I would appreciate pointers
>>> on the best methods
>>> for dealing with the larger entity,
>>> i.e. the sum of the chapters.
>>>
>>> Can I create a MASTER document in Oxygen
>>> in which the chapters are INCLUDED
>>> (by mentionning their names)
>>> for the sake of processing the sum of the chapters?
>>>
>>> (I currently run XSLT transformations on separate chapters for making
>>> indices? How to do that for the sum of the chapters?)
>>>
>>> Thanks for any pointers to the appropriate section inside the Oxygen
>>> documentation (provided that it is possible to do that in Oxygen ...).
>>>
>>> If the "RTL language" limit was not there, I would have used a single
>>> file but that does not seem to be possible.
>>>
>>> -- Jean-Luc Chevillard (Paris-Pondicherry-Hamburg)
>>>
>>>
>>> "https://univ-paris-diderot.academia.edu/JeanLucChevillard"
>>>
>>>
>>>
>>>
>>> _______________________________________________
>>> oXygen-user mailing list
>>> 
>>> https://www.oxygenxml.com/mailman/listinfo/oxygen-user
>>>
>>
>>
>>
>

-- 
Adrian Buza
oXygen XML Editor and Author Support

Tel: +1-650-352-1250 ext.2020
Fax: +40-251-461482