From sitapati at worldsankirtan.net Thu Sep 6 12:34:06 2012 From: sitapati at worldsankirtan.net (Sitapati das Joshua J Wulf) Date: Thu, 6 Sep 2012 22:34:06 +1000 Subject: [publican-list] Publican 3 brand -web packages Message-ID: 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//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 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/. 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 /css/overrides.css file to /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------------
/
 ------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: