Instructions for FOLDOC guest editors

Thanks for volunteering to help edit the Free On-line Dictionary of Computing. This page describes the simplified mark-up used in the dictionary source and gives some general guidelines. Please read it carefully then follow the instructions at the bottom.

Please do not hesitate to ask for clarification but most questions should be answered by browsing through the dictionary or getting a copy of the full source. This will also be useful when relating the entry you are editing to the rest of the dictionary. Please return the edited entry within one month of the date it was sent to you. If I get no reply by this time I will assume you are dead and send the article to another editor. If you can't edit it for any reason, please let me know.

E-mail format

Please submit each definition as plain text in the body of an e-mail message. Don't send attachments (e.g. MIME) or other fancy text, data or word-processor formats. Each message may contain one or several definitions.

Content

Before marking up the article, you should make sure that it is correct, clear and reasonably complete. This may involve e-mail discussion with the original author and/or use of other (net) resources. Try to include any significant dates. The length of the entry should be in proportion to how important you judge the subject to be.

You might also search the dictionary itself to see how the article relates to other articles. Is it already defined (under a different name)? Does it overlap with, contradict or generalise other entries? You may find that several entries need updating or creating on the basis of one submission. I may send you relevant entries along with the submission but feel free to suggest changes to others.

Style

You should follow the "house style" of the dictionary (if you can tell what that is!) I will add guidelines here when I think they are necessary.

Use British spelling except where names or titles use American: "-ise" rather than "-ize", "colour", "grey", "behaviour", "humour", etc.
Write names of incorporated US companies as, e.g., "Motorola, Inc."
Write names of corporations as, e.g. "Oracle Corporation"
Acronyms should just point to an entry for the expansion.
Write acronyms without "."s, e.g. "SMTP", but write Latin acronyms as "e.g.", "i.e.", etc.
Separate paragraphs by a single blank line with no initial indentation.
Put two spaces after a full stop or question mark.
Write decades and pluralised acronyms without apostrophes, e.g. "1960s", "GUIs".
Write numbers zero to ten as words, 11 and up as digits, 10,000 and up with commas.
Hyphenate number-unit pairs used as adjectives. E.g. "a 32-bit bus", "a one-megabyte address space". Otherwise the number and unit should be separated by one space.
In unit prefixes, use lower case "k" for multiplication by 1000 (e.g. km = 1000 metres) and upper case "K" for multiplication by 1024 (e.g. KB = 1024 bytes).
In units of data, use lower case "b" for "bits" and upper case "B" for "bytes".
Never use the word "utilise" (or "utilize"), use "use".
Never use the word "leverage" as a verb.
Comma before "and" or "or": e.g. "A, B, and C".

Mark-up

The dictionary uses annotations in the source which are much simpler than HTML and which are converted to HTML on the fly when an article is requested. In common with HTML, 8-bit ISO8859-1 characters can be used where necessary.

Basic structure

Each entry consists of a heading at column zero, followed by a blank line, followed by any number of body lines, followed by a final blank line. Non-blank body lines should be indented with one tab and should be wrapped so that no line is wider than 70 columns (Emacs fill-column = 70), but don't split long URLs. Tab stops are every eight columns.

Preformatted text (e.g. tables, ASCII art) which is not to be filled by the browser should be indented by extra whitespace after the initial tab. This will be output as preformatted (<pre>) text. No line should start with spaces or end with tabs or spaces.

You should enter the characters ">", "<" and "&" as themselves (unlike in HTML). You should enter an open brace as \{ to distinguish it from a reference (see below).

Each article may have the following parts. Bold indicates a required field. Examples follow each part:

Heading: The normal spelling and capitalisation of the term
Subject classification(s): <language, education>
Acronym: (ISDN)
Alternative forms: (Or "laundromat")
Origin: (From mathematics)
Pronunciation: /dev-nuhl/
Short definition: A single phrase (not a sentence) giving the term's meaning
Full explanation: The main body of the entry
Cross-references: See {Autocode}, See also, Contrast, etc.
External WWW references: {Home (http://www.foo.com/)}.
References to paper literature: ["Distribution and Abstract Types in Emerald", A. Black et al, IEEE Trans Soft Eng SE-13(1), pp. 65-76, Jan 1987].
Modification date: When the article was last changed significantly, in ISO standard form (YYYY-MM-DD).; (1998-08-26)

Heading

The heading should appear with the case and punctuation it would have in the middle of a normal sentence, all lower-case if that's how it's normally written. Where there is a choice the heading should be a noun and other parts of speech should be just cross-references (see below). E.g. "resolve" should just refer to "resolution". Common usage should override this rule however.

Subject classification

The first body line should start with one or more standard subject classifications within angle brackets, separated by comma-space, eg.

3DO

	<company, games, standard> A set of specifications created and
	owned by the 3DO company.

The existing classifications are the headings in the subject listing. Try to stick to these unless you have a good reason to introduce new ones. Include as many existing classifications as you think are useful and pertinent.

Multiple meanings

If a single heading has multiple meanings, these should be given in separate paragraphs tagged by an initial decimal number incrementing from 1. A set of subject classification may precede the "1." or each number may be followed by a set of subjects if different meanings are in different subject areas. E.g.

ALADIN

	1. <language> {A Language for Attributed Definitions}.

	2. <tool> An interactive mathematics system for the {IBM 360}.

Multiple meanings should be ordered from most common to most obscure.

The acronym, alternatives and origin, if present, are all placed within one pair of parentheses, e.g.

Functional object-orientation

	<programming> (FOO, or "free object operation".  From
	the book of the same name)

Pronunciation

Give pronunciation using this notation for entries that are neither words found in a standard English dictionary nor obvious compounds thereof. Bracket phonetic pronunciations with slashes (/.../).

Short definition

The short definition should be a short phrase (not a sentence) defining the term as concisely and accurately as possible. Do not repeat the term at the start of the short definition, or use phrases like "This is...". You should however repeat the term somewhere appropriate in the full explanation which should be composed of proper sentences.

Bozon

	Acme Computer's first 256-bit processor, released in 1999.
	Bozon performs one MIPS and is fabricated using 100 micron
	Sodium Chloride technology.

Cross-references

A reference to another article in the dictionary looks like this:

	An {artificial intelligence} language.

This will produce a cross-reference to an article with heading "artificial intelligence". You should mark up any term which one might reasonably expect to find, whether or not a definition currently exists. This allows me to tell which links people are trying to follow and add definitions as required.

You should try to work cross-references into the body of the article rather than just including them in a "See also ..." at the end. This makes their relationship to the current entry clearer. You should only mark up the first occurrence of each term in an article. Do not use phrases such as "qv" or "which see".

Plurals will get mapped to the corresponding singular entry. E.g.

	A language with {coroutines}.

Would link to the entry for "coroutine" (if it existed), though this only works for singulars of four characters or more.

Redirecton cross-references

As a special case, if the entry consists of only a cross-reference (e.g. when giving the expansion of an acronym) then it should appear exactly like this:

IETF

	{Internet Engineering Task Force}

with no other fields or punctuation. The look-up code will short-circuit such references and go straight to the referenced entry. Acronyms with a single expansion should always be handled like this, though it also has other uses, e.g. redirection between different parts of speech and collection of several closely related terms into a single definition (don't overdo this though).

A person should be listed under their usual name in the usual order with no title, e.g. "Steve Jobs" with cross-references from "Lastname, First Names", e.g. "Sinclair, Sir Clive", and "First Middle Last" and any other forms that is likely to be searched for.

Don't create chains of redirections, point them all at the real definition.

Acronyms

Since acronyms are so common, here is a summary of the rules for handling them:

If the acronym has just one expansion, its definition should be just a cross-reference to the entry for the expansion.
If the acronym has multiple expansions, these should be treated like any other term with multiple definitions - each expansion should be preceded by a number and subjects.

External references

A reference to a URL outside FOLDOC should be in the form {TEXT (URL)}, like this:

	{Patent search (http://sunsite.unc.edu/patents/intropat.html)}.

where TEXT is what the browser will display. TEXT may be omitted but you should try to include a short phrase describing what the link points to. The word "Home" should be used where it is obvious what home page this refers to (i.e. the subject of the article). Check that the URL is valid. Link to English language pages where available.

GNU Emacs

Editors who use GNU Emacs might want to get a copy of my Emacs package for editing FOLDOC, foldoc-mode.el.

Complete example

Here is a complete example, demonstrating some of the features.

blitter

	<hardware, graphics> /blit'r/ (Or "{raster blaster}") A
	special-purpose {integrated circuit} or hardware system built
	to perform {blit} (or "{bit bang}") operations, especially
	used for fast implementation of {bit-mapped} graphics.

	The {Commodore} {Amiga} and a few other {microcomputers} have
	these, but in 1991 the trend is away from them (however, see
	{cycle of reincarnation}).

	{Ulrick's blitter list
	(http://www.acme.com/~ulrick/blitters.html)}.

	["My hundred favourite blitters", Dave Nerdy, pub. Random
	Tab 1996].

	(1998-08-26)

OK, I've read all that, what next?

Please let me know you're ready to start work. Tell me you've read this page otherwise I'll just tell you to read it. Please bookmark this page and read it again before editing your first submission and from time to time to check for changes.

FOLDOC Feedback

Comments or Problems

Again, thanks for visiting NightFlight's WWW server. We hope to hear from you again soon.

If you have problems or comments con cerning our WWW service, please send e-mail to the following address: webmaster@NightFlight.com.

Back to NightFlight's Home page