From 80e49c9679865b536edacfa2d308f42bf7820ab4 Mon Sep 17 00:00:00 2001
From: "Rafael G. Martins" <rafael@rafaelmartins.eng.br>
Date: Sat, 12 Sep 2020 20:31:30 +0200
Subject: blogc: man: added initial blogc-toctree(7)

---
 man/blogc-toctree.7.ronn | 87 ++++++++++++++++++++++++++++++++++++++++++++++++
 man/index.txt            |  1 +
 2 files changed, 88 insertions(+)
 create mode 100644 man/blogc-toctree.7.ronn

(limited to 'man')

diff --git a/man/blogc-toctree.7.ronn b/man/blogc-toctree.7.ronn
new file mode 100644
index 0000000..720a4ee
--- /dev/null
+++ b/man/blogc-toctree.7.ronn
@@ -0,0 +1,87 @@
+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 &lt;<rafael@rafaelmartins.eng.br>&gt;
+
+## SEE ALSO
+
+blogc(1), blogc-source(7), blogc-template(7)
diff --git a/man/index.txt b/man/index.txt
index a68646a..d11e1c9 100644
--- a/man/index.txt
+++ b/man/index.txt
@@ -6,6 +6,7 @@ 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
-- 
cgit v1.2.3-18-g5258