2.2. Using and customizing the output

2.2.1. Recommended Apache configurations

To deep link to a topic inside the help set, simply link directly to the page. This help system uses no frameset, so nothing further is necessary.

Tip

See Chunking into multiple HTML files in Bob Stayton's DocBook XSL: The Complete Guide for information on controlling output file names and which files are chunked in DocBook.

When you perform a search, the results can include brief summaries. These are populated in one of two ways:

  • By adding role="summary" to a para or phrase in the chapter or section.

  • By adding an abstract to the chapterinfo or sectioninfo element.

To customize the look and feel of the help, study the following css files:

  • docs/common/css/positioning.css: This handles the Positioning of DIVs in appropriate positions. For example, it causes the leftnavigation div to appear on the left, the header on top, and so on. Use this if you need to change the relative positions or need to change the width/height etc.

  • docs/common/jquery/theme-redmond/jquery-ui-1.8.2.custom.css: This is the theming part which adds colors and stuff. This is a default theme comes with jqueryui unchanged. You can get any theme based your interest from this. (Themes are on right navigation bar.) Then replace the css theme folder (theme-redmond) with it, and change the xsl to point to the new css.

  • docs/common/jquery/treeview/jquery.treeview.css: This styles the toc Tree. Generally, you don't have to edit this file.

2.2.1. Recommended Apache configurations

If you are serving a long document from an Apache web server, we recommend you make the following additions or changes to your httpd.conf or .htaccess file. TODO: Explain what each thing does.

AddDefaultCharSet UTF-8 # 1
  
      # 480 weeks
      <FilesMatch "\.(ico|pdf|flv|jpg|jpeg|png|gif|js|css|swf)$"> # 2
      Header set Cache-Control "max-age=290304000, public"
      </FilesMatch>
      
      # 2 DAYS
      <FilesMatch "\.(xml|txt)$">
      Header set Cache-Control "max-age=172800, public, must-revalidate"
      </FilesMatch>
      
      # 2 HOURS
      <FilesMatch "\.(html|htm)$">
      Header set Cache-Control "max-age=7200, must-revalidate"
      </FilesMatch>
      
      # compress text, html, javascript, css, xml:
      AddOutputFilterByType DEFLATE text/plain # 3
      AddOutputFilterByType DEFLATE text/html
      AddOutputFilterByType DEFLATE text/xml
      AddOutputFilterByType DEFLATE text/css
      AddOutputFilterByType DEFLATE application/xml
      AddOutputFilterByType DEFLATE application/xhtml+xml
      AddOutputFilterByType DEFLATE application/rss+xml
      AddOutputFilterByType DEFLATE application/javascript
      AddOutputFilterByType DEFLATE application/x-javascript
      
      # Or, compress certain file types by extension:
      <Files *.html> 
      SetOutputFilter DEFLATE
      </Files>

1

See Odd characters in HTML output in Bob Stayton's book DocBook XSL: The Complete Guide for more information about this setting.

2

These lines and those that follow cause the browser to cache various resources such as bitmaps and JavaScript files. Note that caching JavaScript files could cause your users to have stale search indexes if you update your document since the search index is stored in JavaScript files.

3

These lines cause the the server to compress html, css, and JavaScript files and the brower to uncompress them to improve download performance.

Legal notices