                                                                                                                                                                                                                


<?php
//-->-->-->-->-->-->-->-->
//-- Description:
//--   The purpose of this function is to transform an FAQ type document
//--   into some kind of meaningful HTML. The plain text is expected to
//--   have as little 'mark-up' imbedded within it as is possible for 
//--   the given application. 
//--
//--   The overall purpose of this effort is to attempt to allow an
//--   author to write texts in a plain text editor such as 
//--   Microsoft Notepad, Vi, Vim, Emacs, Nano etc and for those
//--   written texts to be transformed into readable and function HTML
//--   and even possibly DocBook XML. 
//--
//-- Notes:
//--
//--   Each 'entry' in the journal is currently indicated or 'marked-up'
//--   with a star (*) character as the first character on the line and then
//--
//--   Normally, each question in the FAQ is collected into a hyperlinked
//--   table of contents which is displayed at the top of the resulting HTML
//--   page. The idea of this is to allow the reader to easily jump to 
//--   the answer for a particular question. I envisage that the occurance 
//--   of this
//--   hyperlinked table of contents should be configurable through the means
//--   of a configuration file, which will probably initially be in a simple
//--   'ini' file format, and then may be converted to an XML format. 
//--   
//--   This configuration file, I imagine, would have the same name as the 
//--   plain text 'source' document but with the extension '.conf' instead of
//--   '.txt'. So the document
//--       wagga-diary.txt     would be transformed into an HTML file called
//--       wagga-diary.html    and the exact appearance of the HTML page could
//--                           be configured via a configuration file called
//--       wagga-diary.conf
//--
//-- 
//-- Notes:
//--   This function has a lot of code in common with fnJournalToHtml and
//--   fnDocumentToHtml. I may also write a function fnFaqBlockToHtml
//--   which will not worry about trying to do things like hyperlinking
//--   and formating of lists. It will leave these tasks to other 
//--   functions
//--
//--   The function needs re-working since it currently uses the 
//--   star character to delimit the start of questions and it doesnt
//--  allow multi-line questions
//--
//-- Please see the file 
//--   fnHyperlinkPlainText.php for explanations as to what sort of 
//--   plain text structures will be hyperlinked.
//--
//-- History:
//--   This script is an evolution on previous
//--   efforts which were written in the Unix Bash
//--   shell scripting language and which relied heavily programs such
//--   as 'sed' and 'grep'. 
//--
//--   These previous efforts should be viewable at URL's such as 
//--   http://www.geocities.com/matth3wbishop/ and (if it still exists)
//--   http://www.ella-associates.org/alexis-docs/
//--
//-- Dependencies:
//--   This dependency list is not particularly reliable. 
//--
//--   fnHyperlinkPlainText
//--   fnReduplicateCharacters
//--   fnUnduplicateCharacters
//--   fnCodeBlockToHtml
//--   fnCodeBlockFromHtml
//--   fnListBlockToHtml
//--
//-- See Also:
//-- 
//--   fnMessageToHtml
//--   retrovox-notepad-save.php    
//--   retrovox-notepad.php    
//--     A script to allow editing of files located on a server using a web
//--     browser.
//--
//-- Author:
//--   matth3wbishop@yahoo.com
//--   http://www.geocities.com/matth3wbishop/
//--

function fnFaqToHtml($sPlainText)
{
  $sReturn = $sPlainText;

  //-- On lines that have nothing but spaces, delete the spaces
  //$sReturn = preg_replace("#\n\s*\n#im", "\n\n", $sReturn);

  //-- Entitize special HTML characters such as < and > so that these
  //-- characters will not be considered part of the resulting HTML.
  //-- We have to do this first so that the HTML which we later insert
  //-- (such as hyperlinks) does not also get entitized. I
  //-- might also have to entitize accented characters such as ???
  $sReturn = htmlspecialchars($sReturn);



  //-- Trailing space serves no purpose.
  $sReturn = preg_replace("#[ \t]*([\n\r])#m", "$1", $sReturn);
  
  //-- Try to allow the delimiters -->> and --<< to stop any further 
  //-- transformations on the plain text (by placing the text with HTML
  //-- <pre> tags and then doubling every letter
  $sReturn = str_replace("--&lt;&lt;", "</pre>", $sReturn);

  $sReturn = str_replace("--&gt;&gt;", "<pre>", $sReturn);
  $sReturn = 
    preg_replace(
         "#<pre>((.|\n)*?)</pre>#ime", 
         "'<pre>'.fnCodeBlockToHtml('$1').'</pre>'", $sReturn);
  

  $sReturn = 
    preg_replace(
         "#^\s*([a1Iu]-(.|\n)*?)\n\s*\n#ime", 
         "''.fnListBlockToHtml('$1').'\n\n'", $sReturn);


  //-- Make empty lines delimite HTML paragraphs
  $sReturn = preg_replace("#^\s*$#im", "</p><p>", $sReturn);

  //-- Make the title into a first level heading  
  $sReturn = 
    preg_replace("#^[ ]*=(.*)#m", "<center><h1>$1</h1></center><dl>", $sReturn);

  $sHeadings = 
     preg_replace('#^\s*[^\*].*$#im', '', $sReturn);

  $sHeadings = 
     preg_replace("#\n\s*\n#m", "\n", $sHeadings);

  //-- Get rid of the leading 'star' characters for each of the questions
  $sHeadings = 
     preg_replace("#^\s*\*\s*#m", "", $sHeadings);

  $sHeadings = 
     preg_replace("#\s*$#m", "", $sHeadings);

  $sHeadings = 
     preg_replace("#^(.*)$#m", "<li><a href = '#$1'>$1</a>" , $sHeadings);

  $sHeadings = 
     "<a name = 'toc'></a><br><ol type = '1'>".$sHeadings."</ol>";

  //echo "<pre>[$sHeadings]</pre>";
  //echo $sHeadings;
  $sReturn = preg_replace(
      "#^\s*\*\s*([^\n\r]*)#m", 
      "<dt><em><a name = '$1'>$1</a></em>&nbsp;<a href = '#toc'>[toc]</a></dt><dd>", 
      $sReturn);

  $sReturn = $sHeadings."\n".$sReturn;

  $sReturn = fnHyperlinkPlainText($sReturn);


  //-- Make a tab into 2 HTML spaces
  $sReturn = preg_replace("#\t#im", "&nbsp;&nbsp;", $sReturn);


  //-- get rid of the [*faq*] meta-tag which is used to tell the transformation
  //-- system that the current document should be transformed according to the 
  //-- rules for a journal for an faq style document.

  //-- This </dl> rubbish is a terrible hack. It is assuming that 
  //-- the faq flag occurs right at the end of the document and that
  //-- there is some kind of definition list in the doc. Very ugly.
  $sReturn = preg_replace("#^\s*\[\*faq\*\]\s*$#im", "</dl>", $sReturn);

  $sReturn = 
    preg_replace(
         "#<pre>((.|\n)*?)</pre>#ime", 
         "'<pre>'.fnCodeBlockFromHtml('$1').'</pre>'", $sReturn);

  return $sReturn;
} //-- function fnFaqToHtml 
     

//--<--<--<--<--<--<--<--<
?>
                                                                                                                                                                                                                                                