Latest News
| Getting Started | Documentation | Glish | Learn More | Programming | Contact Us |
|
| Version 1.9 Build 000 |
Latest News
|
This note supplements the AIPS++ Information System Design with suggestions for HTML style in our hand-written documents. I am still treating it as a "note to myself" as the prospective editor of astronomical HTML in AIPS++, so I am tossing ideas into it as I have them. It will evolve into a more homogeneous document later if others feel that the guidelines are useful. Comments to abridle@nrao.edu are welcome.
We aim to make the handwritten HTML
AIPS++ HTML should comply with the standard that is current at the time of writing. Our aim is to write HTML that displays well across the space of all compliant browsers, not to optimize for just one of them. Never bend the HTML rules to make prettier output in one browser. Avoid browser-specific markup, such as the Netscape-specific HTML "extensions".
In-line images are appropriate for technical graphics, but should be used sparingly or not at all as anchors and headers. Some users may read documents with text-only browsers such as lynx, or with image loading turned off for speed. Although AIPS++ sites should have local copies of all documents, not all browsing will be done over high-speed connections. Many sites have users who connect to them via modem when working from their homes. While we won't design the whole documentation system around such users, we should not put obstacles in their way needlessly. I therefore suggest these guidelines for using images in our HTML:
To use fonts consistently for emphasis, adopt the logical <EM> tag for light emphasis and the <STRONG> tag for strong emphasis rather than physical italic <I> or bold <B> tags. There are several reasons for this. Any given user or browser may prefer a different convention than ours. Some may not like or even have bold or italic versions of their favorite "normal" font. The logical tags leave such choices to the reader (following the basic philosophy of HTML). They are also easier to remember consistently when writing a document!
Logical markup is also preferred when fonts are used to indicate
function, such as citations (use <CITE>), code
examples (use <CODE>), variable names (use <VAR>),
user inputs (use <KBD>).
The first few lines should state the document's purpose clearly. The longer the document, the more important this is. Readers must be able to decide quickly whether the document is likely to be what they were looking for.
It should be possible to generate a contents list automatically by scanning the heading tags. We may want to use software to do this on long hand-written files. Heading tags (<H1>, <H2>, <H3>, <H4>, etc.) should therefore be nested in order within a document, and should be used consistently without skipping levels.
<H1> should be reserved for the first (banner) line in the body of the document. It's always a large font that takes a lot of space.
<H2>, <H3>, <H4> are better for Section, Subsection and Item headings. A document that has many instances of these headings should also have a menu of internal links to each heading. This menu should be placed immediately below the initial statement of purpose, so it works like an active "table of contents" for the document.
<H5> and <H6> are too small as rendered by most browsers to be useful as headings and should probably be avoided.
Never use headings just to change fonts (e.g. to "bold or "very small") or to produce white space.
Anchor text should be as meaningful as possible. When readers scan hypertext on-screen, they tend to see the anchors first because they are high-lit. When literally browsing, they may only see the anchors. Anchor text should therefore give a sense of what is being linked to, rather than being just a quilt of "here" notations in regular text. Anchors are used, among other things, to:
No other markup should ever appear inside anchor tags. For example, a heading may contain an anchor, but there should never be heading markup within an anchor.
Use horizontal rules (HTML <HR>) to separate major sections (topics) in long documents. They add structure and are specially helpful when the document is printed. If we use html2ps to print documents, it is helpful to add <!--NewPage--> comments after major sections to force page breaks.
The many advantages of hypertext and browser-based documents do not eliminate the need for printed manuals. Not all users prefer to navigate the multi-linear structures of hypertext. Some are more comfortable with the logical sequencing implicit in a printed manual. Also, even in the era of laptop computers, not all browsing of documentation is done at a computer. We must expect to produce printed manuals from much of the AIPS++ hypertext documentation.
Our hypertext documentation style must still make sense when the text is printed. This is not difficult if meaningful linking words (anchor text) are used wherever possible. Specifically, avoid "here" as an anchor if the document will be printed (it is sometimes appropriate in documents that will only be seen on-screen.) Mousey constructions such as "click here" should be avoided everywhere, as they are not even meaningful to all browsers (there's nothing to "click" when using lynx!)
People who read printed documents today may want to find them, or some files that they refer to, in the on-line system tomorrow. It is therefore useful if the longer HTML files show their own master URL (i.e., that on aips2.nrao.edu), and those of major references that they make, when printed. Displayed URL's are one more thing to keep track of whenever files are moved within the system, but this connection between the hyspertext system and the printed format will be useful.
This is a tricky area that Friso and I are still discussing. The longer documents in the tutorial parts of our system may benefit from having tree-like link structures and large granularity to help us print manuals from them. The maze of small-grained information in the reference material will almost certainly have to have a web-like link structure and may therefore need built-in navigation tools. There is a design tension between the discipline of trees and the adaptability of webs. Also between the printability of documents as "manuals" and full use of hypertext as a web. We may need tools that let us collate a large collection of files in a web for some purposes and separate them for others. The impact on our style may not be clear until we have explored more possibilities in this area.
Any body of information larger than a typical browser page can be organized in two styles, both of which have advantages and disadvantages:
In favor of multiple files in a cluster:
In favor of a single file with named anchors:
There is no simple, general way to resolve these trade-offs. Documentors must decide which is the better approach for a particular block of information, and provide appropriate navigational aids whichever style is used.
Text menus are useful at both ends of a long document, but obligatory at the start. They can be based on a definition list (<DL>) with <DT> fields as anchors and <DD> as optional explanations, or on <UL> or <OL> lists. List-based menus are most readable when the anchors are at the front of, or early in, each list item <LI>. The end of a long document may offer links to the menu at the start of the document, to a higher level (section/chapter/book) in the same documentation tree, to the Home Menu for the Documentation System, and to the overall AIPS++ Home Page
For tutorials, explain files, specifications, memos and notes, give the authorship, date and time of last modification just below the banner heading at normal text size. For short documents, such as pages in a web cluster, this information can be given less obtrusively at the bottom of each page. Use the <ADDRESS> tag for such fields, to ensure consistent formatting in all our documents on the reader's browser. (Don't use bold or italic tags alone for these data: we want to trigger the browser's address-recognition tool.) <BR> tags are legal to make line breaks within "address" fields, though not all browsers recognize this.
The only way to date a document unambiguously for all readers is to use the name of the month (abbreviated if necessary). The international world has too many different styles for all-numeric dates and we cannot expect new readers to know which we have adopted internally for AIPS++ code! It's better not to confuse them.
When a document is published on the World Wide Web, we expect its source to be copied to other machines, at least for caching. This does not mean that we are giving the reader the right to incorporate the text in other documents (any more than buying a copy of a magazine or newspaper gives a reader unlimited rights to reproduce its contents). The copyright to all AIPS++ source, including the HTML, resides with A.U.I. and a statement to this effect should eventually appear at the end of every HTML document in the AIPS++ information system. The standard format for this statement is:
Copyright © 1995,1998,1999,2000 Associated Universities Inc., Washington, D.C.
The © entity displays the symbol © in all truly HTML-compliant browsers.
You could now go back to the:
Copyright © 1995,1998,1999,2000 Associated Universities Inc., Washington, D.C.
abridle@nrao.edu