---------------------------------------------------
makefaq
Revision:  2.5
Rev Date:  29 Feb 2004

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

 - Installation Notes
 - Upgrade Notes
 - command-line arguments
 - configurations
 - multi-line entries in the data file
 - internationalization/localization issues
 - DocBook XML export
 - files included

---------------------------------------------------
INSTALLATION NOTES

If you are going to create a FAQ and use the sample
files provided, **PLEASE** change the files (faqheader.html
and faqfooter.html) to provide *YOUR* contact information.
Because my (Dan) email address has previously been listed in
the sample files, I have been contacted by several people
who came across a makefaq-created FAQ somewhere on the Web
and could only find my address to which to send e-mail.

By the way, you do not *need* to include the line "This list of
questions and answers was generated by makefaq..."  I included
that line purely as a sample. (faqfooter.html)

---------------------------------------------------
UPGRADE NOTES

If you have been using a previous version of makefaq, please look
at the UPGRADING file to see if there are any issues that affect
your use of the program.

Please note that with version 2.0, there is a MAJOR change to
the data file format. Old data files will NOT work with the
program unless you use the '-r 1' ("revert") command-line option.

---------------------------------------------------

COMMAND LINE ARGUMENTS

makefaq can be run alone as 'makefaq.py', but it also
has the following options:

 -b footer-file   - default is 'faqfooter.html' ('b' for 'bottom')
 -c config-name   - use configuration
 -h               - display help
 -i input-file    - default is 'faq.dat'
 -j               - insert "Return to top of page" links
 -l               - list all configurations
 -L locale        - reads LANG environment variable or defaults to 'en_US'
 -n               - "do nothing" - check config but skip file processing
 -N               - suppress numbering of questions and categories
 -o output-file   - default is 'faq.html'
 -r 1             - revert to old, single-line data file format
 -s		  - sort categories in alphabetical order
 -t header-file   - default is 'faqheader.html' ('t' for 'top')
 -v               - display config settings

Note that if the '-r 1' 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 1' option is not used. The "1" is necessary
because a future version of the program may use a pure XML format, at
which point the pseudo-XML currently used will be available by using
"-r 2".

Without any command-line options, makefaq reads in the data
from 'faq.dat' and writes the output to 'faq.html', using
'faqheader.html' and 'faqfooter.html' for a header and footer.

---------------------------------------------------

CONFIGURATIONS

makefaq.py 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 - uses header of 'faqheader.xml', footer of 'faqfooter.xml'
               and writes to 'faq-output.xml'
  BEAST      - uses header of 'html.1.faq',  footer of 'html.2.faq',
               and 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

As of version 2.0, there was 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.

Note that if you do not wish to type a <p> before every new
paragraph in the faq.dat file, there is a commented out fix
in the (version 2.1) python code that will interpret a blank
line between text as a paragraph break and automatically
insert a <p> tag at the beginning of the next paragraph.
To enable this function, search for the line:

      #x[2] = sub('\n\n','\n<p>\n',x[2])

which can be found in the ReadSource function and uncomment
the line (remove the '#' character from the beginning of the line).
This line is not included by default because it may generate
extra <p> characters where you do not want them.

---------------------------------------------------

INTERNATIONALIZATION/LOCALIZATION ISSUES

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 Brazil, 'pt_BR'. 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.py -L 'fr_FR'

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

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.

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 four cases where the appropriate text
strings will be written out:  en_US, fr_FR, de_DE, and pt_BR.
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 �berarbeitet am:'
       cfg.TOCString = 'Inhalt'

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.

NOTE TO USERS ON NON-LINUX PLATFORMS: It appears that current versions of
the locale module supplied with Python on at least Windows, HP-UX and
FreeBSD 4.x do not allow the operating system locale to be set. Because
of this, the exact format of the date/time stamp may not be localized to
the conventions of your locale.  Other than that, however, the program
will work fine and, if you are using one of the locales mentioned above,
the appropriate text strings *will* be printed out.

---------------------------------------------------

DOCBOOK XML EXPORT

As of version 2.4, a configuration is available that allows for
the *export* of your FAQ data into DocBook XML.  Specifically
a <qandaset> is generated.  This DocBook XML file can now be
processed into formats such as PDF, PostScript, HTML and
HTML Help using DocBook processing tools.

Note that the contents of the <q> and <a> sections of your data
file are simply copied to the XML output file.  If you have
entered HTML tags into either of those sections, they will be
copied over and will make the resulting XML file invalid.

For more information about DocBook, please see
http://www.docbook.org/ and http://www.oasis-open.org/docbook/

---------------------------------------------------

FILES INCLUDED

With this program, there should be the following files:

 makefaq.py        - the python script
 faq.dat           - sample data
 faq.html          - sample HTML output
 faq.txt           - sample text output
 faq-output.xml    - sample DocBook XML output
 faq.css           - CSS stylesheet used by HTML file
 faqheader.html    - default HTML header
 faqfooter.html    - default HTML footer
 faqheader.txt     - default text header
 faqfooter.txt     - default text footer
 faqheader.xml     - default DocBook XML header
 faqfooter.xml     - default DocBook XML footer
 html.1.faq        - sample modified HTML header
 html.2.faq        - sample modified HTML footer
 BUGS              - list of bugs
 CREDITS           - list of acknowledgements
 LICENSE           - yet another copy of the license
 README            - this file
 TODO              - list of changes to be made
 UPGRADING         - notes for people upgrading
 ChangeLog         - list of changes
 Makefile          - makefile to aid in installation
 makefaq.1         - man page for makefaq

The following two files are included as a preview of what the
next XML-based version of makefaq may include:

 faq.xml           - sample XML file for next version of makefaq
 makefaq-xml-1-0.dtd - DTD for future XML format

---------------------------------------------------
Copyright (c) 1999-2004 Dan York, dyork@Lodestar2.com
http://www.lodestar2.com/software/makefaq/
http://www.makefaq.org/

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

This program 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 any later version.

This program 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.
http://www.gnu.org/copyleft/gpl.html

---------------------------------------------------
$Id: README,v 1.12.2.5 2004/02/29 10:53:08 dyork Exp $