diff options
author | Rafael G. Martins <rafael@rafaelmartins.eng.br> | 2016-04-30 02:41:00 +0200 |
---|---|---|
committer | Rafael G. Martins <rafael@rafaelmartins.eng.br> | 2016-04-30 02:41:00 +0200 |
commit | 114b36f95116f62bfcf9d79e441ab81aed35454b (patch) | |
tree | e228416708183618d442b44d5d54cb036bebb0cd /man | |
parent | 82035fc222e8f7cb63c9573d5e9c7b5fea9d1943 (diff) | |
download | blogc-114b36f95116f62bfcf9d79e441ab81aed35454b.tar.gz blogc-114b36f95116f62bfcf9d79e441ab81aed35454b.tar.bz2 blogc-114b36f95116f62bfcf9d79e441ab81aed35454b.zip |
man: added blogc-pagination(7)
Diffstat (limited to 'man')
-rw-r--r-- | man/blogc-pagination.7.ronn | 122 | ||||
-rw-r--r-- | man/blogc-source.7.ronn | 4 | ||||
-rw-r--r-- | man/blogc.1.ronn | 4 | ||||
-rw-r--r-- | man/index.txt | 1 |
4 files changed, 129 insertions, 2 deletions
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 }}/">← Newer</a> + </li> + {% endif %} + {% ifdef NEXT_PAGE %} + <li class="next"> + <a href="/page/{{ NEXT_PAGE }}/">Older →</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 <<rafael@rafaelmartins.eng.br>> + +## 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 <<rafael@rafaelmartins.eng.br>> ## 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) |