Program: pielrf

Author: EatingPie <eatingpie@gmail.com>

    Creates a Sony Reader/Librie lrf file from a text file.
    Includes easy table of contents, chapterization and curly quotes.

QUICKSTART

    pielrf -i infile.txt -o outfile.lrf -t "Book Title" -a "Author Name"

    This will generate a basic LRF file, with a single "Table of Contents"
    entry, flowed paragraphs, and curly-quotes.

INSTALLATION

    The pielrf executable requires three things. (This is the hardest
    part, so hang in there... the program itself is really easy to use.)

    (1) Python 2.5 on Mac OS X
        Python 2.5 is NOT installed by default but is available on
        the Tiger Installation Disk (for the Intel MacBook anyway).
        It should also be available on the Apple Developer Site.

    (2) pylrs-1.0.0 package from Falstaff

        <http://www.falstaffshouse.com>
        <http://www.mobileread.com/forums/showthread.php?t=9768>

    (3) pylrs itself requires ElementTree

        <http://effbot.org/zone/element-index.htm>

    Make sure you have Python 2.5.

    % python --version
    Python 2.5

    Installing the packages is pretty simple.  Just go to the
    package directory after download, and there should be
    a "setup.py" file in each.

    % python setup.py install

    Put the pielrf executable somewhere in your path, typically
    ~/bin, /usr/bin, or /usr/local/bin

    You're ready to go!

QUICKSTART II

    If you want a Table of Contents and Chapters, it takes just ONE WORD(!!)
    in your book's text file!

        <chapter>

    If your book is like this...

        Chapter One
            Some Text
            ...
        Chapter Two
            Some More Text

    Just do this...

        <chapter>Chapter One
            Some Text
            ...
        <chapter>Chapter Two
            Some More Text

    Both chapters are added to the Reader's Table of Contents, as well
    as a "Table of Contents" page.  "Chapter One" and "Chapter Two"
    are also made headers for their respective chapters.  Very nice!

HTML FOR TYPOGRAPHY

    You can control typography for such things as Bold and Italics by
    using standard HTML tags in your text.

    Recognized Tags

        <CENTER></CENTER>    - CENTERED TEXT
        <I></I>              - ITALICS
        <B></B>              - BOLD
        <SUB></SUB>          - SUBSCRIPT
        <SUP></SUP>          - SUPERSCRIPT
        <BR>                 - LINE BREAK (Vertical Whitespace)

    These are the only HTML tags recognized (beside <P></P> for
    paragraphs).

    * See BUGS section for caveats with tag usage.

    pielrf also supports 100% of the HTML Ampersand flags for special
    typographic symbols (the ISO Latin set).  A few examples (of
    the 200 or so!):

        &pound;        - The English Pound Symbol.
        &mdash;        - An Em-Dash.
        &iexcl;        - Inverted exclamation mark.
        &copy;         - the copyright symbol.
        etc.
        etc.
        etc.
        etc. (No, really, there's a lot of these things!)

FEATURES

    * Curly (typographic) quotes.
    * Double or triple dashes are converted to em-dashes
    * Paragraph auto-flow.
    * Table of Contents and Chapterization if you use the <chapter> tag.
    * Understands HTML tags <i></i>, <b></b> <center></center>,
      <sub></sub>, <sup></sup>, <p></p>.
    * Understands ALL HTML Ampersand tags - &amp;, &pound, &uumlat, etc.
    * Paragraphs can be delimited by tabs, spaces, vertical whitespace.
    * Font size / weight (bold) can be controlled from command line.
    * Heck, you can control ALL the options from the command line too!

OPTION OVERLOAD

    You can control just about every option regarding layout.  But don't
    get overwhelmed.  The defaults should work just fine.  All you need to
    provide are the input and output files, and a title and author.  To
    see the options just type:

        pielrf -h

BUGS

    (1) Indentation must be consistent.  If you paragarph-indent
        using a tab, all paragraphs must use a tab or they will
        be lumped together with the previous paragraph.

    (2) If you want to use <BR> and <CENTER>, it's far better to
        delimit paragraphs by the tab/multi-space indent method.
        Using vertical whitespace (carriage return) to delimit
        paragraphs increases the whitespace generated by the <BR>
        tag.

    (3) Vertical Whitespace REQUIRES a <BR> tag.  This isn't really a
        bug.

    (4) A <center> tag generates one Vertical Whitespace above.  This
        is because centering text requires a new paragraph.  The trick
        is to make the centered text part of the previous paragraph,
        so you only get one paragraph break instead of two.  See the
        "crazy-test.txt" example provided.

    (5) Paragraph splitting using HTML <P> has not been tested.
