search

oxygenxml / dita_1_3_to_2_x_converter

Convert DITA 1.3 maps and topics to the DITA 2.x standard
Mozilla Public License 2.0
2 stars 2 forks source link

Navtitles in prolog flagged as invalid #2

Closed infotexture closed 2 years ago

infotexture commented 2 years ago

After running the conversion on the DITA-OT docs source files as in #1, oXygen 24.0 complains about the new location of the <navtitle> element within <prolog>, although this is correct for DITA 2.x doctypes:

Unexpected element "navtitle". The content of the parent element
type must match "(author*,source?,publisher?,copyright*,critdates?,
permissions?,(metadata|change-historylist)*,resourceid*,
(data|sort-as|data-about|foreign|svg-container|mathml|unknown)*)".

I'm using the release/3.7 branch of the DITA-OT repository (with the latest 2.0 draft grammar files) as the custom DITA-OT location under Preferences > DITA, and I have the DITA 2.0 editing support enabled there too.

raducoravu commented 2 years ago

Can you give me a precise example of a topic on which the refactoring is applied and results in this error? I get a bunch of errors in the "docs-develop/extension-points/extension-points-details.dita" caused by the fact that the prolog is generated before the shortdesc instead of being generated after it. The errors are something like:

Unexpected element "shortdesc". The content of the parent element type must match "(title,(abstract|shortdesc)?,prolog?,refbody?,related-links?,reference*)".

but this is different from the error you get.

infotexture commented 2 years ago

Yes, for example https://github.com/dita-ot/docs/blob/develop/reference/dita-v2-0-support.dita

 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA 2.x Concept//EN" "concept.dtd">
 <!--  This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license.  -->
 <concept id="ID">
   <title>DITA 2.0 preview support</title>

-  <titlealts>
+  <prolog>
     <navtitle>DITA 2.0 preview</navtitle>
-  </titlealts>
+  </prolog>

This shows both errors:

If I move the new <prolog> to after the <shortdesc>, validation still complains about the <navtitle> in <prolog>.

In https://github.com/dita-ot/docs/blob/develop/reference/store-api.dita, there's already a <prolog>, so it moves the <navtitle> there:

 <?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
+<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA 2.x Topic//EN" "topic.dtd">
 <!--  This file is part of the DITA Open Toolkit project. See the accompanying LICENSE file for applicable license.  -->
 <topic id="store-api">
   <title>Store API – Processing in memory</title>
-  <titlealts>
-    <navtitle>Store API</navtitle>
-  </titlealts>
+  
   <shortdesc>DITA-OT originally assumed resources would be available on disk and available from file paths. Recent
     versions added URI input, so HTTPS resources could be used, but temporary and output resources were still
     file-based. DITA-OT 3.6 introduces a new Store API that can process temporary resources in memory instead of writing
     them to disk.</shortdesc>
   <prolog>
+    <navtitle>Store API</navtitle>
+  
     <metadata>
       <keywords>
         <indexterm>Store API</indexterm>

but still complains that it's not valid in the new location.

raducoravu commented 2 years ago

@infotexture I added one more XSLT change to try and move the prolog after the shortdesc: https://github.com/oxygenxml/dita_1_3_to_2_x_converter/commit/440fc0c211a03f9d4a0b90e38e86e38ecea058f3

but I'm not sure why you get that error with the "store-api.dita" topic, is a stub topic like this valid for you? Oxygen reports it as valid when using my build of the DITA OT 3.7 as a default DITA OT in the Preferences->"DITA" page.

<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA 2.x Topic//EN" "topic.dtd">
<topic id="store-api">
  <title>Store API – Processing in memory</title>
  <shortdesc></shortdesc>
  <prolog>
    <navtitle>Store API</navtitle>
    <metadata>
      <keywords>
        <indexterm></indexterm>
      </keywords>
    </metadata>
  </prolog>
  <body>
    <p></p>
  </body>
</topic>
infotexture commented 2 years ago

is a stub topic like this valid for you?

@raducoravu It's not. I still get Unexpected element "navtitle" so there may be an issue with my local setup.

As mentioned above, I'm using the latest 2.0 draft grammar files, so it should work:

I'm using the release/3.7 branch of the DITA-OT repository (with the latest 2.0 draft grammar files) as the custom DITA-OT location under Preferences > DITA, and I have the DITA 2.0 editing support enabled there too.

I do have several additional frameworks directories defined under Document Type Association > Locations, so perhaps one of those is taking precedence over the latest 2.0 grammar files on my system.

raducoravu commented 2 years ago

@infotexture with a DITA topic opened in Oxygen there is a toolbar action named "Open associated schema", if you press it at least you will know what DTD Oxygen uses for validation. Maybe indeed you have some extra catalogs in the "XML / XML Catalog" preferences page or as you say some older frameworks in the "Document Type Association > Locations" page which provide their own XML catalogs.

infotexture commented 2 years ago

@raducoravu Thanks, that tip helped me to debug the issue.

The command opened /…/src/main/plugins/org.oasis-open.dita.techcomm.v2_0/dtd/technicalContent/topic.dtd, so it wasn't a matter of any other frameworks overriding the 2.0 grammars.

But when I checked the file system, I noticed that my local copy of the plug-in had not been updated with the latest changes, so oXygen was validating the file against an outdated DTD, which did not contain the new alternative titles domain.

When I updated the plug-in to the latest version from https://github.com/dita-ot/dita-ot/pull/3833, the validation is successful. ✅

Closing this as user error. Sorry for the trouble. 🤦

raducoravu commented 2 years ago

Thanks @infotexture at least we found out that when I generate a prolog to contain the navigation title, it needs to be placed after the shortdesc to have the topic remain as valid. So I added a commit for this case: https://github.com/oxygenxml/dita_1_3_to_2_x_converter/commit/440fc0c211a03f9d4a0b90e38e86e38ecea058f3

infotexture commented 2 years ago

Yes, so at least something good came out of this.

Not sure how to pick up the latest changes from 440fc0c though. It doesn't offer updates when I check via Manage add-ons. 🤔

If I add this repo's URL^1 via Install new addons, I get an error that the add-on is already installed:

Operation 'Convert DITA 1.3 topics and maps to the DITA 2.0 standard' could not be loaded
because there is already an operation 'Convert DITA 1.3 Maps and Topics to DITA 2.0' with
the same ID: 'convertDITA1_3_to_2_0'.

I'm guessing this is because the same action is included via the bundled DITA framework, but I still get the error even if I disable the DITA 2.0 editing support option in the DITA preferences, and the DITA 2.x frameworks under Document Type Association.

Not sure which version of the add-on is loaded when this conflict is reported, but I'll remove this site from the add-on locations and uninstall for now, since the refactoring action is still there without it.

raducoravu commented 2 years ago

Right, I did not update the addon's version in the addon.xml file and Oxygen does not know a new version is available. I see Robert's been busy removing another bunch of DITA 1.3 elements from the DITA 2.0 specs: https://github.com/dita-ot/dita-ot/pull/3847 so I will need to make changes for that as well. Also starting with Oxygen 24.0 we also ship inside Oxygen the same refactoring actions but I hope the ones provided by the add-on will be loaded first by Oxygen.