aboutsummaryrefslogtreecommitdiffstats
path: root/man
diff options
context:
space:
mode:
authorRafael G. Martins <rafael@rafaelmartins.eng.br>2017-11-18 20:57:50 +0100
committerRafael G. Martins <rafael@rafaelmartins.eng.br>2017-11-18 21:02:06 +0100
commita1a4dfa673b4d4e4316de76592d2b58fbddb0fca (patch)
tree75907d5199040c8c77f976d18f6abdcb7dd9c86a /man
parent99c3881dd078da45dc540ff271e73a9831d5d432 (diff)
downloadblogc-a1a4dfa673b4d4e4316de76592d2b58fbddb0fca.tar.gz
blogc-a1a4dfa673b4d4e4316de76592d2b58fbddb0fca.tar.bz2
blogc-a1a4dfa673b4d4e4316de76592d2b58fbddb0fca.zip
man: added blogcfile.5, updated some other pages
Diffstat (limited to 'man')
-rw-r--r--man/blogc-make.1.ronn12
-rw-r--r--man/blogc-source.7.ronn4
-rw-r--r--man/blogc-template.7.ronn4
-rw-r--r--man/blogc.1.ronn4
-rw-r--r--man/blogcfile.5.ronn183
-rw-r--r--man/index.txt3
6 files changed, 200 insertions, 10 deletions
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)