.\" This manpage has been automatically generated by docbook2man-spec
.\" from a DocBook document.  docbook2man-spec can be found at:
.\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> 
.\" Please send any bug reports, improvements, comments, patches, 
.\" etc. to Steve Cheng <steve@ggi-project.org>.
.TH "MAKEFAQ.PY" "1" "11 Nov 2002" "" ""
.SH NAME
makefaq.py \- creates a FAQ HTML page or text file
.SH SYNOPSIS
.sp
\fBmakefaq.py [-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]\fR
.SH "DESCRIPTION"
.PP
\fBmakefaq.py\fR is a Python program that creates a Frequently 
Asked Questions (FAQ) HTML page or text file from a specially formatted
text data file.
.SH "OPTIONS"
.TP
\fB-h\fR
Display help
.TP
\fB-n\fR
Do "nothing" - check config but skip file processing
.TP
\fB-N\fR
Suppresses the numbering of questions.
.TP
\fB-l\fR
List all configurations
.TP
\fB-v\fR
Display config settings
.TP
\fB-s\fR
Sort categories in alphabetical ordeer
.TP
\fB-j\fR
Adds a link after each entry to jump to top of page
.TP
\fB-i input-file\fR
Default is 'faq.dat'
.TP
\fB-o output-file\fR
Default is 'faq.html'
.TP
\fB-t header-file\fR
Default is 'faqheader.html'
.TP
\fB-b footer-file\fR
Default is 'faqfooter.html'
.TP
\fB-L locale\fR
Reads LANG environment variable or defaults to 'en_US'
.TP
\fB-r 1\fR
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.
.TP
\fB-d delimiter\fR
default is the pipe character ('|')

It has no effect if the '-r' option is not used.
.SH "EXAMPLE"
.PP
\fBmakefaq.py -c default -i input.dat -o output.html\fR
.SH "CONFIGURATIONS"
.PP
makefaq.py includes five configurations in the code:
.sp
.nf
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
.sp
.fi
.PP
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.
.SH "MULTI-LINE ENTRIES"
.PP
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:
.PP
.sp
.nf
  <c>General
  <q>When will the snow melt in Ottawa?
  <a>I have <i>no</i> idea!
.sp
.fi
.PP
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.
.PP
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.
.PP
With this format, there are no spacing restrictions at all.
You can put them all on one line:
.PP
<c>General<q>When will the snow melt in Ottawa?<a>I have <i>no</i> idea!
.PP
or you can put the tags on their own lines:
.PP
.sp
.nf
  <c>
  General
  <q>
  When will the snow melt in Ottawa?
  <a>
  I have <i> no</i> idea!
.sp
.fi
.PP
Or any combination of these formats. There is now *no* 
restriction on the length of either questions or answers.
.PP
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.
.SH "INTERNATIONALIZATION"
.PP
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.
.PP
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.
.PP
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'.
.PP
If you do not have the LANG variable set, the program will
default to 'en_US', which is really the pre-2.0 behavior.
.PP
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:
.PP
\fB\&./makefaq.py -L 'fr_FR'\fR
.PP
It will work fine with any other command-line options.
.PP
You also can edit the makefaq.py 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.
.PP
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. 
.PP
IF YOU WOULD LIKE TO ADD YOUR LANGUAGE, simply add a block 
of text that looks like:
.PP
.sp
.nf
    elif lc == 'de_DE':
       cfg.RevString = 'FAQ überarbeitet am:'
       cfg.TOCString = 'Inhalt'
.sp
.fi
.PP
to the function "LocalizeStrings" inside of makefaq.py. 
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.
.SH "BUGS"
.PP
Mail me if you find any.
.SH "AUTHOR"
.PP
Dan York <dyork@lodestar2.com>
.PP
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.
.SH "SEE ALSO"

\fBpython(1)\fR