1--------------------------------------------------- 2makefaq 3Revision: 2.5 4Rev Date: 29 Feb 2004 5 6--------------------------------------------------- 7makefaq is a Python program that creates a Frequently Asked 8Questions (FAQ) HTML page or text file from a specially 9formatted text data file. 10--------------------------------------------------- 11 12 - Installation Notes 13 - Upgrade Notes 14 - command-line arguments 15 - configurations 16 - multi-line entries in the data file 17 - internationalization/localization issues 18 - DocBook XML export 19 - files included 20 21--------------------------------------------------- 22INSTALLATION NOTES 23 24If you are going to create a FAQ and use the sample 25files provided, **PLEASE** change the files (faqheader.html 26and faqfooter.html) to provide *YOUR* contact information. 27Because my (Dan) email address has previously been listed in 28the sample files, I have been contacted by several people 29who came across a makefaq-created FAQ somewhere on the Web 30and could only find my address to which to send e-mail. 31 32By the way, you do not *need* to include the line "This list of 33questions and answers was generated by makefaq..." I included 34that line purely as a sample. (faqfooter.html) 35 36--------------------------------------------------- 37UPGRADE NOTES 38 39If you have been using a previous version of makefaq, please look 40at the UPGRADING file to see if there are any issues that affect 41your use of the program. 42 43Please note that with version 2.0, there is a MAJOR change to 44the data file format. Old data files will NOT work with the 45program unless you use the '-r 1' ("revert") command-line option. 46 47--------------------------------------------------- 48 49COMMAND LINE ARGUMENTS 50 51makefaq can be run alone as 'makefaq.py', but it also 52has the following options: 53 54 -b footer-file - default is 'faqfooter.html' ('b' for 'bottom') 55 -c config-name - use configuration 56 -h - display help 57 -i input-file - default is 'faq.dat' 58 -j - insert "Return to top of page" links 59 -l - list all configurations 60 -L locale - reads LANG environment variable or defaults to 'en_US' 61 -n - "do nothing" - check config but skip file processing 62 -N - suppress numbering of questions and categories 63 -o output-file - default is 'faq.html' 64 -r 1 - revert to old, single-line data file format 65 -s - sort categories in alphabetical order 66 -t header-file - default is 'faqheader.html' ('t' for 'top') 67 -v - display config settings 68 69Note that if the '-r 1' is used to revert to the old file format, the 70following option may be used to change the delimiter: 71 72 -d delimiter - default is the pipe character ('|') 73 74It has no effect if the '-r 1' option is not used. The "1" is necessary 75because a future version of the program may use a pure XML format, at 76which point the pseudo-XML currently used will be available by using 77"-r 2". 78 79Without any command-line options, makefaq reads in the data 80from 'faq.dat' and writes the output to 'faq.html', using 81'faqheader.html' and 'faqfooter.html' for a header and footer. 82 83--------------------------------------------------- 84 85CONFIGURATIONS 86 87makefaq.py includes five configurations in the code: 88 89 default - standard files, writes to faq.html 90 text - standard files, writes to faq.txt 91 screen - standard files, writes to screen 92 DocBookXML - uses header of 'faqheader.xml', footer of 'faqfooter.xml' 93 and writes to 'faq-output.xml' 94 BEAST - uses header of 'html.1.faq', footer of 'html.2.faq', 95 and writes to 'faq.html' 96 97This last config is one Dave uses for http://beast.gtk.org/ 98and is provided as an example of how you might set up your 99own configuration. 100 101--------------------------------------------------- 102 103MULTI-LINE ENTRIES 104 105As of version 2.0, there was a new format for the data file. 106Instead of entries being required to be on a single line 107separated by the pipe ('|') symbol, the file now uses 108and XML-ish format with the fields separated by tags in 109angle brackets. For example: 110 111 <c>General 112 <q>When will the snow melt in Ottawa? 113 <a>I have <i>no</i> idea! 114 115Note that as in the previous file format, HTML can be used 116in either the question or answer field. The program simply 117looks for instances of <c>, <q> and <a>. Note that at the 118moment, it *is* case-sensitive. If you were to use <C>, it 119would NOT work properly. 120 121As before, the first field, <c>, is the "category" of question, 122which is used for grouping questions together in the FAQ output. 123You can have as many or as few categories as you wish, but you 124must have at least *one* category. You do not have to put all 125questions that are in the same category together in the data file, 126as the program will automagically put all those questions together. 127Note that the categories will be output *in the order in which 128they first appear* in the data file, unless the '-s' flag is used, 129in which case they will be sorted alphabetically before being 130written out. 131 132With this format, there are no spacing restrictions at all. 133You can put them all on one line: 134 135 <c>General<q>When will the snow melt in Ottawa?<a>I have <i>no</i> idea! 136 137or you can put the tags on their own lines: 138 139 <c> 140 General 141 <q> 142 When will the snow melt in Ottawa? 143 <a> 144 I have <i>no</i> idea! 145 146Or any combination of these formats. There is now *no* 147restriction on the length of either questions or answers. 148 149If you wish to use different delimiters than <c>, <q> and 150<a>, you can either create your own "configuration" that 151overrides the DefaultConfig settings for 'self.cdelim', 152'self.qdelim' and 'self.adelim'... or simply modify those 153variables in the DefaultConfig class definition. 154 155Note that if you do not wish to type a <p> before every new 156paragraph in the faq.dat file, there is a commented out fix 157in the (version 2.1) python code that will interpret a blank 158line between text as a paragraph break and automatically 159insert a <p> tag at the beginning of the next paragraph. 160To enable this function, search for the line: 161 162 #x[2] = sub('\n\n','\n<p>\n',x[2]) 163 164which can be found in the ReadSource function and uncomment 165the line (remove the '#' character from the beginning of the line). 166This line is not included by default because it may generate 167extra <p> characters where you do not want them. 168 169--------------------------------------------------- 170 171INTERNATIONALIZATION/LOCALIZATION ISSUES 172 173Up until version 2.0, makefaq always printed two strings 174in English: "FAQ Revised:" and "Table of Contents". It then 175put the time in US format after "FAQ Revised:". While this 176worked for many people, those working with languages other 177than English wanted makefaq to automatically use the date 178format and wording appropriate for their language. 179 180Thanks to the help of Guy Brand, I have added support to 181version 2.0 for localization of the makefaq output. In fact, 182it now will localize the file *by default*. It first looks 183to see if you have defined the LANG environment variable. 184If you have, the program will set your locale equal to 185the contents of the LANG variable. It will then use that 186variable to generate an appropriate time string and, in 187some cases, the appropriate text strings. 188 189For instance, if you are in the US, your LANG should be 190set to 'en_US'. In France, it will be 'fr_FR'. 191In Germany, 'de_DE'. In Brazil, 'pt_BR'. In Italy, 'it'. 192 193If you do not have the LANG variable set, the program will 194default to 'en_US', which is really the pre-2.0 behavior. 195 196If you do not have the LANG variable set, but want to modify 197the locale, the easiest option is to use the '-L' (upper case) 198command-line option to set the locale to whatever you want. 199For example: 200 201 ./makefaq.py -L 'fr_FR' 202 203It will work fine with any other command-line options. 204 205You also can edit the makefaq.py file directly and change 206the LOCALE variable at the very top of the file. Note that 207this variable is ONLY consulted if LANG is *NOT* defined 208in your operating system environment. If LANG *is* defined, 209that value will be used and the LOCALE variable will not 210be used at all. 211 212Once the locale is set, the appropriate time string will be 213generated in all cases. However, at the time I am writing 214this, there are only four cases where the appropriate text 215strings will be written out: en_US, fr_FR, de_DE, and pt_BR. 216Those are the only languages for which I have the appropriate 217strings. 218 219IF YOU WOULD LIKE TO ADD YOUR LANGUAGE, simply add a block 220of text that looks like: 221 222 elif lc == 'de_DE': 223 cfg.RevString = 'FAQ �berarbeitet am:' 224 cfg.TOCString = 'Inhalt' 225 226to the function "LocalizeStrings" inside of makefaq.py. 227I would also ask that you send the information about your 228locale and text strings to me at 'dyork@Lodestar2.com' 229so that I can add them to the program for others to use. 230 231NOTE TO USERS ON NON-LINUX PLATFORMS: It appears that current versions of 232the locale module supplied with Python on at least Windows, HP-UX and 233FreeBSD 4.x do not allow the operating system locale to be set. Because 234of this, the exact format of the date/time stamp may not be localized to 235the conventions of your locale. Other than that, however, the program 236will work fine and, if you are using one of the locales mentioned above, 237the appropriate text strings *will* be printed out. 238 239--------------------------------------------------- 240 241DOCBOOK XML EXPORT 242 243As of version 2.4, a configuration is available that allows for 244the *export* of your FAQ data into DocBook XML. Specifically 245a <qandaset> is generated. This DocBook XML file can now be 246processed into formats such as PDF, PostScript, HTML and 247HTML Help using DocBook processing tools. 248 249Note that the contents of the <q> and <a> sections of your data 250file are simply copied to the XML output file. If you have 251entered HTML tags into either of those sections, they will be 252copied over and will make the resulting XML file invalid. 253 254For more information about DocBook, please see 255http://www.docbook.org/ and http://www.oasis-open.org/docbook/ 256 257--------------------------------------------------- 258 259FILES INCLUDED 260 261With this program, there should be the following files: 262 263 makefaq.py - the python script 264 faq.dat - sample data 265 faq.html - sample HTML output 266 faq.txt - sample text output 267 faq-output.xml - sample DocBook XML output 268 faq.css - CSS stylesheet used by HTML file 269 faqheader.html - default HTML header 270 faqfooter.html - default HTML footer 271 faqheader.txt - default text header 272 faqfooter.txt - default text footer 273 faqheader.xml - default DocBook XML header 274 faqfooter.xml - default DocBook XML footer 275 html.1.faq - sample modified HTML header 276 html.2.faq - sample modified HTML footer 277 BUGS - list of bugs 278 CREDITS - list of acknowledgements 279 LICENSE - yet another copy of the license 280 README - this file 281 TODO - list of changes to be made 282 UPGRADING - notes for people upgrading 283 ChangeLog - list of changes 284 Makefile - makefile to aid in installation 285 makefaq.1 - man page for makefaq 286 287The following two files are included as a preview of what the 288next XML-based version of makefaq may include: 289 290 faq.xml - sample XML file for next version of makefaq 291 makefaq-xml-1-0.dtd - DTD for future XML format 292 293--------------------------------------------------- 294Copyright (c) 1999-2004 Dan York, dyork@Lodestar2.com 295http://www.lodestar2.com/software/makefaq/ 296http://www.makefaq.org/ 297 298The author acknowledges significant contributions to the 299code by Dave Seidel (dave@superluminal.com) and he can 300definitely be considered as the co-author of this code. 301 302This program is free software; you can redistribute it and/or 303modify it under the terms of the GNU General Public License 304as published by the Free Software Foundation; either version 2 305of the License, or any later version. 306 307This program is distributed in the hope that it will be useful 308but WITHOUT ANY WARRANTY; without even the implied warranty of 309MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 310GNU General Public License for more details. 311http://www.gnu.org/copyleft/gpl.html 312 313--------------------------------------------------- 314$Id: README,v 1.12.2.5 2004/02/29 10:53:08 dyork Exp $ 315