Configuration

DocbookCS is configured via docbookcs.xml. The schema is published at https://php.github.io/docbook-cs/config.xsd so any modern XML-aware IDE gives you autocomplete and validation automatically.

IDE integration

PhpStorm and VS Code (with the Red Hat XML extension) pick up the schema automatically when the namespace and xsi:schemaLocation declarations are present.

PHP manual example

The config below reflects the setup used for the PHP manual:

docbookcs.xml

<?xml version="1.0" encoding="UTF-8"?>
<docbookcs xmlns="https://php.github.io/docbook-cs/config"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="https://php.github.io/docbook-cs/config
                               https://php.github.io/docbook-cs/config.xsd">

    <project>
        <directory alias="doc-en">en</directory>
        <directory>doc-base</directory>
    </project>

    <sniffs>
        <sniff class="DocbookCS\Sniff\SimparaSniff" />
        <sniff class="DocbookCS\Sniff\ExceptionNameSniff" />
        <sniff class="DocbookCS\Sniff\AttributeOrderSniff" />
        <sniff class="DocbookCS\Sniff\TrailingWhitespaceSniff" />
        <sniff class="DocbookCS\Sniff\MixedIndentationSniff" />
    </sniffs>

    <entities>
        <file>contributors.ent</file>
        <file>extensions.ent</file>
        <file>language-defs.ent</file>
        <file>language-snippets.ent</file>
        <directory>../doc-base/entities/</directory>
        <file>../doc-base/temp/file-entities.ent</file>
        <directory>../doc-base/temp/file-entities</directory>
    </entities>

    <exclude>
        <pattern>*/wkhtmltox/bits/*</pattern>
        <pattern>output/*</pattern>
    </exclude>

</docbookcs>

Sections

<project>

Optional. Declares the root directory names that are expected to exist as siblings of the config file. Each <directory> may carry an optional alias attribute to accept an alternative directory name as the same logical root.

If <project> is omitted, DocbookCS infers the project root from the directory containing the config file.

<sniffs>

Required. Register sniffs by fully-qualified class name. Each <sniff> accepts optional <property> children:

<sniff class="DocbookCS\Sniff\SimparaSniff">
    <property name="additionalInlineElements" value="productname,trademark"/>
</sniff>

<paths>

Still accepted by the schema, but no longer applied: the scan scope is determined entirely by the command-line input. Without arguments, DocbookCS checks the Git diff from the upstream branch point; pass paths or pipe a diff to select a different scope — see Scope.

<exclude>

fnmatch-style patterns for paths to skip during scanning.

<entities>

Entity file paths and directories to load before parsing, so the XML parser can resolve DocBook entities defined outside the scanned tree. Accepts interleaved <file> and <directory> children in any order.

Entity files may declare entities in DTD syntax or in XML format:

<!-- DTD syntax -->
<!ENTITY example.note "This is a note.">
<!ENTITY example.chapter SYSTEM "chapters/example.xml">

<!-- XML format -->
<entity name="example.note">This is a note.</entity>

SYSTEM entities are resolved recursively, including entities declared in the referenced files. Content that enters a document through entity expansion is reported against its actual source file — not against every file that references the entity.