Author Guide

Basic Principles

This website has been designed so that the page author can concentrate on the content
of their page, and ignore the formatting and navigation, which will be handled automatically by the WordPress blogging software.
However, there are some nice navigational and fun features that can be added very simply by
adding in some WordPress custom tags.

Authors should follow the guidelines below when creating all pages.

Creating A New Page

  1. Choose a short, meaningful, alphanumeric pagekey.
  2. Use the WordPress Dashboard to create a New Page (not a new blog entry).
  3. Give the page a title, ideally short and to the point as it is displayed in the left hand side bar and does not wrap.
  4. Create a custom key called page and give it a short, relevant name.
  5. (Optional) Edit the page shortcode to match the page key.
  6. (Optional) Clear track backs and pings.
  7. Publish the page.

The author (or editing tool) should ensure that the page is XHTML 1.0 Strict compliant. It is
important to recall that the author is only responsible for the content, all
navigation and styling will be added automatically.

Naming Conventions

Uploaded files should be given short but meaningful names using alphanumeric characters only and not
relying on case sensitivity. Extensions should be used as follows:

html
A file that when processed, will produce a page that is viewable in a browser.
inc
A fragment of HTML or PHP that is included in other files.
js
All Javascript files.
jpg, png, gif
Image files, to suit.
txt
General data files

Allowable Elements

Each web page document should contain only content! All standard elements, (heading sections,
navigation panes etc.) are added automatically when the page is served.

The author should ensure that all contents are W3C XHTML 1.0 Strict compliant, and in addition
only certain XHTML elements should be used (this is to ensure consistency in display, as only the
elements named below are implemented in the stylesheet).

Block Level Elements

The following block level elements can be used:

<h1> or <h2>
Headings should be as short as possible and all initial letters should be capitalised. They
should also nest correctly.
<a id=”whatever”>
whatever can be most things, except “top” or “ToC” followed by a number.
<a href=”wherever”>
To link to other pages in this website, use ?page=pageid where pageid
is as shown in pageinfo.inc. To make the link open in another window set the
rel attribute to “external”. Do NOT use the target
attribute as this is not strict XHTML.
All normal body text should be enclosed within paragraph elements.
<ol>, <ul> and <dl>
and their associated sub-elements. By default outline lists are numbered, but with the
class “alpha” they will use lower case letters instead.
<table>
and any associated sub-elements. Tables should only be used to layout tabular data or to
organise form elements, not for layout!
<form>
and any associated sub-elements.
<pre>
should be treated like a block level <code> element, and will be formatted
similarly
<div>
only divs containing an <img> tag and a single paragraph are allowed. The
paragraph will be formatted as a caption for the image. The same class attributes as for
img (below) should be used.
<blockquote>
For larger text quotations.

In-line Elements

Only the following in-line elements should be used by authors

<em>
Assume italicised text
<strong>
Assume bold text
<img class=”align-left|align-right|aligncentre”>
All images float, use the class to indicate whether you want it to float to the left or
right (with text flowing around), or be centered and have text below. Alternatively, you can
use these attributes on a div element that contains the image and a paragraph,
which will be formatted as a caption to the image.
<code>
For programming examples
<br />
Avoid if possible, especially if trying to achieve layout effects.
<acronym>
As required.

Footnotes

(These were available in the previous version of the website, but I have not implemented them in the WordPress version).

Supporting Files

Supporting files, such as images, downloads and so on should all be uploaded using the normal WordPress upload facilities, although there are few exceptions for large files that are shared with the previous version of the site.

Image Style

We are aiming for a “soft” look and feel and hence wish to avoid hard edges. Hence, all images
should either be “cut out” from the background, with transparency around it, or should have fuzzy
borders. These can be produced using the GIMP, Filters -> Decor -> Fuzzy
Border with colour set to white, border size 4 to 5, Granularity 4 and no shadow.

Images should not extend beyond the standard page width, or impinge on the left border, so in
general should not be wider than 580 pixels. Image format can be jpg, png or gif as
appropriate.

Scripts

Client side Javascript may be used, but with some restrictions. Note that if any level 1 and 2 headings are added to the document then
they will not be shown in the navigation panel or the fancy navigation
scheme.

There is no HEAD section within authored pages  so you will have to place any Javascript within
<script> tags in the body. These may be placed as required.

Scripts should be placed in the /include folder, in accordance with the naming
conventions above.

Security

The author is referred to the book Programming PHP from O’Reilly and the
recommendations in chapter 12. This chapter should be re-read every so often. Specific
requirements are as follows:

Validate input
All user input should be validated. In particular all text based form fields should be
stripped of any HTML tags by using the PHP function strip_tags.

Fancy Features

Fancy Navigation

Any page can be given the fancy navigation seen on the homepage, simply include the custom tag
fancywith your page, with one of the values matching those in the stylesheet. At the time of writing there are two styles available ‘castle’ and ‘onetreehill’. Others may be added as required.

The existence of the fancy tag will cause the first eight
heading1 elements in your file to appear as large links at the top of the page. When the mouse is
hovered over one of these links the content occuring between the corresponding heading and the next level 1 heading will be shown in the image.

Please note the if you choose to use this fancy feature make sure that the content
under each heading1 is:

  1. quite short, not more than a hundred and fifty or so words.
  2. a succint and useful summary of what that section is about.

Quick Navigation

(This has not been implemented yet).

At any point in a page the author may include a quick navigation
section. This will be floated right of the following paragraph. If used immediately after a fancy
section (above) then it will line up nicely. To use this feature insert the following code
quicknav(“pagekey1=description”, “pagekey2=description”, …) . The
pageids can either be those used in the pagekeys.txt file (see above) or a reference to a local
resource file in the same folder. This function will create a small list of links to each of
these pages or resources, using the supplied description as the link text.

Infobar

Just for fun, I created what I call an “infobar”. This is a small page feature that shows a
randomly chosen snippet of information. It is inserted into a page by creating custom tags named infotop or infobottom and the tag value must be the basename of a specially formatted text
file in the other folder. See /other/reviews.txt for a example.

Links To Other Pages

Links to other pages in the web site should use the format href=”?page=pagekey”, where pagekey is the value of one of the page custom tags. Do not add the server name as WordPress will do this automatically.

In addition, where a subset of pages has a logical order you can create custom tags called next and prev whose values should be pagekeys as above. Links to these pages will be created automatically and displayed as part of the in page navigation.

Narrative Style

All body text should be written in grammatically and syntactically correct English. Remember
to intelligently spell check. The style should be semi-formal, not casual or colloquial. In
particular, avoid lots of exclamation marks!!!

Long narrative should be broken up at regular intervals by headings, this will aid user
navigation. In general there should be not more than 10-12 headings in total on each page. Use
the Next and Prev relationships (see above) to link a
series of pages.

External links should be avoided in the main narrative. They should be gathered into a section
called “Links” or similar at the bottom of the page.

>> Back to the Homepage <<

 

 

 

 

All content © 2011 Karl R. Wilcox unless otherwise stated.