css2xsl
=======

----------------------------

CSS2XSL ("CSS to XSL") is a utility that reads a Rexx highlighting
CSS theme (e.g. `rexx-print.css`) and generates an XSL stylesheet
with `fo:inline` templates for all `rexx_*` elements.  The generated
`.xsl` file is meant to be `xsl:include`'d from the `pdf.xsl`
customization layer used by DocBook XSL + Apache FOP.

This utility is part of the DocBook highlighting workflow, which
allows Rexx code in DocBook `<programlisting>` blocks to be
syntax-highlighted in PDF output produced by Publican or any other
DocBook XSL + FOP toolchain.

### Usage

<pre>
[rexx] css2xsl [<em>options</em>] [<em>output.xsl</em>]
</pre>

If no output file is specified, the default is `rexx-highlight.xsl`.

### Options

----------------------------------------------- --------------------------------
`-s`, `--style` <code><em>STYLE</em></code>     CSS theme name (default: `print`)
`--css` <code><em>FILE</em></code>              CSS file path (overrides `--style`)
`--operator` <code><em>MODE</em></code>         Operator granularity: `group`|`full`|`detail`
`--special` <code><em>MODE</em></code>          Special char granularity: `group`|`full`|`detail`
`--constant` <code><em>MODE</em></code>         Constant granularity: `group`|`full`|`detail`
`--assignment` <code><em>MODE</em></code>       Assignment granularity: `group`|`full`|`detail`
`-h`, `--help`                                  Display help and exit
----------------------------------------------- --------------------------------

\

The default granularity is `group` for all categories.

### Granularity modes

The granularity options control how much detail is preserved in the
generated XSL templates for operators, specials, constants and
assignments.  Each category can be set independently:

- **group** — All elements in a category share the same visual style,
  determined by the generic CSS class (e.g. all operators use the style
  of `rx-op`).  This is the default.
- **full** — Each element gets both generic and specific classes
  (e.g. `rx-op rx-add`), generating one template per combination.
  This is how the CSS cascade works in HTML.
- **detail** — Only elements that have their own specific CSS rules
  get individual templates.  Elements without specific rules inherit
  the group style.  This produces the fewest templates when the CSS
  theme does not differentiate within a category.

### Element naming convention

The XSL templates match XML elements whose names are derived from
the CSS classes by stripping the `rx-` prefix, replacing hyphens
with underscores, and joining them under the `rexx_` prefix:

- `rx-kw` → `rexx_kw`
- `rx-op rx-add` → `rexx_op_add`
- `rx-const rx-method rx-oquo` → `rexx_const_method_oquo`

This is the same naming convention used by the
[DocBook highlighting driver](../../highlighter/docbook/)
in `highlight.rex`.

### Generated output

The output is a valid XSL stylesheet containing `xsl:template`
elements that match `rexx_*` elements and emit `fo:inline` with the
appropriate visual attributes (`font-weight`, `font-style`,
`text-decoration`, `color`).  Background color is not emitted for
inline elements, since the `<programlisting>` already has a
background set by the DocBook XSL.

For example, a keyword template might look like:

```xml
<xsl:template match="rexx_kw">
  <fo:inline font-weight="bold" color="#4169E1">
    <xsl:apply-templates/>
  </fo:inline>
</xsl:template>
```

The number of templates depends on the granularity: `group` mode
with the default `print` theme generates 83 templates; `full` mode
generates 234 templates.

### Integration with DocBook

To use the generated XSL in a DocBook toolchain:

1. Run `css2xsl` to generate the XSL file.
2. Copy the generated file to your DocBook customization directory.
3. Add `<xsl:include href="rexx-highlight.xsl"/>` to your `pdf.xsl`
   customization layer.
4. In your DocBook XML source, use `<programlisting>` blocks
   containing `rexx_*` elements (generated by `highlight --docbook`).

### Prerequisites

No external dependencies beyond the Rexx Parser itself.  The generated
XSL file is standalone and does not require css2xsl at runtime.

### Program source

~~~rexx {source=../../../bin/css2xsl.rex}
~~~
