Initial commit

1 files changed, 124 insertions, 0 deletions

diff --git a/blog.1 b/blog.1
new file mode 100644
index 0000000..03c8c3a
--- /dev/null
+++ b/blog.1
@@ -0,0 +1,124 @@
+.TH BLOG 1 blog\-1.0
+.SH NAME
+blog \- a small static blog generator
+
+.SH SYNOPSIS
+.B blog
+.RB [ init | build | deploy | clean ]
+
+.SH DESCRIPTION
+.B blog
+is a small static blog generator, using a markdown-like syntax and git capabilities.
+For example, first posted and last edited dates are extracted from git history.
+
+.SH GETTING STARTED
+Run "blog init" and follow the interactive configuration.
+This will create the basic structure and initialize a git repository.
+
+.SH STRUCTURE
+Articles are created in the
+.B articles
+directory, using a markdown-like syntax (see
+.BR SYNTAX ).
+HTML templates (configurable chunks of HTML code that will be used for static page generation) are stored in the
+.B templates
+directory, and can be edited (see
+.BR TEMPLATES ).
+Additional data can be stored in the
+.B data
+directory and will be copied at the root of the website.
+
+.SH WORKFLOW
+The articles, templates and data can be created and edited offline.
+To create a local version of the blog, run "blog build".
+It will be available in the
+.B blog
+directory, and the main page is index.html.
+Note that only articles known to git will be created (this is to prevent unfinished articles to be published).
+When its ready for publication, commit the changes to the git repository, and build the blog using "blog build".
+Then run "blog deploy" to publish the site with
+.BR rsync (1)
+to the remote configured at the beginning.
+
+.SH SYNTAX
+The first line of the article text file is its title.
+The next line can be blank, and will be skipped if that case.
+Then the remaining of the file is in a markdown format, with the following formatting options:
+.TP
+.B Sections
+Sections and subsections are defined by lines starting with one or several 
+.RB ' # ',
+each indicating a new section level.
+.TP
+.B Paragraphs
+Paragraphs are started with a blank line.
+.TP
+.B Bold, italics
+Chunks enclosed in stars
+.RB ' * '
+are formatted in bold.
+Chunks enclosed with two stars
+.RB ' ** '
+are formatted in bold.
+.TP
+.B Images
+Images are inserted using the following syntax: "![alternate text](url)".
+.TP
+.B Links
+Links are inserted using the following syntax: "[link text](url)".
+.TP
+.B Comments
+Lines starting with a semi-colon are comments and are ignored.
+It can be used to store metadata.
+In particular, comments beginning with "tags:" indicate tags and are available in the templates in the TAGS variable.
+
+.SH TEMPLATES
+Templates are small HTML code chunks that are used to build the blog pages.
+Any variable reference
+.RB ( $VARNAME )
+is replaced with the corresponding environment variable value.
+
+.SS Index page
+The index page is built using the following templates:
+
+- header.html;
+
+- index_header.html;
+
+- index_entry.html, for each article entry;
+
+- index_footer.html;
+
+- footer.html.
+
+The TITLE variable will contain "index".
+In index_entry, the following additional variables are available:
+
+- URL, containing the (relative) URL of the article;
+
+- DATE, the first publication date;
+
+- TITLE, the title of the article.
+
+.SS Article pages
+Article pages are built from the following templates:
+
+- header.html
+
+- index_header.html
+
+- (then the article file is formatted and inserted)
+
+- index_footer.html
+
+- footer.html
+
+At all stages, the following variables are defined:
+
+- TITLE, the title of the article;
+
+- DATE_POSTED, the first publication date;
+
+- DATE_EDITED, the last edit (commit) date;
+
+- TAGS, the tags parsed from "tags:" comments.