= SUSE XSL Stylesheets :numbered: :website: https://github.com/openSUSE/suse-xsl
This project contains customization layers for the DocBook XSL stylesheets.
== Requirements for use
xsltproc
or Saxon 6 (needs to have support for exslt)== 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:
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]. 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:
cat
, sed
, tar
, ...)trang
xsltproc
xmlcatalog
aspell
For the sass-css
target:
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
After changes to the SASS code: regenerate the suse2021 and suse2022 CSS: make sass-css
Create namespaced suse and suse2013 stylesheets: make
== 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:
Make sure everything you want to include is in the main
branch.
Run the versionbump
command with your next version:
./versionbump
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. a. Accept to let the script create a commit and a tag.
Switch to https://github.com/openSUSE/suse-xsl/releases[suse-xsl release] and make a release.