Documentation Tools

Changeset 208


Ignore:
Timestamp:
08/26/07 16:59:31 (5 years ago)
Author:
kate
Message:

This commit refactors the file structure, and adds theme support.

The directories and files have been re-worked a little, hopefully to make things a little cleaner. The Makefiles are also a little more flexible in overriding the locations and other specific flags.

All WPI-specific customisation is now in its own theme, which is provided by default. Themes are included from the docbook makefile as a central point to override the various things they might need to; this should make adding future themes less chaotic - either bundled with doctools or specific to a user's application.

Hopefully this doesn't break compatibility for anybody.

Location:
trunk
Files:
9 added
4 edited
8 moved

Legend:

Unmodified
Added
Removed

  • trunk/Mk/docbook.mk

    r207 r208  
    1414PDFDIR ?= $(DOCTOOLS_OUTPUT)/pdf 
    1515 
     16# Themes 
     17# These set the default; the selected theme then overrides the various 
     18# variables set below, according to its specific needs. Everything else 
     19# set in this file are theme-independant defaults to be overriden. 
     20# 
     21# A theme must always be provided (documents without CSS are not 
     22# acceptable!); we default to the supplied WPI theme. 
     23# TODO we should default to something bland and generic, instead. 
     24THEMEDIR ?= $(DOCTOOLSDIR)/themes 
     25THEMENAME ?= wpi 
     26THEME ?= $(THEMEDIR)/$(THEMENAME) 
     27 
     28include $(THEME)/theme.mk 
     29 
    1630# XSLT 
    1731XSLT =                  xsltproc --xinclude 
    18 XHTMLSTYLE ?=   $(DOCTOOLSDIR)/xsl/docbook-chunked.xsl 
    19 XHTMLSTYLE_SINGLE ?=    $(DOCTOOLSDIR)/xsl/docbook-single.xsl 
     32XHTMLSTYLE ?=   $(DOCTOOLSDIR)/xsl/xhtml/xhtml-chunked.xsl 
     33XHTMLSTYLE_SINGLE ?=    $(DOCTOOLSDIR)/xsl/xhtml/xhtml-single.xsl 
    2034TEXMLSTYLE ?=   $(DOCTOOLSDIR)/xsl/texml.xsl 
    2135 
    … …  
    2640SOURCE_TEXML =  $(NAME)-texml.xml 
    2741SOURCE_TEX =    $(NAME).tex 
    28 TEXDIR ?=               $(DOCTOOLSDIR)/tex 
    2942 
    30 RESOURCES ?=    $(DOCTOOLSDIR)/resources/*.css $(DOCTOOLSDIR)/resources/*.png 
    31 # TODO rename CSSFILE and TEXFILE to wpi.* 
    32 CSSFILE ?=              docs.css         
    33 TEXFILE ?=              docs.tex 
     43# These are placeholders for themes to override. 
     44RESOURCES ?= 
     45CSSFILE ?= 
     46TEXFILE ?= 
     47TEXDIR ?= 
    3448 
    3549# The intention here is that you can override the TeX customisations, 
    … …  
    5468pdf: $(PDFDIR) $(PDFDIR)/$(SOURCE_TEX) 
    5569        # XXX texexec misbehaves unless we cd 
    56         cd $(PDFDIR) && TEXINPUTS=".:$(TEXDIR):$(TEXINPUTS):" $(TEXEXEC) $(SOURCE_TEX) 
     70        cd $(PDFDIR) && TEXINPUTS=".:$(TEXDIR):$(DOCTOOLSDIR)/tex:$(TEXINPUTS):" $(TEXEXEC) $(SOURCE_TEX) 
    5771 
    5872 

  • trunk/themes/wpi/xhtml/common.xsl

    • Property svn:keywords set to Id
    r206 r208  
    11<?xml version='1.0' encoding="UTF-8"?> 
    22<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> 
     3        <!-- $Id$ --> 
     4 
     5        <!-- 
     6                This stylesheet contains WPI-specific XSLT customisations common to all 
     7                WPI projects, but not specifically to go on the WPI website. In other words, 
     8                a WPI project may include this for rendering user-facing documents outside 
     9                of water-powered.com - For example, the customisation for Puredocs API 
     10                documents may include this. 
     11        --> 
    312 
    413        <!-- WPI-specific parameters --> 
    5         <!-- TODO This file should be moved out under some WPI-specific theme directory --> 
    614        <xsl:param name="suppress.header.navigation">1</xsl:param> 
    715        <xsl:param name="suppress.footer.navigation">0</xsl:param> 

  • trunk/themes/wpi/xhtml/docbook.xsl

    • Property svn:keywords set to Id
    r206 r208  
    11<?xml version='1.0' encoding="UTF-8"?> 
    22<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> 
     3        <!-- $Id$ --> 
     4 
     5        <!-- 
     6                General docbook WPI-themed customisations. Do not include this file directly; 
     7                use the xhtml-{chunked,single}.xsl interfaces. 
     8 
     9                This file includes WPI-themed things such as the navigation headers, which 
     10                are only appropiate to documents which are to be placed on the WPI website 
     11                itself. 
     12 
     13                Therefore this may not be applicable to documented generated by specific 
     14                WPI projects (such as Puredocs). Those projects should provide their own 
     15                customisations, which may share common.xsl for elements common to both 
     16                but outside of the navigational headers and other website-specific items. 
     17        --> 
     18 
    319        <xsl:import href="common.xsl"/> 
    4         <xsl:import href="sanitize.xsl"/> 
    520 
    621        <xsl:output indent="yes"/> 
    … …  
    6277                <div id="footer"> 
    6378                        <p class="copyright"> 
    64                                 Copyright 2005-2007 <a href="http://ideas.water-powered.com">Water-Powered Ideas</a> 
     79                                Copyright 2005, 2006, 2007 <a href="http://ideas.water-powered.com">Water-Powered Ideas</a> 
    6580                                <br/> 
    6681                                All Rights Reserved.  

  • trunk/themes/wpi/xhtml/puredocs.xsl

    • Property svn:keywords set to Id
    r168 r208  
    11<?xml version='1.0' encoding="UTF-8"?> 
    22<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"> 
    3         <!-- 
    4         <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl"/> 
    5         --> 
     3        <!-- $Id$ --> 
     4 
     5        <!-- TODO this should probably be in the puredocs repository, or removed entirely. 
     6                It's for generating puredocs documentation, which doesn't have the WPI header 
     7                (i.e. it's aimed at puredocs users) --> 
    68         
    79        <xsl:import href="http://xsl.water-powered.com/puredocs/current/python-browser.xsl"/> 
    810        <xsl:import href="common.xsl"/> 
    9         <xsl:import href="sanitize.xsl"/> 
     11 
     12        <xsl:import href="../../../xsl/xhtml-chunked.xsl"/> 
    1013 
    1114        <xsl:param name="title"/> 
    … …  
    3538                <div id="footer"> 
    3639                        <p class="copyright"> 
    37                                 Copyright 2005-2007 <a href="http://ideas.water-powered.com">Water-Powered Ideas</a> 
     40                                Copyright 2005, 2006, 2007 <a href="http://ideas.water-powered.com">Water-Powered Ideas</a> 
    3841                                <br/> 
    3942                                All Rights Reserved.  

  • trunk/themes/wpi/xhtml/resources/api.css

    r144 r208  
     1/* 
     2 * TODO This should probably be moved out into the Puredocs repository. 
     3 */ 
     4 
    15@import url("http://ideas.water-powered.com/css/main.css"); 
    26 

  • trunk/themes/wpi/xhtml/resources/api.js

    r120 r208  
     1/* 
     2 * TODO This should probably be moved out into the Puredocs repository. 
     3 */ 
     4 
    15function show_elm(elm_id) { 
    26    document.getElementById(elm_id).style.display = 'block'; 

  • trunk/themes/wpi/xhtml/resources/olddoc.css

    r120 r208  
    8383} 
    8484.navfooter { 
    85         //border-bottom: 1px solid #E0E0E0; 
    86         //border-top: 1px solid #E0E0E0; 
     85        /*border-bottom: 1px solid #E0E0E0; */ 
     86        /*border-top: 1px solid #E0E0E0; */ 
    8787        background-color: #EFEFEF; 
    8888        border: 1px solid #EFEFEF; 
    8989        padding: 0.5em; 
    90 //      font-size: 90%; 
     90/*      font-size: 90%; */ 
    9191        margin: 0; 
    9292} 
    9393.navfooter * td, .navheader * td { 
    94         //border: 1px solid #E0E0E0; 
    95         //border: 1px solid red; 
     94        /*border: 1px solid #E0E0E0; */ 
     95        /*border: 1px solid red; */ 
    9696        padding: 0 1em; 
    9797} 
    … …  
    126126        padding: 0; 
    127127        border: 0; 
    128 //      line-height: 1.5em; 
     128/*      line-height: 1.5em; */ 
    129129} 
    130130 
    … …  
    135135} 
    136136td { 
    137         //background-color: #EFEFEF; 
     137        /*background-color: #EFEFEF; */ 
    138138} 
    139139 

  • trunk/xsl/xhtml-chunked.xsl

    r197 r208  
    33        <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl"/> 
    44 
    5         <xsl:import href="docbook.xsl"/> 
     5        <xsl:import href="xhtml/sanitize.xsl"/> 
    66 
    77        <xsl:template name="body.attributes"> 

  • trunk/xsl/xhtml-single.xsl

    r197 r208  
    33        <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"/> 
    44 
    5         <xsl:import href="docbook.xsl"/> 
     5        <xsl:import href="xhtml/sanitize.xsl"/> 
    66 
    77        <xsl:template name="body.attributes"> 
Note: See TracChangeset for help on using the changeset viewer.