From 114b36f95116f62bfcf9d79e441ab81aed35454b Mon Sep 17 00:00:00 2001 From: "Rafael G. Martins" Date: Sat, 30 Apr 2016 02:41:00 +0200 Subject: man: added blogc-pagination(7) --- Makefile.am | 13 +++++ man/blogc-pagination.7.ronn | 122 ++++++++++++++++++++++++++++++++++++++++++++ man/blogc-source.7.ronn | 4 ++ man/blogc.1.ronn | 4 +- man/index.txt | 1 + 5 files changed, 142 insertions(+), 2 deletions(-) create mode 100644 man/blogc-pagination.7.ronn 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 %} + + {% 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: + +## AUTHOR + +Rafael G. Martins <> + +## 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` : 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`