PCS TT Macros for Web Design
PCS TT Macros for Web Design
We have written a fair number of macros to make templating static web pages for PCS easier. This page attempts to document them, at least the more commonly used ones. We organize the macros by class:
Most of the PCS boiler plate is at the start and end of the file, so
these represent the main reason for the templating mechanism. The header
does everything from the start of the html file (
the initial <html> tag),
all the header info, the metatags, includes the standard CSS file, sets up
the PNCE logo, prints the title next to the logo, and the horizontal rule
underneath the title and logo.
The footers print the final horizontal rule, the links and maintainers lines, and optionally links to W3C validators for HTML and CSS.
This macro takes two positional arguments. The first is required, and determines the name of the page in the HTML header (and by default in our master index). The second gives the name to display next to the logo. The second argument is optional, and the first argument will be used for both if it is omitted.
This is a rather customizable macro through the use of the following optional parameters. These parameters must be given in the named parameter notation.
In addition to everything else, some initialization for the semi-automated indexing stuff is done here.
This version, without args, is appropriate for use on restricted pages, where W3C validation links won't work correctly.
This calls standard_pnce_footer with stuff to include W3C
logos for validating HTML and CSS. This is the appropriate version to include
in public pages.
Note: Including this footer does not MAKE the page valid
HTML, etc. You need to click on the links, and then fix any problems until
the validators say they are valid. The valid logos will always be there,
whether valid or not, and using the valid logos is an implicit agreement with
W3C that you ensured the code is valid. If you are unable to make the
page valid, or may need some time to do so, consider using the
w3c_test_pnce_footer instead.
This is essentially the same as w3cvalid_pnce_footer,
except that it does not display the W3C valid logos but instead text links
to their validators. This should be used on public pages that we are having
trouble making W3C valid, or will remain invalid any length of time.
Most of the following tags are just TT versions of basic HTML tags. Most just take a single argument, and wrap that argument in the named tag. For the most part, the gain in using them is minimal at best, although using these tags will ensure that the start and stop tag match (I've lost count of the number of times I make an h3 start tag and close it with an h4).
Because much of the PCS documentation gives commands, file names,
sample output, etc., the code, samp, and
kbd commands have some extra bells and whistles. And we
also have a file pseudo-tag, as that is not a normal HTML tag,
but by wrapping all of our file references with that we ensure they are
all treated properly.
These tags deal with anchors, etc.
hyperlink(target,text) creates a hyperlink anchor tag,
pointing to the URL in target and printing the text
text.
aname(name, text) creates a name anchor tag, naming the
current position in the file name and printing text
inside the anchor tag.
mailto(addr, text) creates a mailto tag, with
addr being the email address and text being
displayed in the anchor tag.
These create assorted heading tags. There is the generic
header_tag(level, text) which wraps text in a
heading tag of level level. More commonly used are
hN(text) which wraps text in a heading
tag of level N, with N running
from 1 to 6.
These wrap the content argument in strong,
em or var tags respectively. E.g. use
[% strong('This is a WARNING') %]
to get the equivalent of
<strong>This is a WARNING</strong>
These wrap the content argument in super and
sub tags respectively.
Because it is so common in PCS documents to include snippets of codes or commands or computer output, the HTML tags and the corresponding TT macros for these deserve some extra attention. The TT macros can do a bit more than the plain HTML tags.
The code(text) macro wraps the text in
code HTML tags. By default, this tag is given the HTML class
attribute of nowrap, which in the standard CSS file should
inhibit having a line break in the text. This behavior can be turned off
by setting the nowrap option to 0, e.g.
[% code('some code which can have a line break',nowrap=0) %]. Another optional arg pre, sets the class to 'pre' (assuming
nowrap is also set off); this should set the
white-space CSS property to 'pre'.
Macros also exist for samp and kbd which behave
similarly and take the same arguments.
Not only does PCS documentation use code, etc. tags a lot,
there are often variables in it. Thus we have macros
codevar(text), sampvar(text), and
kbdvar(text). In all cases, the text is first
wrapped in 'var' tags, and then in the 'code', 'samp', or 'kbd' tags. All
three also accept nowrap and pre args, with nowrap
being on by default.
Even more elaborate are the variable_code(text),
variable_samp(text), and variable_kbd(text) tags.
These all enclose any capital letters occuring in the text in 'var' tags, and
then wrap the result in 'code', 'samp', or 'kbd' tags, respectively. The
nowrap and pre args are still valid. A special
arg vars is a regular expression stating which text in the string
matches for enclosing in 'var' tags, but this is not working as well as I want
so use at your own risk.
While the code, samp, and kbd
macros, with their codevar and variable_code, etc.
extensions are fine for short excerpts of code, etc., the underlying structure
is based on the respective inline tags.
PCS documentation often needs to display rather extended runs of such, which
should go in their own block. Hence the codeblock(text),
sampblock, and kbdblock macros. In each case,
the text is encased in 'code', 'samp', or 'kbd' tags, respectively, but all
of that is then placed in 'div' tags. The div tags will have the class
'nowrap' or 'pre' assigned depending if optional variables nowrap
or pre are set, with 'nowrap' being the default (this should
prevent individual lines from wrapping). Another variable
breaklines, which is set by default, will cause
<br> tags to be inserted wherever carriage returns are
found in the original text.
Similarly, variable_codeblock(text) and similar for 'samp'
and 'kbd' do all of that, but first wrap any uppercase letters in the text
with 'var' tags.
Filenames crop up a lot in PCS documentation. But HTML does not define
a <file> tag. But to ensure consistency, we define a
macro file(text), along with filevar,
variable_file, fileblock, and
variable_fileblock variants. All behave similarly to the
code versions, except for the actual representation of the
file. Currently, we just map 'file' to 'samp', but we may later decide to
make a special span class for it.
Since we are templating anyway, it seemed worthwhile to use some of that
compilation time to help assemble a master index of PCS content. To this
extent, the addTopic and setCurrentTitle macros.
The major human factor in the semi-automated indexing is that the author
of a document should tell the system what topics the page should be indexed
under. To do this, use the
[% addTopic(entry,URL, title, weight) %] macro. This will
cause the URL URL to be indexed with the title title
under the entry entry. The weight is used to
determine the ordering on the index page when there are multiple references
for a particular entry; higher weights come first. The default weight is 50.
The URL and title default to the 'current URL'
and 'current title', respectively. These can be set with the
setCurrentTitle macro, and are set to the current page and its
title (from the HTML header) by the standard header macro. So typically,
all you see is a line like
[% addTopic(entry) %].
The entry variable defines the topic/subtopic list to index
it under. It is typically a string, with each entry in the chain delimited
by pipe (|) characters. It can also be an array reference, with each element
of the array being a string representing a key in the entry chain. Note that
a single addTopic command only adds a single entry to the index,
located at the given keys and subkeys. Typically, multiple addTopic commands should be given.
Although the 'current URL' and 'current Title' are set to the respective
values for the current page during the standard header macro, sometimes you
want an index entry to point to a specific point within the document. For
this purpose, the setCurrentTitle(title,URL) macro exists, and
will change the defaults for all following addTopic commands
(until another setCurrentTitle command is run). The title is
the alternate title to use, and URL is the alternate URL to
use. If URL starts with a '#', the current page URL is prepended
(because the URL is used in the master index, it must be absolute).
PCS pages often link to the physhelp facility. Since that link may change
before long, it is advisable to use the macro physhelp_link(text).
This will create a hyperlink to the current physhelp page, with text as the anchor text. text will default to 'physhelp'.
The macro user_doc_migration_blurb just prints some standard
text informing the user about the migration of pages that is in progress.
