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

FreeBSD Manual Pages


home | help

NAME - creates a FAQ HTML page or text file

SYNOPSIS  [-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

DESCRIPTION  is  a  Python program that creates a	Frequently Asked Ques-
       tions (FAQ) HTML	page or	text file from a specially formatted text data

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

CONFIGURATIONS 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 and is pro-
       vided as	an example of how you might set	up your	own configuration.

       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:

	 <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 au-
       tomagically 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>

       or you can put the tags on their	own lines:

	 When will the snow melt in Ottawa?
	 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.

       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  lo-
       cale  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 lo-
       cale, the easiest option	is to use the '-L' (upper  case)  command-line
       option to set the locale	to whatever you	want.  For example:

       ./ -L 'fr_FR'

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

       You  also  can  edit the 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 environ-
       ment. 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	I  would  also
       ask that	you send the information about your locale and text strings to
       me at '' so that I can add them to the  program  for
       others to use.

       Mail me if you find any.

       Dan York	<>

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


				  11 Nov 2002			 MAKEFAQ.PY(1)


Want to link to this manual page? Use this URL:

home | help