PHP Labware source code viewer / Internal utilities | 18 Apr, 2024
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv="Content-Language" content="en" />
<meta name="description" content="rTxt2htm is a text-to-HTML converter, generating HTML versions of plain text files - rTxt2htm_README.txt - presented with rTxt2htm, a PHP Labware utility" />
<meta name="keywords" content="rTxt2htm, text to HTML, generator, converter, conversion, PHP, Labware, readme, rTxt2htm_README.txt, rTxt2htm, PHP Labware" />
<style type="text/css" media="all">
<!--/*--><![CDATA[/*><!--*/
a {text-decoration:none; color: blue;}
a:hover {color: red;}
a:visited {color: blue;}
body {margin: 0; padding: 0;}
body, div, html, p {font-family: Georgia, 'Times new roman', Times;}
code.code {font-family: 'Bitstream vera sans mono', 'Courier New', 'Courier', monospace;}
div.comment {padding: 5px; color: #999999; font-size: 80%;}
div.comment a {color: #6699cc;}
div#body {width: 70%; margin: 5px; padding: 5px;} /* holds non-toc content */
div#toc {position: fixed; top: 5px; left: 73%; z-index: 2; margin-top: 5px; margin-left: 5px; border: 1px solid gray; padding: 5px; background-color: #ededed; width: 23%; overflow: auto; max-height:94%; font-size: 90%;} /* holds content table (toc) */
div#top {font-size: 14px; margin: 5px; padding: 5px;} /* holds all content */
div.monospace {overflow: auto; font-family: 'Bitstream vera sans mono', 'Courier New', 'Courier', monospace;}
div.sub-section {padding-left: 15px;}
div.sub-sub-section {padding-left: 30px;}
h1 {font-size: 22px; margin-top: 5px; margin-bottom: 5px;}
h2 {font-size: 20px; float: left; margin-top: 15px; margin-bottom: 5px;}
h3 {font-size: 18px; float: left; margin-top: 15px; margin-bottom: 5px;}
h4 {font-size: 16px; float: left; margin-top: 15px; margin-bottom: 5px;}
hr {margin-top: 15px; margin-bottom: 5px;}
input, textarea {font-family: 'Bitstream vera sans mono', 'Courier New', 'Courier', monospace;}
p.subtle {color: gray; padding: 0; padding-top: 10px; margin: 0;}
p.subtle a, p.subtle a:visited {color: #6699cc;}
span.item-no {color: black;}
span.subtle {color: gray; margin: 0; padding:0;}
span.subtle a, span.subtle a:visited {color: #6699cc;}
span.term {font-family: 'Bitstream vera sans mono', 'Courier New', 'Courier', monospace;}
span.toc-item {color: black;}
span.totop {float: right; margin-top: 15px; margin-bottom: 5px;}
span.totop a, span.totop a:visited {color: #6699cc;}
@media screen { /* fixes for old IE */
* html, * html body {overflow-y: auto!important; height: 100%; margin: 0; padding: 0;}
* html div#body {height: 100%; overflow-y: auto; position: relative;}
* html div#toc {position: absolute;}
}
/*]]>*/-->
</style>
<title>rTxt2htm documentation | rTxt2htm is a text-to-HTML converter, generating HTML versions of plain text files</title>
</head>
<body>
<div id="top">
<h1><a id="peak" name="peak"></a>rTxt2htm documentation</h1>
<div id="toc"><span class="toc-item"><a href="#s1"><span class="item-no">1</span>  About</a></span><br />
  <span class="toc-item"><a href="#s1.1"><span class="item-no">1.1</span>  License & copyright</a></span><br />
  <span class="toc-item"><a href="#s1.2"><span class="item-no">1.2</span>  Formatters</a></span><br />
<span class="toc-item"><a href="#s2"><span class="item-no">2</span>  Usage</a></span><br />
  <span class="toc-item"><a href="#s2.1"><span class="item-no">2.1</span>  Simple</a></span><br />
  <span class="toc-item"><a href="#s2.2"><span class="item-no">2.2</span>  Modifying layout and style</a></span><br />
  <span class="toc-item"><a href="#s2.3"><span class="item-no">2.3</span>  Modifying code logic</a></span><br />
  <span class="toc-item"><a href="#s2.4"><span class="item-no">2.4</span>  Usage with non-English text</a></span><br />
<span class="toc-item"><a href="#s3"><span class="item-no">3</span>  Other</a></span><br />
  <span class="toc-item"><a href="#s3.1"><span class="item-no">3.1</span>  Upgrade</a></span><br />
  <span class="toc-item"><a href="#s3.2"><span class="item-no">3.2</span>  Change-log</a></span><br />
  <span class="toc-item"><a href="#s3.3"><span class="item-no">3.3</span>  Support</a></span><br />
  <span class="toc-item"><a href="#s3.4"><span class="item-no">3.4</span>  Donate</a></span></div><!-- ended div toc -->
<div id="body">
<br />
<div class="comment">rTxt2htm_README.txt<br />
rTxt2htm 1.2.1, 22 January 2019<br />
Copyright Santosh Patnaik<br />
GPL 3 license<br />
A PHP Labware internal utility - <a href="http://www.bioinformatics.org/phplabware/internal_utilities/index.php">http://www.bioinformatics.org/phplabware/internal_utilities/index.php</a> </div>
<br />
<div class="section"><h2>
<a name="s1" id="s1"></a><span class="item-no">1</span>  About
</h2><span class="totop"><a href="#peak">(to top)</a></span><br style="clear: both;" />
<br />
rTxt2htm creates standalone, <span class="term">XHTML 1-Strict</span> HTML files from text files with special but simple and unobtrusive markup. It is intended for generating HTML versions of plain-text documentation (like <span class="term">readme</span> files that accompany software distributions; the <span class="term">r</span> in <span class="term">rTxt2htm</span> hints at <em>readme</em>). It can also be used to create simple web pages.<br />
<br />
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.<br />
<br />
rTxt2htm parses text files written in a specific format for title, URLs, sections, code fragments, styled text, tables of content, etc., creating the necessary HTML elements for presentation in the HTML output. The format rTxt2htm uses is somewhat like the reStructured text or <a href="http://docutils.sourceforge.net/rst.html">rst</a> format.<br />
<br />
A form interface is provided to upload the plain text files, or paste their content, and to set additional information for use in the generated HTML content.<br />
<div class="sub-section"><h3>
<a name="s1.1" id="s1.1"></a><span class="item-no">1.1</span>  License & copyright
</h3><span class="totop"><a href="#peak">(to top)</a></span><br style="clear: both;" />
<br />
rTxt2htm is free software licensed under GPL license version <a href="http://www.gnu.org/licenses/gpl-3.0.txt">3</a>, and copyrighted by Santosh Patnaik, MD, PhD.<br />
</div>
<div class="sub-section"><h3>
<a name="s1.2" id="s1.2"></a><span class="item-no">1.2</span>  Formatters
</h3><span class="totop"><a href="#peak">(to top)</a></span><br style="clear: both;" />
<br />
rTxt2htm looks for specific white-spacing, characters, etc. (<span class="term">formatters</span>) in the plain-text files for creating the necessary HTML elements.<br />
<br />
The formatters that rTxt2htm uses are simple and unobtrusive, and yet meaningful inside plain-text files. A comparison of the <a href="rTxt2htm_README.htm">HTML</a>, and the <a href="rTxt2htm_README.txt">plain-text</a> versions of this <span class="term">readme</span> documentation shows this clearly.<br />
<br />
Formatters (processing done in the shown order) are:<br />
<br />
*  A block of text with <span class="term">+-----(5 or more)+</span> at top and at bottom (leading or trailing spaces are okay) is rendered as plain, <strong>non-formatted</strong>, mono-spaced text for tables, ASCII diagrams, etc.; rest of formatters don't apply to its content. Like:<br />
<br />
<div class="monospace">     +~~~~ ~~~~+<br />
     | *hello* |<br />
     +~~~~ ~~~~+</div>
<br />
*  A block of text with <span class="term">== Content ==(any number of)</span> at top and atleast one empty line at bottom is considered a <strong>table of content</strong> (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 identifiers for the sections, etc.<br />
<br />
The <strong>section identifiers</strong>, that can have the period (<span class="term">.</span>) character, can be numeric (like <span class="term">1</span>, <span class="term">5.4.3</span> and <span class="term">2.2.</span>), or alphanumeric but inside round parentheses -- like, <span class="term">(A)</span>, <span class="term">(5i)</span> and <span class="term">(A.5i.1)</span>. The HTML <span class="term">ID</span> values generated by rTxt2htm for the identifiers asre the same as the identifiers but prefixed with an <span class="term">s</span> and with the brackets replaced with underscores (<span class="term">_</span>). E.g., <span class="term">s5.4.3</span> and <span class="term">s_A.5i.1_</span>.<br />
<br />
*  A block of text flanked with <span class="term">/*</span> style PHP comment markers will be shown in a <em>subtle</em> <span class="term">div</span> element. Like:<br />
<br />
<div class="comment">   Some subtle text<br />
   Like comments </div>
<br />
*  <strong>Title</strong>, <strong>keywords</strong>, <strong>description</strong>, <strong>encoding</strong> and <strong>language</strong> for use with the HTML version are gleaned from lines like this (the lines are not shown in the output):<br />
<br />
<code class="code">    @@title: rTxt2htm documentation</code>
<br />
<code class="code">    @@language: en</code>
<br />
<code class="code">    @@keywords: rTxt2htm, text to HTML, convert, conversion, PHP, Labware, readme</code>
<br />
<code class="code">    @@encoding: utf-8</code>
<br />
<code class="code">    @@description: rTxt2htm generates HTML versions of plain text files</code>
<br />
<br />
The <em>encoding</em> should be a value accepted by <a href="http://www.iana.org/assignments/character-sets">IANA</a>. The <em>language</em> should also be a value accepted by <a href="http://www.iana.org/assignments/language-subtag-registry">IANA</a>. When such lines are missing, the information provided in the form is used. One may also manually edit the generated HTML files to alter such information.<br />
<br />
*  Four or more spaces before a sentence lead to the sentence being shown as <strong>code</strong> (a tab is considered equal to 4 spaces). Like this:<br />
<br />
<code class="code">    <this is some 'code'></code>
<br />
<br />
*  Flanking a word or phrase with ' makes it rendered as a <strong>special</strong> <span class="term">span</span> element, <span class="term">like this</span> (URL and bold or italics formatters are not applied to it). Flanking a word or phrase with ` <em>italicizes it</em>. Flanking a word or phrase with * makes it <strong>appear bold</strong>.<br />
<br />
*  A word followed by <span class="term">:-</span>, a space, and then another word is rendered as the first word <strong>hyperlinked</strong> to the location pointed out by the second one.<br />
<br />
E.g.:<br />
<br />
   --  for rTxt2htm support, see <a href="#s3.2">section 3.2</a><br />
   --  rTxt2htm was created for documenting <a href="http://www.bioinformatics.org/phplabware">htmLawed</a><br />
<br />
*  Words with <span class="term">http:</span>, <span class="term">https:</span>, <span class="term">mailto:</span>, <span class="term">ftp:</span>, <span class="term">file:</span>, and <span class="term">sftp:</span> are rendered with appropriate <strong>hyperlinks</strong>. Like, <a href="http://www.bioinformatics.org/phplabware">http://www.bioinformatics.org/phplabware</a>.<br />
<br />
*  Two <span class="term">=</span> characters followed by optional spaces and then text followed by more <span class="term">=</span> characters on a new line that is preceded by an empty line indicate a <strong>section</strong> start. The text is shown as an <span class="term">h2</span> element. Any o's at the end are for <span class="term">div</span> closures. If the text has a leading number like <span class="term">1</span> and <span class="term">3.2.1</span>, the section gets an anchor named the same as the number but prefixed with <span class="term">s</span>, like <span class="term">s1</span> and <span class="term">s3.2.1</span>.<br />
<br />
*  For <strong>sub-sections</strong> (rendered with an <span class="term">h3</span> element) and <strong>sub-sub-sections</strong> (rendered with an <span class="term">h4</span> element), instead of the <span class="term">=</span> character, the characters <span class="term">-</span> and <span class="term">.</span> respectively are used.<br />
<br />
*  Five or more underscores on a line by themselves and preceded by an empty line are rendered as an <span class="term">hr</span> element (<strong>horizontal rule</strong>); any o's at the end are, like with the formatters for sections, etc., for <span class="term">div</span> closures.<br />
<br />
<strong>Note</strong>:<br />
<br />
Empty spaces are preserved, so any indentation is preserved. For bold, italicized or otherwise stylized text, the characters <span class="term">[</span> and <span class="term">(</span> if at the beginning, and characters <span class="term">?</span>, <span class="term">;</span>, <span class="term">!</span>, <span class="term">:</span>, <span class="term">,</span>, <span class="term">.</span>, <span class="term">)</span>, and <span class="term">]</span> if at the end of a word/phrase are not stylized. Same is true for hyperlinking.<br />
<br />
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.<br />
</div>
</div>
<div class="section"><h2>
<a name="s2" id="s2"></a><span class="item-no">2</span>  Usage
</h2><span class="totop"><a href="#peak">(to top)</a></span><br style="clear: both;" />
<br />
rTxt2htm should work with PHP 4.3 and higher.<br />
<div class="sub-section"><h3>
<a name="s2.1" id="s2.1"></a><span class="item-no">2.1</span>  Simple
</h3><span class="totop"><a href="#peak">(to top)</a></span><br style="clear: both;" />
<br />
Browse to <span class="term">rTxt2htm.php</span> on the server (e.g., <span class="term">http://domain.com/rTxt2htm.php</span>) using a web browser and use the provided form to upload the plain-text file, or paste its content, and to provide additional information. If you are satisfied with the output, save the web-page, appropriately renaming it. The HTML version can now be distributed to others.<br />
<br />
Some browsers do not save web-pages as originally authored. In such a case, you may want to <em>directly</em> save the output of rTxt2htm. If so, check the form option <span class="term">Direct download</span>. rTxt2htm should now prompt you to save the file as a download.<br />
</div>
<div class="sub-section"><h3>
<a name="s2.2" id="s2.2"></a><span class="item-no">2.2</span>  Modifying styles and layout
</h3><span class="totop"><a href="#peak">(to top)</a></span><br style="clear: both;" />
<br />
Simple editing of the <span class="term">CSS</span> value when submitting the form should generally be enough.<br />
</div>
<div class="sub-section"><h3>
<a name="s2.3" id="s2.3"></a><span class="item-no">2.3</span>  Modifying code logic
</h3><span class="totop"><a href="#peak">(to top)</a></span><br style="clear: both;" />
<br />
Code inside <span class="term">rTxt2htm.php</span> is reasonably documented with inline comments. One can edit regular expression patterns inside it, e.g., to implement customized formatters.<br />
</div>
<div class="sub-section"><h3>
<a name="s2.4" id="s2.4"></a><span class="item-no">2.4</span>  Usage with non-English text
</h3><span class="totop"><a href="#peak">(to top)</a></span><br style="clear: both;" />
<br />
rTxt2htm should work well with non-English text. Ensure you have the proper values set for <span class="term">character encoding</span> and <span class="term">language</span> when submitting the form.<br />
</div>
</div>
<div class="section"><h2>
<a name="s3" id="s3"></a><span class="item-no">3</span>  Other
</h2><span class="totop"><a href="#peak">(to top)</a></span><br style="clear: both;" />
<div class="sub-section"><h3>
<a name="s3.1" id="s3.1"></a><span class="item-no">3.1</span>  Upgrade
</h3><span class="totop"><a href="#peak">(to top)</a></span><br style="clear: both;" />
<br />
Simply replace the <span class="term">rTxt2htm.php</span> file.<br />
</div>
<div class="sub-section"><h3>
<a name="s3.2" id="s3.2"></a><span class="item-no">3.2</span>  Change-log
</h3><span class="totop"><a href="#peak">(to top)</a></span><br style="clear: both;" />
<br />
v1.2.1 - released Jan 22, 2019<br />
<br />
  *  bug-fix for parsing of single-quote formatters<br />
<br />
v1.2 - released Dec 15, 2017<br />
<br />
  *  rTxt2htm is now compatible with PHP 7<br />
<br />
v1.1.1 - released Mar 15, 2008<br />
<br />
  *  text content can be pasted/typed in the form<br />
<br />
v1.1 - released Sep 28, 2007<br />
<br />
  *  form interface<br />
  *  auto-identification of title, keywords, etc.<br />
  *  separate style for numbers of headings, support for non-numeric section identifiers, etc.<br />
<br />
v1.0.2 - released Sep 22, 2007<br />
<br />
  *  file: URL auto-linking, nesting for some formatters<br />
  *  minor bug-fixes<br />
<br />
v1.0.1 - released Sep 21, 2007<br />
<br />
  *  text-styling works for items in table of contents<br />
  *  new formatter for unformatted text for displaying tables, ASCII diagrams, etc.<br />
<br />
v1.0 - released Sep 13, 2007<br />
</div>
<div class="sub-section"><h3>
<a name="s3.3" id="s3.3"></a><span class="item-no">3.3</span>  Support
</h3><span class="totop"><a href="#peak">(to top)</a></span><br style="clear: both;" />
<br />
For possible updates, follow up at <a href="http://www.bioinformatics.org/phplabware/internal_utilities">http://www.bioinformatics.org/phplabware/internal_utilities</a> (which also has a forum). For general PHP issues (not rTxt2htm-specific), check on the internet and at <a href="http://php.net">http://php.net</a>.<br />
</div>
<div class="sub-section"><h3>
<a name="s3.4" id="s3.4"></a><span class="item-no">3.4</span>  Donate
</h3><span class="totop"><a href="#peak">(to top)</a></span><br style="clear: both;" />
<br />
A donation in any currency and amount to appreciate or support this software can be sent by <a href="http://paypal.com">PayPal</a> to this email address: drpatnaik at yahoo dot com.<br />
<br />
Thank you!
</div>
</div>
<br />
<hr /><br /><br /><span class="subtle"><small>HTM version of <em><a href="rTxt2htm_README.txt">rTxt2htm_README.txt</a></em> generated on 22 Jan, 2019 using <a href="http://www.bioinformatics.org/phplabware/internal_utilities">rTxt2htm</a> from PHP Labware</small></span>
</div><!-- ended div body -->
</div><!-- ended div top -->
</body>
</html>Presented with Sourceer