man: added blogcfile.5, updated some other pages

8 files changed, 211 insertions, 11 deletions

diff --git a/.gitignore b/.gitignore
index 1a95a3f..4c0dd28 100644
--- a/.gitignore
+++ b/.gitignore
@@ -44,7 +44,7 @@ Makefile.in
 !/m4/pkg.m4
 
 # man pages
-/blogc*.[17]
+/blogc*.[157]
 blogc*.html
 
 # binaries
diff --git a/Makefile.am b/Makefile.am
index 6117951..5f9d5af 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -293,6 +293,7 @@ EXTRA_DIST += \
 	man/blogc-git-receiver.1.ronn \
 	man/blogc-make.1.ronn \
 	man/blogc-runserver.1.ronn \
+	man/blogcfile.5.ronn \
 	man/blogc-source.7.ronn \
 	man/blogc-template.7.ronn \
 	man/blogc-pagination.7.ronn \
@@ -318,6 +319,7 @@ endif
 if BUILD_MAKE_LIB
 dist_man_MANS += \
 	blogc-make.1 \
+	blogcfile.5
 	$(NULL)
 endif
 
@@ -363,6 +365,14 @@ blogc-runserver.1: man/blogc-runserver.1.ronn
 		--manual "$(PACKAGE_NAME) Manual" \
 		$(top_srcdir)/man/blogc-runserver.1.ronn > blogc-runserver.1
 
+blogcfile.5: man/blogcfile.5.ronn
+	$(AM_V_GEN)$(RONN) \
+		--roff \
+		--pipe \
+		--organization "Rafael G. Martins" \
+		--manual "$(PACKAGE_NAME) Manual" \
+		$(top_srcdir)/man/blogcfile.5.ronn > blogcfile.5
+
 blogc-source.7: man/blogc-source.7.ronn
 	$(AM_V_GEN)$(RONN) \
 		--roff \
diff --git a/man/blogc-make.1.ronn b/man/blogc-make.1.ronn
index 656d9d0..f60e630 100644
--- a/man/blogc-make.1.ronn
+++ b/man/blogc-make.1.ronn
@@ -8,9 +8,11 @@ blogc-make(1) -- a simple build tool for blogc
 
 ## DESCRIPTION
 
-**blogc-make** is a simple build tool for blogc websites.
+**blogc-make** is a simple build tool for blogc websites. It reads a blogcfile(5)
+and generates the output files using blogc(1) and some predefined rules, that are
+useful enough for most common use cases.
 
-EXPAND-ME!
+See blogcfile(5) for details on the file format.
 
 ## OPTIONS
 
@@ -97,6 +99,10 @@ when called by `blogc-make`.
 
 Build all files:
 
+    $ blogc-make
+
+or
+
     $ blogc-make all
 
 Clean built files:
@@ -113,4 +119,4 @@ Rafael G. Martins &lt;<rafael@rafaelmartins.eng.br>&gt;
 
 ## SEE ALSO
 
-blogc(1), blogc-runserver(1)
+blogc(1), blogc-runserver(1), blogcfile(5)
diff --git a/man/blogc-source.7.ronn b/man/blogc-source.7.ronn
index f369461..06f2f20 100644
--- a/man/blogc-source.7.ronn
+++ b/man/blogc-source.7.ronn
@@ -45,7 +45,7 @@ You can omit seconds, minutes and hours if you want, they will be filled with
 ``yyyy-mm-dd hh`` and ``yyyy-mm-dd``
 
 The ``DATE_FORMAT`` variable should be passed to blogc(1) as a global
-variable. Its value must be a valid strptime(3) format.
+variable. Its value must be a valid strftime(3) format.
 
 The source parser will also automatically generate a variable called `FILENAME`,
 that stores the name of the source file, without its extension. This is useful
@@ -283,4 +283,4 @@ Rafael G. Martins &lt;<rafael@rafaelmartins.eng.br>&gt;
 
 ## SEE ALSO
 
-blogc(1), blogc-template(7), strptime(3)
+blogc(1), blogc-template(7), strftime(3)
diff --git a/man/blogc-template.7.ronn b/man/blogc-template.7.ronn
index c6a3af1..1caa839 100644
--- a/man/blogc-template.7.ronn
+++ b/man/blogc-template.7.ronn
@@ -114,7 +114,7 @@ in the template. If user append `_FORMATTED` to the end of the variable name,
 a formatter will be applied, if available for the variable name:
 
 - Date formatter: if variable name starts with `DATE_`, it is formatted with
-  a strptime(3) format, provided by `DATE_FORMAT` variable. The `DATE_FORMATTED`
+  a strftime(3) format, provided by `DATE_FORMAT` variable. The `DATE_FORMATTED`
   "meta-variable" will return the formatted version of the `DATE` variable.
   If `DATE_FORMAT` is not provided, the original value will be returned.
 
@@ -270,4 +270,4 @@ Rafael G. Martins &lt;<rafael@rafaelmartins.eng.br>&gt;
 
 ## SEE ALSO
 
-blogc(1), blogc-source(7), strcmp(3)
+blogc(1), blogc-source(7), strcmp(3), strftime(3)
diff --git a/man/blogc.1.ronn b/man/blogc.1.ronn
index fc865b8..04d966e 100644
--- a/man/blogc.1.ronn
+++ b/man/blogc.1.ronn
@@ -86,7 +86,7 @@ files must have valid UTF-8 content.
 
 No environment variables are required by `blogc`, but global timezone will
 be used by locale-dependant datetime input field descriptors (like `%c`), and
-can be overridden using environment variables. See strptime(3).
+can be overridden using environment variables. See strftime(3).
 
 ## EXAMPLES
 
@@ -110,4 +110,4 @@ Rafael G. Martins &lt;<rafael@rafaelmartins.eng.br>&gt;
 
 ## SEE ALSO
 
-blogc-source(7), blogc-template(7), blogc-pagination(7) make(1), strptime(3)
+blogc-source(7), blogc-template(7), blogc-pagination(7) make(1), strftime(3)
diff --git a/man/blogcfile.5.ronn b/man/blogcfile.5.ronn
new file mode 100644
index 0000000..4fe3de8
--- /dev/null
+++ b/man/blogcfile.5.ronn
@@ -0,0 +1,183 @@
+blogcfile(5) -- blogc-make's configuration file
+===============================================
+
+## DESCRIPTION
+
+**blogcfile** is the configuration file for blogc-make(1), that is a simple
+build tool for blogc(1). It is an INI-style file, with some predefined
+sections, that will provide the data required by blogc-make(1) rules to
+build websites.
+
+**blogcfile** must be valid UTF-8.
+
+## OPTIONS
+
+### Global variables
+
+The `[global]` section contains all the blogc(1) variables that should be
+passed to all blogc(1) calls.
+
+The following variables are required and should be always provided:
+
+  * `AUTHOR_NAME`:
+    The name of the website main author.
+
+  * `AUTHOR_EMAIL`:
+    The email of the website main author.
+
+  * `BASE_DOMAIN`:
+    The base domain of the website.
+
+  * `SITE_TITLE`:
+    The website title.
+
+  * `SITE_TAGLINE`:
+    The website tagline.
+
+### Settings
+
+blogc-make(1) relies on a predefined set of rules to build the websites,
+however these rules can be customized with the following settings, from the
+`[settings]` section:
+
+  * `atom_ext` (default: `.xml`):
+    The extension of the generated Atom feeds.
+
+  * `atom_order` (default: `DESC`):
+    The ordering (`ASC` or `DESC`) of the Atom feeds. Please note that the files
+    are not sorted by date, they are sorted by their order in the `[posts]`
+    section.
+
+  * `atom_posts_per_page` (default: `10`):
+    Number of posts per page in the Atom feeds.
+
+  * `atom_prefix` (default: `atom`):
+    The prefix of the generated Atom feeds. It is relative to the output
+    directory. With the default values of the settings, the main Atom feed will
+    be `atom.xml`, the Atom feed for the `foo` tag will be `atom/foo.xml` and so
+    on.
+
+  * `content_dir` (default: `content`):
+    The directory that stores the source files. This directory is relative
+    to `blogcfile`.
+
+  * `date_format` (default: `%b %d, %Y, %I:%M %p GMT`):
+    The strftime(3) format that should be used when formating dates. Please note
+    that the times are always handled as UTC/GMT.
+
+  * `html_ext` (default: `/index.html`):
+    The extension of the generated HTML files. The default value will result on
+    friendly URL, by creating directories with `index.html` files inside, instead
+    of creating the HTML file directly. The `index` page is a special case:
+    instead of generating something like `/index/index.html`, it will generate
+    `/index.html`, because this is behavior that most users would expect.
+
+  * `html_order` (default: `DESC`):
+    The ordering (`ASC` or `DESC`) of the posts in the listing indexes.
+    Please note that the files are not sorted by date, they are sorted by
+    their order in the `[posts]` section.
+
+  * `index_prefix` (default: unset):
+    The prefix of the index HTML page, that is the listing of blog posts. This
+    option is useful if the user wants to host a page in the root of the website,
+    and move the posts listing index to a subdirectory.
+
+  * `locale` (default: unset):
+    The locale to be used when calling blogc(1). E.g. `en_US.UTF-8`.
+
+  * `main_template` (default: `main.tmpl`):
+    The template file that should be used when building HTML files. This file
+    is relative to `template_dir`.
+
+  * `pagination_prefix` (default: `page`):
+    The prefix of the generated pagination pages. It is relative to the
+    output directory.
+
+  * `post_prefix` (default: `post`):
+    The prefix of the posts file names. It is used for both content and output
+    directories, and is relative to `content_dir` and the output directory.
+
+  * `posts_per_page` (default: `10`):
+    Number of posts per page in the pagination pages.
+
+  * `source_ext` (default: `.txt`):
+    The extension of the source files.
+
+  * `tag_prefix` (default: `tag`):
+    The prefix of the generated tag listing index pages. It is relative to the
+    output directory.
+
+  * `template_dir` (default: `templates`):
+    The directory that stores the template files. This directory is relative
+    to `blogcfile`.
+
+### Posts listing
+
+The `[posts]` section is a listing of the posts that will be included in the
+website. They should be listed without the post prefix and without the extension,
+only the "slugs" should be used. For example, with default settings, if the source
+of the post is `content/post/foo.txt`, the line added to the `[posts]` section
+is `foo`.
+
+All the posts are relative to the `post_prefix` in the root of the website.
+
+### Pages listing
+
+The `[pages]` section is a listing of the pages that will be included in the
+website. They should be listed without the page prefix and without the extension,
+only the "slugs" should be used. For example, with default settings, if the source
+of the page is `content/foo.txt`, the line added to the `[pages]` section is `foo`.
+
+All the pages are relative to the root of the website.
+
+### Tags listing
+
+The `[tags]` section is a listing of the tags that should be listed in the
+website. blogc-make(1) will generate post listing indexes and Atom feeds for
+each tag listed in the section.
+
+### Copy listing
+
+The `[copy]` section is a listing of the files that should be copied to the
+output directory.
+
+All the files are relative to the `blogcfile`, and their directory structure
+will be built inside the output directory.
+
+## EXAMPLE
+
+    [global]
+    AUTHOR_NAME = Author
+    AUTHOR_EMAIL = author@example.org
+    SITE_TITLE = Site Title
+    SITE_TAGLINE = Site Tagline
+    BASE_DOMAIN = http://example.org
+
+    [settings]
+    locale = en_US.utf8
+
+    [posts]
+    post1
+    post2
+
+    [pages]
+    about
+
+    [tags]
+    tag1
+    tag2
+
+    [copy]
+    assets/custom.css
+
+## BUGS
+
+Please report any issues to: <https://github.com/blogc/blogc>
+
+## AUTHOR
+
+Rafael G. Martins &lt;<rafael@rafaelmartins.eng.br>&gt;
+
+## SEE ALSO
+
+blogc(1), blogc-make(1), strftime(3)
diff --git a/man/index.txt b/man/index.txt
index b588121..7491608 100644
--- a/man/index.txt
+++ b/man/index.txt
@@ -3,6 +3,7 @@ blogc(1)               blogc.1.ronn
 blogc-git-receiver(1)  blogc-git-receiver.1.ronn
 blogc-make(1)          blogc-make.1.ronn
 blogc-runserver(1)     blogc-runserver.1.ronn
+blogcfile(5)           blogcfile.5.ronn
 blogc-source(7)        blogc-source.7.ronn
 blogc-template(7)      blogc-template.7.ronn
 blogc-pagination(7)    blogc-pagination.7.ronn
@@ -12,5 +13,5 @@ make(1)                http://man.cx/make(1)
 chsh(1)                http://man.cx/chsh(1)
 su(1)                  http://man.cx/su(1)
 strcmp(3)              http://man.cx/strcmp(3)
-strptime(3)            http://man.cx/strptime(3)
+strftime(3)            http://man.cx/strftime(3)
 git(7)                 http://man.cx/git(7)