File: genhtml/__docs_

$DOCTYPE$

<HTML>

<HEAD>

<!-- META=Unicode type, STYLE=css link, SCRIPT=analytics  -->
<!-- feb18: STYLE now includes a viewport meta for mobile -->

$META$

$ICON$

$STYLE$

$SCRIPT$

<STYLE>
/* local styles not in _main.css */

/* aug18: notebox now uses common version in _main.css */
/* sep19: notebox (and its .belownote) now unused here */ 

LI {                       /* feb18 mobile: redesign by-date lists for mobile */
    margin-bottom: 8px;    /* all double-space, else hard to read or tap; sep20: 5=>8 */
}

DT {                       /* sep20: was .dlspace, but no other <dt>s here */
    margin-top: 8px;       /* aug18: for <li> converted to <dl> */
}

H2 {
    background-color: #eeeeee;
    margin-top: 32px;
    padding-left: 2px;     /* dec18: add space to left of title text */
}

.topspace {
    margin-top: 20px;      /* aug18: more whitespace (now just some lists) */
}

.belownote {
    margin-top: 40px;      /* sep20: notebox spacing: now unused ('new' note dropped) */
}

</STYLE>

<TITLE>genhtml - Web-Page Macros Utility</TITLE> 

</HEAD>

<BODY>


<!-- ====================================================================== -->


<H1><I>genhtml</I> &mdash; Static HTML Inserts for Website Files</H1>

<!-- Sep 2020: drop the "New" box (2017 updates no longer are) -->

<P>
This is the home of <I>genhtml</I>, a Python script used to 
construct most of the web pages published at this site.  With genhtml,
site-wide updates are easy, because common page components are split 
off to automatic inserts and referenced by name.

<P>
This page describes genhtml's roles and mechanics, and provides
download links.  If you're looking for a quick example of genhtml 
in action, check out the 
<A HREF="cgi/showcode.py?name=genhtml/__docs__/genhtml.html">template</A> of 
the page you are viewing; one of the 
<A HREF="cgi/showcode.py?name=genhtml/__docs__/genhtml--STYLE.txt">inserts</A>
it references; and its genhtml 
<A HREF="cgi/showcode.py?name=genhtml.html">expansion</A>.
To dive right in, read the docstring of the <A HREF="genhtml/genhtml.py">script</A>,
and find genhtml's usage in this site's master publishing 
<A HREF="genhtml/__docs__/PUBLISH.py">utility</A>.
And for the full story, read on here.


<!-- ====================================================================== -->


<H2>Overview</H2>

<P>
This Python 3.X program provides basic <I>HTML macro</I> functionality.
It replaces keys in a folder's HTML-template files with the content 
of correspondingly named insert files.  The net effect automatically 
updates static web pages when any common content they share is changed.
Among its features, this program has:

<DL>
<P>
<DT>Automatic dependency tracking
    <DD>HTML files are regenerated whenever&mdash;and only when&mdash;their 
    templates or any inserts they use have changed

<DT class=dlspace>Configurable Unicode support
    <DD>Encodings in a sequence are tried in turn for each HTML template file

<DT class=dlspace>One-level nested inserts
    <DD>Insert files can insert other insert files for added flexibility

<DT class=dlspace>Automatic generation-date insertion
    <DD>Built-in date keys support multiple formats
</DL>

<P>
This script addresses only static content: common text that can change over time,
but need not be generated on each new page request.  For such content, though,
this program is a simple alternative to:

<UL>
<LI>Mass cut-and-paste edits, which are prohibitively tedious
<LI>JavaScript hacks on the client, which users may disable
<LI>PHP or Apache inserts on the server, which make your pages 
    unviewable offline
<LI>Unix cpp + make, which may not be present on every platform,
    and requires manual makefiles
<LI>HTML preprocessors, which have many of cpp's tradeoffs, 
    and are overkill for the use case
</UL>

<P>
Besides its utility, this program uses and requires only Python 3.X,
runs on any platform that Python 3.X supports (including most PCs and
smartphones), and illustrates a typical role for Python code in 
content-creation pipelines.


<!-- ====================================================================== -->


<H2>Resources</H2>

<P>
See the main script's docstring and other items below for usage details.


<P class=topspace>
<B><I>Code and docs</I></B>:
<UL>
<LI><A HREF="genhtml/genhtml.py">genhtml.py</A> &mdash; the main script's source (560 lines, 1/2 docstring)
</UL>


<P class=topspace>
<B><I>Example</I></B>:
<UL>
<LI><A HREF="cgi/showcode.py?name=genhtml/Html-templates/test1.html">Template page</A> &mdash; with insert targets

<LI><A HREF="genhtml/Html-inserts/FOOTERMAIN.txt">Insert file</A> &mdash; filename gives template key 

<LI><A HREF="genhtml/Html-inserts/FOOTER-COMMON.txt">Nested insert</A> &mdash; referenced in prior item

<LI><A HREF="cgi/showcode.py?name=genhtml/Complete/test1.html">Generated page</A> &mdash; with inserts applied

<LI><A HREF="genhtml/Complete/test1.html">Generated page</A> &mdash; as rendered by your browser
</UL>


<P class=topspace>
<B><I>Usage</I></B>:
<UL>
<LI><A HREF="genhtml/__docs__/PUBLISH.py">Site publishing script</A> &mdash; runs genhtml automatically

<LI><A HREF="genhtml/__docs__/run-log.txt">Run log examples</A> &mdash; basic script interaction

<LI><A HREF="genhtml/__docs__/console.png">Console screenshot</A> &mdash; session console capture

<LI><A HREF="genhtml/__docs__">Docs folder</A> &mdash; assorted documentation augmenting the script's docstring
</UL>


<!-- ====================================================================== -->


<H2>Download</H2>

<P>
Use the following to fetch genhtml, or view its unzipped content.

<UL>
<LI><A HREF="genhtml/genhtml.zip">genhtml.zip</A> &mdash; with all tests, docs, and examples</A>

<LI><A HREF="genhtml/">Unzipped content online</A> &mdash; script, docs, more examples and test pages
</UL>
</P>

<P>
This program was last changed: December 2018.     <!-- or pagegen date: $_DATELONG2$ -->

<P>
<I>Recent upgrades</I>: genhtml now handles <code>.*</code> Mac/Unix cruft files 
in inserts and templates folders.  This includes both <code>.DS_Store</code> Finder files,
and any <code>._*</code> AppleDouble resource-fork files on non-Mac drives.  Both are 
skipped in inserts to avoid errors, but are simply copied like other non-HTML in templates 
because more may crop up before site publication; filter later with your zip or upload 
tools (e.g., <code>-skipcruft</code> in <A HREF="ziptools.html">ziptools</A>).

<P>
For more code examples, see the
<A HREF="programs.html">programs</A> page.  
</P>


<!-- ====================================================================== -->


$FOOTERTAN$

</BODY>
</HTML>