Name
----

godot -- phlog wrapper for gophernicus gopher server

Synopsis
--------

godot FILE

Description
-----------

godot is posix shell script written for gophernicus' CGI; number of operations,
where UTF-8 chars assumed, depend on GNU awk (feel free to change to any other
awk if you don't use UTF-8 e.g. in pictures).

Features:

- (not so) fancy layout
- comments, categories, search, most viewed, most commented, category stats
- post views counter
- anonymous/admin comments with geoiplookup and timeout protection
- sdf.org username in comments

Format
------

Text format is markdown-alike. There are two format modes: brief and verbatim
post. Brief mode is used for wrapped brief phlog entries, verbatim - for full
post article and comments.

Verbatim mode does not change text format except recognized links (see
further). Here you should care about gopher info line width supported by server
(in case it trims wide lines). All other format notes relate to brief mode.

Text is wrapped automagically by paragraphs of 40 chars width. Lists (starting
with dash) and quotes (starting with ">") converted too. Indented text is
unrecognized.

Links are converted to gopher resources and dumped after special directive or
automatically at the end of document. HTTP[S]/FTP links are recognized without
markup (on end of line requires space). Foreign server links are recognized
with "gopher://" prefix. Link example: [example](link) . Link names starting
with "?" converted to gopher search entries. Links started with "!" followed by
character converted to gopher resource of character type. Example:
[!Ipicture](link) . Combined example: [?!Irequest image](link) . Start link
name with space to preserve special characters: [ !help](link) .

Lines starting with "#" considered tags (categories) list with each category as
single word prefixed with "#".

Directives are one per line commands prefixed with percent (much like pandoc):

break::     empty/"transparent" space between paragraphs
div::       single line of indented 30 chars width caption
hr::        insert decorated break inside of paragraph
links::     dump links (useful after each phlog record)
body::      cut line for brief phlog feed and verbatim marker for full post
raw::       raw gopher markup marker
end::       end of verbatim or raw mode for full post body
phlog latest:: display latest record
phlog cats:: display categories summary
phlog last comments:: process last comments file
phlog top views:: top views from views counter file
phlog top comments:: same for comments

Install
-------

Installation done with shipped Makefile performing next steps.

    $ export INSTALL=/sdf/ftp/pub/users/ulcer/cgi-bin
    $ make install
    $ vim "${INSTALL}/godot-config.sh"

Fill with default content:

    $ install -m 644 nav.txt quotes.txt special.godot main.godot godot.md "$(INSTALL)/.."
    $ cp -r my_pictures "${INSTALL}/.."
    $ cp -r my_phlog "${INSTALL}/.."

Then link any gophermap to "godot?main".

NOTE: pay attention to lock and other files with special permissions,
      consult Makefile for exact values

Usage
-----

Godot files have extension ".godot". Calling "godot?FILE" will take
../FILE.godot . 

Example call from gopher file:

    godot?main

Example call from command line:

    ./godot /tmp/generated_content

*Categories*

Calling godot-cats will take all files under ../phlog directory and generate
summary of used tags. Calling "godot-cats?TERM" will generate briefs of all
records under given TERM category.

*Posts*

godot-post displays posts with comments and should be used instead of
godot?post notation (both increase views counter).

New post creation helper script: godot-mkpost.

Admin comment helper script: godot-mkcomment.

*Views*

Views counter records only default extension files (.godot).

*Admin*

Use godot-mkpost to create new post file hierarchy and godot-mkcomment for root
comment.

NOTE: admin log is rotated

Files
-----

Assuming script is located in cgi-bin folder:

../gophermap::         example page linking to "godot?main"
../main.godot::     main layout
../special.godot::  special page: categories list, stats, etc.
../nav.txt::        navigation quotes up to 30 chars wide
../quotes.txt::     quotes to be wrapped around pictures
../pictures/FILE.asc:: asciiart pictures
godot::             main script
godot-wrap.sh::     wrap quote around picture script
godot-post::        display post with comments
godot-cats::        display category posts
godot-all::         display posts archive
godot-phlog::       display latest posts feed
godot-search::      display fulltext search results
godot-cnt::         suid wrapper for views counter script
godot-cnt.sh::      views counter script
godot-comment::     suid wrapper for commenting script
godot-comment.sh::  add comment, maintain last comments list
godot-config.sh::   config data
ugly-godot/::       gophernicus fix - comment wrappers
../admin/godot-mkpost:: new post helper script
../admin/godot-mkcomment:: add comment (use for author comments)
../admin/godot-regen-comments:: refresh (repair) comments counter
../log/godot-comments.log:: comments with remote IPs
../phlog/::         phlog entries (see structure below)
../var/godot-counter:: views counter: "N page" per line
../var/godot-counter.lastip:: stores last passed IP and page
../var/godot-last_comments:: last file/comments
../var/godot-comments:: comments counter: "N page" per line
../var/godot-comments.tmp:: last comments temp file

Phlog directory structure:

    phlog
    ├── 20170326_1000
    │   ├── comments
    │   └── post.godot
    └── 20170409_1000
        ├── comments
        └── post.godot

gophernicus fixes:

    cgi-bin
    └── ugly-godot
        ├── 20170326_1000.sh
        └── 20170409_1000.sh

Authors
-------

ulcer <ulcer@sdf.org>, 2017

Licensed under terms of WTFPL. See full license text in tarball.

Bugs
----

It's youneks.

Lock files should be created beforehand to prevent abuse and be owned by user.
Suid wrappers should be chmod u+s user.

stat and other tools synthax differs significantly between GNU/BSD utils; see
shipped deploy file. GNU awk and sed are required for correct unicode
processing. Default sed considered to be unicode-aware.

Each comment gophermap exists due to current (version 1.6) gophernicus
inability to pass both static arguments and gopher search string to CGI script.

File locations are relative and hardcoded, changing those may be tricky.

Performance may be significantly improved by caching temporary files of
godot-post.

See also
--------

RFC1436, gophernicus(1)