Skip site navigation (1)Skip section navigation (2)

  
 
  

home | help 
MAKEFAQ.PY(1)							   MAKEFAQ.PY(1)

NAME
     makefaq.py - creates a FAQ HTML page or text file

SYNOPSIS
     makefaq.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  delim-
     iter]

DESCRIPTION
     makefaq.py  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.py -c default -i input.dat -o output.html

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 - 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 en-
     tries 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  cate-
     gory  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 ei-
     ther create your own "configuration" that overrides the DefaultConfig  set-
     tings  for 'self.cdelim', 'self.qdelim' and 'self.adelim'... or simply mod-
     ify 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  lan-
     guages other than English wanted makefaq to automatically use the date for-
     mat 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 environ-
     ment 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.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 vari-
     able 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.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.

BUGS
     Mail me if you find any.

AUTHOR
     Dan York <dyork@lodestar2.com>

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

SEE ALSO
     python(1)

				   11 Nov 2002			   MAKEFAQ.PY(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=makefaq&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>

home | help