
= Some Information About The Alexis-Info Web Pages

Date: april 2003
Please send suggestions to: 
  matthew@ella-associates.org or matth3wbishop@yahoo.com

INTRODUCTION
  
  This page attempts to provide some information which may be
  useful in order to maintain the web pages under the directory /alexis-info

SOME INFORMATION

  The web pages under the directory http://www.ella-associates.org/alexis-info
  have been generated from text files. The scripts used to generate the text files
  are located in the directory http://www.ella-associates.org/alexis-info/utils/

  The most important scripts are 'plaintext2html.sh, plaintext2pdf.sh,
  linkdoc2html.sh and diary2html.sh'. Each of these scripts contains a detailed
  description in the script file of how to use the script. In general the text to HTML scripts
  can be used by typing at the 'bash shell prompt':
  -->>
     ./scriptname.sh textFilename > outputFileName
  --<<
  and the text to pdf scripts can be used by typing:
  -->>
     ./scriptname.sh textFileName outputFileName
  --<<

  Which script to use depends on the type of information contained in the text file. For
  example, the file 'mjb-work.txt' is transformed using the script 'diary2html.sh'
  because 'mjb-work.txt' contains diary type entries and information. The translation
  (or 'porting') of these scripts to Perl CGI, PHP or Java Servlets should be reasonably
  simple since the task is only a matter of converting the 'sed' regular expression
  syntax into the regular expression syntax of the target language.

  In the source of each HTML file, in the head element, is contained the information;
  which script generated the file, what was the name of the source file, and on what
  date the HTML was generated.

  Usually (but not necessarily always) the HTML file is generated from a text file
  with the same 'base-name' as the HTML file. That is, if the HTML file is called
  'resources.html', then it will have been generated from a file called
  'resources.txt'. This is also true of Adobe Acrobat files (pdf) which have
  been generated.

  In the future, the scripts may be modified to produce XML as well as HTML.
  This system of generating HTML from plain text files is less flexible and
  adaptable than using XML as the 'master file' but was simpler to set up, and
  in some ways is simpler to maintain. It should be possible to modify these
  scripts to produce a simple 'docbook' XML output. Once a Docbook XML file has
  been produced other formats are reasonably simple to produce using tools such
  as the 'xalan' XSL processore, or the 'OpenJade' tool. Another alternative
  is to use the Apache, Tomcat, Cocoon application server. Cocoon will automatically
  generate documents in a variety of formats (plain text, HTML, pdf, latex) given
  a Docbook (or other DTD) XML document and the appropriate XSL style sheets.
  This solution is perhaps more appropriate to an 'enterprise' type of environment
  where a large number of documents in a variety of formats needs to be produced.
  For the purposes of Ella-Associates this is probably not necessary. 
  
OTHER NOTES

  As a matter of interest, on the 'local server', the HTML files can be 
  generated from within the 'vim' text editor by typing ',1' or ',2'
  etc. ',1' will filter the text file currently being edited into HTML 
  using the 'plaintext2html.sh' script, ',2' does the same using the 
  'linkdoc2html.sh' script. Type ':map' to see the other 'shortcuts' which
  can be used to filter text files from within vim. (Dont actually type
  any of the single quote characters)

  for questions and comments please contact:
    matthew@ella-associates.org or matth3wbishop@yahoo.com

