<div align="center">
    
<img src="https://raw.githubusercontent.com/ietf-tools/common/main/assets/logos/xml2rfc.svg" alt="XML2RFC" height="125" />
    
[![Release](https://img.shields.io/github/release/ietf-tools/xml2rfc.svg?style=flat&maxAge=600)](https://github.com/ietf-tools/xml2rfc/releases)
[![License](https://img.shields.io/github/license/ietf-tools/xml2rfc)](https://github.com/ietf-tools/xml2rfc/blob/main/LICENSE)
[![PyPI - Version](https://img.shields.io/pypi/v/xml2rfc)](https://pypi.org/project/xml2rfc/)
[![PyPI - Status](https://img.shields.io/pypi/status/xml2rfc)](https://pypi.org/project/xml2rfc/)
[![PyPI - Format](https://img.shields.io/pypi/format/xml2rfc)](https://pypi.org/project/xml2rfc/)
    
##### Generate RFCs and IETF drafts from document source in XML according to the IETF xml2rfc v2 and v3 vocabularies
    
</div>

- [Changelog](https://github.com/ietf-tools/xml2rfc/blob/main/CHANGELOG.md)
- [Installation](#installation)
- [Docker container](#docker-container)
- [Updating xml2rfc](#updating-xml2rfc)
- [Usage](#usage)
- [Contributing](https://github.com/ietf-tools/.github/blob/main/CONTRIBUTING.md)
- [Getting Started](#getting-started)
    - [Git Cloning Tips](#git-cloning-tips)
    - [Docker Dev Environment](#docker-dev-environment)
- [Release Procedure](https://github.com/ietf-tools/.github/blob/main/CONTRIBUTING.md#release-procedure)

---

### Introduction

The [IETF] uses a specific format for the standards and other documents it publishes as [RFCs], and for the draft documents which are produced when developing documents for publications. There exists a number of different tools to facilitate the formatting of drafts and RFCs according to the existing rules, and this tool, **xml2rfc**, is one of them. It takes as input an xml file that contains the text and meta-information about author names etc., and transforms it into suitably formatted output. The input xml file should follow the grammars in [RFC7749] *(for v2 documents)* or [RFC7991] *(for v3 documents)*.

[RFCXML vocabulary reference] is available at [authors.ietf.org].

**xml2rfc** provides a variety of output formats. See the command line help for a full list of formats. It also provides conversion from v2 to v3, and can run the [preptool] on its input.

### Installation

`xml2rfc` is available as Python package and container image (see [Docker-container-usage](#Docker-container-usage)).
You can install the python package with the following command:

```sh
pip install xml2rfc
```

If you're using [pipx](https://pipx.pypa.io/stable/), you can install `xml2rfc` with the following command:
```sh
pipx install xml2rfc
```

`xml2rfc` also provides `pdf` extra package to install required packages required for PDF file generation.
See [next section](#installation-of-support-libraries-for-the-pdf-formatter) about additional requirements for PDF generation.

To install `xml2rfc` with PDF generation support run:
```sh
pip install "xml2rfc[pdf]"
```

To install `pdf` extra with `pipx` run:
```sh
pipx install "xml2rfc[pdf]"
```

#### Installation of support libraries for the PDF-formatter

In order to generate PDFs, **xml2rfc** uses the [WeasyPrint] module, which depends on external libraries that must be installed as native packages on your platform, separately from the **xml2rfc** install.

1. First, install the **Pango**, and other required libraries on your system.  See installation instructions on the [WeasyPrint Docs].

2. Next, install WeasyPrint python modules using pip.

```sh
pip install "xml2rfc[pdf]"
```
3. Finally, install the required fonts:
  * Download latest fonts from [xml2rfc-fonts](https://github.com/ietf-tools/xml2rfc-fonts/releases/latest).
  * In the **Assets** section, download either the `tar.gz` or the `zip` archive.
  * Extract the contents of the downloaded `xml2rfc-fonts` archive.
  * Install the fonts found in the `noto` and `roboto_mono` directories to your operating system.

With these installed and available to **xml2rfc**, the `--pdf` switch will be enabled.

### Docker container

A series of docker images are available to accommodate various use cases. The table below describes the features of each image type. 

| Docker image name | Description                                                                              |
| ----------------- | ---------------------------------------------------------------------------------------- |
| xml2rfc-slim      | xml2rfc without PDF support; small image.                                                |
| xml2rfc-base      | xml2rfc with PDF generation and required fonts; large image.                             |
| xml2rfc-dev       | xml2rfc with multiple Python versions and development tools; large image for developers. |

Example using the `xml2rfc-slim` image:

```sh
docker run --rm `# automatically remove container upon termination` \
  -v "$(pwd):/data" `# bind current working directory to /data` \
  ghcr.io/ietf-tools/xml2rfc-slim:latest \
  --html example.xml
# if input is example.xml, output will be example.html
```

Single line:

```sh
docker run --rm -v "$(pwd):/data" ghcr.io/ietf-tools/xml2rfc-slim:latest --html example.xml
```

Development images are further documented under [#docker-dev-environment](#docker-dev-environment).

#### Image versioning

Docker image versions follow the regular release versioning.
Use a versioned tag to ensure reproducibility in CI / CD:

```sh
docker run --rm -v "$(pwd):/data" ghcr.io/ietf-tools/xml2rfc-slim:v3.32.0 --html example.xml
```

### Updating xml2rfc

To update `xml2rfc`, run the following command:
```sh
pip install --upgrade xml2rfc
```

If you are using `pipx`, you can update it with:
```sh
pipx upgrade xml2rfc
```

### Usage

**xml2rfc** accepts a single XML document as input and outputs to one or more conversion formats.

#### Basic Usage

```sh
xml2rfc SOURCE [options] FORMATS...
```

Run `xml2rfc --help` for a full listing of command-line options.

### Getting Started

This project is following the standard **Git Feature Workflow** development model. Learn about all the various steps of the development workflow, from creating a fork to submitting a pull request, in the [Contributing](https://github.com/ietf-tools/.github/blob/main/CONTRIBUTING.md) guide.

> Make sure to read the [Styleguides](https://github.com/ietf-tools/.github/blob/main/CONTRIBUTING.md#styleguides) section to ensure a cohesive code format across the project.

You can submit bug reports, enhancements and new feature requests in the [discussions](https://github.com/ietf-tools/xml2rfc/discussions) area. Accepted tickets will be converted to issues.

#### Git Cloning Tips

As outlined in the [Contributing](https://github.com/ietf-tools/.github/blob/main/CONTRIBUTING.md) guide, you will first want to create a fork of the xml2rfc project in your personal GitHub account before cloning it.

For example *(replace `USERNAME` with your GitHub username)*:

```sh
git clone https://github.com/USERNAME/xml2rfc.git
```
#### Docker Dev Environment

Run `./run.sh` command to build and start a docker development environment.
The initial build may take time because it downloads all required fonts as well.


```sh
./run.sh
```

[IETF]: https://www.ietf.org/
[RFCs]: https://www.rfc-editor.org/
[RFC7749]: https://www.rfc-editor.org/info/rfc7749
[RFC7991]: https://www.rfc-editor.org/info/rfc7991
[RFCXML vocabulary reference]: https://authors.ietf.org/en/rfcxml-vocabulary
[authors.ietf.org]: https://authors.ietf.org/
[preptool]: https://www.rfc-editor.org/info/rfc7998
[WeasyPrint]: https://weasyprint.org/
[WeasyPrint Docs]: https://doc.courtbouillon.org/weasyprint/stable/first_steps.html
