README
author Mahlon E. Smith <mahlon@martini.nu>
Wed, 02 Dec 2009 17:07:11 -0800
changeset 5 75ab86f72a38
parent 3 1b5eb968d2c4
permissions -rw-r--r--
... aaaand, revert the header line to reflect real paths, instead of what is live on martini.nu.


                                                       WHAT IS THIS?
---------------------------------------------------------------------

Vimoutliner already comes with some otl to HTML converters that work
quite well.  I maintain a few different otl files, that are displayed
on a internal intranet - the step of converting to HTML on every little
change before upload was becoming mildly irritating, and countering my
near legendary laziness.

This mod_perl handler teaches apache how to pretty print otl natively.

Now, I can just edit the otl files directly - skip the conversion step
altogether, and let Apache make some delicious looking outlines.


                                                        INSTALLATION
---------------------------------------------------------------------

First of all, prerequisites!

    - apache2
    - mod_perl2
    - libapreq2 (Apache2::Request)

Add the following lines in your httpd.conf, or in a
separate otl.conf in the apache Includes directory:

    -------------------------
    PerlSwitches -I/path/to/perl/libraries
    PerlModule Apache::OTL

    <FilesMatch ".*\.otl">
        SetHandler perl-script
        PerlResponseHandler Apache::OTL
    </FilesMatch>
    -------------------------

Doublecheck that your apreq2 module is setup to load, as well.

That's it.  Apache will now pretty-print all your otl files.


                                                            SETTINGS
---------------------------------------------------------------------

Settings for the otl_handler are stored on the first line of the otl
files themselves, prefixed by the 'user no wrap' character, '<'. See
the sample.otl for an example settings line.  All settings are entirely
optional.

title
    Type: string
    Default: filename

    The title of the OTL.  Used as a header, and the html title.
    If this is not set, the html title is derived from the filename.


style
    Type: string
    Default: none

    A path to css style(s).
    Comma separated values load different files in order.
    Media type defaults to 'screen', if the css name contains the
    string 'print' anywhere, the media type is changed to print.

    :style=/css/otl_style.css,/css/print_style.css

js
    Type: string
    Default: none

    Use javascript?  If set, loads an external javascript library.
    Comma separated values load diff files in order.


last_mod
    Type: boolean
    Default: 0

    Show modification time of the otl file?

    
legend
    Type: boolean
    Default: 0

    Display small legend for todo and done items?


sort
    Type: boolean
    Default: 0

    Show sort links?


sorttype
    Type: string
    Default: none

    Default sorting method.  Valid values are
        percent
        alpha


sortrev
    Type: boolean
    Default: 0

    Should we default to reverse sorting?


counts
    Type: boolean
    Default: 0

    Count and display sub items?


timer
    Type: boolean
    Default: 0

    Display how long the parser took to generate the html?



                                                      INCLUDED FILES
---------------------------------------------------------------------

/Apache/OTL.pm
    The mod_perl content handler.

/javascript/*
    Example (but functional!) javascript.  Create line numbers,
    various eye candies, and clickable folds.

    This requires the 'jquery.js' library, also included.

/sample.otl
    An example vimoutliner file, with optional settings.

/styles/*
    "Theme" examples for customizing OTL display.


                                                    ACKNOWLEDGEMENTS
---------------------------------------------------------------------

Thanks to Nathan Dabney <nathan.dabney@gmail.com> and
Michael Granger <ged@faeriemud.org> for their help and advice!