Topics support

[sgblog.git] / README.texi

diff --git a/README.texi b/README.texi
index c2b5887c45acee02d80385d178c2ba9b72caed94..a0309d81dd4dd38677b4b8b27845d510b8d1e2d1 100644 (file)
--- a/README.texi
+++ b/README.texi
@@ -25,6 +25,7 @@ Its main competitive features:
 @item Uses @url{https://en.wikipedia.org/wiki/Inetd, inetd} interface
     for working as @url{https://en.wikipedia.org/wiki/Gopher_(protocol), Gopher}
     server
+@item Topics (tags/categories) support
 @item Supports on the fly generation of
     @url{https://en.wikipedia.org/wiki/Atom_(feed), Atom} feeds
     for posts, comments and per-post comments
@@ -33,9 +34,9 @@ Its main competitive features:
     copy of your blog/phlog!
 @end itemize
 
-All of that, except for comments and phlog, could be achieved with some
-Git viewer like @url{https://git.zx2c4.com/cgit/about/, cgit}. But
-SGBlog also is able to:
+All of that, except for comments, topics and phlog, could be achieved
+with some Git viewer like @url{https://git.zx2c4.com/cgit/about/, cgit}.
+But SGBlog also is able to:
 
 @itemize
 @item Convert URLs to clickable links
@@ -56,6 +57,7 @@ see the file COPYING for copying conditions.
 
 @menu
 * Comments::
+* Topics::
 * Installation::
 * Configuration::
 @end menu
@@ -67,7 +69,7 @@ Comments are posted through the email interface, just by sending the
 message to special address. For example:
 
 @example
-mutt "mailto:comment@@blog.example.com?subject=576540a5b98517b46d0efc791bb90b9121bf147e" <<EOF
+$ mutt "mailto:comment@@blog.example.com?subject=576540a5b98517b46d0efc791bb90b9121bf147e" <<EOF
 This is the comments contents.
 Could be multilined of course.
 EOF
@@ -86,6 +88,18 @@ Technically comments are stored in concatenated
 are accepted and only with UTF-8, US-ASCII, ISO-8859-1 character sets.
 Sane people won't send HTML email anyway, but this is just a precaution.
 
+@node Topics
+@unnumbered Topics
+
+Each post can have any number of attached topics (also known as tags or
+categories). They are whitespace separated single words kept in separate
+@url{https://git-scm.com/docs/git-notes, note} namespace. You can
+add/change comments with commands like:
+
+@example
+$ git notes --ref=topics add -m "linux hate" @@
+@end example
+
 @node Installation
 @unnumbered Installation
 
@@ -191,6 +205,11 @@ optional fields:
   CommentsNotesRef: refs/notes/comments
   # Display link for comment writing, if email is set
   CommentsEmail: something@@example.com
+
+  # If that ref is set, then topics will be loaded from it
+  TopicsNotesRef: refs/notes/topics
+  # Optional file for topics state caching
+  TopicsCachePath: /path/to/sgblog-topics-cache.gob
 @}
 @end example
 
@@ -210,6 +229,10 @@ options:
   # Both are optional
   CommentsNotesRef: refs/notes/comments
   CommentsEmail: something@@example.com
+
+  # Both are optional too
+  TopicsNotesRef: refs/notes/topics
+  TopicsCachePath: /path/to/sgblog-topics-cache.gob
 @}
 @end example