akfquiz(5)                                                          akfquiz(5)



NAME
       akfquiz - file-format for quiz-games, exercises, psycho-tests


DESCRIPTION
       AKFQuiz-files can be made and edited with a normal text-editor.

       AKFQuiz-files could get the file-extension ".akfquiz" or ".aqz", but in
       lots of cases it's okay to leave the extension away.

       A line, which begins with a hash-sign (#) is  a  comment  and  will  be
       ignored.   Only  spaces  are allowed in front of the hash-sign.  If the
       hash-sign is not at the beginning, it will be regarded as normal  char-
       acter.

       The  AKFQuiz-format is based on keywords.  The keywords may be intended
       and they are case-insensitive.  To disable keywords, you  could  put  a
       hash-sign (#) in front of it.

       There  are  one-line keywords. These are for global settings.  One-line
       keywords must be at the beginning of the file,  before  the  block-ori-
       ented keywords.

       Then there are also block-oriented keywords. These build up the visible
       content of the quiz. The text for the block-oriented  keywords  has  to
       start in an new line.

       Have a look at the example-files.


keywords
       Detailed description of the keywords:


       AKFQuiz
              Put  the term AKFQuiz at the beginning of an AKFQuiz-file (after
              the #!  line if you use that). Behind that that  you  can  enter
              information about which version is needed.

              If needed you can also use a variant name like this:
              AKFQuiz-testing version 4.1.0

              Attention:  In  version 4.1.0 or higher the keyword AKFQuiz must
              be used and it must be at the  beginning  of  the  line.   Lines
              before that keyword are ignored.


       end    The  keyword end should be used at the end of a quiz-file. Lines
              after that keyword will be ignored.  So  AKFQuiz  files  can  be
              embedded in other textoriented file formats.


   line-oriented keywords:
       title: Title of the quiz - there should always be a unique title!


       author:
              The  author of the quiz. This should be the one who is responsi-
              ble for the content ie. the questions.  - not the one, who  made
              a quiz-file of it.


       authorlink:
              Link  to  the  homepage  of the autor, or the email adress. This
              should be given in form of an URI, ie. with the  protocol  name.
              For  example:  http://akfoerster.de/  or  mailto:akfquiz@akfoer-
              ster.de


       edited:
              List of people, who have edited the quiz-file


       copyright:
              the one who holds the copyright.  This keyword may  be  used  as
              alternative  to  author:.   But  there are also cases, where the
              author and the copyright-holder are different. In this case  you
              can use both keywords.


       license:
              Which  license  applies to the quiz. Please be precise about the
              name and the version of the license.

              You may put the term Public Domain here, which means, you  don't
              claim any Copyright at all.


       licenselink:
              A  link  to  the  license  text  or  an  URN which refers to the
              license.


       translator:
              the translator, if it is a translation.


       charset:
              Which charset is to be used. (The charset is not the font!)  The
              default  depends  on the platform, and it will always be written
              into the HTML-output.

              supported: UTF-8, ISO-8859-1, IBM850, US-ASCII

              (use IBM850 instead of IBM437 to avoid trouble)


       language:
              The language should be given in the usual  two-letter  abbrevia-
              tion  as  defined in ISO-639-1.  For example "en" for English or
              "de" for Deutsch. You should always use  the  correct  language-
              code, even if it's not yet supported by the programs, because it
              is copied into the (X)HTML-code for further analysis.  Languages
              not defined in ISO-639-1 should start with "x-", for example "x-
              cherokee".

              supported languages: en, de, da, it


       rtl:   can be set to "yes", "true" or "1". This means the text is writ-
              ten in a right-to-left language, eg. hebrew or arabic.

              This  is  only  supported for HTML output so far. Please contact
              me, if you want more support.


       neutral:
              can be set to "yes", "true" or "1",  which  means  the  programs
              should answer in a neutral way, ie. not mark answers as right or
              wrong or say that less than 1 point is "not enough" or so.  This
              should  be  used  together  with  the keywords "assessment:" and
              "assessmentlink:".


       assessmentlink:
              A link, which references a document, which  explains,  what  the
              result  means.   It could say for example "over 80% is good, 10%
              or less is bad".

              Assessmentlink is only used, when the output  is  HTML  (mkquiz,
              akfquiz.cgi).  You  should  also  use the block-keyword "assess-
              ment:" as alternative for the other  programs.  Only  using  the
              keyword "assessment:" is also okay when it's enough for you.

              Advanced  use: When the last character of the URI is a question-
              mark (?), then values for "points",  "maxpoints"  and  "percent"
              are appended, so that they can be used by scripts.

              Example: assessmentlink: schulnote.html?

              This  example-file  calculates a school-mark (german school-sys-
              tem).  It uses JavaScript. Of course you can also use CGI or PHP
              scripts.


       htmlcode:
              can be set to "yes", "true" or "1", if you want to use HTML-code
              in the file directly - the HTML-tags are copied into  the  HTML-
              output  directly.   Other AKFQuiz-interpreters simply skip HTML-
              tags.
              Attention: You should then use &lt; for <, &gt; for >, &amp; for
              &  and &quot; for "!  These HTML-entities are also recognized by
              non-HTML-based AKFQuiz-interpreters. The entity &euro;  is  also
              supported.

              The  automatic URI recognition (see below) is switched off, when
              htmlcode: is activated.


       baseURI:
              URI for the image files and CSS-files.  Can  be  a  relative  or
              absolute  address.  This  keyword  is only used for akfquiz.cgi.
              Example: /akfquiz


       layout: (css:)
              points to a CSS file. This keyword  just  makes  sense  for  the
              (X)HTML-output  and  is  ignored otherwise.  CSS-files influence
              the appearance of the quiz in a web-browser.  The implementation
              for  different  output  media  should  be  done  in the CSS file
              itself.  You may use my example files in your own  projects  and
              distribute them together.


       keywords:
              Keywords  for  the  meta-data  of  (X)HTML-files.   Used by some
              search-engines.


       javascript:
              can be used to point to another JavaScript file.   This  keyword
              is obsolete now. Don't use it.


       noindex:
              can be set to "yes", "true" or "1". It puts a command for search
              engines into the (X)HTML-code, saying that the quiz  should  not
              be  indexed  in  the  search engine. Most search engines respect
              this command.


       default:
              default answer for questions with just one correct answer.  This
              answer  is  always  listed  as  the  last  one and is checked by
              default.  You should use this keyword, if you want to give nega-
              tive values for wrong answers.


   block-oriented keywords:
       comment:
              puts a comment into the quiz. The comment may have several lines
              and is closed by an empty line.  Comments  can  be  put  at  the
              beginning,  between the questions or at the end. You cannot have
              an empty line in one comment. To begin a new  paragraph,  put  a
              single  dot  as  only  character  in  a  line  (Whitespace still
              allowed).  (see also "hint:" and "assessment:")


       hint:, remark:
              This is similar to a "comment:", but it is only shown after  the
              previous question has been answered. So for the interactive ver-
              sions of AKFQuiz there is no difference to a "comment:", but  in
              the  HTML variants the "hint:" is only shown on the result page.


       question:, mc:
              defines a question with just one possible answer. There  may  be
              more  than  one  correct answer, but just one can be chosen, for
              example for "best guess"-questions.

              The question can have several lines and is closed  by  an  empty
              line.   To begin a new paragraph, put a single dot as only char-
              acter in a line (Whitespace still allowed).

              Then the possible answers and their score follow: put the  score
              for  an  answer  at  the beginning of the line, then one or more
              spaces or tabs and then the answer-text. If you need  more  than
              one  line,  put  a backslash (\) at the end of the line to show,
              that the text is not yet ended.

              example:

              question:
              The question can have more than one line.
              Paragraphs are also possible.
              .
              Can answers also have more than one line?

              0 No
              1 yes, but you have to mask the end of the line \
                with a backslash

              Useful values for the score are either 0 and 1, or  -1  and  +1.
              But other integer values are also possible if appropriate.

              (see also "multi:", "default:")


       multi:, query:, mcma:
              defines  a  question,  that  could  have  more  than one correct
              answer.  In contrast to the keyword  "question:"  the  user  can
              choose  several answers at the same time. The format is the same
              as in the keyword "question:". But the values 0 and 1  shouldn't
              be  used  here, because then the user could simply choose every-
              thing to get the full score.  You should work with the values -1
              and +1 instead.  The keyword "default:" has no influence here.


       assessment:
              like a comment:-field, but it's shown at the very end.  The key-
              word "assessment:" has to be at the end of the  quiz!   AKFQuiz-
              interpreters  only  show  that comment after they calculated the
              result.

              When the output is HTML (mkquiz, akfquiz.cgi)  and  the  keyword
              assessmentlink:  is given, then this assessment is not shown. So
              both keywords can be used as alternatives for  different  output
              formats.

              (see also "assessment%:")


       assessment%:
              The  content  of  the  "assessment%:" block looks similar to the
              answers to a question; first a number at the  beginning  of  the
              line,  then one or more spaces or tabs and then the text. If you
              need more than one line, put a backslash (\) at the end  of  the
              line  to show, that the text is not yet ended. But the number in
              this case means the minimum  percentage  needed  for  the  given
              assessment-text.    Attention:  The  values  must  be  given  in
              descending order and the last entry must be 0!

              The keyword "assessment%:" has to be at the end of the quiz!

              Example:

              assessment%:
              95 very good
              80 good
              65 satisfactory
              45 adequate
              25 not so good
              0  that's bad

              When the output is HTML (mkquiz, akfquiz.cgi)  and  the  keyword
              assessmentlink: is given, then this assessment% is not shown. So
              both keywords can be used as alternatives for  different  output
              formats.

              (see also "assessment:")


AUTOMATIC URI RECOGNITION
       The  Web  based  variants  of  AKFQuiz automatically recognize most URI
       schemes when "htmlcode" is not set.  URIs may be surrounded  by  spaces
       or  tabs  or  quote characters (") or enclosed with <...>. When the URI
       doesn't start with a known protocal idetifier, you can prepend it  with
       "URI:"  or "URL:", so you can have relative addresses. Protocol identi-
       fiers must be given in lower case letters, while the prefixes "URI:" or
       "URL:" mut be in upper case letters. "URN:" can be used both, uper case
       or lower case.

       Images can be directly included into the webpage by  using  the  prefix
       "image:".   Attention:  the positioning of images is still experimental
       and may change in later versions.


   Examples:
       http://akfoerster.de/akfquiz/
       <http://akfoerster.de/akfquiz/>
       URI:next.html
       image:URI:next.png
       <mailto:akfquiz@akfoerster.de>
       telnet://akf@akfoerster.de/
       file://localhost/usr/share/pixmaps/myimage.png

       Many other URIs are supported.

       Use "file:"-URIs only as last resort, when nothing else is possible.


ADVANCED USE
       On Posix-compatible systems you can make the  quiz-file  executable  by
       writing the following in the very first line:
       #! /usr/bin/env akfquiz
       Then you can set the execution bit with the command chmod(1).

       As MIME-type you should use application/x-akfquiz.



LICENSE
       Copyright  2003-2006 Andreas K. Foerster
       <akfquiz@akfoerster.de>

       AKFQuiz  is  free  software;  you  can redistribute it and/or modify it
       under the terms of the GNU General Public License as published  by  the
       Free  Software Foundation; either version 2 of the License, or (at your
       option) any later version.

       AKFQuiz is distributed in the hope that it will be useful, but  WITHOUT
       ANY  WARRANTY;  without even the implied warranty of MERCHANTABILITY or
       FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General  Public  License
       for more details.



INTERNET
       contact:
              mailto:akfquiz@akfoerster.de


       homepage:
              http://akfoerster.de/akfquiz/


       examples:
              http://akfoerster.de/akfquiz/quiz.html


       publish quiz:
              http://akfoerster.de/akfquiz/quizupload (no guaranty!)



SEE ALSO
       scrquiz(1)   grquiz(1)   diaquiz(1)  mkquiz(1)  cgiquiz(8)  linequiz(1)
       gtkquizchooser(1)




AKFQuiz                              4.2.2                          akfquiz(5)
