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

FreeBSD Manual Pages

  
 
  

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
       delimiter]

DESCRIPTION
       makefaq.py  is  a  Python program that creates a	Frequently Asked Ques-
       tions (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 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 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>
       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  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 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:

       ./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  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 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.

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
       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.0>

home | help