Integrate HTML files into DITA Webhelp Responsive system

jcjackson · Post by **jcjackson** » Mon Jan 30, 2017 9:36 pm

I am writing SDK API documentation, where HTML files are created dynamically from Doxygen.
I want to create these auto-generated files into my DITA Webhelp Responsive output so that they can be searchable.
Does anyone have a solution on how to do this?

alin · Post by **alin** » Tue Jan 31, 2017 5:51 pm

Hello,

You can configure the WebHelp transformation scenario to copy the additional HTML documents in the output directory. This way the HTML documents will be indexed by the WebHelp search engine. The HTML documents should be XML well-formed (XHTML) and they should have the ".html" extension.
This procedure is described in our User Manual: https://www.oxygenxml.com/doc/versions/ ... _resources

Please note that this procedure only ensures that the additional HTML documents are copied in the output directory and they are indexed by the search engine. They will not be linked in the HTML content generated from the DITA sources. They can be accessed only by performing a search operation.

Regards,
Alin

jcjackson · Post by **jcjackson** » Thu Apr 20, 2017 11:30 am

Unfortunately, this doesn't quite work for my needs. I am integrating five (and more) Web Help projects via Doxygen. This then requires a folder structure to keep the topics separate. But the transformation scenario requires a flat structure, and the files are then imported to the root. The auto-generated topics from Doxygen would overwrite each other.
Also, Doxygen outputs HTML, not XHTML.

I have added all five Web Help projects to my DITA project by creating topics with Object elements and pointing to the index.html file from the Data attribute:

Code: Select all

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

<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">

<topic id="topic_kjk_dvd_5y">

  <title>MIP Transaction Reference Manual</title>

  <body>

    <p> </p>

    <object width="700" height="700" data="../Resources/Transacthelp/index.html"

      outputclass="iframe"/>

    <p> </p>

  </body>

</topic>

and

Code: Select all

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

<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">

<topic id="topic_jwd_1pb_5y">

  <title>Configuration API Reference Manual</title>

  <body>

    <p> </p>

    <object width="700" height="700" data="../Resources/ConfigAPIhelp/index.html"

      outputclass="iframe"/>

    <p> </p>

  </body>

</topic>

etc.

This outputs nice working topics with embedded Web Help, but the topics are still not searchable. Any suggestions? If there's anyone familiar with Doxygen outputs, perhaps I could tweak that? It is very important that I can search these auto-generated topics. I assume this is not an unusual requirement for documenting APIs.

Thanks,
Jon

alin · Post by **alin** » Mon Apr 24, 2017 10:49 am

Hello,

This then requires a folder structure to keep the topics separate. But the transformation scenario requires a flat structure, and the files are then imported to the root. The auto-generated topics from Doxygen would overwrite each other.

The transformation scenario does not need a flat structure. The transformation scenario will copy the content of the directory that the "webhelp.custom.resources" parameter points to. For example, if you set the parameter to point to the top directory of the structure generated by Doxygen then the entire content (directories and files) beneath that directory will be copied to the output folder.

Also, Doxygen outputs HTML, not XHTML.

Unfortunately, the WebHelp search engine can only index well-formed XML files. We already have an improvement request registered on this matter and I have increased its priority. I am afraid that, until this issue is fixed, there is no workaround for indexing non well-formed HTML files.
I am not familiar with what Doxygen does and thus I cannot give you any hints on how to tweak its output.

Regards,
Alin

jcjackson · Post by **jcjackson** » Mon Apr 24, 2017 12:25 pm

Thank you for the reply. Just to clarify, when you say:

The transformation scenario does not need a flat structure. The transformation scenario will copy the content of the directory that the "webhelp.custom.resources" parameter points to. For example, if you set the parameter to point to the top directory of the structure generated by Doxygen then the entire content (directories and files) beneath that directory will be copied to the output folder.

Does this mean the output retains the folder structure? In my experience, the topics are all imported, but the folder structure is lost. The loose topics are then placed at the root. And because the different Doxygen jobs name the topics numerically, topic 00001.html from Job A is overwritten by topic 00001.html from Job B, etc.

If the folder structure is supposed to be maintained at import, then I will have another look and see if I am setting it up wrong.

Thanks,
Jon

alin · Post by **alin** » Mon Apr 24, 2017 12:47 pm

Yes, the output should retain the folder structure for the directory referenced with the "webhelp.custom.resources" parameter.

For example, for the following folder structure:

Code: Select all


Folder A

  - a.html

  - Folder B

    - b1.html

    - b2.html

    - b3.html

  - Folder C

    - c1.html

    - c2.html

    - c3.html

if you set the parameter to point to the "Folder A" directory, then the transformation scenario will copy "a.html", "Folder B" and "Folder C" to the output folder.
The output folder will look like this:

Code: Select all


Output Folder

  ................

  - a.html

  - Folder B

    - b1.html

    - b2.html

    - b3.html

  - Folder C

    - c1.html

    - c2.html

    - c3.html

  .................

Furthermore, if you also want "Folder A" to be copied to output, then the parameter should point to the parent directory of "Folder A". Note that this way other resources residing in the parent directory will also be copied to the output.

jcjackson · Post by **jcjackson** » Wed Apr 26, 2017 4:09 pm

Super.. Thanks for your help.
I believe I have come up with a solution to the well-formatted input. Instead of producing HTML, I can generate DocBook from my Doxygen projects. I can then convert the DocBook projects to DITA using oXygen, and then incorporate the final DITA projects in my main project.

Next step is to automate the whole thing

Integrate HTML files into DITA Webhelp Responsive system

Integrate HTML files into DITA Webhelp Responsive system

Re: Integrate HTML files into DITA Webhelp Responsive system

Re: Integrate HTML files into DITA Webhelp Responsive system

Re: Integrate HTML files into DITA Webhelp Responsive system

Re: Integrate HTML files into DITA Webhelp Responsive system

Re: Integrate HTML files into DITA Webhelp Responsive system

Re: Integrate HTML files into DITA Webhelp Responsive system