DITA To Eclipse Help

[PhilSmith]

I am looking to generate Eclipse Help from the Transformation Scenario.
The transformation fails with the following error message:

The markup in the document preceding the root element must be well-formed.
<?xml version="1.0" encoding="UTF-8"?>
<?NLS type="org.eclipse.help.contexts"?>
</contexts>

This is out of the box, I have not made any changes.

Some comments:
1. Eclipse Help requires a .xml file not a .ditamap?
2. When I look at the individual files, they appear to have been created OK.
3. Seems just the index / toc fails.
4. Do I need to download and install a plugin? or Eclipse Help?

Thanks

[sorin_ristache]

Hello,

The transformation fails with the following error message:

The markup in the document preceding the root element must be well-formed.
<?xml version="1.0" encoding="UTF-8"?>
<?NLS type="org.eclipse.help.contexts"?>
</contexts>

This is out of the box, I have not made any changes.

What Oxygen version do you use? There is an XML file created by the DITA Eclipse Help transformation that contains a NLS type processing instruction but it should be like:

Code: Select all

<?NLS TYPE="org.eclipse.help.toc"?>

not like:

Code: Select all

<?NLS type="org.eclipse.help.contexts"?>

and of course it should be a well-formed XML file. The contexts.xml file, also created by the DITA Eclipse Help transformation, does not contain any processing instruction, but starts with something like:

Code: Select all

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

<contexts>

   <context id="introduction">

      <description>Introduction</description>

      <topic label="Introduction" href="topics/introduction.html#introduction"/>

   </context>

   . . .

1. Eclipse Help requires a .xml file not a .ditamap?

Any DITA transformation (including the Eclipse one) requires a valid DITA map file. The extension of the DITA map file is not important. The important thing is to be a valid DITA map file, as reported by the action Validate and Check for Completeness available on the toolbar of the DITA Maps Manager view.

2. When I look at the individual files, they appear to have been created OK.

What is the name of the file that is not well-formed (the file that contains the <?NLS type="org.eclipse.help.contexts"?> instruction) ? What is the name of the input DITA map file?

3. Seems just the index / toc fails.

Does the output directory contain an index.xml file and a [map-file-name].xml file, where [map-file-name] is the name (without extension) of the input DITA map file?

What is the full error message in the output view of the DITA transformation (at the bottom of the Oxygen window)? Does this view contain also other transformation errors?

4. Do I need to download and install a plugin? or Eclipse Help?

No. If the input DITA map is valid, the DITA Eclipse Help transformation should create a valid Eclipse Help set out of the box, which means an Eclipse plugin that extends the "org.eclipse.help.toc" and "org.eclipse.help.index" Eclipse points. You can test the Eclipse Help plugin created by the DITA transformation by deploying it in an Eclipse platform and restarting the platform.

But of course, the transformation should end without (major) errors in Oxygen first.


Regards,
Sorin

[PhilSmith]

Hi Sorin,
Apologies for the delay - been in for a new hip.
In response to your points:
1. Am using 15.2 now - was 15.1 at the time
2. I can find <?NLS type="org.eclipse.help.contexts"?> not .toc is in the Book.xml file in the Eclipse Help Output
3. Searched, but could not find a context.xml file
4. All xml files created contain <?NLS type="org.eclipse.help.contexts"?> Each file has an equivalent html file that displays OK when opened.
5.Yes an index.xml file and a [map-file-name].xml file is created

6. Now I am on 15.2, I can't generate any output. The Oxygen error is "[DOTA003F] Cannot find the user specified XSLT stylesheet 'C:\Program Files\Oxygen XML Editor 15\frameworks\dita\DITA-OT\plugins\cshelp\xsl\dit2context.xsl'.

Thanks

[sorin_ristache]

Hi,

Let's start with a simple DITA map, for example the sample flowers.ditamap that comes in the default Oxygen project (samples.xpr) opened in the Project view. The path is: samples/dita/flowers/flowers.ditamap. Please open this map in the DITA Maps Manager view and apply the built-in (which means not customized) Eclipse Help transformation to this map. The output directory (samples/dita/flowers/out/eclipsehelp) should contain a file flowers.xml that starts with:

Code: Select all

<?NLS TYPE="org.eclipse.help.toc"?>

<toc label="Growing Flowers" topic="topics/introduction.html">

. . .

and also a file contexts.xml that starts with:

Code: Select all

<contexts>

   <context id="introduction">

      <description> . . .

The files index.xml and plugin.xml should also be present in the output directory. The plugin.xml file is the one that plugs the DITA transformation output into Eclipse as a help plugin, because it contains:

Code: Select all

<plugin>

   <extension point="org.eclipse.help.toc">

      <toc file="flowers.xml" primary="true"/>

   </extension>

   <extension point="org.eclipse.help.index">

      <index file="index.xml"/>

   </extension>

</plugin>

Do you get all these files in the output directory of the Eclipse Help transformation?


Regards,
Sorin

[PhilSmith]

Hi Sorin,
Yes, have all those files
Phil

[sorin_ristache]

Hi Phil,

In that case maybe you can send a sample DITA map and the topics included in the map for reproducing the problem. It is strange to have the DITA Eclipse Help transformation working correctly on one map (the sample flowers.ditamap) but not on another one, without getting errors in the transformation.


Regards,
Sorin

[PhilSmith]

Hi Sorin,
Following is the ditamap for one of the books. I tried a couple, and they both failed with the following error:
Description: [DOTX050W]: Default id "org.sample.help.doc" is used for Eclipse plug-in. If you want to use your own plug-in id, please specify it using the id attribute on your map. The location of this problem was at (File = E:\Documentation\Products\PC220-Connectors\TechManual\PC220_TSMBook.ditamap, Element = bookmap:1;3:22)
Start location: 3:22
and
C:\Program Files\Oxygen XML Editor 15\frameworks\dita\DITA-OT\plugins\org.dita.eclipsehelp\build_dita2eclipsehelp.xml:28: input file E:\Documentation\Products\PC220-Connectors\TechManual\out\eclipsehelp\Products\PC220-Connectors\TechManual\PC220_TSMBook.xml does not exist

Did you want a copy of the actual files in the ditamap?

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE bookmap PUBLIC "-//OASIS//DTD DITA BookMap//EN" "bookmap.dtd">
<bookmap rev="Draft">
<booktitle>
<mainbooktitle rev="20140105">..-PC 220 Connectors</mainbooktitle>
<booktitlealt/>
</booktitle>
<bookmeta>
<prodinfo>
<prodname>PC220</prodname>
<vrmlist>
<vrm version="1"/>
</vrmlist>
</prodinfo>
<othermeta name="status" content="draft"/>
<bookid>
<booknumber>PC220 Connectors</booknumber>
</bookid>
<bookrights>
<copyrfirst>
<year>2010</year>
</copyrfirst>
<copyrlast>
<year>2013</year>
</copyrlast>
<bookowner>
<organization>Becker</organization>
</bookowner>
</bookrights>
</bookmeta>
<frontmatter>
<preface>
<topicref href="../../01_Common_Files/Preface.xml" navtitle="Preface"/>
<topicref href="Revision.xml" navtitle="Revision"/>
</preface>
<booklists>
<toc/>
<figurelist/>
</booklists>
</frontmatter>
<chapter navtitle="Introduction" toc="yes">
<topicref href="../../01_Common_Files/SignsAndSymbols.xml" navtitle="Signs And Symbols"
toc="yes" format="dita"/>
<topicref href="01_Purpose/PC220_Safety.xml" navtitle="PC220 Safety"/>
<topicref href="01_Purpose/PC220_Electrical_Data.xml" navtitle="PC220 Electrical Data"/>
<topicref href="01_Purpose/PC220_Mechanical_Data.xml" navtitle="PC220 Mechanical Data"/>
</chapter>
<chapter navtitle="Operation">
<topicref href="02_Operation/PC220_Connections_WithPilot.xml"
navtitle="PC220 Connections - With Pilot"/>
<topicref href="02_Operation/PC220_Connections_WithoutPilot.xml"
navtitle="Connections - Without Pilot"/>
</chapter>
<chapter navtitle="Maintenance" toc="yes">
<topicref href="04_Maintenance/PC220_Maintenance.xml" navtitle="PC220 Maintenance"/>
<topicref href="04_Maintenance/PC220_Plugs.xml" navtitle="PC 220 Plugs"/>
<topicref href="04_Maintenance/PC220_PlugsTerminating.xml"
navtitle="PC 220 Terminating Plugs"/>
<topicref href="04_Maintenance/PC220_Sockets.xml" navtitle="PC 220 Sockets"/>
<topicref href="04_Maintenance/PC220_PlugTesting.xml" navtitle="PC220 Plug Testing"/>
<topicref href="04_Maintenance/PC220_Socket_Fixing.xml" navtitle="PC220 Socket Fixing"/>
</chapter>
<chapter navtitle="Installation Commissioning" rev="01" toc="yes">
<topicref href="../../01_Common_Files/PersonnelQualifications.xml"
navtitle="Personnel Qualifications"/>
<topicref href="../../01_Common_Files/Storage.xml" navtitle="Storage"/>
<topicref href="../../01_Common_Files/Equipment_Repair.xml" navtitle="Equipment Repair"/>
<topicref href="../../01_Common_Files/WarrantyLiability.xml"
navtitle="Warranty and Liability"/>
<topicref href="05_Install_Commission/PC220_Spares.xml" navtitle="PC220 Spares"/>
</chapter>
<backmatter>
<booklists>
<indexlist/>
</booklists>
</backmatter>
</bookmap>




Thanks

[sorin_ristache]

Hi,

Hi Sorin,
Following is the ditamap for one of the books. I tried a couple, and they both failed with the following error:
Description: [DOTX050W]: Default id "org.sample.help.doc" is used for Eclipse plug-in. If you want to use your own plug-in id, please specify it using the id attribute on your map. The location of this problem was at (File = E:\Documentation\Products\PC220-Connectors\TechManual\PC220_TSMBook.ditamap, Element = bookmap:1;3:22)
Start location: 3:22

This is only a warning and a recommendation. The string value that is the Eclipse plugin ID value is not the cause of the transformation failure.

C:\Program Files\Oxygen XML Editor 15\frameworks\dita\DITA-OT\plugins\org.dita.eclipsehelp\build_dita2eclipsehelp.xml:28: input file E:\Documentation\Products\PC220-Connectors\TechManual\out\eclipsehelp\Products\PC220-Connectors\TechManual\PC220_TSMBook.xml does not exist

This error says that the output file contexts.xml could not be created because the input file PC220_TSMBook.xml which was expected in the directory Products\PC220-Connectors\TechManual was not found. This file with the same name as the input DITA map but with the .xml extension should be created by the Eclipse Help transformation before the creation of contexts.xml, and the creation of contexts.xml is based on it.

Did you want a copy of the actual files in the ditamap?

Not enough details are available so far for troubleshooting the issue, so a complete set of working files is needed: a sample DITA map and all the included DITA topics.


Regards,
Sorin

[PhilSmith]

Sorin,
I can't see where to add the attachments? Also, should they be files / directories or a .zip file?
Thanks

[sorin_ristache]

You can attach your files as a zip archive in the online problem report form that I linked also in the above posts.


Regards,
Sorin

[PhilSmith]

Morning Sorin,
Updated the file as you requested - what was the problem? I wasn't aware I had made a change in that file.
The file produces an output now, but I get an error message "No CSS file specified."
Unfortunately, I am not that familiar with Eclipse, I am looking at options for the future. I am unable to produce an output - say, similar to WebHelp. Is this because I have not associated a Cascading Stylesheet?
Is there a default one I can use to get an idea of the output, and then modify to suit.
Thanks again
Phil

[sorin_ristache]

Hi Phil,

Morning Sorin,
Updated the file as you requested - what was the problem? I wasn't aware I had made a change in that file.

I am not sure if or what you changed in the ANT build script for the Eclipse Help output. If you get a different result you might compare the two ANT build files (the one that I sent you and your original one) to find the exact differences between them.

The file produces an output now, but I get an error message "No CSS file specified."
Unfortunately, I am not that familiar with Eclipse, I am looking at options for the future. I am unable to produce an output - say, similar to WebHelp. Is this because I have not associated a Cascading Stylesheet?

You can set a CSS file to format the output pages using the args.css parameter. You should also set the args.copycss parameter to true when you set the args.css parameter.

Is there a default one I can use to get an idea of the output, and then modify to suit.

The default one is [Oxygen-install-dir]\frameworks\dita\DITA-OT\resource\commonltr.css. An alternative one is [Oxygen-install-dir]\frameworks\dita\DITA-OT\plugins\com.oxygenxml.webhelp\oxygen-webhelp\resources\css\webhelp_topic.css.


Regards,
Sorin

[PhilSmith]

Hi Sorin,
Finally got back to this.
Used both of the CSS files you nominated in the Eclipse transformation scenario.
All appears to build OK, but the output that opens in Oxygen has an error message
'Cannot load the associated CSS file(s). The error was No CSS File Specified.
Switch to text mode and use the AssociateXSLT / CSS Stylesheet action to associate...'

Did that, and could see the TOC contents, open in a tab in Oxygen.

Now, all the topics appear in the output as html files and are viewable as expected - but there is no 'book' html file that allows me to access the individual files

[sorin_ristache]

Hi Phil,

The output file that is opened automatically in the Oxygen window at the end of the DITA Eclipse Help transformation is the XML file containing the Table of Contents of the entire Eclipse helpset. By default the name of this XML file is the same as the name of the input DITA map file, in your case I think it should be PC220_TSMBook.xml.

This XML file is one of the XML files required by the Eclipse platform for Eclipse Help plugins, so you don't have to associate a CSS file to it in Oxygen just for opening it in Author mode. Oxygen opens it at the end of the transformation just to show you where it is located and to allow you some basic checks such as checking if it is a well-formed XML file, etc. This file should be used only together with all the other files from teh output directory of the Eclipse Help transformation (the directory containing this PC220_TSMBook.xml file). If you want to access and see the content of the individual HTML help files you should deploy the output of the Eclipse Help transformation as an Eclipse plugin on an Eclipse platform.


Regards,
Sorin

[PhilSmith]

Ahhhh, the fog lifts.
Thanks for your patience Sorin - think i have a handle on this now.