SUSE XSL Stylesheets

This project contains customization layers for the DocBook XSL stylesheets.

1. Requirements for use

• DAPS from https://github.com/openSUSE/daps

• DocBook XSL stylesheets from https://github.com/docbook/xslt10-stylesheets

• XSLT processor like xsltproc or Saxon 6 (needs to have support for exslt)

• Python 3

2. Using the stylesheets with daps

In case you want to use the latest stylesheet from the main branch (and not the one that are installed on your system), proceed as follows:

1. Clone this repo if you haven’t done yet.

2. Memorize the path to your repo. In this procedure, we use the placeholder SUSEXSL_REPO.

3. Copy the following lines into your ~/.bashrc file. Don’t forget to replace <SUSEXSL_REPO> with the path to your cloned repo from the previous step.

   dapsxsl ()
   {
       local styleroot="<SUSEXSL_REPO>/suse2022-ns/";
       daps --styleroot=$styleroot $*
   }

4. Open a new shell.

5. Use the dapsxsl command instead of daps to use the stylesheets from this repo.

3. Building

3.1. Requirements

These stylesheets can be used as-is for DocBook 4 content. To use them with DocBook 5 content, build them with make. For a successful build, you will need:

• standard GNU utilities (cat, sed, tar, …​)

• trang

• xsltproc

• xmlcatalog

• aspell

For the sass-css target:

• sassc (openSUSE’s RPM-packaged version is good enough). For details, see sass README

3.2. Creating a build

• After changes to the SASS code: regenerate the suse2021 and suse2022 CSS: make sass-css

• Create namespaced suse and suse2013 stylesheets: make

4. Requirements for testing

• dapscompare from Documentation:Tools

5. Running tests

Note	The dapscompare test utility never left the beta state and does not have a maintainer currently.

The current tests are not run automatically and need some manual intervention for use. They are based upon creating reference images of test documents, making a code change and then creating updated images of the test documents. Then, you can compare the updated images to the reference images.

On the command line, do the following:

1. In the first invocation, run ./run_dapscompare.sh reference (from the tests/ directory). This will create reference images, that is the baseline from which you can judge if what you did was correct or not).

2. Perform the stylesheet changes.

3. Now run ./run_dapscompare.sh (without any arguments) again. This will create the comparison images. If there are changes between reference and comparison images, those will be shown to you in a GUI.

The reference images are currently not stored centrally: They differ somewhat, depending on, for example, font rendering settings between different computers.

6. Creating a new release

To create a new release, do the following steps:

1. Make sure everything you want to include is in the main branch.

2. Run the versionbump command with your next version:

   ./versionbump <NEXT_VERSION>

3. Answer the questions from the script. Confirm with typing y or type n to skip this question.

   1. Set your version number.

   2. Add a change log entry. You should always create one for each new version.

   3. Accept to let the script create a commit and a tag.

4. Switch to suse-xsl release and make a release.