Metadata-Version: 2.1
Name: dita-convert
Version: 1.0.1
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
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: lxml >=4.9.2

# DITA Custom XSLT

**dita-custom-xslt** is a set of XSLT stylesheets that convert a generic DITA topic to a specialized DITA concept, reference, or task. **dita_convert** is a Python 3 package that provides a convenient access to these stylesheets and a command-line utility to perform the conversions.

In combination with [asciidoctor-dita-topic](https://github.com/jhradilek/asciidoctor-dita-topic), this project can be used to rapidly convert AsciiDoc content to DITA.

## Installation

Install the `dita_convert` Python package:

```
python3 -m pip install --upgrade dita_convert
```

## Usage

### Using the command-line interface

To convert a DITA topic to a specialized DITA content type, run the following command:

```
python3 -m dita.convert -t TYPE TOPIC_FILE
```

For convenience, the package also provides a wrapper script that you can run directly as follows:

```
dita-convert -t concept sample.dita
```

Available `TYPE` values are `concept`, `reference`, `task`, and `task-generated` for converting files generated by [asciidoctor-dita-topic](https://github.com/jhradilek/asciidoctor-dita-topic) that follow the guidelines for procedure modules as defined  in the [Modular Documentation Reference Guide](https://redhat-documentation.github.io/modular-docs/).

### Using the Python interface 

To convert a DITA topic to a specialized DITA content type, the **dita_convert** package exports the corresponding `to_concept()`, `to_reference()`, `to_task()`, and `to_task_generated()` functions that return an ElementTree object:

```python
from lxml import etree
from dita.convert import to_task

# Parse the contents of a sample DITA topic file:
topic = etree.parse("topic.dita")

# Convert the DITA topic to a DITA task:
task  = to_task(topic)

# Print the resulting XML to standard output:
print(str(task))
```

If you prefer to work with the underlying XSLT stylesheets directly, you can access their Path objects as follows:

```python
from dita.convert import xslt

# Print the full path to the XSLT stylesheet for DITA reference:
print(xslt.reference)
```

Available variables are `concept`, `reference`, `task`, and `task_generated`.

## Copyright

Copyright © 2024 Jaromir Hradilek

This program is free software, released under the terms of the MIT license. It is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
