Web Paging - Directory Structure

This website is organized using a directory tree structure, which is common to any modern operating system. A website directory must contain at least the following files

• .level gives directory related information and references the website macro package
• Makefile drives the m4 to html process
• index.htm4,v or index.htm4 the index file for this directory. The .htm4,v files are the sources under revision control management (RCS). The name could be different from index, but for consistency it's generally a good idea to not change it.

Additionally, the "website" must have the following to "define" the site.

• Every website must have a .site file for site dependent info,
• and, of course, the HTML macro package htm4 and associated files.

Other web pages can be added, for example myinfo.htm4,v or myinfo.htm4, which the index file will then reference. This web file will then refer to the index file as its "up-page" in the START_HTML macro. The "this-page" entry is the basename for this page (i.e. no extensions).

The .level file

The .level file gives certain directory information and includes the website specific site file .site. A typically looks like the following:

 
divert(-1)
#
# level information
#
define(`DIR_LEVEL',	2)
define(`THIS_DIR',	howto/webpaging/)
include(../../.site)
include(../../htm4)@[]@_DNL
_DEFINE(@[_SUBTITLE]@,	Dr.RK's Web Paging ($1))@[]@_DNL

The m4 macro divert(-1) is a convenient way to eliminate unnecessary text like comments. The rest of the macros either define directory specific info, include m4 macro packages, or define information common to all webpages in this directory for this implementation.

• DIR_LEVEL gives the level of this directory below this website's "root"
• THIS_DIR gives the directory path from the website "root" to this directory. This string is pasted on any file names relating to this directory. This is necessarily specific to the operating system.
• The first include file includes in the site specific information.
• The next include file is the HTML macro package.
• _SUBTITLE is a convenience for ensuring all the web pages in this directory have similar and identifiable titles. The "@[]@_DNL" is added to avoid blank lines appearing at the head of the resulting .html file.
• Miscellaneous macros may be added at the end to signal special processing for all the webpages in this directory. For example:
  

  _PRESENTATION@[]@_DNL

Note that the m4 quoting mechanism before & after the htm4 inclusion changes from `'s to @[]@s, as well as all of the m4 macros have been redefined to avoid accidental consequences. The file inclusions are also operating system specific. However, this is isolated to the .level files of each directory.

The Makefile

The Makefile drives the process of creating HTML web pages from the .htm4 or .htm4,v. The Makefile is generated semi-automagically by using the Setupmake script in the webroot and executing it in the current directory. A typical Makefile looks like the following:

# generated by "setupmake" on Wed Dec 25 12:42:50 PST 1996
SRCS	=  index.htm4 myinfo.htm4
OBJS	=  index.html myinfo.html
SHELL	= /bin/sh
HTML_ID	= 1
KEY_ID	= 3
VER_ID	= 4
NULL	= /dev/null
M4	= mm4
.SUFFIXES:
.SUFFIXES: .htm4 .html

all: $(OBJS)

setupmake:
	$(WEBROOT)/Setupmake $(M4)

master:
	-if [ $(M4) = mm4 ];then \
	for f in $(SRCS) ; \
		do $(M4) $(M4FLAGS) $$f $(HTML_ID)> $(NULL) \
			$(KEY_ID)>> $(WEBROOT)/.masterkey \
			$(VER_ID)>> $(WEBROOT)/.masterver ; \
	done; fi

.htm4.html:
	-if [ $(M4) = mm4 ];then \
		$(M4) $(M4FLAGS) $< $(HTML_ID)> $@ \
			$(KEY_ID)>> $(WEBROOT)/.masterkey \
			$(VER_ID)>> $(WEBROOT)/.masterver ; \
	else \
		$(M4) $(M4FLAGS) $< | $(SHELL) ; \
	fi

clean:
	-rm $(OBJS) *.key *.ver 2> $(NULL)

One of the Makefile's jobs is to recursively call the Makefiles in any subdirectory. From the webroot the entire website can be cleaned up or pages regenerated (with a possibly new look & feel). The best way to create the Makefile is to invoke the Setupmake script. It will analyze the current working directory and create a Makefile tailored for it. If a Makefile already exists then invoke

	make setupmake

The index.htm4 file

The index file primarily gives the links to the other files within this directory and perhaps some introductory material that explains the goal of the information in this directory.

A typical index file may look like the following:

include(.level)_DNL
START_HTML(_SUBTITLE(index), _UP(1)index, index,
$Date$
)
_C _REVISION( $Revision$ ) _UNC
_C _RCSID( $Id$ ) _UNC

_KEYWORD(keyword1 keyword2 morekeywords)

Some introductory material for this directory of
information.  The following is an unordered list of links
to the pages in this directory (or subdirectories).
_UL
_LI A page  detailing _PAGE(myinfo, my information)
_LI A another page  detailing _PAGE(myotherinfo, my other information)
_LI This points to a _PAGE(subdir1/index, subdirectory of information)
_LI This points to another _PAGE(subdir2/index, subdirectory of information)
_UNUL

END_HTML

The .site file

A typical .site file contains the following site-specific type of information and must use "raw m4" macros to define certain quantities for later instantiation of the htm4 macro package. For example:

 
divert(-1)
#
# Site specific information --> myISP.net
#
# Tailor this to your own site with global definitions
#  This must be in native m4
#
define(`_FTP_SITE_',	ftp://ftp.myisp.net/pub/rkowen/)
define(`_CGI_SITE_',	http://www.myisp.net/cgi-bin/rkowen/)
define(`_WWW_SITE_',	http://www.myisp.net/~rkowen/)

define(`_EXT',		.html)
define(`_KEY',		.key)
define(`_VER',		.ver)
# for security reasons the HTML password file should NOT be within the website
define(`_PASSWDFILE',	/home/rkowen/.htpasswd)

where

• _FTP_SITE_ is the anonymous ftp site
• _CGI_SITE_ is where the cgi-bin scripts & programs are located.
• _WWW_SITE_ is the "root" for this website
• _EXT is the web page file extension
• _KEY is the keyword file extension for each web page
• _VER is the version file extension for each web page
• _PASSWDFILE where the .htpasswd password file is located. It should not be part of the website tree.