AKFFAQ-FAQ

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

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.

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.

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

http://akfoerster.de/akffaq/

No. Only this FAQ. ☺

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

<akffaq xml:lang="en">

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

<answer>
Hello World!
</answer>
</section>

</akffaq>

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”.

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!

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.

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.

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.

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.

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.

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

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>.

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>.

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.