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
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.2 Formatters
(to top)
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, and the
plain-text versions of this
readme documentation shows this clearly.
Formatters (processing done in the shown order) are:
* A block of text with
== Content ==(any number of) at top and two empty lines at bottom is considered a table of content (TOC); rest of formatters don't apply to its content.
* A block of text flanked with
/* style PHP comment markers will be shown in a
subtle div element. Like:
* 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 `
italicizes it. Flanking a word or phrase with * makes it
appear bold. Flanking a word or phrase with ' makes it rendered as a special
span element,
like this.
* 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
* Words with
http:,
https:,
mailto:,
ftp:, and
sftp: are rendered with appropriate hyperlinks. Like,
http://www.bioinformatics.org/phplabware.
* Two
= characters followed by a space and then text followed by more
= characters 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
. are respectively used.
* Five or more underscores on a line by themselves 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.
rTxt2htm 1.0 documentation, 13 September 2007
Copyright Santosh Patnaik
GPLv3 license
A PHP Labware internal utility - http://www.bioinformatics.org/phplabware