general questions

writing FAQs

general questions

What is AKFFAQ?

AKFFAQ is an easy XML-based language for writing FAQs (“Frequently Asked Questions”).

What is a FAQ?

FAQ stands for “Frequently Asked Questions”. Whether these questions are really frequently asked is another topic. Some people like me simply like this style of writing.

What else could AKFFAQ be used for?

AKFFAQ can be used for anything where there are questions or claims and answers for them. For example also for interviews, or for debunking myths.

What is the current status of AKFFAQ?

Alpha — That means it is still under developement and the definition may still change.

What is the official website for AKFFAQ?


Is there any documentation for AKFFAQ?

No. Only this FAQ. ☺

writing FAQs

Could you show me a small example to get me started?

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE akffaq SYSTEM "akffaq.dtd">
<?xml-stylesheet type="text/xsl" href="akffaq.xsl"?>

<akffaq xml:lang="en">

<question id="greet">
Do you want to greet somebody?

Hello World!


The first three lines might look complicated first. But don't worry. In most cases you can simply copy them as they are. They are not always all necessary, but it is better to put them in there, just in case.

Please note that there must be at least one “section”. If you want to use more than just one, you should use the attributes “id” and “title”.

What does the first line mean?

This line is makes it clear, that it is an XML-document. That line need not be there, but then you can only use the UTF-8 or UTF-16 encoding.

The parameter “version” means the version of the XML specification. It is not the version number for your FAQ nor is it the version number of AKFFAQ. Just use 1.0 for now and nothing else.

The encoding however is the encoding of your XML-file. UTF-8 is a good encoding for almost any language. But if your text-editor cannot save a text as UTF-8, then replace it with the encoding that your editor can use. On old systems you can replace it for example with “ISO-8859-1”.

But if you can save it as UTF-8, then use that!

What is the “DOCTYPE” line for?

The DOCTYPE line is a reference to the “Document Type Definition” (DTD). The DTD file “akffaq.dtd” is the machine-readable specification of the AKFFAQ-format. This is used by some programs to check your file for formal errors. But note that a lot of programs don't do that.

In the DTD file there can also be definitions for so called “entities”. For example the akffaq.dtd defines &smiley; for a smiley (☺). Unfortunately some programs don't read the DTD file at all, so that doesn't always work. ☹ But there are hacks to work around it.

Now what is that “xml-stylesheet”-line for?

This refers to the file “akffaq.xsl”. And that file is where the real work for AKFFAQ is done.

Actually I think “stylesheet” is really a misnomer. This is a script that converts the XML-file into HTML. It is not only a simple translation, but it is really a little programming language with which many things can be automated. For example in AKFFAQ the table of contents can be created automatically...

New web-browsers can display the XML-file with this script directly. But you can also use external tools to convert it into HTML, so that also older browsers are supported.

With which program can I convert it under GNU/Linux?

Most GNU/Linux-Systems already have the tool “xsltproc” installed. Use it like this: xsltproc akffaq.xsl myfaq.xml > myfaq.html.

For more info see http://xmlsoft.org/XSLT/xsltproc.html.

Tell me more about the “id”-attribute.

The “id” should be a unique identifier for the question or section. It should be short and without spaces. But you can use a hyphen or an underscore character inside of the identifier.

This identifier is used for the overview in the HTML-output. But it can also be used from other web pages to point to a specific question or section.

If you leave the “id” out, an id is automatically generated if needed. That works for the automatically generated overview. But it is not so good for links from external pages, because the generated id can be different from time to time.

You mentioned an “automatic overview”. Tell me more about that.

If you want to get an automatic overview for the HTML-output, you can put the command <overview back="back"/> either before the first section, or after the last one.

Note, that there must be a slash before the closing angle-bracket!

With the “back”-attribute you can determine the name for the links back to the overview. You could also write back="back to the overview" or something like that.

How can I write a headline for the FAQ?

User something like this: <heading>About this and that</heading>. Put that line directly after the opening <akffaq>.

How can I make paragraphs in the answers?

By enclosing each paragraph with <p>...</p>.

Unlike in HTML this always has to be used pairwise. You cannot leave the closing “</p>” away. If you use it, use it consequently.

Attention: Questions can not contain separated paragraphs!

There are actually two possibilities:

The easiest way is to enclose the link like this: <link>http://akfoerster.de</link>. In this case the target of the link is also the shown text.

If you want to have some other text as link, you can do it like in HTML:

<a href="http://akfoerster.de">Andreas K. Förster</a>.

What other tags for marking text can be used?

Emphasized text can be enclosed with <em>...</em>. Code segments can be enclosed with <code>...</code>. Larger code-blocks can be enclosed with <code-block>...</code-block>. For keyboard-inputs, you can use <kbd>...</kbd>.

There are a lot of similarities to HTML. Can I use any deliberate HTML tag in AKFFAQ documents?

No. I have defined many tags similar to HTML to make it easier for users, who already know HTML and because it was easier to convert it to HTML. But you can only use the tags and attributes, that are explicitely defined for AKFFAQ.

created using AKFFAQ