[publican-list] Publican 3 brand -web packages

Thu Sep 6 12:34:06 UTC 2012

I'm converting my Publican 2 brand to Publican 3. Here's what I've got so
far, and my question (at the very end):

== Publican 2 vs Publican 3 brands ==

Publican 3 introduces -web brand packages. These packages are used to
centralize brand assets on the Publican 3 webserver rather than
distributing a copy of the brand files with each book. This is the
new-in-Publican-3 "web style 2" [1]

A Publican 3 desktop package of a book can be installed without the brand
package for that book being installed, because all the brand files needed
to render the book are compiled into the desktop package. However, a
Publican 3 web package of a book requires the web-version of the brand
package to be installed before it can be properly installed.

Publican 2 installs all the brand files for a book into the same directory
as the book, effectively making each book on the webserver self-sufficient.
This was inefficient use of space.

Publican 3 instead installs the brand files for a brand to a single
location, and rewrites the references in the book to point to the
centralized location. This is a more efficient use of space, and also means
that many brand updates can be applied without rebuilding the books that
use that brand*.

* with the caveat that brands that use xsl customizations require a book
rebuild when those xsl customizations are changed.

[1] https://www.redhat.com/archives/publican-list/2012-August/msg00006.html

== css filename differences between Publican 3 desktop and -web brand
packages ==

To build a book using a brand, you need to install the brand package. To
make a Desktop package or to build a book locally you need the local brand
package installed. The local brand package provides the files for Desktop
package and local builds.

When you build a Publican 3 book or a Publican 3 desktop package, the
overrides.css file from the brand
(/usr/share/publican/Common_Content/<brand_name>/en-US/css/overrides.css)
is included in the Common_Content folder of the local build output /
Desktop package, just like Publican 2.

A header (html <head> element content) is written into the html output of
the built Publican 3 book to include the default.css file. This file
imports the overrides.css file, so your brand customizations appear via
this mechanism.

To install a book on a Publican web server using web_style 2, the web
server needs the -web package for the brand installed. This installs your
brand content to /var/www/html/docs/<brand-name>. However, it does not
behave the same way as the Desktop package does. The only folders that are
installed are css and images. The css folder only contains a menu.css file,
if one exists -- overrides.css is not copied.

When you build a Publican 3 web package of a book, the header is written to
point to the menu.css of the brand.

To get a Publican 2 customised brand css to work in Publican 3 web server:

1. Copy the <lang>/css/overrides.css file to <lang>/css/menu.css in the
brand source to get it in the web package. The menu.css will be included in
the web package, and your brand css customisations will appear on the
Publican web server.

== Including .woff, .js, and other arbitrary assets in your brand ==

You can also use the css folder to include other resources for your built
html book, such as .woff web fonts and javascript files*. All the content
from the css folder is included in the Common_Content/css folder of the
built book / Desktop package, so you can write brand customizations that
inject references to these either via css (for .woff web fonts) or xsl
customizations for javascript files.

Any additional assets such as web fonts and javascript files however are
*not* copied into the css directory of the web version of the brand.

* [ https://bugzilla.redhat.com/show_bug.cgi?id=839975 is an RFE for a less
hacky way to do this]

To make a web-package of a brand, you modify the Publican 2 brand spec file
to include a Publican 3 -web sub-package, by adding content like this:

------------begin additional (to be merged) content------------

%package web
Summary: Web styles for %{brand}
Group: Documentation
Requires: publican >= 3.0

%description web
Web Site common files for the %{brand} brand.

%install
mkdir -p -m755 $RPM_BUILD_ROOT%{_datadir}/publican/Common_Content
publican install_brand
--path=$RPM_BUILD_ROOT%{_datadir}/publican/Common_Content
mkdir -p -m755 $RPM_BUILD_ROOT%{wwwdir}/%{brand}
publican install_brand --web --path=$RPM_BUILD_ROOT%{wwwdir}/%{brand}

%files web
%defattr(-,root,root,-)
%{wwwdir}/%{brand}

------------end additional (to be merged) content---------------

In the %install section, you will note that a --web option is passed to
publican install_brand to generate the web package for the brand.

You can add the additional assets to your brand by adding a copy operation
to the spec file:

--------begin hack------------

mkdir -p -m755 $RPM_BUILD_ROOT%{wwwdir}/%{brand}
publican install_brand --web --path=$RPM_BUILD_ROOT%{wwwdir}/%{brand}
cp -r en-US/css/* $RPM_BUILD_ROOT%{wwwdir}/%{brand}/en-US/css/

--------end hack--------------

The issue now, however, is that the path to these assets differs between
the Desktop / local build, and the web build.

In the local build / Desktop package you can rely on your web fonts and
javascript being in the Common_Content/css folder, and code your brand xsl
customizations accordingly; however the path will be different in the web
package.

In Publican 2 you can reliably do this in your brand xsl customization:

------begin brand html-single.xsl excerpt------------

<xsl:template name="user.footer.content">
   <div class="skynetBookID"><xsl:value-of
select="//productname[1]"/>/<xsl:value-of select="//title[1]"/></div>
   <script src="Common_Content/css/code-lang-switcher.js"></script>
   <script src="Common_Content/css/skynet-book.js"></script>
</xsl:template>

------end brand html-single.xsl excerpt------------

This will work for Publican 2 and for Publican 3 desktop packages and local
builds. However, the pathing is wrong for the Publican 3 web package.

For the Publican 3 web package the pathing needs to be:

   <script
src="../../../../../<brand_name>/en-US/css/code-lang-switcher.js">

Inside Publican it looks like the pathing of the brand assets in the header
is accomplished by templating in the file
/usr/share/publican/templates/web_2_head.tmpl, rather than through xsl
customization or spec file settings.

I haven't yet been able to figure out a way to intercept this functionality
outside of modifying the Publican source.

So my question, for anyone who is still reading and knows what I'm talking
about (Jeff, are you out there?):

Am I on the right track here? Is there a way to do this that I missed? XSL
parameters that can be set when building web vs desktop versions of books
maybe?

- Josh
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/publican-list/attachments/20120906/ac91b368/attachment.htm>