From a1a4dfa673b4d4e4316de76592d2b58fbddb0fca Mon Sep 17 00:00:00 2001 From: "Rafael G. Martins" Date: Sat, 18 Nov 2017 20:57:50 +0100 Subject: man: added blogcfile.5, updated some other pages --- .gitignore | 2 +- Makefile.am | 10 +++ man/blogc-make.1.ronn | 12 ++- man/blogc-source.7.ronn | 4 +- man/blogc-template.7.ronn | 4 +- man/blogc.1.ronn | 4 +- man/blogcfile.5.ronn | 183 ++++++++++++++++++++++++++++++++++++++++++++++ man/index.txt | 3 +- 8 files changed, 211 insertions(+), 11 deletions(-) create mode 100644 man/blogcfile.5.ronn diff --git a/.gitignore b/.gitignore index 1a95a3f..4c0dd28 100644 --- a/.gitignore +++ b/.gitignore @@ -44,7 +44,7 @@ Makefile.in !/m4/pkg.m4 # man pages -/blogc*.[17] +/blogc*.[157] blogc*.html # binaries diff --git a/Makefile.am b/Makefile.am index 6117951..5f9d5af 100644 --- a/Makefile.am +++ b/Makefile.am @@ -293,6 +293,7 @@ EXTRA_DIST += \ man/blogc-git-receiver.1.ronn \ man/blogc-make.1.ronn \ man/blogc-runserver.1.ronn \ + man/blogcfile.5.ronn \ man/blogc-source.7.ronn \ man/blogc-template.7.ronn \ man/blogc-pagination.7.ronn \ @@ -318,6 +319,7 @@ endif if BUILD_MAKE_LIB dist_man_MANS += \ blogc-make.1 \ + blogcfile.5 $(NULL) endif @@ -363,6 +365,14 @@ blogc-runserver.1: man/blogc-runserver.1.ronn --manual "$(PACKAGE_NAME) Manual" \ $(top_srcdir)/man/blogc-runserver.1.ronn > blogc-runserver.1 +blogcfile.5: man/blogcfile.5.ronn + $(AM_V_GEN)$(RONN) \ + --roff \ + --pipe \ + --organization "Rafael G. Martins" \ + --manual "$(PACKAGE_NAME) Manual" \ + $(top_srcdir)/man/blogcfile.5.ronn > blogcfile.5 + blogc-source.7: man/blogc-source.7.ronn $(AM_V_GEN)$(RONN) \ --roff \ 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 <> ## 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 <> ## 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 <> ## 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 <> ## 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: + +## AUTHOR + +Rafael G. Martins <> + +## 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) -- cgit v1.2.3-18-g5258