[HT2HTML-devel] CVS: ht2html/doc style.ht,NONE,2.1 links.h,2.1,2.2

[Fred L. D. <fd...@us...>]

Update of /cvsroot/ht2html/ht2html/doc
In directory usw-pr-cvs1:/tmp/cvs-serv9757

Modified Files:
	links.h 
Added Files:
	style.ht 
Log Message:
Add documentation on the stylesheet support in the Skeleton class.

--- NEW FILE: style.ht ---
Title: ht2html.py -- A web page template processor

<h3>Using Stylesheets with HT2HTML</h3>

<p>The HTML generated by HT2HTML contains a lot of style-based markup
directly in the document.  You can control just how much of this is
done by controlling the generator class; the <tt>Skeleton</tt> class
is fairly agressive about controlling the page layout using
presentational markup, and tailoring that though subclassing can cause
a good deal of duplicated code.</p>

<p>Fortunately, support has been added to support using stylesheets
with HT2HTML, at least to some degree.  Each of the <a href=
"components.html">major components</a> of the page is assigned a class
attribute that can be used in a stylesheet, with some special
treatment for the continuation section.</p>

<h4>Page Component Classes</h4>

<p>Each of the page components is contained in an element which
carries a <tt>class</tt> attribute with the same name as the component
is given in the description of the <a href="components.html">page
components</a>.  The class names are given in all lower case.  The <a
href="components.html#continuation">continuation</a> component is
treated a little specially since the general expectation is that it's
content should be mostly like that of the <a href=
"components.html#body">body</a>.  Specifically, it is contained in a
pair of elements, the outer having the class <tt>body</tt> and the
inner having the class <tt>continuation</tt>.  This allows a style
sheet to set up all the normal body styles using the <tt>body</tt>
class, and speciallize anything that needs to be by using both both in
the selector, like this:</p>

<blockquote>
<pre>
.body h2               { font-size: 120%; }
.body .continuation h4 { font-size: 125%; }
</pre>
</blockquote>

<p>One common need is to add a little space between the edge of the
browser's canvas (the portion of the display the content actually gets
displayed on), and the text which is presented in the continuation
area.  This is needed since the normal margins are overridden so that
the <a href="components.html#banner">banner</a> and <a href=
"components.html#sidebar">sidebar</a> do not appear to be "floating"
on the page.  Using a stylesheet, this bit of CSS can be used to add
reasonable margins:</p>

<blockquote>
<pre>
.continuation { margin-left: 1em;
                margin-right: 1em; }
</pre>
</blockquote>

<h4>Generator Support</h4>

<p>The <tt>Skeleton</tt> generator base class supports two hooks that
allow generators to add style information.  Each of these takes the
form of a method that can be overridden if needed.</p>

<dl>
  <dt><code><b>get_style()</b></code></dt>
  <dd>Return a fragment of a stylesheet that will be embedded into the
  page directly:

  <blockquote>
  <pre>&lt;style type="text/css"&gt;
/* This was returned by get_style() */
&lt;/style&gt;</pre>
  </blockquote>

  <p>This stylesheet fragment must be written in CSS; XSLT is not
  supported here.  If this function returns a string with not style
  information, or any false value, the <tt>style</tt> element will not
  be generated.</p>
  </dd>

  <dt><code><b>get_stylesheet()</b></code></dt>
  <dd>This method should return a URL reference to the stylesheet that
  should be linked to from the generated page.  For example, if this
  method returns 'style.css', the following link will be added to the
  generated document head:

  <blockquote>
  <pre>&lt;link rel="STYLESHEET" href="style.css" type="text/css"&gt;</pre>
  </blockquote>

  <p>An XML-style stylesheet link will be added as well:</p>

  <blockquote>
  <pre>&lt;?xml-stylesheet href="style.css" type="text/css"?&gt;</pre>
  </blockquote>

  <p>The code that generates the document header understands the file
  extensions <tt>.css</tt>, <tt>.xsl</tt>, and <tt>.xslt</tt>, and
  generate the right value for the <tt>type</tt> attribute.</p>
  </dd>
</dl>

Index: links.h
===================================================================
RCS file: /cvsroot/ht2html/ht2html/doc/links.h,v
retrieving revision 2.1
retrieving revision 2.2
diff -C2 -d -r2.1 -r2.2
*** links.h	25 Mar 2002 17:43:59 -0000	2.1
--- links.h	5 Apr 2002 06:02:28 -0000	2.2
***************
*** 5,8 ****
--- 5,9 ----
  <li><a href="bugs.html">Bugs&nbsp;and&nbsp;Peculiarities</a>
  <li><a href="docstring.html">Usage</a>
+ <li><a href="style.html">Using Stylesheets</a>
  <li><a href="examples.html">Examples</a>
  <h3>ht2html sites</h3>