= SUSE XSL Stylesheets
:numbered:
:website: https://github.com/openSUSE/suse-xsl

This project contains customization layers for the DocBook XSL stylesheets.


== 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


== 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:

. Clone this repo if you haven't done yet.
. Memorize the path to your repo. In this procedure, we use the
   placeholder `SUSEXSL_REPO`.
. 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.
+
[source,bash]
----
dapsxsl ()
{
    local styleroot="<SUSEXSL_REPO>/suse2022-ns/";
    daps --styleroot=$styleroot $*
}
----

. Open a new shell.
. Use the `dapsxsl` command instead of `daps` to use the stylesheets from
  this repo.


== Building

=== 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`
* `sassc` (openSUSE's RPM-packaged version is good enough). For details, see https://github.com/openSUSE/suse-xsl/tree/main/source-assets/styles2022/sass[sass README]


=== Creating a build

1. Change the SASS code, if necessary.
1. Regenerate the suse2021 and suse2022 CSS: `make sass-css`
1. Create namespaced suse and suse2013 stylesheets: `make`
1. Create a new release (see below).


== Requirements for testing

* `dapscompare` from Documentation:Tools


== 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:

. 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).

. Perform the stylesheet changes.

. 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.

== 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.

1. Run the `versionbump` command with your next version:

    ./versionbump <NEXT_VERSION>

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

   a. Set your version number.
   a. Add a change log entry. You should always create one for
      each new version. Get an overview of all changes by using the
      following URL (replace the `PREV_VERSION` placeholder accordingly):
      https://github.com/openSUSE/suse-xsl/compare/PREV_VERSION...HEAD
   a. Accept to let the script create a commit and a tag.

1. Switch to https://github.com/openSUSE/suse-xsl/releases[suse-xsl release] and make a release
   at https://build.opensuse.org/package/show/Documentation:Tools/suse-xsl-stylesheets[OBS repo for stylesheets].
