man: added blogc-pagination(7)

5 files changed, 142 insertions, 2 deletions

diff --git a/Makefile.am b/Makefile.am
index e18be01..d3ab12c 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -161,6 +161,7 @@ EXTRA_DIST += \
 	man/blogc-runserver.1.ronn \
 	man/blogc-source.7.ronn \
 	man/blogc-template.7.ronn \
+	man/blogc-pagination.7.ronn \
 	man/index.txt \
 	blogc-git-receiver.1 \
 	blogc-runserver.1 \
@@ -170,6 +171,7 @@ dist_man_MANS = \
 	blogc.1 \
 	blogc-source.7 \
 	blogc-template.7 \
+	blogc-pagination.7 \
 	$(NULL)
 
 if BUILD_GIT_RECEIVER
@@ -230,6 +232,14 @@ blogc-template.7: man/blogc-template.7.ronn
 		--manual "$(PACKAGE_NAME) Manual" \
 		$(top_srcdir)/man/blogc-template.7.ronn > blogc-template.7
 
+blogc-pagination.7: man/blogc-pagination.7.ronn
+	$(AM_V_GEN)$(RONN) \
+		--roff \
+		--pipe \
+		--organization "Rafael G. Martins" \
+		--manual "$(PACKAGE_NAME) Manual" \
+		$(top_srcdir)/man/blogc-pagination.7.ronn > blogc-pagination.7
+
 else
 
 blogc.1:
@@ -247,6 +257,9 @@ blogc-source.7:
 blogc-template.7:
 	$(AM_V_GEN)echo "error: ronn not found. failed to build man page: $@"; exit 1
 
+blogc-pagination.7:
+	$(AM_V_GEN)echo "error: ronn not found. failed to build man page: $@"; exit 1
+
 endif
 
 
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-source.7.ronn b/man/blogc-source.7.ronn
index c49f3ce..1a2cc76 100644
--- a/man/blogc-source.7.ronn
+++ b/man/blogc-source.7.ronn
@@ -45,6 +45,10 @@ 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.
+
 ## SOURCE CONTENT - BLOCK ELEMENTS
 
 ### Paragraphs
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 40a80d6..4ca6e67 100644
--- a/man/index.txt
+++ b/man/index.txt
@@ -4,6 +4,7 @@ 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)