Merge branch 'master' into feature/directives

6 files changed, 341 insertions, 8 deletions

diff --git a/man/blogc-git-receiver.1.ronn b/man/blogc-git-receiver.1.ronn
new file mode 100644
index 0000000..e26ed09
--- /dev/null
+++ b/man/blogc-git-receiver.1.ronn
@@ -0,0 +1,126 @@
+blogc-git-receiver(1) -- a simple login shell/git hook to deploy blogc websites
+===============================================================================
+
+## SYNOPSIS
+
+chsh -s $(command -v `blogc-git-receiver`) <user>
+
+## DESCRIPTION
+
+**blogc-git-receiver** provides a PaaS-like way to deploy blogc(1) websites.
+When used as a login shell, it will accept git payloads, creating bare repositories
+as needed, and installing a hook, that will take care of rebuilding the website each
+time someone push something to the `master` branch.
+
+The git repository must provide a `Makefile` (or a `GNUMakefile`), that should
+accept the `OUTPUT_DIR` variable, and install built files in the directory pointed
+by this variable.
+
+`blogc-git-receiver` is part of `blogc` project, but isn't tied to blogc(1). Any
+repository with `Makefile` that builds content and install it to `OUTPUT_DIR`
+should works with `blogc-git-receiver`.
+
+## SETUP
+
+After creating an user (`blogc` for the examples), change its shell to
+blogc-git-receiver(1):
+
+    # chsh -s $(command -v blogc-git-receiver) blogc
+
+Now add ssh keys to `/home/blogc/.ssh/authorized_keys`. Every key in
+`authorized_keys` will be allowed to push to the git repositories, and even
+create new ones.
+
+Also, make sure to install all the dependencies required by the websites,
+including a web server. `blogc-git-receiver` can't handle web server virtual hosts.
+
+To deploy a website (e.g. blogc example repository):
+
+    $ git clone https://github.com/blogc/blogc-example.git
+    $ cd blogc-example
+    $ git remote add blogc blogc@${SERVER_IP}:blogs/blogc-example.git
+    $ git push blogc master
+
+This will deploy the example to the server, creating a symlink to the built content
+in `/home/blogc/repos/blogs/blogc-example.git/htdocs`. This symlink should be used
+as the document root for the web server virtual host.
+
+### Setup with SELinux enabled (Fedora)
+
+Supposing the usage of nginx as webserver, running as the `nginx` user:
+
+    # dnf install -y nginx policycoreutils-python-utils
+    # useradd -m -s $(command -v blogc-git-receiver) blogc
+    # gpasswd -a nginx blogc
+    # chmod -R g+rx /home/blogc
+    # su -c "mkdir /home/blogc/{builds,repos}" -s /bin/sh blogc
+    # semanage fcontext -a -t httpd_sys_content_t "/home/blogc/(builds|repos)(/.*)?"
+    # restorecon -R -v /home/blogc
+    # systemctl restart nginx
+
+After running these commands, the machine is ready to be used.
+
+## REPOSITORY MIRRORING
+
+Users can rely on `blogc-git-receiver` to mirror repositories to a remote Git
+repository (e.g. a free Bitbucket private repository). This feature just requires
+adding a remote called `mirror` to the bare repository in the server. If such remote
+exists, `blogc-git-receiver` will `git push --mirror` to it.
+
+Please note that the `blogc` user must be able to push to the remote repository, and
+that any content manually pushed to the remote repository is overwritten by
+`blogc-git-receiver`.
+
+Some reasonable ways to allow the `blogc` user to push to the remote repository are:
+
+- Create a password-less SSH key. The key *must* be password-less, because the push
+  is automatic, and remote git hooks can't be interactive.
+- Create an oauth token in the hosting service (if it supports oauth authentication
+  in git, e.g. GitHub) and add it to the git URL.
+
+The mirroring feature wont't block a `git push`, it will just raise warnings. That
+means that if an error happens when mirroring the repository, the deploy will still
+succeed. Users should pay attention to the git hook logs, to avoid losing data
+due to repositories not being mirrored.
+
+To add the `mirror` remote:
+
+    # su -s /bin/bash - blogc
+    $ git remote add --mirror=push mirror $YOUR_GIT_MIRROR_URL
+
+### Caveats of repository mirroring with SSH
+
+The authentication must be done with a password-less SSH key created by the `blogc`
+user.
+
+As the `git push --mirror` call is automated, users must disable SSH strict host
+checking in SSH's `~/.ssh/config` file:
+
+    Host bitbucket.org
+        StrictHostKeyChecking no
+
+The example uses `bitbucket.org` as remote host, that should be changed if needed.
+
+To change this file, users must login with `/bin/bash` or any other "real" shell,
+as `root`:
+
+    # su -s /bin/bash - blogc
+
+## ENVIRONMENT VARIABLES
+
+`blogc-git-receiver` will export an environment variable called `BLOGC_GIT_RECEIVER`
+when calling `gmake` to build websites. This variable can be used to enable building
+of content that should only be built when running in production environment, for
+example.
+
+## 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), git(7), chsh(1), su(1), make(1)
diff --git a/man/blogc-pagination.7.ronn b/man/blogc-pagination.7.ronn
new file mode 100644
index 0000000..db40334
--- /dev/null
+++ b/man/blogc-pagination.7.ronn
@@ -0,0 +1,122 @@
+blogc-pagination(7) -- blogc's pagination support
+=================================================
+
+## DESCRIPTION
+
+blogc(1) supports some basic pagination and post filtering, when running on
+`listing` mode. Files are listed in the order that they are provided to
+blogc(1) in the command line, no sorting is done.
+
+## PAGINATION PARAMETERS
+
+blogc(1) accepts some variables as `-D` options, that are used to filter the
+files passed as arguments to it:
+
+  * `FILTER_PER_PAGE`:
+    Integer, limits the maximum number of files to be listed.
+
+  * `FILTER_PAGE`:
+    Integer, current page. If calling blogc(1) with 10 files,
+    `FILTER_PER_PAGE`=4 and `FILTER_PAGE`=3, it will return just the 2 last
+    files, skipping the first 2 pages with 4 files each one.
+
+  * `FILTER_TAG`:
+    String, if defined, blogc(1) will only list files that declare a `TAGS`
+    variable, as a space-separated list of tags (tags can't have spaces,
+    obviously). See blogc-source(7) for details about how to define source
+    variables. The pagination filters will only act on the files with the
+    provided tag, instead of filtering the whole file set.
+
+## TEMPLATE VARIABLES
+
+blogc(1) will export some global blogc-template(7) variables, that can be used
+to build links for next and previous page.
+
+  * `CURRENT_PAGE`:
+    Integer, usually the same value of `FILTER_PAGE` pagination paramenter, if
+    defined, or 1.
+
+  * `FIRST_PAGE`:
+    Integer, 1 if more than zero files were listed.
+
+  * `LAST_PAGE`:
+    Integer, last page available if more than zero files were listed.
+
+  * `PREVIOUS_PAGE`:
+    Integer, `CURRENT_PAGE` minus 1, if `CURRENT_PAGE` is bigger than 1.
+
+  * `NEXT_PAGE`:
+    Integer, `CURRENT_PAGE` plus 1, if `LAST_PAGE` is bigger than `CURRENT_PAGE`.
+
+blogc(1) can output the value of the variables after evaluation, instead of
+actually rendering the files, using the `-p` option. See blogc(1) for details.
+This is useful to know the last page that needs to be built, using `-p LAST_PAGE`,
+for example.
+
+### Date variables
+
+blogc(1) will also export some global blogc-template(7) variables related to
+the `DATE` variable, as specified in blogc-source(7).
+
+  * `DATE_FIRST`:
+    String, `DATE` variable from the first file in the listing.
+  * `DATE_LAST`:
+    String, `DATE` variable from the last file in the listing.
+
+These variables can be also formatted with `DATE_FORMAT` global blogc(1) parameter,
+if provided, using `DATE_FIRST_FORMATTED` and `DATE_LAST_FORMATTED` global
+template variables.
+
+### File name variables
+
+blogc(1) will also export some global blogc-template(7) variables related to
+the `FILENAME` variable, as automatically exported by the source file parser,
+see blogc-source(7) for details.
+
+  * `FILENAME_FIRST`:
+    String, `FILENAME` variable from the first file in the listing.
+  * `FILENAME_LAST`:
+    String, `FILENAME` variable from the last file in the listing.
+
+## EXAMPLES
+
+### Source file with tags
+
+    TITLE: My post
+    TAGS: foo bar baz
+    -----------------
+    Post content
+
+This source file defines 3 tags: `foo`, `bar` and `baz`.
+
+### Template with pagination
+
+    {% block listing_once %}
+    <ul class="pager">
+        {% ifdef PREVIOUS_PAGE %}
+        <li class="previous">
+            <a href="/page/{{ PREVIOUS_PAGE }}/">&larr; Newer</a>
+        </li>
+        {% endif %}
+        {% ifdef NEXT_PAGE %}
+        <li class="next">
+            <a href="/page/{{ NEXT_PAGE }}/">Older &rarr;</a>
+        </li>
+        {% endif %}
+    </ul>
+    {% endblock %}
+
+This example does not uses all the variables, but the concept is the same for
+all of them.
+
+## 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-source(7), blogc-template(7)
diff --git a/man/blogc-runserver.1.ronn b/man/blogc-runserver.1.ronn
new file mode 100644
index 0000000..a306fbe
--- /dev/null
+++ b/man/blogc-runserver.1.ronn
@@ -0,0 +1,48 @@
+blogc-runserver(1) -- a simple HTTP server to test blogc websites
+=================================================================
+
+## SYNOPSIS
+
+`blogc-runserver` [`-t` <HOST>] [`-p` <PORT>] <DOCROOT><br>
+`blogc-runserver` [`-h`|`-v`]
+
+## DESCRIPTION
+
+**blogc-runserver** is a simple HTTP server that makes it easy to test blogc websites.
+Users just need to point it to the directory where the target files where built. It
+comes with a few pre-defined rules, similar to production webservers, that allow users
+to quickly test their websites without configuring a webserver.
+
+`blogc-runserver` is part of `blogc` project, but isn't tied to blogc(1). It may be
+able to serve any website built by static site generators.
+
+## OPTIONS
+
+  * `-t` <HOST>:
+    HTTP server listen address, defaults to `127.0.0.1`.
+
+  * `-p` <PORT>:
+    HTTP server listen port, defaults to `8080`.
+
+  * `-v`:
+    Show program name, version and exit.
+
+  * `-h`:
+    Show help message and exit.
+
+## ARGUMENTS
+
+  * <DOCROOT>:
+    HTTP server document root.
+
+## 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)
diff --git a/man/blogc-source.7.ronn b/man/blogc-source.7.ronn
index 7fa0796..b583d6e 100644
--- a/man/blogc-source.7.ronn
+++ b/man/blogc-source.7.ronn
@@ -45,6 +45,15 @@ You can omit seconds, minutes and hours if you want, they will be filled with
 The ``DATE_FORMAT`` variable should be passed to blogc(1) as a global
 variable. Its value must be a valid strptime(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
+for building permalinks in templates. This variable can't be overriden by an
+explicit definition in source file.
+
+Another variable, `DESCRIPTION`, will be automatically created by the source
+parser. Its content is the first line of the first paragraph of the content.
+This variable can be overriden by an explicit definition in source file.
+
 ## SOURCE CONTENT - BLOCK ELEMENTS
 
 ### Paragraphs
@@ -203,18 +212,35 @@ Images are defined using the following syntax:
 
     This is an image: ![This is the image alt text](picture.jpg)
 
+Whitespace characters and new lines are allowed between alt text and image URL:
+
+    This is an image: ![This is the image alt text]
+    (picture.jpg)
+
 ### Links
 
 Links are defined using the following syntax:
 
     To learn more about blogc, [click here](https://blogc.rgm.io).
 
+Whitespace characters and new lines are allowed between link text and link URL:
+
+    To learn more about blogc, [click here]
+    (https://blogc.rgm.io).
+
 ### Image Links
 
 Links can be combined with images:
 
     [![This is the image alt text](picture.jpg)](https://blogc.rgm.io)
 
+Whitespace characters and new lines are allowed between link text and link URL,
+and between alt text and image URL:
+
+    [![This is the image alt text]
+    (picture.jpg)]
+    (https://blogc.rgm.io)
+
 ### Automatic Links
 
 Automatic link is defined with 2 '[' before and 2 ']' after the URL.
@@ -226,6 +252,11 @@ Automatic link is defined with 2 '[' before and 2 ']' after the URL.
 Line breaks can be added after a paragraph line adding 2 or more white spaces
 to the end of the line.
 
+### En dashes and Em dashes
+
+Sequences of 2 '-' characters are converted to an En dash HTML entity.
+Sequences of 3 '-' characters are converted to an Em dash HTML entity.
+
 
 ## BUGS
 
diff --git a/man/blogc.1.ronn b/man/blogc.1.ronn
index 7ee617f..baee026 100644
--- a/man/blogc.1.ronn
+++ b/man/blogc.1.ronn
@@ -44,7 +44,7 @@ designed to be used with make(1).
   * `-p` <KEY>:
     Show the value of a global configuration parameter right after the source
     parsing and exits. This is useful to get parameters for your `Makefile`,
-    like the last page when using pagination.
+    like the last page when using pagination, see blogc-pagination(7) for details.
 
   * `-t` <TEMPLATE>:
     Template file. It is a required option, if `blogc` needs to render something.
@@ -93,4 +93,4 @@ Rafael G. Martins &lt;<rafael@rafaelmartins.eng.br>&gt;
 
 ## SEE ALSO
 
-blogc-source(7), blogc-template(7), make(1), strptime(3)
+blogc-source(7), blogc-template(7), blogc-pagination(7) make(1), strptime(3)
diff --git a/man/index.txt b/man/index.txt
index a85e2a0..4ca6e67 100644
--- a/man/index.txt
+++ b/man/index.txt
@@ -1,9 +1,15 @@
 # manuals
-blogc(1)            blogc.1.ronn
-blogc-source(7)     blogc-source.7.ronn
-blogc-template(7)   blogc-template.7.ronn
+blogc(1)               blogc.1.ronn
+blogc-git-receiver(1)  blogc-git-receiver.1.ronn
+blogc-runserver(1)     blogc-runserver.1.ronn
+blogc-source(7)        blogc-source.7.ronn
+blogc-template(7)      blogc-template.7.ronn
+blogc-pagination(7)    blogc-pagination.7.ronn
 
 # external manuals
-make(1)             http://man.cx/make(1)
-strcmp(3)           http://man.cx/strcmp(3)
-strptime(3)         http://man.cx/strptime(3)
+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)
+git(7)                 http://man.cx/git(7)