diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/blogc-git-receiver.1.ronn | 112 | ||||
| -rw-r--r-- | man/blogc-make.1.ronn | 219 | ||||
| -rw-r--r-- | man/blogc-pagination.7.ronn | 22 | ||||
| -rw-r--r-- | man/blogc-runserver.1.ronn | 8 | ||||
| -rw-r--r-- | man/blogc-source.7.ronn | 13 | ||||
| -rw-r--r-- | man/blogc-template.7.ronn | 128 | ||||
| -rw-r--r-- | man/blogc-toctree.7.ronn | 87 | ||||
| -rw-r--r-- | man/blogc.1.ronn | 57 | ||||
| -rw-r--r-- | man/blogcfile.5.ronn | 207 | ||||
| -rw-r--r-- | man/index.txt | 16 |
10 files changed, 56 insertions, 813 deletions
diff --git a/man/blogc-git-receiver.1.ronn b/man/blogc-git-receiver.1.ronn index 3aac9f2..dc35621 100644 --- a/man/blogc-git-receiver.1.ronn +++ b/man/blogc-git-receiver.1.ronn @@ -12,13 +12,13 @@ When used as a login shell, it will accept git payloads, creating bare repositor 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 blogcfile(5) (if blogc-make(1) is installed), or -a `Makefile` (or a `GNUMakefile`) that should accept the `OUTPUT_DIR` variable, and -install built files into the directory pointed out by this variable. +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) or -blogc-make(1). Any repository with `Makefile` that builds content and install it to -`OUTPUT_DIR` should work with `blogc-git-receiver`. +`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 @@ -29,12 +29,7 @@ blogc-git-receiver(1): 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. It is also possible to add `blogc-git-receiver` as a command in -the `authorized_keys` file for each key, but this setup is slightly more tricky, -as you may leak shell access to an user by mystake, if you forget to add the command -to a key that should not have shell access. Only use this method if you don't have -another option (e.g. in shared hosting environments that only provide one shell -account), or if you know exactly what you are doing. +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. @@ -48,27 +43,7 @@ To deploy a website (e.g. blogc example repository): 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. If this symlink can't be -readed by your webserver for some reason, you can create it in some other directory -by adding the full symlink path to the ~/blogc-git-receiver.ini configuration file: - - $ $EDITOR ~/blogc-git-receiver.ini - [repo:blogs/blogc-example.git] - symlink=/path/to/my/symlink - -Do not duplicate the section if it already exists, just append the symlink path to -it. - -### Rebuild last successful build - -If for some reason you want to rebuild the last successful build of a given website, -you can run its `pre-receive` hook manually in the server: - - # su -s /bin/sh - blogc - $ cd ~/repos/blogs/blogc-example.git - $ ./hooks/pre-receive - -This should re-run the last build as if it was pushed to git. +as the document root for the web server virtual host. ### Setup with SELinux enabled (Fedora) @@ -88,7 +63,9 @@ 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). +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 @@ -106,29 +83,14 @@ means that if an error happens when mirroring the repository, the deploy will st succeed. Users should pay attention to the git hook logs, to avoid losing data due to repositories not being mirrored. -This feature just requires adding a remote called `mirror` to the bare repository -in the server, or creating a configuration file (~/blogc-git-receiver.ini), that is -a simple INI-style file where each repository is represented by a section and the -value of the `mirror` variable is the URL that should be used to push. - -Edit configuration file (recommended, do not duplicate the section if it already -exists, just append the mirror to it): - - # su -s /bin/sh - blogc - $ $EDITOR ~/blogc-git-receiver.ini - [repo:myblog.git] - mirror=$YOUR_GIT_MIRROR_URL - -Or to add the `mirror` remote: +To add the `mirror` remote: - # su -s /bin/sh - blogc + # su -s /bin/bash - blogc $ cd repos $ git init --bare myblog.git # if not created yet $ cd myblog.git $ git remote add --mirror=push mirror $YOUR_GIT_MIRROR_URL -Both examples assume that your repository is named `myblog.git`. - ### Caveats of repository mirroring with SSH The authentication must be done with a password-less SSH key created by the `blogc` @@ -142,49 +104,17 @@ checking in SSH's `~/.ssh/config` file: The example uses `bitbucket.org` as remote host, that should be changed if needed. -To change this file, users must login with `/bin/sh` or any other "real" shell, +To change this file, users must login with `/bin/bash` or any other "real" shell, as `root`: - # su -s /bin/sh - blogc - -### Push to mirror manually - -If for some reason you want to push the repository of a given website to remote -mirror, you can run its `post-receive` hook manually in the server: - - # su -s /bin/sh - blogc - $ cd ~/repos/blogs/blogc-example.git - $ ./hooks/post-receive - -WARNING: If you push manually and your server's repository is empty, you'll clean -your mirror repository. - -## ENVIRONMENT - -The following variables can be set in the SSH Server (usually in `~/.ssh/environment`) -to change `blogc-git-receiver` behaviour: - - * `BLOGC_GIT_RECEIVER_BASE_DIR`: - Path to the base directory that should be used by `blogc-git-receiver`. Defaults - to user's home directory. Useful for shared hosting environments that only provide - one shell user. - * `BLOGC_GIT_RECEIVER_BUILDS_DIR`: - Path to the directory that should be used to store the blogc builds. Defaults - to `$BLOGC_GIT_RECEIVER_BASE_DIR/builds`. This directory must be readable by - your webserver. This variable is useful to keep your git repositories unreadable, - while letting your webserver access the built files. In this case, users need to - also define custom symlinks for every repository in - `$BLOGC_GIT_RECEIVER_BASE_DIR/blogc-git-receiver.ini`, because the default - `htdocs` symlink inside the git repositories won't be acessible by the webserver. + # su -s /bin/bash - blogc -The following variable is exported by `blogc-git-receiver` when building websites -with make(1): +## ENVIRONMENT VARIABLES - * `BLOGC_GIT_RECEIVER=1`: - This variable can be used to enable building of content that should only be - built when running in production environment, for example. This variable will - not be exported when using blogc-make(1), whose builds are always considered to - be "production" (blogc-make(1) is never called with `-D`). +`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 @@ -196,4 +126,4 @@ Rafael G. Martins <<rafael@rafaelmartins.eng.br>> ## SEE ALSO -blogc(1), git(1), git-shell(1), chsh(1), su(1), make(1) +blogc(1), git(7), chsh(1), su(1), make(1) diff --git a/man/blogc-make.1.ronn b/man/blogc-make.1.ronn deleted file mode 100644 index d44b685..0000000 --- a/man/blogc-make.1.ronn +++ /dev/null @@ -1,219 +0,0 @@ -blogc-make(1) -- a simple build tool for blogc -============================================== - -## SYNOPSIS - -`blogc-make` [`-V`] [`-f` <FILE>] [<RULE> ...]<br> -`blogc-make` [`-h`|`-v`] - -## DESCRIPTION - -**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. - -See blogcfile(5) for details on the file format. - -## OPTIONS - - * `-D`: - Builds for development environment. This option is useful to load local, - non-optimized assets for development purposes. It adds two global - variables to all blogc(1) calls: `MAKE_ENV_DEV=1` and `MAKE_ENV=dev`. - - * `-V`: - Activates verbose mode, that will give more details of commands runs. - - * `-f` <FILE>: - Reads <FILE> as `blogcfile`. - - * `-v`: - Show program name, version and exit. - - * `-h`: - Show help message and exit. - -## HELPER RULES - -### all - -Run all build rules. This is the default rule. - -### clean - -Clean built files and empty directories in output directory. - -### runserver - -Run `blogc-runserver(1)` (if available) pointing to output directory, watching -for changes in the source files and rebuilding as needed. This rule accepts -some arguments, in the following format: - - runserver:host=127.0.0.1,port=8080,threads=20 - -The values in the example are the default values. Rebuilds are done by running -`blogc-make all` internally. - -### watch - -Watch for changes in the source files, rebuilding as needed. - -Rebuilds are done by running `blogc-make all` internally. - -### atom_dump - -Dump default Atom feed template based on current blogcfile(5) settings. - -The template is dumped to the standard output, and can be used as base -for customized Atom feed templates. - -## BUILD RULES - -### index - -Build website index from posts. - -The rule passes the following helper variables to blogc(1): - - * `MAKE_RULE`: - `index` - * `MAKE_TYPE`: - `post` - -### atom - -Build main atom feed from posts. - -The rule passes the following helper variables to blogc(1): - - * `MAKE_RULE`: - `atom` - * `MAKE_TYPE`: - `atom` - -### atom_tags - -Build atom feeds for each tag from posts. - -The rule passes the following helper variables to blogc(1): - - * `MAKE_RULE`: - `atom_tags` - * `MAKE_TYPE`: - `atom` - -### pagination - -Build pagination pages from posts. This rule is disabled if `posts_per_page` -value in blogcfile(5) is negative or `0`. - -The rule passes the following helper variables to blogc(1): - - * `MAKE_RULE`: - `pagination` - * `MAKE_TYPE`: - `post` - -### pagination_tags - -Build pagination pages for each tag from posts. This rule is disabled if -`posts_per_page` value in blogcfile(5) is negative or `0`. - -The rule passes the following helper variables to blogc(1): - - * `MAKE_RULE`: - `pagination_tags` - * `MAKE_TYPE`: - `post` - -### posts - -Build individual pages for each post. - -The rule passes the following helper variables to blogc(1): - - * `MAKE_RULE`: - `posts` - * `MAKE_TYPE`: - `post` - * `MAKE_SLUG`: - The slug of the post being built, as provided in blogcfile - -### tags - -Build post listings for each tag from posts. - -The rule passes the following helper variables to blogc(1): - - * `MAKE_RULE`: - `tags` - * `MAKE_TYPE`: - `post` - -### pages - -Build individual pages for each page. - -The rule passes the following helper variables to blogc(1): - - * `MAKE_RULE`: - `pages` - * `MAKE_TYPE`: - `page` - * `MAKE_SLUG`: - The slug of the page being built, as provided in blogcfile - -### copy - -Copy static files from source directory to output directory. - -## FILES - -The `blogc-make` command expects a settings file, called `blogcfile` by default, -or any other file passed to `-f` option. `blogcfile` must have valid UTF-8 content. - -The `blogc-make` command will read any files listed on `blogcfile`, and may write -files to the configured output directory. - -## ENVIRONMENT - - * `BLOGC`: - Path to `blogc(1)` binary. If not provided, the `blogc` binary in `$PATH` will - be used. - - * `BLOGC_RUNSERVER`: - Path to `blogc-runserver(1)` binary. If not provided, the `blogc-runserver` - binary in `$PATH` will be used, if available. - - * `OUTPUT_DIR`: - Path to the directory where `blogc-make` should write (or instruct blogc(1) to - write) output files. - -Any other environment variables are inherited by blogc(1) and blogc-runserver(1), -when called by `blogc-make`. - -## EXAMPLES - -Build all files: - - $ blogc-make - -or - - $ blogc-make all - -Clean built files: - - $ blogc-make clean - -## BUGS - -Please report any issues to: <https://github.com/blogc/blogc> - -## AUTHOR - -Rafael G. Martins <<rafael@rafaelmartins.eng.br>> - -## SEE ALSO - -blogc(1), blogc-runserver(1), blogcfile(5) diff --git a/man/blogc-pagination.7.ronn b/man/blogc-pagination.7.ronn index ceb41d6..db40334 100644 --- a/man/blogc-pagination.7.ronn +++ b/man/blogc-pagination.7.ronn @@ -12,16 +12,14 @@ blogc(1) in the command line, no sorting is done. 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 + `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_PER_PAGE`: - Integer, limits the maximum number of files to be listed. If negative or - `0`, no posts are included. Have no effect if `FILTER_PAGE` is not - defined. - * `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, @@ -29,18 +27,6 @@ files passed as arguments to it: variables. The pagination filters will only act on the files with the provided tag, instead of filtering the whole file set. - * `FILTER_REVERSE`: - Boolean (1/y/yes/true/on), if set, blogc(1) will list files in reverse order. - This filter is combined with `FILTER_SORT`, and all the other filters will - get the files already in the reverse order. - - * `FILTER_SORT`: - Boolean (1/y/yes/true/on), if set, blogc(1) will sort files using the `DATE` - variable provided in the files, instead of respecting the order of the - source files provided to blogc(1). The files are sorted in descending order - and combined with `FILTER_REVERSE`, that will result in the files sorted in - ascending order. All the other filters will get the files already sorted. - ## TEMPLATE VARIABLES blogc(1) will export some global blogc-template(7) variables, that can be used diff --git a/man/blogc-runserver.1.ronn b/man/blogc-runserver.1.ronn index a8534f8..a306fbe 100644 --- a/man/blogc-runserver.1.ronn +++ b/man/blogc-runserver.1.ronn @@ -35,14 +35,6 @@ able to serve any website built by static site generators. * <DOCROOT>: HTTP server document root. -## ENVIRONMENT - - * `BLOGC_RUNSERVER_DEFAULT_HOST`: - Changes the default HTTP server listen address, if defined. - - * `BLOGC_RUNSERVER_DEFAULT_PORT`: - Changes the default HTTP server listen port, if defined. - ## BUGS Please report any issues to: <https://github.com/blogc/blogc> diff --git a/man/blogc-source.7.ronn b/man/blogc-source.7.ronn index 56fa552..0273194 100644 --- a/man/blogc-source.7.ronn +++ b/man/blogc-source.7.ronn @@ -45,19 +45,13 @@ 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 strftime(3) format. +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. -The variable `FIRST_HEADER` is created by the source parser by default, -containing the unparsed value of the first header found in the source file. -The content is not parsed but HTML entities are encoded. Headers inside -blockquotes are ignored. This variable can be overriden by an explicit -definition in source file, that must have the HTML entities escaped manually. - Another variable, `DESCRIPTION`, will be automatically created by the source parser. It contains the unparsed content of the first paragraph found in the source file. The content is not parsed but HTML entities are encoded. Paragraphs @@ -219,9 +213,6 @@ Code is defined with 1 or 2 '`' before and after the text. This is inline code: `code` This is inline code: ``code`` -The later form is particularly useful when a '`' is part of the code, because -escaping delimiters with '\' is not possible. - ### Images Images are defined using the following syntax: @@ -286,4 +277,4 @@ Rafael G. Martins <<rafael@rafaelmartins.eng.br>> ## SEE ALSO -blogc(1), blogc-template(7), strftime(3) +blogc(1), blogc-template(7), strptime(3) diff --git a/man/blogc-template.7.ronn b/man/blogc-template.7.ronn index 1530fb3..d010a1c 100644 --- a/man/blogc-template.7.ronn +++ b/man/blogc-template.7.ronn @@ -22,8 +22,7 @@ matches the requirements of the given block. Blocks can be defined more than once, but can't be nested. -The available blocks are: `entry`, `listing`, `listing_empty`, `listing_entry` -and `listing_once`. +The available blocks are: `entry`, `listing` and `listing_once`. ### entry block @@ -57,42 +56,6 @@ This is how a `listing` block is defined: will be included once for each entry. {% endblock %} -### listing_empty block - -This block is similar to the `listing` block, but its content is included -only when there are no entries to be listed, either because no source files -were provided or because there are no entries remaining after filtering (see -blogc-pagination(7)). - -This is how a `listing_empty` block is defined: - - {% block listing_empty %} - No entries available. - {% endblock %} - -### listing_entry block - -This block is identical to the `entry` block, but its content is included in -the output file only when blogc(1) is called with `-l` and `-e` <SOURCE> -options. The variables available in the block are provided by the source -file provided using `-e` <SOURCE> option. - -This is how a `listing_entry` block is defined: - - {% block listing_entry %} - This content will only be included when rendering a listing, but with - content provided by a single entry. - {% endblock %} - -When multiple `listing_entry` blocks are defined, blogc(1) should be called -with multiple `-e` <SOURCE> options. If a `listing_entry` block does not have -a corresponding `-e` <SOURCE> option, or if its value is an empty string, -the content of the `listing_entry` block is not included. - -`listing_entry` blocks inside iterator are evaluated as multiple blocks and -also require multiple `-e` <SOURCE> options. blogc(1) won't use the same -source for every iteration. - ### listing_once block The content of a `listing_once` block is included in the output file when @@ -111,8 +74,8 @@ This is how a `listing_once` block is defined: will be included only once. {% endblock %} -This is a 'real world' usage example of a `listing_once` block, supposing -that the `TITLE` variable is defined: +This is a 'real life' usage example of a `listing_once` block, supposing +that each source file defines a `TITLE` variable: {% block listing_once %} <ul> @@ -151,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 strftime(3) format, provided by `DATE_FORMAT` variable. The `DATE_FORMATTED` + a strptime(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. @@ -174,53 +137,6 @@ An existing variable is not overrided by the truncate syntax. That means that if `FOO_5` variable exists, it won't be handled as a truncate "meta-variable", and `FOO_5` variable value will be returned normally. -## PREDEFINED TEMPLATE VARIABLES - -blogc(1) provides some template variables, that can be used to display some build -metadata in your website. - -If some of the variables are not available in the system running the build, they -won't be defined. It is recommended to rely on template conditionals, mainly -`ifdef` and `ifndef` when using these variables. - -### Static variables - -These variables are always available, and are set during the blogc(1) binary -compilation. - - * `BLOGC_VERSION`: - The version of blogc(1) used to build. e.g.: `blogc 0.14.1`. - -### Resource usage variables - -It is not possible to measure the resource usage of blogc(1) until the end of -the execution, because the rendering of these variables itself is using resources, -and the evaluation of the used resources was already done. To get better values, -it is recommended to use these variables only in the website footer. - - * `BLOGC_RUSAGE_CPU_TIME`: - The CPU time used to build, up to the point where this variable was used for - the first time in the template (value is cached). e.g.: `12.345ms`. - - * `BLOGC_RUSAGE_MEMORY`: - The memory used to build, up to the point where this variable was used for the - first time in the template (value is cached). e.g.: `1.234MB`. - -### System information variables - - * `BLOGC_SYSINFO_HOSTNAME`: - The hostname of the machine where the build happened (short hostname only, not - FQDN). - - * `BLOGC_SYSINFO_USERNAME`: - The username of the user that executed the build. - - * `BLOGC_SYSINFO_DATETIME`: - The GMT datetime of the build. e.g. `2019-02-10 22:00:00`. - - * `BLOGC_SYSINFO_INSIDE_DOCKER`: - If built inside a docker container, this variable will be defined, with value `1`. - ## TEMPLATE CONDITIONALS Template conditionals are used to include content to the output, or not, @@ -317,40 +233,16 @@ This is how a `foreach` iterator is defined in a template: {% endforeach %} Where `TAGS` is the variable with space-separated list of items, and `FOREACH_ITEM` -is the variable defined by blogc(1), that will store the item for a given iteration. +is the variable defined by blogc(1), that will store the item value for a given +iteration. If the value of the `TAGS` variable is "item1 item2 item3", this template is -rendered 3 times, one for each item. - -It is possible to map the items to arbitrary strings by defining other variables -following a predefined for naming schema, like: - - TAGS__ITEM1 - -Where `TAGS` is the variable defined in the foreach iterator, and `ITEM1` is the -current iteration item (the value of `FOREACH_ITEM` for the current iteration, -converted to upper case and with special characters converted to `_`). - -This is how a `foreach` iterator using arbitrary string mapping is defined in a template: - - {% foreach TAGS %} - <a href="/tag/{{ FOREACH_ITEM }}/">{{ FOREACH_VALUE }}</a> - {% endforeach %} - -`FOREACH_VALUE` is the variable defined by blogc(1), that will store the arbitrary string -mapped to current iteration item. This variable can be checked using `ifdef` conditionals -(and similar) as usual: - - {% foreach TAGS %} - {% ifdef FOREACH_VALUE %} - <a href="/tag/{{ FOREACH_ITEM }}/">{{ FOREACH_VALUE }}</a> - {% endif %} - {% endforeach %} +rendered 3 times, one for each item value. -The `FOREACH_ITEM` and `FOREACH_VALUE` variables can be truncated, like: +The `FOREACH_ITEM` variable can be truncated, like: {% foreach TAGS %} - <a href="/tag/{{ FOREACH_ITEM_5 }}/">{{ FOREACH_VALUE_5 }}</a> + <a href="/tag/{{ FOREACH_ITEM }}/">{{ FOREACH_ITEM_5 }}</a> {% endforeach %} ## WHITESPACE CONTROL @@ -378,4 +270,4 @@ Rafael G. Martins <<rafael@rafaelmartins.eng.br>> ## SEE ALSO -blogc(1), blogc-source(7), strcmp(3), strftime(3) +blogc(1), blogc-source(7), strcmp(3) diff --git a/man/blogc-toctree.7.ronn b/man/blogc-toctree.7.ronn deleted file mode 100644 index 720a4ee..0000000 --- a/man/blogc-toctree.7.ronn +++ /dev/null @@ -1,87 +0,0 @@ -blogc-toctree(7) -- blogc's "table of contents" tree support -============================================================ - -## DESCRIPTION - -blogc(1) generates a "table of contents" tree for every source file, out of -its content headers, that is available for usage as a `{{ TOCTREE }}` -template variable. The tree is composed by lists of links for the headers, -and is usually placed right before the content, as an index. - -## USAGE - -For a source file with the following content: - - TITLE: Some Title - ----------------- - # Header 1 - - Some content. - - ## Header 2 - - More content. - - ### Header 3 - - Content. - -A template block with the following content: - - {% block entry %} - {{ TOCTREE }} - {% endblock %} - -Would generate output similar to this: - - <ul> - <li><a href="#header-1">Header 1</a></li> - <ul> - <li><a href="#header-2">Header 2</a></li> - <ul> - <li><a href="#header-3">Header 3</a></li> - </ul> - </ul> - </ul> - -The depth of the tree can be controlled using the `TOCTREE_MAXDEPTH` variable, -that may be defined globally (see blogc(1)) or for each source file (see -blogc-source(7)). Setting this variable to `0` disables the generator. -Setting this variable to a positive number will limit the number of tree -levels to such value. The default value is `-1`, which means no maximum depth. - -Please note that the depth is evaluated from the lower header level available -in the content. This means that if a source file only have level 2 and level 3 -headers, and `TOCTREE_MAXDEPTH=1`, only headers with level 2 are included in the -"table of contents" tree. - -For a source file with the following content: - - TITLE: Some Title - TOCTREE_MAXDEPTH: 1 - ----------------- - ## Header 2 - - Some content - - ### Header 3 - - More content - -With the same template presented before, would generate output similar to this: - - <ul> - <li><a href="#header-2">Header 2</a></li> - </ul> - -## 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.1.ronn b/man/blogc.1.ronn index 11f7808..a97122b 100644 --- a/man/blogc.1.ronn +++ b/man/blogc.1.ronn @@ -3,21 +3,14 @@ blogc(1) -- a blog compiler ## SYNOPSIS -`blogc` [`-d`] [`-D` <KEY>=<VALUE> ...] `-t` <TEMPLATE> [`-o` <OUTPUT>] <SOURCE><br> -`blogc` `-l` [`-e` <SOURCE>] [`-d`] [`-D` <KEY>=<VALUE> ...] `-t` <TEMPLATE> [`-o` <OUTPUT>] [<SOURCE> ...]<br> -`blogc` `-l` [`-e` <SOURCE>] [`-d`] [`-D` <KEY>=<VALUE> ...] `-t` <TEMPLATE> [`-o` <OUTPUT>] [<SOURCE> ...]<br> -`blogc` `-l` [`-e` <SOURCE>] `-p` <KEY> [`-d`] [`-D` <KEY>=<VALUE> ...] [<SOURCE> ...]<br> -`blogc` `-i` [`-d`] [`-D` <KEY>=<VALUE> ...] `-t` <TEMPLATE> [`-o` <OUTPUT>] < <FILE_LIST><br> -`blogc` `-i` `-l` [`-e` <SOURCE>] [`-d`] [`-D` <KEY>=<VALUE> ...] `-t` <TEMPLATE> [`-o` <OUTPUT>] < <FILE_LIST><br> -`blogc` `-i` `-l` [`-e` <SOURCE>] `-p` <KEY> [`-d`] [`-D` <KEY>=<VALUE> ...] < <FILE_LIST><br> -`echo` `-e` "<SOURCE>\n..." | `blogc` `-i` [`-d`] [`-D` <KEY>=<VALUE> ...] `-t` <TEMPLATE> [`-o` <OUTPUT>]<br> -`echo` `-e` "<SOURCE>\n..." | `blogc` `-i` `-l` [`-e` <SOURCE>] [`-d`] [`-D` <KEY>=<VALUE> ...] `-t` <TEMPLATE> [`-o` <OUTPUT>]<br> -`echo` `-e` "<SOURCE>\n..." | `blogc` `-i` `-l` [`-e` <SOURCE>] `-p` <KEY> [`-d`] [`-D` <KEY>=<VALUE> ...]<br> +`blogc` `-d` [`-D` <KEY>=<VALUE> ...] `-t` <TEMPLATE> [`-o` <OUTPUT>] <SOURCE><br> +`blogc` `-d` `-l` [`-D` <KEY>=<VALUE> ...] `-t` <TEMPLATE> [`-o` <OUTPUT>] [<SOURCE> ...]<br> +`blogc` `-d` `-l` `-p` <KEY> [`-D` <KEY>=<VALUE> ...] [<SOURCE> ...]<br> `blogc` [`-h`|`-v`] ## DESCRIPTION -**blogc** compiles source files and templates into blog/website resources. It +**blogc** converts source files and templates into blog/website resources. It gets one (or more) source files and a template, and generates an output file, based on the template and the content read from the source file(s). It was designed to be used with make(1). @@ -30,39 +23,20 @@ designed to be used with make(1). page or a post. * `listing`: - Listing mode, second example in [SYNOPSIS][], activated when calling `blogc` - with `-l` option. Accepts multiple source files, and allow users to iterate - over the content of all the source files to produce listing pages, like - indexes and feeds. By providing another source file to `blogc` with `-e` - option, third example in [SYNOPSIS][], its content will be available for usage - during listing, similar to the default entry mode. This is useful for users - that want to have an index page with content and posts listing together. - See blogc-template(7) for details. + Listing mode, second example in [SYNOPSIS][], activated when + calling `blogc` with `-l` option. Accepts multiple source files, and allow + users to iterate over the content of all the source files to produce listing + pages, like indexes and feeds. ## OPTIONS * `-d`: Activates debug. - * `-i`: - Reads list of source files from standard input. Content of standard input is - parsed as a file where each line is a file path. Empty lines and lines - starting with `#` are ignored. If some source files are provided to command - line while using this option, they will be parsed **before** the files read - from standard input. - * `-l`: Activates listing mode, allowing user to provide multiple source files. See blogc-source(7) for details. - * `-e` <SOURCE>: - When used together with `-l` the source file will be parsed and its content - will be made available for usage in the templates in listing mode via - `listing_entry` blocks. This option can be used more than once, so users can - have more than one `listing_entry` block in the same template. Passing an - empty string will skip the `listing_entry` block. See blogc-template(7) for - details. - * `-D` <KEY>=<VALUE>: Set global configuration parameter. <KEY> must be an ascii uppercase string, with only letters, numbers (after the first letter) and underscores (after @@ -71,10 +45,9 @@ designed to be used with make(1). See blogc-template(7) for details. * `-p` <KEY>: - Show the value of a variable right after the source parsing and exits. This - is useful to get parameters for your `Makefile`, like the last page when - implementing pagination, see blogc-pagination(7) for details. This option can - also dump variables defined in a source file, if called without `-l`. + 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, see blogc-pagination(7) for details. * `-t` <TEMPLATE>: Template file. It is a required option, if `blogc` needs to render something. @@ -100,7 +73,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 strftime(3). +can be overridden using environment variables. See strptime(3). ## EXAMPLES @@ -108,10 +81,6 @@ Build index from source files: $ blogc -l -t template.tmpl -o index.html source1.txt source2.txt source3.txt -Build index from source files, with additional content from `index.txt`: - - $ blogc -l -e index.txt -t template.tmpl -o index.html source1.txt source2.txt source3.txt - Build entry page from source file: $ blogc -t template.tmpl -o entry.html entry.txt @@ -128,4 +97,4 @@ Rafael G. Martins <<rafael@rafaelmartins.eng.br>> ## SEE ALSO -blogc-source(7), blogc-template(7), blogc-pagination(7) make(1), strftime(3) +blogc-source(7), blogc-template(7), blogc-pagination(7) make(1), strptime(3) diff --git a/man/blogcfile.5.ronn b/man/blogcfile.5.ronn deleted file mode 100644 index 3d4f482..0000000 --- a/man/blogcfile.5.ronn +++ /dev/null @@ -1,207 +0,0 @@ -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. If negative, all the posts are - included. If `0`, no Atom feeds are generated. - - * `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. - - * `atom_template` (default: internal template) - The template file that should be used when building Atom feeds. This file - is relative to `template_dir`. If not provided, an internal default template - will be used instead. The internal template can be dumped using the `atom_dump` - blogc-make(1) rule. - - * `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. - - * `listing_entry` (default: unset): - The page that will be included in the listing pages of the website, without - the page prefix and without the extension, only the "slug" should be used. - See blogc(1) and the description of `listing_entry` block in blogc-template(7) - for details. - - * `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. If negative, all the posts - are included. If `0`, no post listing pages are generated. Also, if negative or - `0`, the `pagination` build rule is disabled. - - * `posts_sort` (default: `false`): - If true, blogc(1) will sort the posts by date, despite the order of the posts - in the `[posts]` section, in descending order. This setting is compatible with - `html_order` and `atom_order` settings, to control the order of the posts. - - * `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. - -The tags will be also provided to blogc as a `MAKE_TAGS` variable, that is a -space-separated list of the tags, useful to generate tag clouds using the -`foreach` template iterator. See blogc-template(7). - -### 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: <https://github.com/blogc/blogc> - -## AUTHOR - -Rafael G. Martins <<rafael@rafaelmartins.eng.br>> - -## SEE ALSO - -blogc(1), blogc-make(1), blogc-template(7) strftime(3) diff --git a/man/index.txt b/man/index.txt index d11e1c9..4ca6e67 100644 --- a/man/index.txt +++ b/man/index.txt @@ -1,19 +1,15 @@ # manuals 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-toctree(7) blogc-toctree.7.ronn blogc-pagination(7) blogc-pagination.7.ronn # external manuals -make(1) https://man.cx/make(1) -chsh(1) https://man.cx/chsh(1) -su(1) https://man.cx/su(1) -strcmp(3) https://man.cx/strcmp(3) -strftime(3) https://man.cx/strftime(3) -git(1) https://man.cx/git(1) -git-shell(1) https://man.cx/git-shell(1) +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) |