For a new web site, you build a tree of file system directories. You can choose the names of directories freely, but I recommend to avoid blanks in the directory names.
The structure of the tree shall be appropriate to the way a user might later navigate the web site.
Each directory of the file system tree shall correspond to one web page. All auxiliary files pertaining to this web page ‑ like graphics ‑ shall go into this directory.
You generate a file body.htm
in each directory. This file will hold
the core web page content. You are free to choose any tool that
generates modern HTML. The only requirement to the tool is that it can
generate and maintain two specific meta
HTML elements in the head
section of the HTML:
<meta name="htTab" content="TabName"/> <meta name="htOrder" content="nn"/>
The string TabName
will be used for navigation and shall be an
abbreviated version of the title of the page.
The string nn
is used to order the navigation for siblings of web
pages.
The top most body.htm
file must be marked with an additional element
<meta name="htHom" content="y"/>
This element marks this specific body.htm
file as the home page
and the directory it contains as the home directory. However, you
can freely chose the name of that directory.
Each body.htm
file has to be a complete and valid stand alone HTML
file, with html
, head
and body
elements and must be a valid XML
document. However you do not need to consider
Issue 1. shall be taken care of by a central CSS style sheet.
trgensit
makes using such a central style sheet easy.
Issues 2. and 3. are taken care of by a central XSLT style sheet. The
XSLT stylesheet trWSite.xsl
determines how the navigation of the
site will look and work. trgensit
contains three example style
sheets that show two different navigation designs. The designs are
deliberately simple, to highlight the principles.
I use mark-up to write the body.htm
content, rather than writing
HTML directly. The manual section about Org mode explains.
When you have set-up your complete site with all directories and all
body.htm
files in them, you run the script trwnvall.py
from the home
directory of your site. This will generate trWNav.xml
files in each
directory. These auxiliary files are later used to build the final web
pages. In a sense, these files "index" the site to allow to build the
navigation.
When separating content from navigation, there is the possibility to design the navigation separately. The navigation model could be chosen according to the overall structure and complexity of the site.
In the next step you build the XSLT style sheet trWSite.xsl
in the
parent directory of your home directory. You might want to reference
the example trWSite.xsl file, that was used to build this
documentation site. There reference for the trWsite.xsl
XSLT
transformation template can be found here.
You can then run the script trwupall.py
from the home directory to
build the whole site.
Optionally, but highly recommended, you design a central CSS style sheet, and store it in the home directory. You might reference the example site.css file, that configures the design of this documentation site. Details…
Note that trWSite.xsl
refers to the place where the CSS style sheet
is stored and its name. trWSite.xsl
will build proper relative links
such that each web page automatically references the same central CSS
style sheet file site.css
.
Furthermore the HTML elements you create in trWSite.xsl
‑ like
navigation elements or other content like static footers ‑ should have
matching definitions in the central CSS style sheet.
If you just change one body.htm
file, you just run trwupds.py
to
update the corresponding index.htm
, upload that and you are done.
Graphical illustration of the process to generate or update a web page:
When you change either of the htTab
or htOrder
meta-elements, then
you are touching the navigation. In the former case, you change the
name of the navigation links that lead to that page. In the latter
case you change the order in which this page is appearing among its
siblings. These changes require to run trwnvall.py
and trupall.py
on the affected parts of the web-site tree. Due to the model chosen by
trgensit ‑ which is the choice of related nodes ‑ you need to run
trwnvall.py
and trupall.py
on the parent node of the changed
node.
When you add a twig, i.e. add a new web page, you
body.htm
filetrwnvall.py
to generate the navigation meta data of this new
twig, and also update the navigation meta data of the other pagestrwupall.py
to generate the index.htm
file of the new twig,
and also update the other index.htm
files, such that their
navigation includes the new twig
You should run the last two steps on the parent directory of the new
twig. This makes sure that all possibly impacted pages are updated.
See the concept of related nodes, that trgensit
uses. The impacted
nodes are the nodes that have the new twig node in their related node
set.
The tab-name is the short name for a page that is used in the
navigation. If you change the tab-name of an existing page, you need
to update all impacted nodes i.e. you need to run trwnvall.py
and
trwupall.py
. This makes sure that the new tab-name is properly
updated in all impacted nodes.
Later, when changes of the structure or size of the site warrants it,
you might also want to change the navigation model. Due to the
separation of content from navigation, such a change is done easily
with trgensit
. The content of the web pages would not need to
change, i.e. the structure of the tree would stay the same and all
body.htm
files would be unchanged, but all index.htm
files would
be updated, to implement the new navigation model.
The necessary steps are
trWSite.xsl
XSLT style sheet to implement the
new navigation modeltrwnvall.py
on the home directorytrwupall.py
on the home directoryindex.htm
files.Examples for such different navigation approaches are
Not that changing the navigation differs from just changing the
appearance of the navigation. Changing the appearance would just
need a change in the central css
file. For example changing the
navigation to appear at the top of the page rather than on the left of
the page.
Sometimes a web site needs re-organising. For example you want to move
a twig of the tree to another ‑ possibly new ‑ branch. I recommend to
hold on to the principle that URLs should not change. To achieve this,
you copy the twig content ‑ i.e. the body.htm
file(s) ‑ to the new
branch and keep the old twig in the tree, but remove it from the
navigation. This is achieved by adding
<meta name="htIgnore" content="Y" />
to the top level body.htm
file of the twig. This meta
element is
honoured by the trgensit
scripts and it causes to remove the twig from
the navigation by omitting the twig from the other trWNav.xml
files.
Thus, somebody navigating the site using the navigation HTML elements would only see the new structure. Somebody using the old URL will access the old twig.
If the content changed and you want to make sure that somebody using the old URL gets to see the new content, you could insert the element
<meta http-equiv="refresh" content="0; URL=newuri"/>
in the old page's body.htm
file. This is preferred over adding it to
the index.htm
file, because trgensit
considers all index.htm
files as always machine generated.
For a hidden web page, the page itself but also its children are
removed from navigation by the trgensit
scripts, but the page is
still accessible using the old URL. Note that the navigation does
not get updated for such dead twigs (the trWNav.xml
files do not
get updated). When somebody accesses the children of the hidden page,
he/she might still access other parts of the dead twig and the rest of
the web site using the state of the navigation where it was before the
twig was cut. If you want to make sure that always the new content
gets accessed, then equip all pages of the twig with above mentioned
meta
element.
The approach chosen causes obsolete twigs to still follow changes in
the style or model of the navigation, when you update their
index.htm
. This ensures the look and feel of a web site stays
consistent, even for "old" content.
The python scripts could of course be run from the command line. This
would be most easy if you include the trgensit
module
directory in
your PATH, make them executable and add an appropriate shebang line,
if you work in a *nix environment.
I prefer to use the good old make
tool. As an example, trgensit
contains the Makefile
I use to maintain the documentation you are
just reading.
I steer everything from my file editor (I use GNU Emacs), where the
"compile" command kicks off make
. That works equally well under a
Linux and a Windows environment and should also work under Mac OS.
I write all body content using Emacs' org-mode. This is described
here. However, I omitted the body.org
files from the standard distribution
ZIP file, to avoid confusion. I have added a second ZIP file
trgensit-org.zip
that contains the org-mode artifacts for your
reference.
Likewise, markdown could be use to write the body content, which I briefly describe here.
This is for information only. You are free to generate and edit the
body.htm
files with any tool you like.