


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



                           11 Nov 2002                          1





MAKEFAQ(1)                                             MAKEFAQ(1)


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 pro-
       vided 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 sep-
       arated 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  cate-
       gories  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?



                           11 Nov 2002                          2





MAKEFAQ(1)                                             MAKEFAQ(1)


         <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  sim-
       ply 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 for-
       mat  after  "FAQ  Revised:".  While  this worked for many people, those
       working with languages other than English wanted makefaq  to  automati-
       cally 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 vari-
       able at the very top of the file. Note that this variable is ONLY  con-
       sulted  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



                           11 Nov 2002                          3





MAKEFAQ(1)                                             MAKEFAQ(1)


       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 oth-
       ers 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.6(1)
































                           11 Nov 2002                          4


