Metadata-Version: 1.1
Name: weblog
Version: 0.4
Summary: Weblog is a blog publisher. It takes structured text files as input and outputs static HTML and RSS files. Weblog aims to be simple and robust.
Home-page: http://henry.precheur.org/weblog/
Author: Henry Precheur
Author-email: henry@precheur.org
License: ISC
Description: Weblog manual
        =============
        :Author: Henry Precheur <henry@precheur.org>
        :Reviewers: Anis Kadri, Bastien Simondi, Eric Salama
        
        Abstract
        --------
        Weblog is a *web log* or *blog* publisher. It takes structured text files as
        input and outputs static HTML / RSS files. Weblog aims to be simple and robust.
        
        In the following document *Weblog* is the name of the software. The *web log*
        concept is referred as the more common term *blog*.
        
        According to Wikipedia_:
        
        A *blog* (a portmanteau of *web log*) is a website where entries are written in
        chronological order and commonly displayed in reverse chronological order.
        
        .. _Wikipedia: http://en.wikipedia.org/wiki/Blog
        
        Pre-requirements
        ~~~~~~~~~~~~~~~~
        
        - Python version 2.4+
        - Jinja version 1.1+.
        
        You can learn how to install Jinja at
        http://jinja.pocoo.org/documentation/installation.
        
        Installation
        ------------
        Download Weblog's latest version at http://henry.precheur.org/weblog/.
        
        Extract it::
        
        tar zxf weblog.tar.gz
        
        It can be used right away.
        
        You can also install it using the supplied ``setup.py`` script. Run ``python
        setup.py --help`` to learn how to use it.
        
        Quick Start
        -----------
        In the following examples ``weblog/`` represents Weblog's installation
        directory.
        
        Create a new directory named ``my_blog``. The $ sign represents the
        shell prompt, do not type it!::
        
        $ mkdir my_blog
        
        Copy from the Weblog installation directory the file ``weblog.ini`` into
        ``my_blog``::
        
        $ cp weblog/examples/weblog.ini my_blog
        
        ``weblog.ini`` is the configuration file of the blog. Check the configuration
        file section for more information. Do not worry about it now, no modification is
        required to get the following examples working.
        
        Create a file named ``first_post.html`` in the ``my_blog`` directory::
        
        title: First post
        author: Me
        date: 2007-08-25
        
        Hello world!
        
        Actually all the post filenames must end with ``.html``.
        
        Go in the ``my_blog`` directory and run the ``weblog_publish.py`` script::
        
        $ cd my_blog/
        $ python weblog/weblog_publish.py
        
        Or if ``weblog_publish.py`` is in your ``PATH``::
        
        $ weblog_publish.py
        
        It should create a directory named ``output`` which contains the generated
        files. You can look at the results by opening the file ``output/index.html`` in
        your browser.
        
        The first 3 lines of the file ``first_post.html`` define the post's parameters.
        These are standard :RFC:`2822` headers (the headers used in Emails). Only
        ``title`` and ``date`` are mandatory. ``author`` is optional. If you don't fill
        this field, the author will be the one specified in ``weblog.ini``.
        
        The line ``Hello world!`` is the actual content of the post. Note that a
        blank line is required between the headers and the content.
        
        The content is an HTML block. Use the HTML syntax to format your post content.
        For example create a second file named ``second_post.html``::
        
        title: Second post
        author: Me (again!)
        date: 2007-08-26
        
        <em>Second</em> <q>test</q> <strong>post</strong>!
        <p>
        &copy 2007 Me
        </p>
        
        Regenerate the blog files::
        
        $ python weblog/weblog_publish.py
        
        Or::
        
        $ weblog_publish.py
        
        Reload the page in your browser. You should see a second post with some
        formating.
        
        The default post file encoding is ASCII. If you want to use a different
        encoding you can specify it via the field ``encoding``::
        
        title: Encoding test
        date: 2007-11-5
        encoding: latin-1
        
        Here you can put some ISO-8856-1 text ...
        
        If you always use the same encoding. You can specify the default encoding in
        ``weblog.ini``.
        
        Encoding and escaping
        ---------------------
        
        Weblog tries to make sure its output is always *correct*. Non-ASCII characters, are
        converted to HTML entities so you don't have to worry about it. The output will
        *never* be encoded into ISO-8856-1, UTF-8 or another non-ASCII encoding.
        Encoding conversions are not so simple in practice. By doing only one conversion
        to the simplest encoding possible, a lot of problems are solved.
        
        The content of the post is not escaped. The title and the date of the post are
        escaped. A title like this: ``Hello <em>World</em>`` will be escaped. HTML tags
        will appear, and no formating will be applied to ``world``. The original text
        "Hello <em>World</em>" will appear instead of "Hello *World*",
        
        You can override this by specifying ``raw`` as the encoding. Using the ``raw``
        encoding nothing will be escaped or converted, but you must make sure all
        characters are ASCII characters::
        
        title: Non-escaped <em>title</em>
        author: <q>Me</q> &lt;me@my_weblog.org&gt;
        encoding: raw
        
        When the ``raw`` encoding is used. No checking is performed to make sure there
        are only ASCII characters in the text. This might change in the future.
        
        Command line parameters
        -----------------------
        
        Usage: weblog_publish.py [options]
        
        Options:
        -h, --help            show this help message and exit
        -s DIR, --source-dir=DIR
        The source directory where the blog posts and thefile
        weblog.ini are located
        -o DIR, --output-dir=DIR
        The directory where all the generated files willbe
        written. If it does not exist it will be created.
        
        Configuration file
        ------------------
        
        All configuration options are in the ``weblog`` section. Learn more about the
        format of the configuration file:
        http://docs.python.org/lib/module-ConfigParser.html.
        
        A configuration file looks like this::
        
        [weblog]
        title: Blog's title
        url: http://example.com/
        description: A sample blog.
        source_dir: path/to/my/posts
        output_dir: path/to/output/directory
        encoding: latin-1
        author: Me <me@example.com>
        
        Fields description
        ~~~~~~~~~~~~~~~~~~
        
        title
        The blog's title. It appears at the top of the blog's homepage and in the
        page's title
        
        This field is mandatory.
        
        url
        The base URL of your blog. For example ``http://my-host.com/my-weblog/``. It
        is used to generate the absolute URL's to your blog.
        
        This field is mandatory.
        
        description
        A short description of your blog. Like "My favorite books reviews", or "Dr.
        Spock, publications about electronics".
        Note that it is possible to use multiple lines like this::
        
        description: My blog
        about
        configuration files.
        
        the description will be merged to a single line like this ``My blog about
        configuration files.``.
        
        This field is mandatory.
        
        source_dir
        The directory containing the file ``weblog.ini``, the post files and possibly
        the ``templates`` directory. By default the current directory.
        
        output_dir
        The output directory. Generated files will be put there. By default
        ``output``.
        
        encoding
        The default post file encoding. Default ``ASCII``. It is overridden by the
        ``encoding`` field in the post file.
        
        author
        The default author. It is overridden by the ``author`` field in the post file.
        
        post_per_page
        The number of post displayed per listing page. Default is 10.
        
        rss_post_limit
        The maximum number of post to be included in the RSS file. The most recent
        posts are the ones included. Default is 10.
        
        html_head
        Additional information for the ``<head>`` section. Useful to add custom CSS
        style sheets. Can be a string or a filename. If a file with this name exists
        in the source directory then it is read. Else it is considered as a string.
        The result is processed using Jinja. You can use the variable ``top_dir`` to
        link to external files. It contains the path to the top directory of the
        blog.
        
        Examples::
        
        html_head=<style type='text/css'>body { font-family: sans-serif; }</style>
        
        html_head={{ top_dir }}my_stylesheet.css
        
        html_header
        Additional content located just before the blog content. Can be a string or a
        filename. (See html_head above)
        Useful to add a logo or a search box at the top.
        
        html_footer
        Additional content located just after the blog content. Can be a string or a
        filename. (See html_head above)
        Useful to add ... a footer!
        
        .. vim:se tw=80 sw=2 ts=2 et encoding=utf-8:
Keywords: weblog blog journal rss
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content :: News/Diary
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python
Requires: Jinja (>=1.1)
