Metadata-Version: 1.1
Name: weblog
Version: 1.1
Summary: Simple blog publisher. It reads structured text files and generates static HTML / 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: ISCL
Description: Weblog manual
        =============
        :Author: Henry Pr?cheur <henry@precheur.org>
        :Reviewers: Anis Kadri, Bastien Simondi, Eric Salama
        
        Abstract
        --------
        Simple blog publisher. It reads structured text files and generates static HTML
        / RSS files. Weblog aims to be simple and robust.
        
        In this 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.5+
        - Jinja version 1.1+ or Jinja 2.0+.
        
        Learn how to install Jinja at
        
        http://jinja.pocoo.org/2/documentation/intro#installation
        
        or
        
        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 using the helper script ``weblog_run.py``.
        
        Or install it using the supplied ``setup.py`` script. Run ``python setup.py
        --help`` to learn how to use it.
        
        Alternatively if easy_install is present, simply type::
        
        easy_install weblog
        
        It fetches the latest version of Weblog and installs it.
        
        Quick Start
        -----------
        
        In the following examples ``weblog/`` represents Weblog's installation
        directory.
        
        If you downloaded the source tarball without installing Weblog; Use the helper
        script ``weblog_run.py`` instead of the ``weblog`` command::
        
        $ python /path/to/weblog/weblog_run.py --help
        
        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 using the publish command::
        
        $ cd my_blog/
        $ weblog publish
        
        It should create a directory named ``output`` containing the generated files.
        Look at the results by opening the file ``output/index.html`` in your
        web-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`` is mandatory. ``date`` and ``author`` are optional. If you don't fill
        these fields, the author is the one specified in ``weblog.ini``, and the post's
        date is the post file's last modification date.
        
        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::
        
        $ weblog publish
        
        Reload the page in your browser. You should see a second post with some
        formating.
        
        The default post file encoding is ASCII. To use a different encoding 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 ...
        
        Specify the default encoding in ``weblog.ini``, to avoid setting the encoding
        field for every file.
        
        While writing your blog post, don't bother about the ``date`` field immediately.
        Weblog automatically sets the date to the filename's last modification time.
        
        A good practice though is to set the date when the post gets published. By doing
        so the date won't get changed if the file gets copied. To set the date of a
        post, use the command ``date``::
        
        $ date
        Mon Apr 14 00:10:44 PDT 2008
        
        $ cat my_blog_post.html
        title: My blog post
        
        This is a blog post without any date.
        
        $ weblog date my_blog_post.html
        Setting date to 2008-04-14 00:12:22 in file my_blog_post.html
        
        $ cat my_blog_post.html
        title: My blog post
        date: 2008-04-14 00:12:22
        
        This is a blog post without any date.
        
        $ weblog date my_blog_post 2008-5-15
        Setting date to 2008-05-15 in file my_blog_post.html
        
        $ cat my_blog_post.html
        title: My blog post
        date: 2008-05-15
        
        This is a blog post without any date.
        
        The ``date`` command accepts 3 formats as argument:
        
        - YEAR-MONTH-DAY (2008-01-31)
        - YEAR-MONTH-DAY HOUR:MINUTE (2008-01-31 16:45)
        - YEAR-MONTH-DAY HOUR:MINUTE:SECONDS (2008-01-31 16:45:14)
        
        For conciseness the ``date`` command uses aliases to specify commonly used date:
        
        - now
        - today (like now but only set the date, not the time)
        - tomorrow (now + 24 hours)
        - next_day (like tomorrow but only sets the date, not the time)
        
        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
        is *never* 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. The title ``Hello <em>World</em>`` is escaped. HTML tags appear, and no
        formating is applied to ``world``. The original text "Hello <em>World</em>"
        appears instead of "Hello *World*",
        
        It is possible to override this by specifying ``raw`` as the encoding. Using the
        ``raw`` encoding nothing is 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
        
        If the ``raw`` encoding is used, all the characters must be ASCII characters.
        Otherwise an error is reported.
        
        Attaching a file to a post
        --------------------------
        
        To attach files like images to a blog post, use the field ``files``::
        
        title: Attach a file
        files: picture.png directory/file
        
        <img src='picture.png' alt='a picture'>
        <a href='directory/file'>a file</a>
        
        It will copy ``picture.png`` and ``directory/file``. If ``directory`` does not exist,
        it will be created.
        
        How URI's are handled
        ---------------------
        
        Relative links (``<a href='test.html'>``) are rewritten in the RSS file and in
        some HTML files. In the RSS file ``base_url`` is prepended to the link to make
        sure it always points to the correct URI.
        
        Absolute links (``<a href='http://example.com'>``) are not rewritten. It should
        always point to the correct location regardless of the context.
        
        Note that Weblog considers ``/`` as the root directory. If ``base_url`` is
        ``http://example.com/``; ``test.html`` and ``/test.html`` are both rewritten to
        ``http://example.com/test.html``.
        
        Command line parameters
        -----------------------
        
        Usage: weblog [options]
        
        Options:
        -h, --help            show this help message and exit
        -s DIR, --source-dir=DIR
        The source directory where the blog posts and the file
        weblog.ini are located
        -o DIR, --output-dir=DIR
        The directory where all the generated files are
        written. If it does not exist it is created.
        -q, --quiet           Do not output anything except critical error messages
        
        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 sample configuration file::
        
        [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 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::
        
        description: My blog
        about
        configuration files.
        
        The description is merged to a single line; ``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 are 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.
        
        feed_limit
        The maximum number of post to be included in the Feed file. The most recent
        posts are the ones included. Default is 10.
        
        Note: rss_limit has been renamed to feed_limit.
        
        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. 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!
        
        extra_files
        Additional files to be copied. Typically used to copy CSS style sheets and/or
        pictures for the blog graphic design.
        Files are copied into `output_dir`. The path is not preserved: The file
        `style/weblog.css` gets copied into `output_dir/weblog.css` not into
        `output_dir/style/weblog.css`. This behavior is likely to change in the
        future.
        
        Tips on Uploading
        -----------------
        
        rsync_ is a useful tool to upload files generated by Weblog.
        
        To make sure rsync does not change the last modification time of the files that
        did not change, use the following::
        
        rsync --compress --checksum --recursive path/to/blog remote_host:public/dir/
        
        Accurate last modification time makes efficient caching possible.
        
        .. _rsync: http://samba.anu.edu.au/rsync/
        
        Need more help?
        ---------------
        
        Don't hesitate to ask questions about Weblog:
        
        http://groups.google.com/group/weblog-users
        
        or
        
        weblog-users@googlegroups.com
        
        .. vim:se tw=80 sw=2 ts=2 et encoding=utf-8:
Keywords: weblog blog journal diary atom
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content :: News/Diary
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python
Requires: Jinja2 (>=2.0)
