From: Sergey Matveev Date: Sat, 9 May 2020 11:57:00 +0000 (+0300) Subject: Texinfo website contents X-Git-Tag: v0.6.0~3 X-Git-Url: http://www.git.stargrave.org/?p=sgblog.git;a=commitdiff_plain;h=869e50f9038fe122c513d4e4f9219c585defc285 Texinfo website contents --- diff --git a/README b/README deleted file mode 100644 index 282be72..0000000 --- a/README +++ /dev/null @@ -1,85 +0,0 @@ - SGBlog -- Git-based CGI/inetd blogging/phlogging engine - ======================================================= - -DESCRIPTION - -SGBlog is a simple blogging engine with a Git-based storage, CGI -interface for HTTP-server, inetd interface for serving as Gopher server. -It can be used as a cgit replacement for readonly Git repository viewing -and Atom feed generation. But it has better features: - -* URLs are tried to be converted to clickable links -* SHA1 hashes are tried to be converted to blog links itself -* Relative links are included for easy navigation -* Each page has ETag and it is checked against the request for client-side - caching -* Pages can be gzip-compressed, depending on Accept-Encoding header -* Gopher protocol support for phlog creation -* Commenting support - -CONFIGURATION - -SGBlog is configured via Hjson configuration file: - - { - GitPath: /home/git/pub/stargrave-blog.git - Branch: refs/heads/english - Title: "English Stargrave's blog" - - BaseURL: http://blog.stargrave.org - URLPrefix: /english - - AtomId: "urn:uuid:18e2f27c-a668-4e85-822e-b902376be5e3" - AtomAuthor: Sergey Matveev - - # URL to CSS file, optional - CSS: /style.css - # Email address of the webmaster, optional - Webmaster: "webmaster@example.com" - # URL to about page, optional - AboutURL: / - # Optional list of optional Git URLs for corresponding - GitURLs: [ - git://git.stargrave.org/stargrave-blog.git - https://git.stargrave.org/git/stargrave-blog.git - ] - - # If that ref is set, then comments will be loaded from it - CommentsNotesRef: refs/notes/comments - # Display link for comment writing, if email is set - CommentsEmail: something@example.com - } - -Gopher mode can use the same configuration file, but it requires much -less options: - - { - GitPath: /home/git/pub/stargrave-blog.git - Branch: refs/heads/english - Title: "English Stargrave's blog" - - AboutURL: http://blog.stargrave.org/ - - CommentsNotesRef: refs/notes/comments - CommentsEmail: something@example.com - - GopherDomain: phlog.stargrave.org - } - -COMMENTS - -Each comment is just a plaintext with From and Date headers. They are -stored in concatenated netstring serialized format as a Git note to -corresponding commit. They are added through email by feeding email -message to sgblog-comment-add. - -LICENCE - -This program is free software: you can redistribute it and/or modify -it under the terms of the GNU Affero General Public License as -published by the Free Software Foundation, version 3 of the License. - -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. diff --git a/README.texi b/README.texi new file mode 100644 index 0000000..37840b3 --- /dev/null +++ b/README.texi @@ -0,0 +1,215 @@ +\input texinfo +@documentencoding UTF-8 +@settitle SGBlog + +@copying +Copyright @copyright{} 2020 @email{stargrave@@stargrave.org, Sergey Matveev} +@end copying + +@node Top +@top + +SGBlog is minimalistic and simple Git-backed CGI/inetd +@url{https://en.wikipedia.org/wiki/Blog, blogging} and +@url{https://en.wikipedia.org/wiki/Phlog, phlogging} engine +with email-backed comments support, written on @url{https://golang.org/, Go}. + +Its main competitive features: + +@itemize +@item Single binary, responsible for both blog and phlog +@item @url{https://git-scm.com/, Git} DVCS as a storage for posts and comments +@item Single small @url{https://hjson.github.io/, Hjson} configuration file +@item Uses @url{https://en.wikipedia.org/wiki/Common_Gateway_Interface, CGI} + interface (simplicity, remember?) for dealing with HTTP-server +@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 Supports on the fly generation of + @url{https://en.wikipedia.org/wiki/Atom_(feed), Atom} feeds +@item Single binary for email-backed comments posting +@item If access is granted, then everyone can easily create an offline + 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: + +@itemize +@item Convert URLs to clickable links +@item Convert SHA1-like hashes to blog links itself +@item Include relative @code{} links for ease of navigation in + some browsers +@item @url{https://en.wikipedia.org/wiki/Gzip, gzip} compress both HTML + pages and Atom feeds +@item Respect @url{https://en.wikipedia.org/wiki/HTTP_ETag, ETag} + caching for both of them above +@end itemize + +@url{http://blog.stargrave.org/example/, Here} is an example blog. + +SGBlog is free software, licenced under +@url{https://www.gnu.org/licenses/agpl-3.0.html, GNU AGPLv3}: +see the file COPYING for copying conditions. + +@menu +* Comments:: +* Installation:: +* Configuration:: +@end menu + +@node Comments +@unnumbered Comments + +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" < "/path/to/sgblog") + cgi.assign = ("sgblog" => "/path/to/sgblog") + setenv.add-environment = ( + "SGBLOG_CFG" => "/path/to/example.hjson", + ) + @} +@} +@end example + +And be sure that you have read access to the Git repository, for example +by placing @code{lighttpd} user into @code{git} group. + +Example @command{inetd} configuration (for phlog): + +@example +gopher stream tcp nowait lighttpd /path/to/sgblog sgblog -gopher /path/to/gopher.hjson +gopher stream tcp6 nowait lighttpd /path/to/sgblog sgblog -gopher /path/to/gopher.hjson +@end example + +For comments workability you have to configure your SMTP server to feed +incoming messages to @command{sgblog-comment-add} utility. For example, +Postfix'es @file{/etc/aliases} can contain: + +@example +comment: "| /path/to/sgblog-comment-add -git-dir /path/to/blog.git -committer-email comment@@blog.example.com" +@end example + +to run that utility for all @code{comment@@} address messages. +You must have enough permission to be able to write to Git repository, +but Postfix by default runs all that commands from a @code{nobody} user. +So possibly you will need to @code{setuid} that executable give +permission for @code{nobody} running: + +@example +-rwsr-x--- git:nobody sgblog-comment-add +@end example + +And also do not forget about @code{lighttpd} user's (possibly in +@code{git} group) read permission permissions. Make sure +@command{sgblog-comment-add} runs with correctly set @code{-umask} (027 +by default) for newly created Git objects/files. + +@node Configuration +@unnumbered Configuration + +SGBlog is configured via Hjson configuration file. More or less +self-describing blog configuration looks like that and contains many +optional fields: + +@example +@{ + GitPath: /home/sgblog/blog.git + Branch: refs/heads/example + Title: "Example blog" + + BaseURL: http://blog.example.com + URLPrefix: /example + + AtomId: "urn:uuid:54e6e53f-c615-48f1-812c-6f6b094ebbdd" + AtomAuthor: John Doe + + # URL to CSS file, optional + CSS: /style.css + # Email address of the webmaster, optional + Webmaster: "webmaster@@example.com" + # URL to about page, optional + AboutURL: / + # Optional list of optional Git URLs for corresponding + GitURLs: [ + git://git.example.com/blog.git + https://git.example.com/git/blog.git + ] + + # If that ref is set, then comments will be loaded from it + CommentsNotesRef: refs/notes/comments + # Display link for comment writing, if email is set + CommentsEmail: something@@example.com +@} +@end example + +Gopher configuration can use the same file, but it requires much less +options: + +@example +@{ + GitPath: /home/sgblog/blog.git + Branch: refs/heads/example + Title: "Example blog" + + GopherDomain: phlog.example.com + + AboutURL: http://blog.example.com/ + + # Both are optional + CommentsNotesRef: refs/notes/comments + CommentsEmail: something@@example.com +@} +@end example + +@bye diff --git a/cmd/sgblog-comment-add/mail.go b/cmd/sgblog-comment-add/mail.go index 45ce053..88d95d8 100644 --- a/cmd/sgblog-comment-add/mail.go +++ b/cmd/sgblog-comment-add/mail.go @@ -1,5 +1,5 @@ /* -SGBlog -- Git-based CGI/inetd blogging/phlogging engine +SGBlog -- Git-backed CGI/inetd blogging/phlogging engine Copyright (C) 2020 Sergey Matveev This program is free software: you can redistribute it and/or modify diff --git a/cmd/sgblog-comment-add/main.go b/cmd/sgblog-comment-add/main.go index 7233a6a..e74558e 100644 --- a/cmd/sgblog-comment-add/main.go +++ b/cmd/sgblog-comment-add/main.go @@ -1,5 +1,5 @@ /* -SGBlog -- Git-based CGI/inetd blogging/phlogging engine +SGBlog -- Git-backed CGI/inetd blogging/phlogging engine Copyright (C) 2020 Sergey Matveev This program is free software: you can redistribute it and/or modify @@ -15,7 +15,7 @@ You should have received a copy of the GNU Affero General Public License along with this program. If not, see . */ -// Git-based CGI/inetd blogging/phlogging engine +// Git-backed CGI/inetd blogging/phlogging engine package main import ( diff --git a/cmd/sgblog/gopher.go b/cmd/sgblog/gopher.go index f27b765..1e3eb72 100644 --- a/cmd/sgblog/gopher.go +++ b/cmd/sgblog/gopher.go @@ -1,5 +1,5 @@ /* -SGBlog -- Git-based CGI/inetd blogging/phlogging engine +SGBlog -- Git-backed CGI/inetd blogging/phlogging engine Copyright (C) 2020 Sergey Matveev This program is free software: you can redistribute it and/or modify diff --git a/cmd/sgblog/http.go b/cmd/sgblog/http.go index 4d88fb8..de92039 100644 --- a/cmd/sgblog/http.go +++ b/cmd/sgblog/http.go @@ -1,5 +1,5 @@ /* -SGBlog -- Git-based CGI/inetd blogging/phlogging engine +SGBlog -- Git-backed CGI/inetd blogging/phlogging engine Copyright (C) 2020 Sergey Matveev This program is free software: you can redistribute it and/or modify diff --git a/cmd/sgblog/main.go b/cmd/sgblog/main.go index 06f1e37..9b03e4c 100644 --- a/cmd/sgblog/main.go +++ b/cmd/sgblog/main.go @@ -1,5 +1,5 @@ /* -SGBlog -- Git-based CGI/inetd blogging/phlogging engine +SGBlog -- Git-backed CGI/inetd blogging/phlogging engine Copyright (C) 2020 Sergey Matveev This program is free software: you can redistribute it and/or modify @@ -15,7 +15,7 @@ You should have received a copy of the GNU Affero General Public License along with this program. If not, see . */ -// Git-based CGI/inetd blogging/phlogging engine +// Git-backed CGI/inetd blogging/phlogging engine package main import ( diff --git a/common.go b/common.go index bcc0d9c..97b29f7 100644 --- a/common.go +++ b/common.go @@ -1,4 +1,4 @@ -// SGBlog -- Git-based CGI/inetd blogging/phlogging engine +// SGBlog -- Git-backed CGI/inetd blogging/phlogging engine package sgblog const (