dita-convert 1.0.0__py3-none-any.whl

dita/convert/__init__.py

@@ -0,0 +1,36 @@
+# Copyright (C) 2024 Jaromir Hradilek
+
+# MIT License
+#
+# Permission  is hereby granted,  free of charge,  to any person  obtaining
+# a copy of  this software  and associated documentation files  (the "Soft-
+# ware"),  to deal in the Software  without restriction,  including without
+# limitation the rights to use,  copy, modify, merge,  publish, distribute,
+# sublicense, and/or sell copies of the Software,  and to permit persons to
+# whom the Software is furnished to do so,  subject to the following condi-
+# tions:
+#
+# The above copyright notice  and this permission notice  shall be included
+# in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS",  WITHOUT WARRANTY OF ANY KIND,  EXPRESS
+# OR IMPLIED,  INCLUDING BUT NOT LIMITED TO  THE WARRANTIES OF MERCHANTABI-
+# LITY,  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT
+# SHALL THE AUTHORS OR COPYRIGHT HOLDERS  BE LIABLE FOR ANY CLAIM,  DAMAGES
+# OR OTHER LIABILITY,  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+# ARISING FROM,  OUT OF OR IN CONNECTION WITH  THE SOFTWARE  OR  THE USE OR
+# OTHER DEALINGS IN THE SOFTWARE.
+
+"""Convert a generic DITA topic to a specialized concept, task, or reference."""
+
+# Module metadata:
+__author__      = 'Jaromir Hradilek'
+__copyright__   = 'Copyright (C) 2024 Jaromir Hradilek'
+__license__     = 'MIT License'
+__description__ = __doc__
+__version__     = '1.0.0'
+
+# Expose general information about the project:
+NAME        = 'dita-convert'
+VERSION     = __version__
+DESCRIPTION = __doc__

dita/convert/__main__.py

@@ -0,0 +1,27 @@
+# Copyright (C) 2024 Jaromir Hradilek
+
+# MIT License
+#
+# Permission  is hereby granted,  free of charge,  to any person  obtaining
+# a copy of  this software  and associated documentation files  (the "Soft-
+# ware"),  to deal in the Software  without restriction,  including without
+# limitation the rights to use,  copy, modify, merge,  publish, distribute,
+# sublicense, and/or sell copies of the Software,  and to permit persons to
+# whom the Software is furnished to do so,  subject to the following condi-
+# tions:
+#
+# The above copyright notice  and this permission notice  shall be included
+# in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS",  WITHOUT WARRANTY OF ANY KIND,  EXPRESS
+# OR IMPLIED,  INCLUDING BUT NOT LIMITED TO  THE WARRANTIES OF MERCHANTABI-
+# LITY,  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT
+# SHALL THE AUTHORS OR COPYRIGHT HOLDERS  BE LIABLE FOR ANY CLAIM,  DAMAGES
+# OR OTHER LIABILITY,  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+# ARISING FROM,  OUT OF OR IN CONNECTION WITH  THE SOFTWARE  OR  THE USE OR
+# OTHER DEALINGS IN THE SOFTWARE.
+
+from . import cli
+
+if __name__ == '__main__':
+    cli.parse_args()

dita/convert/cli.py

@@ -0,0 +1,116 @@
+# Copyright (C) 2024 Jaromir Hradilek
+
+# MIT License
+#
+# Permission  is hereby granted,  free of charge,  to any person  obtaining
+# a copy of  this software  and associated documentation files  (the "Soft-
+# ware"),  to deal in the Software  without restriction,  including without
+# limitation the rights to use,  copy, modify, merge,  publish, distribute,
+# sublicense, and/or sell copies of the Software,  and to permit persons to
+# whom the Software is furnished to do so,  subject to the following condi-
+# tions:
+#
+# The above copyright notice  and this permission notice  shall be included
+# in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS",  WITHOUT WARRANTY OF ANY KIND,  EXPRESS
+# OR IMPLIED,  INCLUDING BUT NOT LIMITED TO  THE WARRANTIES OF MERCHANTABI-
+# LITY,  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT
+# SHALL THE AUTHORS OR COPYRIGHT HOLDERS  BE LIABLE FOR ANY CLAIM,  DAMAGES
+# OR OTHER LIABILITY,  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+# ARISING FROM,  OUT OF OR IN CONNECTION WITH  THE SOFTWARE  OR  THE USE OR
+# OTHER DEALINGS IN THE SOFTWARE.
+
+import argparse
+import errno
+import sys
+
+from lxml import etree
+from . import NAME, VERSION, DESCRIPTION
+from .transform import to_concept, to_reference, to_task, to_task_generated
+
+# Print a message to standard error output and terminate the script:
+def exit_with_error(error_message, exit_status=errno.EPERM):
+    # Print the supplied message to standard error output:
+    print(f'{NAME}: {error_message}', file=sys.stderr)
+
+    # Terminate the script with the supplied exit status:
+    sys.exit(exit_status)
+
+# Convert the selected file:
+def convert(source_file, target_type):
+    # Select the appropriate XSLT transformer:
+    transform = {
+        'concept':   to_concept,
+        'reference': to_reference,
+        'task':      to_task,
+        'task-gen':  to_task_generated,
+    }[target_type]
+
+    try:
+        # Run the transformation:
+        xml = transform(etree.parse(source_file))
+    except Exception as ex:
+        # Terminate the script if an error is encountered:
+        exit_with_error(f'{source_file}: {ex}')
+
+    # Print any warning messages to standard error output:
+    for error in transform.error_log:
+        print(f'{source_file}: {error.message}', file=sys.stderr)
+
+    # Return the result:
+    return xml
+
+# Parse supplied command-line options:
+def parse_args():
+    # Configure the option parser:
+    parser = argparse.ArgumentParser(prog=NAME,
+        description=DESCRIPTION,
+        add_help=False)
+
+    # Redefine section titles for the main command:
+    parser._optionals.title = 'Options'
+    parser._positionals.title = 'Arguments'
+
+    # Add supported command-line options:
+    info = parser.add_mutually_exclusive_group()
+    info.add_argument('-h', '--help',
+        action='help',
+        help='display this help and exit')
+    info.add_argument('-v', '--version',
+        action='version',
+        version=f'{NAME} {VERSION}',
+        help='display version information and exit')
+    parser.add_argument('-t', '--type',
+        choices=('concept', 'reference', 'task', 'task-gen'),
+        required=True,
+        help='target DITA content type')
+    parser.add_argument('-o', '--output',
+        default=sys.stdout,
+        help='write output to the selected file instead of stdout')
+
+    # Add supported command-line arguments:
+    parser.add_argument('file', metavar='FILE',
+        help='specify the DITA topic file to convert')
+
+    # Parse the command-line options:
+    args = parser.parse_args()
+
+    # Convert the selected file:
+    xml = convert(args.file, args.type)
+
+    # Determine whether to write to standard output:
+    if args.output == sys.stdout:
+        # Print to standard output:
+        sys.stdout.write(str(xml))
+
+        # Terminate the script:
+        sys.exit(0)
+
+    try:
+        # Write to the selected file:
+        with open(args.output, 'w') as f:
+            f.write(str(xml))
+    except Exception as ex:
+        # Terminate the script if an error is encountered:
+        exit_with_error(f'{args.output}: {ex}')

dita/convert/transform.py

@@ -0,0 +1,34 @@
+# Copyright (C) 2024 Jaromir Hradilek
+
+# MIT License
+#
+# Permission  is hereby granted,  free of charge,  to any person  obtaining
+# a copy of  this software  and associated documentation files  (the "Soft-
+# ware"),  to deal in the Software  without restriction,  including without
+# limitation the rights to use,  copy, modify, merge,  publish, distribute,
+# sublicense, and/or sell copies of the Software,  and to permit persons to
+# whom the Software is furnished to do so,  subject to the following condi-
+# tions:
+#
+# The above copyright notice  and this permission notice  shall be included
+# in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS",  WITHOUT WARRANTY OF ANY KIND,  EXPRESS
+# OR IMPLIED,  INCLUDING BUT NOT LIMITED TO  THE WARRANTIES OF MERCHANTABI-
+# LITY,  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT
+# SHALL THE AUTHORS OR COPYRIGHT HOLDERS  BE LIABLE FOR ANY CLAIM,  DAMAGES
+# OR OTHER LIABILITY,  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+# ARISING FROM,  OUT OF OR IN CONNECTION WITH  THE SOFTWARE  OR  THE USE OR
+# OTHER DEALINGS IN THE SOFTWARE.
+
+from lxml import etree
+from .xslt import *
+
+# Define which symbols are to be exported:
+__all__ = ['to_concept', 'to_reference', 'to_task', 'to_task_generated' ]
+
+# Expose the XSLT transformers:
+to_concept        = etree.XSLT(etree.parse(concept))
+to_reference      = etree.XSLT(etree.parse(reference))
+to_task           = etree.XSLT(etree.parse(task))
+to_task_generated = etree.XSLT(etree.parse(task_generated))

dita/convert/xslt/concept.xsl

@@ -0,0 +1,68 @@
+<?xml version='1.0' encoding='utf-8' ?>
+
+<!--
+  Copyright (C) 2024 Jaromir Hradilek
+
+  A custom XSLT stylesheet to convert a generic DITA topic to a specialized
+  DITA concept topic.
+
+  Usage: xsltproc ––novalid concept.xsl YOUR_TOPIC.dita
+
+  MIT License
+
+  Permission  is hereby granted,  free of charge,  to any person  obtaining
+  a copy of  this software  and associated documentation files  (the "Soft-
+  ware"),  to deal in the Software  without restriction,  including without
+  limitation the rights to use,  copy, modify, merge,  publish, distribute,
+  sublicense, and/or sell copies of the Software,  and to permit persons to
+  whom the Software is furnished to do so,  subject to the following condi-
+  tions:
+
+  The above copyright notice  and this permission notice  shall be included
+  in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS",  WITHOUT WARRANTY OF ANY KIND,  EXPRESS
+  OR IMPLIED,  INCLUDING BUT NOT LIMITED TO  THE WARRANTIES OF MERCHANTABI-
+  LITY,  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT
+  SHALL THE AUTHORS OR COPYRIGHT HOLDERS  BE LIABLE FOR ANY CLAIM,  DAMAGES
+  OR OTHER LIABILITY,  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+  ARISING FROM,  OUT OF OR IN CONNECTION WITH  THE SOFTWARE  OR  THE USE OR
+  OTHER DEALINGS IN THE SOFTWARE.
+-->
+
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+  <!-- Compose the XML and DOCTYPE declarations: -->
+  <xsl:output encoding="utf-8" method="xml" doctype-system="concept.dtd" doctype-public="-//OASIS//DTD DITA Concept//EN" />
+
+  <!-- Format the XML output: -->
+  <xsl:output indent="yes" />
+  <xsl:strip-space elements="*" />
+  <xsl:preserve-space elements="codeblock pre screen" />
+
+  <!-- Report an error if the converted file is not a DITA topic: -->
+  <xsl:template match="/*[not(self::topic)]">
+    <xsl:message terminate="yes">ERROR: Not a DITA topic</xsl:message>
+  </xsl:template>
+
+  <!-- Perform identity transformation: -->
+  <xsl:template match="@*|node()">
+    <xsl:copy>
+      <xsl:apply-templates select="@*|node()" />
+    </xsl:copy>
+  </xsl:template>
+
+  <!-- Transform the root element: -->
+  <xsl:template match="/topic">
+    <xsl:element name="concept">
+      <xsl:apply-templates select="@*|node()" />
+    </xsl:element>
+  </xsl:template>
+
+  <!-- Transform the body element: -->
+  <xsl:template match="body">
+    <xsl:element name="conbody">
+      <xsl:apply-templates select="@*|node()" />
+    </xsl:element>
+  </xsl:template>
+
+</xsl:stylesheet>

dita/convert/xslt/reference.xsl

@@ -0,0 +1,80 @@
+<?xml version='1.0' encoding='utf-8' ?>
+
+<!--
+  Copyright (C) 2024 Jaromir Hradilek
+
+  A custom XSLT stylesheet to convert a generic DITA topic to a specialized
+  DITA reference topic.
+
+  Usage: xsltproc ––novalid reference.xsl YOUR_TOPIC.dita
+
+  MIT License
+
+  Permission  is hereby granted,  free of charge,  to any person  obtaining
+  a copy of  this software  and associated documentation files  (the "Soft-
+  ware"),  to deal in the Software  without restriction,  including without
+  limitation the rights to use,  copy, modify, merge,  publish, distribute,
+  sublicense, and/or sell copies of the Software,  and to permit persons to
+  whom the Software is furnished to do so,  subject to the following condi-
+  tions:
+
+  The above copyright notice  and this permission notice  shall be included
+  in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS",  WITHOUT WARRANTY OF ANY KIND,  EXPRESS
+  OR IMPLIED,  INCLUDING BUT NOT LIMITED TO  THE WARRANTIES OF MERCHANTABI-
+  LITY,  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT
+  SHALL THE AUTHORS OR COPYRIGHT HOLDERS  BE LIABLE FOR ANY CLAIM,  DAMAGES
+  OR OTHER LIABILITY,  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+  ARISING FROM,  OUT OF OR IN CONNECTION WITH  THE SOFTWARE  OR  THE USE OR
+  OTHER DEALINGS IN THE SOFTWARE.
+-->
+
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+  <!-- Compose the XML and DOCTYPE declarations: -->
+  <xsl:output encoding="utf-8" method="xml" doctype-system="reference.dtd" doctype-public="-//OASIS//DTD DITA Reference//EN" />
+
+  <!-- Format the XML output: -->
+  <xsl:output indent="yes" />
+  <xsl:strip-space elements="*" />
+  <xsl:preserve-space elements="codeblock pre screen" />
+
+  <!-- Report an error if the converted file is not a DITA topic: -->
+  <xsl:template match="/*[not(self::topic)]">
+    <xsl:message terminate="yes">ERROR: Not a DITA topic</xsl:message>
+  </xsl:template>
+
+  <!-- Perform identity transformation: -->
+  <xsl:template match="@*|node()">
+    <xsl:copy>
+      <xsl:apply-templates select="@*|node()" />
+    </xsl:copy>
+  </xsl:template>
+
+  <!-- Transform the root element: -->
+  <xsl:template match="/topic">
+    <xsl:element name="reference">
+      <xsl:apply-templates select="@*|node()" />
+    </xsl:element>
+  </xsl:template>
+
+  <!-- Transform the body element: -->
+  <xsl:template match="body">
+    <xsl:element name="refbody">
+      <xsl:choose>
+        <xsl:when test="section">
+          <xsl:element name="section">
+            <xsl:apply-templates select="section[1]/preceding-sibling::*" />
+          </xsl:element>
+          <xsl:apply-templates select="section|section/following-sibling::*" />
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:element name="section">
+            <xsl:apply-templates select="@*|node()" />
+          </xsl:element>
+        </xsl:otherwise>
+      </xsl:choose>
+    </xsl:element>
+  </xsl:template>
+
+</xsl:stylesheet>

dita/convert/xslt/task-generated.xsl

@@ -0,0 +1,281 @@
+<?xml version='1.0' encoding='utf-8' ?>
+
+<!--
+  Copyright (C) 2024 Jaromir Hradilek
+
+  A custom XSLT stylesheet  to convert a generic DITA topic  generated with
+  the  asciidoctor-dita-topic[1] plug-in  to a specialized DITA task topic.
+  The stylesheet expects  that the original AsciiDoc file  has followed the
+  guidelines for procedure modules as defined  in the Modular Documentation
+  Reference Guide[2].
+
+  Usage: xsltproc ––novalid task-generated.xsl YOUR_TOPIC.dita
+
+  [1] https://github.com/jhradilek/asciidoctor-dita-topic
+  [2] https://redhat-documentation.github.io/modular-docs/
+
+  MIT License
+
+  Permission  is hereby granted,  free of charge,  to any person  obtaining
+  a copy of  this software  and associated documentation files  (the "Soft-
+  ware"),  to deal in the Software  without restriction,  including without
+  limitation the rights to use,  copy, modify, merge,  publish, distribute,
+  sublicense, and/or sell copies of the Software,  and to permit persons to
+  whom the Software is furnished to do so,  subject to the following condi-
+  tions:
+
+  The above copyright notice  and this permission notice  shall be included
+  in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS",  WITHOUT WARRANTY OF ANY KIND,  EXPRESS
+  OR IMPLIED,  INCLUDING BUT NOT LIMITED TO  THE WARRANTIES OF MERCHANTABI-
+  LITY,  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT
+  SHALL THE AUTHORS OR COPYRIGHT HOLDERS  BE LIABLE FOR ANY CLAIM,  DAMAGES
+  OR OTHER LIABILITY,  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+  ARISING FROM,  OUT OF OR IN CONNECTION WITH  THE SOFTWARE  OR  THE USE OR
+  OTHER DEALINGS IN THE SOFTWARE.
+-->
+
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+  <!-- Compose the XML and DOCTYPE declarations: -->
+  <xsl:output encoding="utf-8" method="xml" doctype-system="task.dtd" doctype-public="-//OASIS//DTD DITA Task//EN" />
+
+  <!-- Format the XML output: -->
+  <xsl:output indent="yes" />
+  <xsl:strip-space elements="*" />
+  <xsl:preserve-space elements="codeblock pre screen" />
+
+  <!-- Report an error if the converted file is not a DITA topic: -->
+  <xsl:template match="/*[not(self::topic)]">
+    <xsl:message terminate="yes">ERROR: Not a DITA topic</xsl:message>
+  </xsl:template>
+
+  <!-- Report an error if the converted file contains a section: -->
+  <xsl:template match="//section">
+    <xsl:message terminate="yes">ERROR: Section not allowed in a DITA task</xsl:message>
+  </xsl:template>
+
+  <!-- Define a list of valid cmd element children: -->
+  <xsl:variable name="cmd-children" select="' abbreviated-form apiname b boolean cite cmdname codeph data data-about draft-comment equation-inline filepath fn foreign i image indexterm indextermref keyword line-through markupname mathml menucascade msgnum msgph numcharref option overline parameterentity parmname ph q required-cleanup sort-as state sub sup svg-container synph systemoutput term text textentity tm tt u uicontrol unknown userinput varname wintitle xmlatt xmlelement xmlnsname xmlpi xref '" />
+
+  <!-- Perform identity transformation: -->
+  <xsl:template match="@*|node()">
+    <xsl:copy>
+      <xsl:apply-templates select="@*|node()" />
+    </xsl:copy>
+  </xsl:template>
+
+  <!-- Transform the root element: -->
+  <xsl:template match="/topic">
+    <xsl:element name="task">
+      <xsl:apply-templates select="@*|node()" />
+    </xsl:element>
+  </xsl:template>
+
+  <!-- Transform the body element: -->
+  <xsl:template match="body">
+    <xsl:element name="taskbody">
+      <!-- Compose the prereq element: -->
+      <xsl:call-template name="compose-element">
+        <xsl:with-param name="name" select="'prereq'" />
+        <xsl:with-param name="contents" select="*[not(@outputclass='title') and preceding-sibling::p[@outputclass='title'][1][b='Prerequisites']]" />
+      </xsl:call-template>
+      <!-- Compose the context element: -->
+      <xsl:choose>
+        <xsl:when test="p[@outputclass='title']">
+          <xsl:call-template name="compose-element">
+            <xsl:with-param name="name" select="'context'" />
+            <xsl:with-param name="contents" select="p[@outputclass='title'][1]/preceding-sibling::*" />
+          </xsl:call-template>
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:call-template name="compose-element">
+            <xsl:with-param name="name" select="'context'" />
+            <xsl:with-param name="contents" select="*" />
+          </xsl:call-template>
+        </xsl:otherwise>
+      </xsl:choose>
+      <!-- Compose the steps element: -->
+      <xsl:call-template name="steps">
+        <xsl:with-param name="contents" select="*[not(@outputclass='title') and preceding-sibling::p[@outputclass='title'][1][b='Procedure']]" />
+      </xsl:call-template>
+      <!-- Compose the result element: -->
+      <xsl:call-template name="compose-element">
+        <xsl:with-param name="name" select="'result'" />
+        <xsl:with-param name="contents" select="*[not(@outputclass='title') and preceding-sibling::p[@outputclass='title'][1][b='Verification']]" />
+      </xsl:call-template>
+      <!-- Compose the tasktroubleshooting element: -->
+      <xsl:call-template name="compose-element">
+        <xsl:with-param name="name" select="'tasktroubleshooting'" />
+        <xsl:with-param name="contents" select="*[not(@outputclass='title') and preceding-sibling::p[@outputclass='title'][1][b='Troubleshooting' or b='Troubleshooting steps']]" />
+      </xsl:call-template>
+      <!-- Compose the postreq element: -->
+      <xsl:call-template name="compose-element">
+        <xsl:with-param name="name" select="'postreq'" />
+        <xsl:with-param name="contents" select="*[not(@outputclass='title') and preceding-sibling::p[@outputclass='title'][1][b='Next steps' or b='Next step']]" />
+      </xsl:call-template>
+      <!-- Issue a warning if the converted file contains an unsupported title:  -->
+      <xsl:for-each select="p[@outputclass='title']/b/text()">
+        <xsl:variable name="titles" select="'|Prerequisites|Procedure|Verification|Troubleshooting|Troubleshooting steps|Next steps|Next step|'" />
+        <xsl:if test="not(contains($titles, concat('|', ., '|')))">
+          <xsl:message terminate="no">WARNING: Unsupported title '<xsl:copy-of select="." />' found, skipping...</xsl:message>
+        </xsl:if>
+      </xsl:for-each>
+    </xsl:element>
+  </xsl:template>
+
+  <!-- Compose the steps element: -->
+  <xsl:template name="steps">
+    <xsl:param name="contents" />
+    <xsl:variable name="list" select="$contents[self::ol or self::ul][1]" />
+    <xsl:if test="$contents">
+      <xsl:if test="$contents[not(self::ol or self::ul)]">
+        <xsl:message terminate="no">WARNING: Non-list elements found in steps, skipping...</xsl:message>
+      </xsl:if>
+      <xsl:if test="$contents[self::ol or self::ul][2]">
+        <xsl:message terminate="no">WARNING: Extra list elements found in steps, skipping...</xsl:message>
+      </xsl:if>
+      <xsl:if test="not($list)">
+        <xsl:message terminate="no">WARNING: No list elementes found in steps</xsl:message>
+      </xsl:if>
+      <xsl:if test="$list">
+        <xsl:variable name="name">
+          <xsl:choose>
+            <xsl:when test="$list[self::ul]">
+              <xsl:text>steps-unordered</xsl:text>
+            </xsl:when>
+            <xsl:otherwise>
+              <xsl:text>steps</xsl:text>
+            </xsl:otherwise>
+          </xsl:choose>
+        </xsl:variable>
+        <xsl:element name="{$name}">
+          <xsl:for-each select="$list/li">
+            <xsl:call-template name="step-substep">
+              <xsl:with-param name="type" select="'step'" />
+            </xsl:call-template>
+          </xsl:for-each>
+        </xsl:element>
+      </xsl:if>
+    </xsl:if>
+  </xsl:template>
+
+  <!-- Compose the step/substep element: -->
+  <xsl:template name="step-substep">
+    <xsl:param name="type" />
+    <xsl:element name="{$type}">
+      <xsl:choose>
+        <xsl:when test="text()">
+          <xsl:variable name="info-element" select="*[not(contains($cmd-children, concat(' ', name(), ' ')))][1]" />
+          <xsl:choose>
+            <xsl:when test="$info-element">
+              <xsl:call-template name="compose-element">
+                <xsl:with-param name="name" select="'cmd'" />
+                <xsl:with-param name="contents" select="$info-element/preceding-sibling::*|$info-element/preceding-sibling::text()" />
+              </xsl:call-template>
+              <xsl:call-template name="info">
+                <xsl:with-param name="parent" select="$type" />
+                <xsl:with-param name="contents" select="$info-element|$info-element/following-sibling::*|$info-element/following-sibling::text()" />
+              </xsl:call-template>
+            </xsl:when>
+            <xsl:otherwise>
+              <xsl:call-template name="compose-element">
+                <xsl:with-param name="name" select="'cmd'" />
+                <xsl:with-param name="contents" select="text()|*" />
+              </xsl:call-template>
+            </xsl:otherwise>
+          </xsl:choose>
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:call-template name="compose-element">
+            <xsl:with-param name="name" select="'cmd'" />
+            <xsl:with-param name="contents" select="*[1]/text()|*[1]/*" />
+          </xsl:call-template>
+          <xsl:if test="*[2]">
+            <xsl:call-template name="info">
+              <xsl:with-param name="parent" select="$type" />
+              <xsl:with-param name="contents" select="*[position() > 1]" />
+            </xsl:call-template>
+          </xsl:if>
+        </xsl:otherwise>
+      </xsl:choose>
+    </xsl:element>
+  </xsl:template>
+
+  <!-- Compose the info element: -->
+  <xsl:template name="info">
+    <xsl:param name="parent" />
+    <xsl:param name="contents" />
+    <xsl:choose>
+      <xsl:when test="$parent = 'step'">
+        <xsl:call-template name="info-substeps">
+          <xsl:with-param name="contents" select="$contents" />
+        </xsl:call-template>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:call-template name="compose-element">
+          <xsl:with-param name="name" select="'info'" />
+          <xsl:with-param name="contents" select="$contents" />
+        </xsl:call-template>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:template>
+
+  <!-- Compose alternating info/substeps elements: -->
+  <xsl:template name="info-substeps">
+    <xsl:param name="contents" />
+    <xsl:variable name="substeps-count" select="count($contents[self::ol])" />
+    <xsl:variable name="first-info" select="$contents[following-sibling::ol[$substeps-count]]" />
+    <xsl:if test="$substeps-count = 0">
+      <xsl:call-template name="compose-element">
+        <xsl:with-param name="name" select="'info'" />
+        <xsl:with-param name="contents" select="$contents" />
+      </xsl:call-template>
+    </xsl:if>
+    <xsl:if test="$first-info">
+      <xsl:call-template name="compose-element">
+        <xsl:with-param name="name" select="'info'" />
+        <xsl:with-param name="contents" select="$first-info" />
+      </xsl:call-template>
+    </xsl:if>
+    <xsl:for-each select="$contents[self::ol]">
+      <xsl:variable name="current-position" select="position()" />
+      <xsl:element name="substeps">
+        <xsl:for-each select="li">
+          <xsl:call-template name="step-substep">
+            <xsl:with-param name="type" select="'substep'" />
+          </xsl:call-template>
+        </xsl:for-each>
+      </xsl:element>
+      <xsl:choose>
+        <xsl:when test="following-sibling::ol">
+          <xsl:call-template name="compose-element">
+            <xsl:with-param name="name" select="'info'" />
+            <xsl:with-param name="contents" select="following-sibling::*[following-sibling::ol[$substeps-count - $current-position]]" />
+          </xsl:call-template>
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:variable name="last-info" select="following-sibling::*|following-sibling::text()" />
+          <xsl:if test="$last-info">
+            <xsl:call-template name="compose-element">
+              <xsl:with-param name="name" select="'info'" />
+              <xsl:with-param name="contents" select="$last-info" />
+            </xsl:call-template>
+          </xsl:if>
+        </xsl:otherwise>
+      </xsl:choose>
+    </xsl:for-each>
+  </xsl:template>
+
+  <!-- Helper: Compose an element with the given name and contents: -->
+  <xsl:template name="compose-element">
+    <xsl:param name="name" />
+    <xsl:param name="contents" />
+    <xsl:if test="$contents">
+      <xsl:element name="{$name}">
+        <xsl:apply-templates select="$contents" />
+      </xsl:element>
+    </xsl:if>
+  </xsl:template>
+
+</xsl:stylesheet>

dita/convert/xslt/task.xsl

@@ -0,0 +1,255 @@
+<?xml version='1.0' encoding='utf-8' ?>
+
+<!--
+  Copyright (C) 2024 Jaromir Hradilek
+
+  A custom XSLT stylesheet to convert a generic DITA topic to a specialized
+  DITA task topic:
+
+    1. Any contents preceding the first ordered list is  considered part of
+       the <context> element.
+    2. The first ordered list is transformed into <steps>.
+    3. Any contents following the first  ordered list is considered part of
+       the <result> element.
+
+  Sections are not permitted and will result in an error.
+
+  Usage: xsltproc ––novalid task.xsl YOUR_TOPIC.dita
+
+  MIT License
+
+  Permission  is hereby granted,  free of charge,  to any person  obtaining
+  a copy of  this software  and associated documentation files  (the "Soft-
+  ware"),  to deal in the Software  without restriction,  including without
+  limitation the rights to use,  copy, modify, merge,  publish, distribute,
+  sublicense, and/or sell copies of the Software,  and to permit persons to
+  whom the Software is furnished to do so,  subject to the following condi-
+  tions:
+
+  The above copyright notice  and this permission notice  shall be included
+  in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS",  WITHOUT WARRANTY OF ANY KIND,  EXPRESS
+  OR IMPLIED,  INCLUDING BUT NOT LIMITED TO  THE WARRANTIES OF MERCHANTABI-
+  LITY,  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT
+  SHALL THE AUTHORS OR COPYRIGHT HOLDERS  BE LIABLE FOR ANY CLAIM,  DAMAGES
+  OR OTHER LIABILITY,  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+  ARISING FROM,  OUT OF OR IN CONNECTION WITH  THE SOFTWARE  OR  THE USE OR
+  OTHER DEALINGS IN THE SOFTWARE.
+-->
+
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+  <!-- Compose the XML and DOCTYPE declarations: -->
+  <xsl:output encoding="utf-8" method="xml" doctype-system="task.dtd" doctype-public="-//OASIS//DTD DITA Task//EN" />
+
+  <!-- Format the XML output: -->
+  <xsl:output indent="yes" />
+  <xsl:strip-space elements="*" />
+  <xsl:preserve-space elements="codeblock pre screen" />
+
+  <!-- Report an error if the converted file is not a DITA topic: -->
+  <xsl:template match="/*[not(self::topic)]">
+    <xsl:message terminate="yes">ERROR: Not a DITA topic</xsl:message>
+  </xsl:template>
+
+  <!-- Report an error if the converted file contains a section: -->
+  <xsl:template match="//section">
+    <xsl:message terminate="yes">ERROR: Section not allowed in a DITA task</xsl:message>
+  </xsl:template>
+
+  <!-- Define a list of valid cmd element children: -->
+  <xsl:variable name="cmd-children" select="' abbreviated-form apiname b boolean cite cmdname codeph data data-about draft-comment equation-inline filepath fn foreign i image indexterm indextermref keyword line-through markupname mathml menucascade msgnum msgph numcharref option overline parameterentity parmname ph q required-cleanup sort-as state sub sup svg-container synph systemoutput term text textentity tm tt u uicontrol unknown userinput varname wintitle xmlatt xmlelement xmlnsname xmlpi xref '" />
+
+  <!-- Perform identity transformation: -->
+  <xsl:template match="@*|node()">
+    <xsl:copy>
+      <xsl:apply-templates select="@*|node()" />
+    </xsl:copy>
+  </xsl:template>
+
+  <!-- Transform the root element: -->
+  <xsl:template match="/topic">
+    <xsl:element name="task">
+      <xsl:apply-templates select="@*|node()" />
+    </xsl:element>
+  </xsl:template>
+
+  <!-- Transform the body element: -->
+  <xsl:template match="body">
+    <xsl:element name="taskbody">
+      <xsl:variable name="steps" select="ol[1]" />
+      <xsl:call-template name="context">
+        <xsl:with-param name="steps" select="$steps" />
+      </xsl:call-template>
+      <xsl:call-template name="steps">
+        <xsl:with-param name="steps" select="$steps" />
+      </xsl:call-template>
+      <xsl:call-template name="result">
+        <xsl:with-param name="steps" select="$steps" />
+      </xsl:call-template>
+    </xsl:element>
+  </xsl:template>
+
+  <!-- Compose the context element: -->
+  <xsl:template name="context">
+    <xsl:param name="steps" />
+    <xsl:choose>
+      <xsl:when test="$steps">
+        <xsl:call-template name="compose-element">
+          <xsl:with-param name="name" select="'context'" />
+          <xsl:with-param name="contents" select="ol[1]/preceding-sibling::*" />
+        </xsl:call-template>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:call-template name="compose-element">
+          <xsl:with-param name="name" select="'context'" />
+          <xsl:with-param name="contents" select="*" />
+        </xsl:call-template>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:template>
+
+  <!-- Compose the steps element: -->
+  <xsl:template name="steps">
+    <xsl:param name="steps" />
+    <xsl:if test="$steps">
+      <xsl:element name="steps">
+        <xsl:for-each select="$steps/li">
+          <xsl:call-template name="step-substep">
+            <xsl:with-param name="type" select="'step'" />
+          </xsl:call-template>
+        </xsl:for-each>
+      </xsl:element>
+    </xsl:if>
+  </xsl:template>
+
+  <!-- Compose the result element: -->
+  <xsl:template name="result">
+    <xsl:param name="steps" />
+    <xsl:if test="$steps">
+      <xsl:call-template name="compose-element">
+        <xsl:with-param name="name" select="'result'" />
+        <xsl:with-param name="contents" select="ol[1]/following-sibling::*" />
+      </xsl:call-template>
+    </xsl:if>
+  </xsl:template>
+
+  <!-- Compose the step/substep element: -->
+  <xsl:template name="step-substep">
+    <xsl:param name="type" />
+    <xsl:element name="{$type}">
+      <xsl:choose>
+        <xsl:when test="text()">
+          <xsl:variable name="info-element" select="*[not(contains($cmd-children, concat(' ', name(), ' ')))][1]" />
+          <xsl:choose>
+            <xsl:when test="$info-element">
+              <xsl:call-template name="compose-element">
+                <xsl:with-param name="name" select="'cmd'" />
+                <xsl:with-param name="contents" select="$info-element/preceding-sibling::*|$info-element/preceding-sibling::text()" />
+              </xsl:call-template>
+              <xsl:call-template name="info">
+                <xsl:with-param name="parent" select="$type" />
+                <xsl:with-param name="contents" select="$info-element|$info-element/following-sibling::*|$info-element/following-sibling::text()" />
+              </xsl:call-template>
+            </xsl:when>
+            <xsl:otherwise>
+              <xsl:call-template name="compose-element">
+                <xsl:with-param name="name" select="'cmd'" />
+                <xsl:with-param name="contents" select="text()|*" />
+              </xsl:call-template>
+            </xsl:otherwise>
+          </xsl:choose>
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:call-template name="compose-element">
+            <xsl:with-param name="name" select="'cmd'" />
+            <xsl:with-param name="contents" select="*[1]/text()|*[1]/*" />
+          </xsl:call-template>
+          <xsl:if test="*[2]">
+            <xsl:call-template name="info">
+              <xsl:with-param name="parent" select="$type" />
+              <xsl:with-param name="contents" select="*[position() > 1]" />
+            </xsl:call-template>
+          </xsl:if>
+        </xsl:otherwise>
+      </xsl:choose>
+    </xsl:element>
+  </xsl:template>
+
+  <!-- Compose the info element: -->
+  <xsl:template name="info">
+    <xsl:param name="parent" />
+    <xsl:param name="contents" />
+    <xsl:choose>
+      <xsl:when test="$parent = 'step'">
+        <xsl:call-template name="info-substeps">
+          <xsl:with-param name="contents" select="$contents" />
+        </xsl:call-template>
+      </xsl:when>
+      <xsl:otherwise>
+        <xsl:call-template name="compose-element">
+          <xsl:with-param name="name" select="'info'" />
+          <xsl:with-param name="contents" select="$contents" />
+        </xsl:call-template>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:template>
+
+  <!-- Compose alternating info/substeps elements: -->
+  <xsl:template name="info-substeps">
+    <xsl:param name="contents" />
+    <xsl:variable name="substeps-count" select="count($contents[self::ol])" />
+    <xsl:variable name="first-info" select="$contents[following-sibling::ol[$substeps-count]]" />
+    <xsl:if test="$substeps-count = 0">
+      <xsl:call-template name="compose-element">
+        <xsl:with-param name="name" select="'info'" />
+        <xsl:with-param name="contents" select="$contents" />
+      </xsl:call-template>
+    </xsl:if>
+    <xsl:if test="$first-info">
+      <xsl:call-template name="compose-element">
+        <xsl:with-param name="name" select="'info'" />
+        <xsl:with-param name="contents" select="$first-info" />
+      </xsl:call-template>
+    </xsl:if>
+    <xsl:for-each select="$contents[self::ol]">
+      <xsl:variable name="current-position" select="position()" />
+      <xsl:element name="substeps">
+        <xsl:for-each select="li">
+          <xsl:call-template name="step-substep">
+            <xsl:with-param name="type" select="'substep'" />
+          </xsl:call-template>
+        </xsl:for-each>
+      </xsl:element>
+      <xsl:choose>
+        <xsl:when test="following-sibling::ol">
+          <xsl:call-template name="compose-element">
+            <xsl:with-param name="name" select="'info'" />
+            <xsl:with-param name="contents" select="following-sibling::*[following-sibling::ol[$substeps-count - $current-position]]" />
+          </xsl:call-template>
+        </xsl:when>
+        <xsl:otherwise>
+          <xsl:variable name="last-info" select="following-sibling::*|following-sibling::text()" />
+          <xsl:if test="$last-info">
+            <xsl:call-template name="compose-element">
+              <xsl:with-param name="name" select="'info'" />
+              <xsl:with-param name="contents" select="$last-info" />
+            </xsl:call-template>
+          </xsl:if>
+        </xsl:otherwise>
+      </xsl:choose>
+    </xsl:for-each>
+  </xsl:template>
+
+  <!-- Helper: Compose an element with the given name and contents: -->
+  <xsl:template name="compose-element">
+    <xsl:param name="name" />
+    <xsl:param name="contents" />
+    <xsl:if test="$contents">
+      <xsl:element name="{$name}">
+        <xsl:apply-templates select="$contents" />
+      </xsl:element>
+    </xsl:if>
+  </xsl:template>
+
+</xsl:stylesheet>

dita/convert/xslt.py

@@ -0,0 +1,33 @@
+# Copyright (C) 2024 Jaromir Hradilek
+
+# MIT License
+#
+# Permission  is hereby granted,  free of charge,  to any person  obtaining
+# a copy of  this software  and associated documentation files  (the "Soft-
+# ware"),  to deal in the Software  without restriction,  including without
+# limitation the rights to use,  copy, modify, merge,  publish, distribute,
+# sublicense, and/or sell copies of the Software,  and to permit persons to
+# whom the Software is furnished to do so,  subject to the following condi-
+# tions:
+#
+# The above copyright notice  and this permission notice  shall be included
+# in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS",  WITHOUT WARRANTY OF ANY KIND,  EXPRESS
+# OR IMPLIED,  INCLUDING BUT NOT LIMITED TO  THE WARRANTIES OF MERCHANTABI-
+# LITY,  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT
+# SHALL THE AUTHORS OR COPYRIGHT HOLDERS  BE LIABLE FOR ANY CLAIM,  DAMAGES
+# OR OTHER LIABILITY,  WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+# ARISING FROM,  OUT OF OR IN CONNECTION WITH  THE SOFTWARE  OR  THE USE OR
+# OTHER DEALINGS IN THE SOFTWARE.
+
+from pathlib import Path
+
+# Define which symbols are to be exported:
+__all__ = ['concept', 'reference', 'task', 'task_generated' ]
+
+# XSLT file paths:
+concept        = Path(__file__).parent / 'xslt/concept.xsl'
+reference      = Path(__file__).parent / 'xslt/reference.xsl'
+task           = Path(__file__).parent / 'xslt/task.xsl'
+task_generated = Path(__file__).parent / 'xslt/task-generated.xsl'

dita_convert-1.0.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+Copyright (C) 2024 Jaromir Hradilek
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

dita_convert-1.0.0.dist-info/METADATA

@@ -0,0 +1,19 @@
+Metadata-Version: 2.1
+Name: dita-convert
+Version: 1.0.0
+Summary: Convert a generic DITA topic to a specialized concept, task, or reference.
+Author-email: Jaromir Hradilek <jhradilek@gmail.com>
+Project-URL: Homepage, https://github.com/jhradilek/dita-custom-xslt
+Project-URL: Repository, https://github.com/jhradilek/dita-custom-xslt
+Project-URL: Issues, https://github.com/jhradilek/dita-custom-xslt/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Documentation
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: lxml >=4.9.2
+

dita_convert-1.0.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+dita/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dita/convert/__init__.py,sha256=fHAajA4TJxTH5fOA-0DpEGbf341hXGPM-odHeCg0eEE,1552
+dita/convert/__main__.py,sha256=wSZ4tvdFNJdMR-QvkIOGcIAfGhJxdug_2AFT4ZDoRWc,1215
+dita/convert/cli.py,sha256=ZN4B5-n2tgUvF6T50noHC1WTESbiEjsjmLY94ihK6gY,4135
+dita/convert/transform.py,sha256=L2wzDkxJpOEQjco5dS-vc82UcqutGynd-vEijwXpvYw,1560
+dita/convert/xslt.py,sha256=FwblAeb288PG3gNT1kSjQNhyqcsBpa2xNLWgcdzqMnM,1545
+dita/convert/xslt/concept.xsl,sha256=6d_JvtQvt47xlmoGulo2_4D35n2Pyu_jdsAMDg-juNE,2552
+dita/convert/xslt/reference.xsl,sha256=DuFIF6WYmeKN7CLx2RpCPBI-QkREaiN1SZdw2jL0waU,2995
+dita/convert/xslt/task-generated.xsl,sha256=d7xYIqwR8cOEj9GRLRrue08GutNOvU65CPBt66Sp_CM,12728
+dita/convert/xslt/task.xsl,sha256=X0Vw1CDSpzRB04Yi8J3sYIf6x3Q1n_CT_EhA9s7_aW0,10375
+dita_convert-1.0.0.dist-info/LICENSE,sha256=FMHDtn9pVEoLrhKfIUfnY9tL4CYO5vwLv62mCQgSC20,1073
+dita_convert-1.0.0.dist-info/METADATA,sha256=9GcsdDw7PUlZYCxHqZHmMRjocct269L-cJtsseM7Eo8,798
+dita_convert-1.0.0.dist-info/WHEEL,sha256=GV9aMThwP_4oNCtvEC2ec3qUYutgWeAzklro_0m4WJQ,91
+dita_convert-1.0.0.dist-info/entry_points.txt,sha256=WaZkA6L5pH0XjsXOnzc_DLemaL3gfBR_hLsUc7fG38A,61
+dita_convert-1.0.0.dist-info/top_level.txt,sha256=pcySPGjS3m2yMBIIBm9b-Zdh7qTNpybOV9OxOjETKas,5
+dita_convert-1.0.0.dist-info/RECORD,,

dita_convert-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.1.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

dita_convert-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dita-convert = dita.convert.cli:parse_args

dita_convert-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+dita