From adc3e6d77117d095e485ec64a93f1b64ffbf2cea Mon Sep 17 00:00:00 2001
From: "Rafael G. Martins" <rafael@rafaelmartins.eng.br>
Date: Tue, 2 Apr 2019 22:57:33 +0200
Subject: blogc: added `-e` cli option and `listing_entry` template block

---
 man/blogc-template.7.ronn | 15 +++++++++++++++
 man/blogc.1.ronn          | 34 ++++++++++++++++++++++++----------
 2 files changed, 39 insertions(+), 10 deletions(-)

(limited to 'man')

diff --git a/man/blogc-template.7.ronn b/man/blogc-template.7.ronn
index afa884b..cf397b7 100644
--- a/man/blogc-template.7.ronn
+++ b/man/blogc-template.7.ronn
@@ -87,6 +87,21 @@ that the `TITLE` variable is defined:
     </ul>
     {% 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>. The
+variables available in the block are provided by the source file provided
+using `-e`.
+
+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 %}
+
+
 ## TEMPLATE VARIABLES
 
 Template variables are used to provide content to templates from blogc(1)
diff --git a/man/blogc.1.ronn b/man/blogc.1.ronn
index 11af48c..8bcd12d 100644
--- a/man/blogc.1.ronn
+++ b/man/blogc.1.ronn
@@ -4,14 +4,15 @@ blogc(1) -- a blog compiler
 ## SYNOPSIS
 
 `blogc` [`-d`] [`-D` <KEY>=<VALUE> ...] `-t` <TEMPLATE> [`-o` <OUTPUT>] <SOURCE><br>
-`blogc` `-l` [`-d`] [`-D` <KEY>=<VALUE> ...] `-t` <TEMPLATE> [`-o` <OUTPUT>] [<SOURCE> ...]<br>
-`blogc` `-l` `-p` <KEY> [`-d`] [`-D` <KEY>=<VALUE> ...] [<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>] &lt; <FILE_LIST><br>
-`blogc` `-i` `-l` [`-d`] [`-D` <KEY>=<VALUE> ...] `-t` <TEMPLATE> [`-o` <OUTPUT>] &lt; <FILE_LIST><br>
-`blogc` `-i` `-l` `-p` <KEY> [`-d`] [`-D` <KEY>=<VALUE> ...] &lt; <FILE_LIST><br>
+`blogc` `-i` `-l` [`-e` <SOURCE>] [`-d`] [`-D` <KEY>=<VALUE> ...] `-t` <TEMPLATE> [`-o` <OUTPUT>] &lt; <FILE_LIST><br>
+`blogc` `-i` `-l` [`-e` <SOURCE>] `-p` <KEY> [`-d`] [`-D` <KEY>=<VALUE> ...] &lt; <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` [`-d`] [`-D` <KEY>=<VALUE> ...] `-t` <TEMPLATE> [`-o` <OUTPUT>]<br>
-`echo` `-e` "<SOURCE>\n..." | `blogc` `-i` `-l` `-p` <KEY> [`-d`] [`-D` <KEY>=<VALUE> ...]<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` [`-h`|`-v`]
 
 ## DESCRIPTION
@@ -29,10 +30,14 @@ 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.
+    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.
 
 ## OPTIONS
 
@@ -50,6 +55,11 @@ designed to be used with make(1).
     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. 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
@@ -100,6 +110,10 @@ 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
-- 
cgit v1.2.3-18-g5258