dita-ot / org.dita.normalize Goto Github PK

It's plugin.xml should also contain a:

 <feature extension="dita.conductor.transtype.check" value="dita" type="text"/>

because the transtype metadata way of declaring transtypes does not work with DITA OT 1.8.

How this plugin handles IDs in conrefered contend depends on the nesting context and can result in output files with duplicate IDs:

• If a conrefered element contains an ID the plugin ignores this for the output element.
  Source: <conref> --> <ph id=”ABC”>
  Output: <ph>

• If a conrefered element contains other elements with IDs the plugin generates new IDs for these elements in the corresponding output elements.
  Source: <conref> --> <ph id=”ABC”><ph id=”DEF”>
  Output: <ph><ph id=”djpigfv”>
  But it generates for each conref target only one publication wide ID.
  If a conref is used several times within a topic (e. g. product name variables) we get duplicate IDs in the output.

• If an element with conkeyref attribute on top level contains a ID there are two possible outputs:

1. If the conrefered element contains another conkeyref the ID of this target will be set as output ID all other IDs (top-level and all lower conreference levels) are ignored.
   Source: <conref1 id=”ABC”> --> <conref2 id=”DEF”> --> <conref3 id=”GHI”>
   Output: Output ID from conref 2 id=“DEF”
2. If the conrefered element is not a conreference element by itself the top-level ID is set as output ID
   Source: <conref1 id=”ABC”> --> <ph id="DEF"><conref2 id=”GHI”> --> <conref3 id=”JKL”>
   Output: Output ID from conref 1 id=“ABC”

("top-level" means the conreference cascade chain starting point)
("low-level" means the last conrefered target in chain finaly rendered)

I am not shure about the intended handling but first of all it would be good to prevent duplicate ID generation within a topic. Is it possible to generate new IDs for each use case of a conref target or to set a suffix?
Otherwise maybe it would be possible to controll ID generation of nested elements using something like -dita-use-conref-target.

Additionally I would like to get the original id values rendered to the output files instead of new generated.

In my opinion the described cases 1. and 2. should grab IDs from the same level: "ABC" (top level) or "DEF" (second level).

Testing Files:
ID-handling-normalizeDITA.zip

When using chunking, a Composite topic is created instead of nested topicrefs like in the original map.

Original map

<topicref href="concepts/springFlowers.dita" chunk="to-content">
    <topicref href="topics/flowers/iris.dita"/>
    <topicref href="topics/flowers/snowdrop.dita"/>
</topicref>

generates the following

Normalized map

<topicref href="concepts/springFlowers.dita#springFlowers" type="concept" chunk="to-content">
    <topicref href="concepts/springFlowers.dita#iris" type="topic"/>
    <topicref href="concepts/springFlowers.dita#snowdrop" type="topic"/>
</topicref>

Composite topic springFlowers.dita

<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "dita.dtd">
<dita>
  <concept id="springFlowers">
    <title>Spring Flowers</title>
    <topic id="iris">
      <title>Iris</title>
      <topic id="use">
        <title>Use</title>
      </topic>
    </topic>
    <topic id="snowdrop">
      <title>Snowdrop</title>
    </topic>
  </concept>
</dita>

According to the following references, Composite topics are regarded obsolete and might be deprecated in the future. So if there is no compelling technical reason for using Composite topics I'd prefer getting nested topicrefs in the output, which would simplify further processing.

• Composite (ditabase), DITA Style Guide by Tony Self
• Chunking and Composite Topics by Chris Nitchie

Best regards,
Frank

Expected Behavior

When producing normalized dita from dita 1.3 documents, one would hope that the normalized dita would conform to the dita 1.3 schema.

Actual Behavior

When producing normalized dita from dita 1.3 documents, the documents include a @specialization attribute, which is only valid for dita 2.0

Possible Solution

It might be time to add an optional parameter to the dita-ot command that allows one to specify which dita version to target for normalized dita. If this already exists, I can find no mention of it in the documentation.

Steps to Reproduce

sample_dita.zip

1. Using and version of dita-ot 3.5.0 onward, execute the following (using the attached sample file)

   dita --input="sample concept.dita" --format=dita

2. And a quick way to verify that the new one is invalid...

   dita --input="out\sample concept.dita" --format=html5

3. You will get an error like so:

   Line 4:Attribute "specializations" must be declared for element type "concept".

Copy of the error message, log file or stack trace

Environment

• DITA-OT version: 3.5.0 - 3.6.1 (probably even current dev version)
• Operating system and version:
  (Linux, macOS, Windows)
  I've tried it on Linux (Ubuntu 20.04 LTS) and Windows 10
• How did you run DITA-OT?
  (dita command, Ant, startcmd, oXygen, other editor, CMS, etc.)

dita --input="sample concept.dita" --format=dita

• Transformation type:
  (HTML5, PDF, custom, etc.)
  dita

Here's example output from this plugin for elements:
<abbreviated-form href="../../../1_reuse/terms/g_hi.xml" keyref="g_hi" type="glossentry">hearing impaired</abbreviated-form>

It should probably be "hearing impaired" with no markup.

I seem to remember that some users wanted to obtain a merged DITA Map (map with all topicrefs resolved inside it), is it possible with the plugin? Or does it output only individual topic files?

Table cell with column span contains @colname.

<table>
  <tgroup cols="3">
    <colspec colname="col1" colnum="1"/>
    <colspec colname="col2" colnum="2"/>
    <colspec colname="col3" colnum="3"/>
    <thead>
      <row>
        <entry colname="col1">First Header</entry>
        <entry align="center" colname="col2">Second Header</entry>
        <entry align="right" colname="col3">Third Header</entry>
      </row>
    </thead>
    <tbody>
      <row>
        <entry colname="col1">Content</entry>
        <entry align="center" namest="col2" nameend="col3" colname="col2"><i>Long Cell</i></entry>
      </row>
      <row>
        <entry colname="col1">Content</entry>
        <entry align="center" colname="col2"><b>Cell</b></entry>
        <entry align="right" colname="col3">Cell</entry>
      </row>
    </tbody>
  </tgroup>
</table>

Moved from jelovirt/org.lwdita#140

Markdown topics are normalized and converted to DITA, but passed through with their original filenames, which creates the impression that they have not been modified.

Tools that handle files based on extension will expect Markdown, and may fail as the content is actually XML.

Hi,

I've successfully run the transformation that comes with DITA-OT 3.0.1 after integrating our own specialization. However, the specialized DOCTYPE's public identifier is not reproduced in the output so

<!DOCTYPE datasheet PUBLIC "-//MY//DTD Datasheet//EN" "datasheet.dtd"> becomes

<!DOCTYPE datasheet PUBLIC "-//OASIS//DTD DITA Datasheet//EN" "datasheet.dtd">.

Is this the desired behavior or a bug?

Best regards,
Frank

Add support to generalize output to include only specified types. Configuration could be done using e.g. normalize.generalize="topic concept task reference hi-d" to generalize to least general of listed types.