Customizing

[Haug Bürger]

I just played around with daps and I'm quite impressed.

The image handling just works, with pdf and html. The svg is
automatically converted and the size just fits. That's much better than
the alternatives I tried.

I'm now at the point where I would like to make the document look good.
The html defaults use the browser layout, which look quite ugly. I
wonder how to create a decent looking html document. The documentation
points to the stylesheets and ends there. The stylesheets look
frightening complex to me.

I wonder if there is an easier way to get a decent looking document and
customize, e.g. colors?

[Thomas Schraitle]

Hi Haug,

I just played around with daps and I'm quite impressed.

Thanks! :-)

I wonder how to create a decent looking html document. The documentation
points to the stylesheets and ends there. The stylesheets look frightening complex to me.

Yes, this is a bit pity. However, our documentation deals with DAPS and how to install and configure it. Explaining XSLT would go far beyond the scope.

Usually it boils down to two options:

• writing customization layers
• adapting parameters

Writing customization layers can be overwhelming at a first glance. After you've understood the concept, it isn't that difficult. I've wrote a book with typical DocBook XSL customizations. You can read it for free here:

http://doccookbook.sourceforge.net/html/en/index.html

Although it is not DAPS related, you can find the usual things: how to write customization layers, how to extract typical information, styling titles etc. It is written for print and online output formats. However, it may be still be complicated as it assume a certain level of XSLT expertise. Nevertheless, I've added a hint on each topic how difficult it is. That should makes things easier, although it could be highly subjective. ;)

I wonder if there is an easier way to get a decent looking document and customize, e.g. colors?

This would be the second option: adapting parameters. Each stylesheet consists of a bunch of parameters you can adapt. This is quite easy and you can see the result immediately. Find here some details:

http://opensuse.github.io/daps/doc/cha.daps.user.layout.html

We've thought about a DAPS developer guide, however it is not written yet. There is an issue on GitHub, here is the link:

https://github.com/openSUSE/daps/issues/203

Feel free to subscribe to it, if you are interested.

Hope that helps to sort this out.

Tom

[Haug Bürger]

Thanks for the tips. Parameters are nice but there is an even easier solution!

In the file DC-daps-example is:

##-------------------
## Custom Stylesheets
## (if not defined, the DocBook stylesheets will be used)
##
#STYLEROOT=""
#FALLBACK_STYLEROOT=""
HTML_CSS="__your_favorite_css__.css.xml"
#EPUB_CSS=""

You have to make sure it is an XML file like:

<?xml version="1.0"?>
<style>
h3 { 
font: italic normal 1.4em georgia, sans-serif;
letter-spacing: 1px; 
margin-bottom: 0; 
color: #7D775C;
}
</style>

This way you can easily change fonts, colors and sizes of the HTML output. Just drop in your favorite CSS.

If you want the TOC on a different place or JavaScript menues you probably need XSL transformations. But for a decent looking HTML the CSS works great.

This tip would fit nicely into chapter 9 "Customizing Layout of the Output Formats" of the documentation.

[Frank Sundermeyer]

Hi,

specifying a plain CSS file with HTML_CSS (rather than an XML file as you are suggesting) should work. Using an absolute path is recommended. Applying a custom CSS file aslo works with ePUB (EPUB_CSS).
This, however, does not help when wanting to provide complex CSS consisting of multiple CSS files and images. DAPS supports "--statdir=<DIR>" for such a purpose.

static/
          |-css/
          |-js/
          |-images/

The contents of static/ will be copied to the HTML result directory. If a custom --statdir is specified, DAPS assumes that the admonition graphics (tip, note, etc), navigation graphics, and callout graphics are located in the images/ subdirectory. The first *.css file in the css/ subdirectory will also be used automatically (so prefixing the filename with "0" is recommended).

However, providing a custom CSS does not help when creating PDFs. Therefore we are planning to make creating a custom brand based on an XSL skeleton easier:

• https://github.com/openSUSE/daps/issues/308
• https://github.com/openSUSE/daps/issues/65

But that's a rather complex undertaking, so I cannot say when it will be ready. We haven't even started, yet, but are planning to start with a one week coding sprint in early December... .