/*
rTxt2htm_README.txt
rTxt2htm 1.0.2 documentation, 22 September 2007
Copyright Santosh Patnaik
GPLv3 license
A PHP Labware internal utility - http://www.bioinformatics.org/phplabware/internal_utilities
*/

Download latest original file from http://bioinformatics.org/phplabware/downloads/rTxt2htm.zip


== Content ==========================================================


1  About
  1.1  License & copyright
  1.2  Formatters  
2  Usage
  2.1  Simple
  2.2  Modifying layout and style
  2.3  Modifying code logic
  2.4  Usage with non-English text
3  Other
  3.1  Upgrade
  3.2  Changelog
  3.3  Support
  3.4  Donate


== 1  About =========================================================


rTxt2htm creates standalone, XHTML 1-strict HTML files from text files with special but simple and unobtrusive markup. It is intended for generating HTML versions of plain-text documentation (like 'readme' files that accompany software distributions; the 'r' in rTxt2htm hints at `readme`).

Documentation files are often in plain-text format, which, while versatile, lacks the enhanced functionality of hyperlinks that allow one to jump between sections of the documentation or to resources outside it.

rTxt2htm parses text files written in a specific format for URLs, sections, code fragments, styled text, tables of content, etc., creating the necessary HTML elements for presentation in the HTML output.


-- 1.1  License & copyright -----------------------------------------


rTxt2htm is free software licensed under GPL license version 3 and copyrighted by Santosh Patnaik, MD, PhD. One may freely modify and use portions of the code.


-- 1.2  Formatters -------------------------------------------------o


rTxt2htm looks for specific white-spacing, characters, etc. ('formatters') in the plain-text files for creating the necessary HTML elements.

The formatters that rTxt2htm uses are simple and unobtrusive, and yet meaningful inside plain-text files. A comparison of the HTML:- rTxt2htm_README.htm, and the plain-text:- rTxt2htm_README.txt versions of this 'readme' documentation shows this clearly.

Formatters (processing done in the shown order) are:

*  A block of text with '+-----(5 or more)+' at top and at bottom (leading or trailing spaces are okay) is rendered as plain, unformatted, mono-spaced text for tables, ASCII diagrams, etc.; rest of formatters don't apply to its content. Like:

    +-----------+
     +~~~~ ~~~~+
     | *hello* |
     +~~~~ ~~~~+
    +-----------+

*  A block of text with '== Content ==(any number of)' at top and atleast one empty lines at bottom is considered a table of content (TOC); rest of formatters except those for styled text don't apply to its content. Lines inside the block are made into TOC items, that get auto-linked to different sections, etc., if they have the identifying numbers for the sections, etc.

*  A block of text flanked with '/*' style PHP comment markers will be shown in a `subtle` 'div' element. Like:

   /*
   Some subtle text
   Like comments
   */

*  Four or more spaces before a sentence lead to the sentence being shown as code (a tab is considered equal to 4 spaces). Like this:

    <this is some 'code'>

*  Flanking a word or phrase with ' makes it rendered as a special 'span' element, 'like this' (URL and bold or italics formatters are not applied to it). Flanking a word or phrase with ` `italicizes it`. Flanking a word or phrase with * makes it *appear bold*. 

*  A word followed by ':-', a space, and then another word is rendered as the first word hyperlinked to the location pointed out by the second one. E.g.:

   --  for rTxt2htm support, see section:- #3.2
   --  rTxt2htm was created for documenting htmLawed:- http://www.bioinformatics.org/phplabware
   
*  Words with 'http:', 'https:', 'mailto:', 'ftp:', 'file:', and 'sftp:' are rendered with appropriate hyperlinks. Like, http://www.bioinformatics.org/phplabware.

*  Two '=' characters followed by optional spaces and then text followed by more '=' characters on a new line that is preceded by an empty line indicate a `section` start. The text is shown as an 'h2' element. Any o's at the end are for 'div' closures. If the text has a leading number like '1' and '3.2.1', the section gets an anchor named the same as the number but prefixed with 's', like 's1' and 's3.2.1'.

*  For `sub-sections` (rendered with an 'h3' element) and `sub-sub-sections` (rendered with an 'h4' element), instead of the '=' character, the characters '-' and '.' respectively are used. 

*  Five or more underscores on a line by themselves and preceded by an empty line are rendered as an 'hr' element; any o's at the end are, like with the formatters for sections, etc., for 'div' closures.

*Note*:

Empty spaces are preserved, so any indentation is preserved. For bold, italicized or otherwise stylized text, the characters '[' and '(' if at the beginning, and characters '?', ';', '!', ':', ',', '.', ')', and ']' if at the end of a word/phrase are not stylized. Same is true for hyperlinking.

Formatters for HTML lists, tables, colored text, etc., are missing as such information either cannot be expressed in plain-text format or is adequately functional in it without a need for a formatter.


== 2  Usage =======================================================oo


rTxt2htm should work with PHP 4.3 and higher.


-- 2.1  Simple ------------------------------------------------------


It is assumed that the plain-text has the 'formatters' in place as described in section:- #1.2, and that it has been placed on the server.

To generate an HTML version of it, edit the values for the variables '$text_file', '$meta_desc' and '$meta_kword' at the beginning of the code in 'rTxt2htm.php'. Place the 'rTxt2htm.php' file on the server and browse to its location using a web browser. If you are satisfied with the output, save the web-page, appropriately renaming it. The HTML version can now be distributed to others.

Some browsers do not save web-pages as originally authored. In such a case, you may want to `directly` save the output of rTxt2htm. If so, set '$direct' at the beginning of the code in 'rTxt2htm.php' to '1'.


-- 2.2  Modifying styles and layout --------------------------------o
    
    
Simple editing of the '$css' variable value in the code in 'rTxt2htm.php' should generally be enough.


-- 2.3  Modifying code logic ---------------------------------------o


Code inside 'rTxt2htm.php' is reasonably documented with inline comments. You can edit regular expression patterns inside it, e.g., to implement customized formatters.


-- 2.4  Usage with non-English text --------------------------------o


rTxt2htm should work well with non-English text. Ensure you have the proper values set for variables '$enc' and '$lang' at the beginning of the code in 'rTxt2htm.php'.
    
 
== 3  Other =======================================================oo


-- 3.1  Upgrade -----------------------------------------------------


Simply replace the 'rTxt2htm.php' file.


-- 3.2  Changelog --------------------------------------------------o


v1.0.2 - released Sep 22, 2007
  
  *  file: URL auto-linking, nesting for some formatters
  *  minor bug-fixes

v1.0.1 - released Sep 21, 2007
  
  *  text-styling works for items in table of contents
  *  new formatter for unformatted text for displaying tables, ASCII diagrams, etc.

v1.0 - released Sep 13, 2007
  

-- 3.3  Support ----------------------------------------------------o


For possible updates, follow up at http://www.bioinformatics.org/phplabware/internal_utilities (which also has a forum). For general PHP issues (not rTxt2htm-specific), check on the internet and at http://php.net.
  
    
-- 3.4  Donate -----------------------------------------------------o


A donation in any currency and amount to appreciate or support this software can be sent by PayPal:- http://paypal.com to this email address: drpatnaik at yahoo dot com.

Thank you!

___________________________________________________________________oo