MAKEFAQ(1)                                                          MAKEFAQ(1)



NAME
       makefaq - creates a FAQ HTML page or text file

SYNOPSIS
       makefaq [-h] [-v] [-n] [-N] [-l] [-j] [-s] [-r 1] [-c config-name] [-i
       input-file] [-o output-file] [-t header-file] [-b footer-file] [-d
       delimiter]

DESCRIPTION
       makefaq is a Python program that creates a Frequently Asked Questions
       (FAQ) HTML page or text file from a specially formatted text data file.

OPTIONS
       -h     Display help

       -n     Do "nothing" - check config but skip file processing

       -N     Suppresses the numbering of questions.

       -l     List all configurations

       -v     Display config settings

       -s     Sort categories in alphabetical ordeer

       -j     Adds a link after each entry to jump to top of page

       -i input-file
              Default is 'faq.dat'

       -o output-file
              Default is 'faq.html'

       -t header-file
              Default is 'faqheader.html'

       -b footer-file
              Default is 'faqfooter.html'

       -L locale
              Reads LANG environment variable or defaults to 'en_US'

       -r 1   Revert to old, single-line data file format

              Note that if the '-r' is used to revert to the old file format,
              the following option may be used to change the delimiter.

       -d delimiter
              default is the pipe character ('|')

              It has no effect if the '-r' option is not used.

EXAMPLE
       makefaq -c default -i input.dat -o output.html

CONFIGURATIONS
       makefaq includes five configurations in the code:

       default - standard files, writes to faq.html
       text    - standard files, writes to faq.txt
       screen  - standard files, writes to screen
       DocBookXML - standard files, writes to faq-output.xml
       BEAST   - uses header of 'html.1.faq' and footer of
                 'html.2.faq', writes to faq.html


       This last config is one Dave uses for http://beast.gtk.org/ and is
       provided as an example of how you might set up your own configuration.

MULTI-LINE ENTRIES
       With version 2.0, there is a new format for the data file.  Instead of
       entries being required to be on a single line separated by the pipe
       ('|') symbol, the file now uses and XML-ish format with the fields
       separated by tags in angle brackets. For example:

         <c>General
         <q>When will the snow melt in Ottawa?
         <a>I have <i>no</i> idea!


       Note that as in the previous file format, HTML can be used in either
       the question or answer field. The program simply looks for instances of
       <c>, <q> and <a>. Note that at the moment, it *is* case-sensitive. If
       you were to use <C>, it would NOT work properly.

       As before, the first field, <c>, is the "category" of question, which
       is used for grouping questions together in the FAQ output.  You can
       have as many or as few categories as you wish, but you must have at
       least *one* category. You do not have to put all questions that are in
       the same category together in the data file, as the program will
       automagically put all those questions together.  Note that the
       categories will be output *in the order in which they first appear* in
       the data file, unless the '-s' flag is used, in which case they will be
       sorted alphabetically before being written out.

       With this format, there are no spacing restrictions at all.  You can
       put them all on one line:

       <c>General<q>When will the snow melt in Ottawa?<a>I have <i>no</i>
       idea!

       or you can put the tags on their own lines:

         <c>
         General
         <q>
         When will the snow melt in Ottawa?
         <a>
         I have <i> no</i> idea!


       Or any combination of these formats. There is now *no* restriction on
       the length of either questions or answers.

       If you wish to use different delimiters than <c>, <q> and <a>, you can
       either create your own "configuration" that overrides the DefaultConfig
       settings for 'self.cdelim', 'self.qdelim' and 'self.adelim'... or
       simply modify those variables in the DefaultConfig class definition.

INTERNATIONALIZATION
       Up until version 2.0, makefaq always printed two strings in English:
       "FAQ Revised:" and "Table of Contents". It then put the time in US
       format after "FAQ Revised:". While this worked for many people, those
       working with languages other than English wanted makefaq to
       automatically use the date format and wording appropriate for their
       language.

       Thanks to the help of Guy Brand, I have added support to version 2.0
       for localization of the makefaq output. In fact, it now will localize
       the file *by default*. It first looks to see if you have defined the
       LANG environment variable.  If you have, the program will set your
       locale equal to the contents of the LANG variable. It will then use
       that variable to generate an appropriate time string and, in some
       cases, the appropriate text strings.

       For instance, if you are in the US, your LANG should be set to 'en_US'.
       In France, it will be 'fr_FR'.  In Germany, 'de_DE'. In Italy, 'it'.

       If you do not have the LANG variable set, the program will default to
       'en_US', which is really the pre-2.0 behavior.

       If you do not have the LANG variable set, but want to modify the
       locale, the easiest option is to use the '-L' (upper case) command-line
       option to set the locale to whatever you want.  For example:

       ./makefaq -L 'fr_FR'

       It will work fine with any other command-line options.

       You also can edit the makefaq file directly and change the LOCALE
       variable at the very top of the file. Note that this variable is ONLY
       consulted if LANG is *NOT* defined in your operating system
       environment. If LANG *is* defined, that value will be used and the
       LOCALE variable will not be used at all.

       Once the locale is set, the appropriate time string will be generated
       in all cases. However, at the time I am writing this, there are only
       three cases where the appropriate text strings will be written out:
       en_US, fr_FR, and de_DE.  Those are the only languages for which I have
       the appropriate strings.

       IF YOU WOULD LIKE TO ADD YOUR LANGUAGE, simply add a block of text that
       looks like:

           elif lc == 'de_DE':
              cfg.RevString = 'FAQ uberarbeitet am:'
              cfg.TOCString = 'Inhalt'


       to the function "LocalizeStrings" inside of makefaq.  I would also ask
       that you send the information about your locale and text strings to me
       at 'dyork@Lodestar2.com' so that I can add them to the program for
       others to use.

BUGS
       Mail me if you find any.

AUTHOR
       Dan York <dyork@lodestar2.com>

       The author acknowledges significant contributions to the code by Dave
       Seidel (dave@superluminal.com) and he can definitely considered as the
       co-author of this code.

SEE ALSO
       python2.7(1)



                                  11 Nov 2002                       MAKEFAQ(1)
