Home > Usage

Usage

Generating a New Web Site

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

  1. the exact look (design) of the page, like fonts, colours et cetera
  2. administrative content, like static headers and footers
  3. the navigation to other pages of the same site

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.

"Indexing" the Whole Site

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.

Navigation is Easily Configurable

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.

Maintaining a Web Site

Changing a Web Page

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.

Adding a Web Page i.e. Adding a Twig

When you add a twig, i.e. add a new web page, you

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.

Changing the Tab-Name

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.

Changing Navigation

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

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.

Hiding Obsolete Twigs

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.

Usage Hints

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.


Last change: 2024-09-27
© 2002-2024 Dr. Thomas Redelberger redetho(at)gmx.de