Apache Tutor: Help

Apache Tutor is organised as a directory of resources. The primary resources are the articles, which deal with subjects relevant to Apache development, administration and deployment. These are presented interactively using mod_annot, an XML-based publication framework for interactive publishing.

This help page describes how to work with the organisation and software, and get the most from the site.

Login and Identity

The Login button is available at the top of every static page, and every article while you are not authenticated. It enables you to identify yourself to the system.

Whereas you can read any published article anonymously, authenticated users may have additional privileges relevant to participating fully in the site. Every article at ApacheTutor contains access control information that determines the level of access available to anonymous and identified users, as well as ownership and an access control list for additional privileges.

Annotations

Annotations are user comments, in the manner of a blog. But unlike a typical blog, annotations apply not to the article as a whole, but to individual sections. They are presented as margin notes.

When you are reading an article that permits annotations (subject to your login privileges), a button labelled Annotate will be displayed alongside every section of the article. This gives you a Form to annotate the section, by entering your comments in a margin note. Annotations are simple text only: no markup will be displayed.

Existing annotations are shown in the left margin. To avoid clutter and confusion, annotation texts are not ordinarily displayed. Each annotation is represented by an annotation icon in the margin. These icons serve two purposes: a mouseover will display the annotation's author and time/date, while clicking on it will display the full text. This of course depends on browser capabilities: browsers that don't support stylesheets and scripting may display the entire annotations all the time.

It is expected that document editors will periodically update a document, taking into account any annotations. The system therefore makes a distinction between old and new annotations. New annotations are those made since a section was last updated, and comment on the current text. Old annotations refer to an earlier version of the section, and should have been taken into account in the current version of the text.

There is always a possibility of a race condition arising if a section gets updated while you are composing an annotation. If this happens, your annotation may be refused. You can then re-enter it, if it is still relevant to the updated article text.

Editing

Subject to your login privileges, a button labelled Edit will be displayed alongside every section of the article. This gives you a Form to edit the section.

When you edit a section, you update the entire markup of the section in the manner of a wiki (the existing markup is of course pre-loaded into the Edit form). Since this is a critical operation, the system will always validate your markup when you submit your edits. If it finds any errors, your edits will be refused: you should then use your browser's back button to return to the editor and fix the errors. The DTD used here serves both to guarantee that articles remain valid XHTML 1.0 and to prevent malicious code being inserted.

There is always a possibility of a race condition arising if a section gets updated while you are editing it yourself. If this happens, your updates will be refused. You will have to restart, using the updated version.

The Content DTD

The DTD used here serves to validate the contents of a section, not the entire document. Thus all permitted markup must be valid within an XHTML 1.0 <div> element. No deprecated markup is permitted, and some further restrictions are placed by the system to impose structure and prevent disruptive or malicious markup. Principal limitations include:

The Full DTD is available here.

Errors

There are three basic error conditions that may prevent you submitting an annotation or edit for which you are authorised: an article lock, a sequencing error, or an invalid update.

Article Lock
Exceptionally, a document owner may wish to make major updates to a document. To do so, they will lock the entire document against any edits or annotations while work is in progress. This should always be a temporary condition.
Sequencing Error
A sequencing error occurs when a section of an article is updated after you load the Annotation or Edit form for the section, but before you submit it. To avoid conflicts arising from the race condition, updates will be refused. In this case, if the update does not already address your points, you will have to reload the relevant form from the updated article and repeat.
Invalid update
Edits will always be refused if your markup is invalid according to the section dtd. Go back and fix it.

Any error will be indicated by an HTTP error code together with an error document. The HTTP code may cause browsers to issue their own error messages.