A FAQ is the nickname for a "Frequently Asked Questions" document. There are thousands of FAQs available on the World Wide Web on many different topics. The basic format of a FAQ is that someone asks a question, and someone else answers.

FAQs were very popular on specialist bulletin boards, mailing lists and USENET newsgroups. On these discussion forums, the same questions appear repeatedly: newbies ask the same questions and new approaches to solving problems get developed. These questions and answers are collected into FAQs; newbies can be directed to the FAQs for good answers, and the FAQs can get updated.

In several cases, FAQs are ultimately revised into book form and published in paper: The SGML FAQBook by Steve DeRose and Chinese Japanese Korean Vietnamese Information Processing by Ken Lunde are both examples of FAQs in book form.

You can find a good collection of FAQs at the web site of faq.org (http://www.faq.org/).

A markup language lets you name the various elements in your text: HTML is the most famous markup language. You just insert special codes called tags into your text; these tags tell you where each interesting element starts or finishes.

The term markup was coined by Dr Charles Goldfarb at IBM in the early 1970s. Goldfarb invented SGML, the Standard Generalized Markup Language (Internation Standard 8879:1986) which is now becoming available over the WWW as XML, the Extensible Markup Language.

QAML is a markup language created specially to help write, use and maintain FAQs. It is smaller and simpler than HTML.

A QAML document has a very simple structure: it has a head and a body. The body is made up of qna elements, each of which has a q question and a answer.

Because the questions and answers are clearly marked up by tags, it makes life a lot easier for people to write programs to manipulate the FAQ: to automatically generate indexes of questions, to make global changes to stylesheets, or to split the questions and answers into different pages.

QAML version 1.0 was written by Justin Higgens, of faq.org. Email jhiggins@dn.net. This version used SGML, and so is very lenient on tagging errors.

QAML version 2.0 uses XML, and so you need to be more careful with providing all the tags needed for a well-formed XML document. It has very full support for the latest World Wide Web Consortium specifications (see http://www.w3.org). It was written by Rick Jelliffe, of the Academia Sinica Computing Centre, Taipei, Taiwan.

HTML is much more complicated and richer than QAML. However, HTML allows you to create documents which look pretty but which do not have the tagging needed to create indexes or to convert the data to different forms: it gives you too much!

FAQ documents can be accessed from all sorts of systems, not only visual web browsers. So QAML does not provide the types of elements which cannot be seen on many different media: telnet terminals, Braille readers, speech synthesizers, mobile phones, etc.

However, it is very easy to convert QAML to HTML. There are XSL stylesheets available to do this. So you can write your FAQ in QAML, but deliver it in HTML.

You can use any text editor, or SGML or HTML editor. The NotePad or WordPad applications allow it. You can use most word processors (but remember to save the document as "Text". You can even use a WYSIWYG HTML editor to create the FAQ, and then use a text editor to alter the element type names and attributes as appropriate.

There is also an OmniMark script available which does automates much of the HTML-to-QAML conversion work.

A QAML document has a very simple structure: it has a head and a body.

The head has to have some metadata which gives the title, the maintainers name and email contact address, the official archive site for the FAQ, and keywords which can be given to a search robot.

The body is made up of qna elements, each of which has a q question and a answer. These qna elements can be collected into sections, and given general section titles.

Within each answer, you can have p paragraph elements. The only element types allowed inside a paragraph are link and span.

The following empty document is the smallest QAML 2 document that is valid. You must have at least the FAQ title and one question and answer.

You can use this example as a template for creating new FAQs.

]]>

]]>

You can use the ]]> tag to start a list, and the ]]> tag to end it. Inside the list, each item can be tagged with a special version of the paragraph tag ]]>

So here is the markup:

AAAA

BBBB

And here is how your browser and your current stylesheet displays it:

QAML is geared towards text systems which may not have sophisticated visual formatting available. This is why there are no tables in QAML. So if you use lists, keep them simple, and make sure the text explains that you are using a lists: some formatters may just show a paragraph as a paragraph.

There are CSS and XSL stylesheets available from Academia Sinica Computing Centre's Chinese XML Now! project, at http://www.ascc.net/xml/en/utf-8/resource-index.html

The link element has an attribute called href. Just put in the URL of the resource that is the link's target.

Remember that the data inside the link should also contain the URL. This is because some people may read the FAQ from a paper printout. Don't forget them!

An example follows.

<p>This is <link href="qaml-faq.xml">qaml-faq.xml</link></p>

(Some WWW browsers may display that example wrong, so another version of the same thing follows: the one with the angle brackets is the correct one.)

This is qaml-faq.xml

Dublin Core metadata is a list of some basic metadata categories that is useful for any WWW document authored by a general person. It is "Metadata for the rest of us".

QAML 2 was written with the Dublin Core catgories in mind. Because QAML 1 was written before Dublin Core, the same names are not used, but the QAML 2 DTD includes the mappings to Dublin Core elements as comments.

The mappings between Dublin Core elements (with the DC prefix) and QAML 2 element types is given below.

Other Dublin Core metadata may be available: for example the maintainer may in some cases be regarded as the publisher. Information about the copyrights and extents of the data are not available through standard mappings. Note however that the QAML 2 DTD does include a minimal copyright notice for FAQs: its primary purpose is to remind authors to make copyright policy explicit, and to protect them to a certain extent if they forget.

The answer element of a qna can have an attribute called gist. This attribute should have a one to five word summary of the answer.

This summary may be useful on display devices with limited bandwidth and to aid the user of a QAML document figure out if the answer looks interesting or useful to read further.

The email element is used in fields for authors, contrrbutors, maintainers. As of QAML 2.4, it is only mandatory for the maintainers.

QAML was simply not designed for rich graphics. Authors are restricted to using fairly simple text. However, two kinds of graphics are available: inline linked graphics and logos.

You can put in inline graphics using the link element inside paragraphs. You must also specify an href attribute with the WWW URL of the graphic and a role attribute with the value "Image". (Another role you may find useful is "Sound".)

You can put in logos using the logo element. You can put a logo in as the first element of a qna, a section, an author, a contributor and the maintain-er.

These allow logos belonging to the particular person or organization, or to the individual topic. Graphics and logos that belong to a whole series of FAQs are best put into the stylesheet or the FAQ-transformed-into-HTML.

The logo element is not intended to be used to include rich graphics. However, if you need it, it is there. But beware that some stylesheets may not print the logo or any links, and some stylesheets may expect the logo to be banner-sized or thumbnail sized.

FAQs started on Internet mailing lists and newsgourps. Newcomers ("newbies") often ask the same question. So a FAQ gets newbies up to speed, and stops them from wasting too much time for the grumpy old-timers.

The FAQ format can be a quite useful format for spreading information. Many people find it quite useful because it the questions often are real questions that people ask rather than the questions that gurus think should be asked. Also, the answers are fairly targetted to answering particular needs; so FAQs are in a way fairly similar to the "for Dummies" books.

In the case of the QAML FAQ, some of the questions are real, some are faked to

QAML is also being used for inhouse corporate information systems; for companies where user-support is a key component but where the user-liason staff are not specialists, QAML can provide a way to make sure that when someone finds an answer, the answer is available to other people.

A text processing language reads in a text file, recognizes certain delimiters and symbolic tokens, and performs various kinds of transformations based on those tokens.

UNIX has many small text processing languages; these have been bundled together into Perl, which is the most famous general text processing language. Omnimark is another excellent text processing language, geared towards marked-up documents.

James Clark, of http://www.jclark.com, categorizes text processing languages into "push" languages (the events discovered in a document drive trigger function calls) and "pull" languages (the document is read into a data structure like a tree, and then the main function inserts the appropriate parts of the data into a template.

QAML (and other XML and SGML) documents can be processed using general-purpose text processing tools. But they can be also processed using structure-aware tools, such as XP or LotusXSL, which are freely-available implementations of the XSLT language (Extensible Stylesheet Transformation Language).

The most common thing to do with a text processing language and a QAML (or XML) document, is to transform the document in HTML. The HTML can fit into the corporate style or taste of the publisher.

Standards are very useful, because they allow us to build amazing things co-operatively.

But a standard is usually general purpose, and a general-purpose tool is usually sub-optimal than a custom-made, specific-purpose tool. So QAML is better for representing FAQs than HTML, but your own markup language will be even better for marking up your own FAQ.

But if you make your own markup language, you have to also then write all your own computer tools to use it. However, QAML is very simple, so even if you do have your own markup language for FAQs, you may find it is not difficult to export your information into QAML format, so that you can use any QAML tools. Or you may find you can convert QAML tools for your requirements too!

XML is the Extensible Markup Language. It is a simple syntax for constructing markup languages to exchange data over the WWW. QAML 2.0 documents are XML documents. (And XML documents are SGML documents.)

See http://www.w3.org/ for more details.

I18n is the contraction used to mean "internationalization", because there are 18 letters missing.

I18n means the features available to allow documents in different languages, perhaps even within the same document.

QAML 2.0 is highly internationalized, following WWW best practise. (One of QAML 2.0's authors is a member of the World Wide Web Consortium's I18n Interest Group, and proposed most of the i18n features of XML.) It currently does not have support for bi-directional text; this can be added on request.

QAML 2.0 documents can use any standard character encoding, and all elements can have an attribute xml:lang to give the language being used.

Accessability means that the document can be read by people on unusual mediums or formats: large magnifaction screens, speech synthesizers, Braille readers and so on.

QAML has been written following the World Wide Web Consortium guidelines in this area: elements with vision-dependencies have kept out, and logo images must have alternative forms.

The Dublin Core is a basic set of 13 elements which various experts have decided are a minimum useful list for capturing basic metadata about small documents on the Web. This metadata allows searching by users and rudamentary classification by librarians.

The QAML DTD (Document Type Definition) shows the mappings to the various Dublin Core elements. Also, we encourage the use of a final section, with class dc, with explicit markup of the Dublin Core elements. This assists users of printed versions of your FAQ.

For more information on Dublin Core, there is a small QAML FAQ on Metadata at http://www.ascc.net/xml/en/utf-8/dc-fq.xml.