ref: 0d10a955e2d485f98d893f013331fd65a73fac75
parent: c7faa54ac73cd0fb2fc35b3e074071dd0b5c01fe
author: sl <sl@gaff>
date: Thu Feb 13 19:30:02 EST 2025
update documentation, clean up defaults, clarify examples, fix some bugs (thanks, khm)
--- a/README
+++ b/README
@@ -2,23 +2,24 @@
DESCRIPTION
BARF utilizes rc(1) and command line tools to compile
- a structured directory of files into a single page of
- HTML. Tagging and RSS 2.0 feeds have been
+ a structured directory of files into a burst of HTML.
+ Pagination, tagging, and RSS 2.0 feeds have been
implemented.
-
+
SETUP
- To enable BARF, add:
-
+ To install BARF, clone or unpack the program directory
+ under werc/apps/.
+
+ To enable BARF for a specific website, add the
+ following to _werc/config under the site root:
+
conf_enable_barf
-
- to _werc/config under the site root.
- To configure BARF, copy or create the following files
+ To configure BARF, create or copy the following files
under the site root (example files have been included
- in this distribution):
+ with this distribution under examples/):
_werc/barf/config
-
A list of variables that control various site options:
barf_type=paste # blog, image, log, paste
@@ -27,8 +28,22 @@
show_footer=0
show_header=0
show_sidebar=0
- require_login=0 # redirect to /login
+ require_login=0
allow_anon=1 # allow posts without logging in
+
+ _werc/barf/items
+ A list of constituent parts used to build a post:
+
+ body
+ date
+ img # only required for barf_type=image
+ link
+ tags
+ title
+
+ BARF will attempt to work with whatever is listed
+ here. Add to or omit from the list as needed. As
+ always, if something breaks, consult the source.
_werc/barf/footer
HTML or markdown that will appear as the foot of
@@ -41,88 +56,116 @@
_werc/barf/sidebar
HTML or markdown that will appear on one side of
the BARF content area.
-
- Finally, sample stylesheets are provided in the directory
- pub/. Copy any of these to _werc/pub/style.css to try
- them out.
-
+
+ src/
+ Directory where posts live. Must be writeable
+ by the webserver process in order to post from
+ the browser.
+
+ tags
+ File where an index of the site's tags is
+ stored. Must be writeable by the webserver
+ process in order to post from the browser.
+
+ Sample stylesheets are provided in the directory pub/.
+ Copy any of these to _werc/pub/style.css to try them
+ out.
+
+ Note: To further customize BARF's behavior, copy any
+ of the files in lib/ to _werc/lib/ under the site root
+ and edit.
+
POSTS
- Posts are stored in the directory src/ relative to the
- site root.
-
- Directory names in src/ that do not match the regular
- expression ^[0-9]*$ will not be included in the listing of
- posts that are displayed in the browser. However, such
- directories are still accessible when called directly via
- an appropriately constructed URL.
-
+ Posts are stored in the directory src/ under the site
+ root.
+
+ A post comprises a numbered directory containing
+ several files. Post directories whose names do not
+ match the regular expression ^[0-9]*$ will not be
+ included in the listing of posts displayed in the
+ browser. However, such directories will still be
+ accessible when called directly via an appropriately
+ constructed URL.
+
A post's directory contains the following files and
- directories (an example post's directory has been
- included in this distribution):
-
+ directories (an example post has been included in this
+ distribution under examples/src/1/):
+
body
date
- img/
+ img/ # only required for barf_type=image
link
tags/
title
- The img/ directory contains images uploaded to the
- image board, including the original image and a
- thumbnail version, resized to no greater than 500
- pixels wide and 600 pixels tall.
-
- The tags/ directory contains one empty file named
- for each tag associated with the post.
-
- The site root contains a file named tags that is compr-
- ised of an index of the tags associated with each post.
- This index is consulted when searching for a given tag in
- the web browser.
-
+ The img/ directory contains an image
+ file.{gif,jpg,png} and a thumbnailed version+ small.file.png, resized to no greater than 500 pixels
+ wide and 600 pixels tall.
+
+ The tags/ directory contains one or more empty files
+ named for each tag associated with the post.
+
+ The site root contains a file named tags that
+ comprises an index of the tags for the entire site.
+ This index is consulted when the user selects a given
+ tag in the browser.
+
UTILS
+ WARNING: Mostly outdated.
+
bin/gf
Parse Livejournal and Tumblr RSS feeds into
- BARF posts. (Abandoned, may no longer work.)
+ BARF posts. (Abandoned, probably no longer works.)
bin/gk
- Create a list of known tags in the site root in
- a file named known_tags.
+ Create a report about known tags in a file
+ called known_tags under the site root.
bin/gr
- Parse Google Reader bundles into BARF posts.
+ Parse Google Reader bundles into BARF posts. (Haha.)
bin/gt
- Create an index of tags in the site root in a file
- named tags.
-
+ Create an index of tags in a file named tags
+ under the site root.
+
For more information on these tools, read the source.
ADMIN
Any tool that can create, alter, or delete flat files
- and directories is sufficient to administer a BARF.
+ and directories is sufficient to administer BARF.
+
+ --- continue at own risk ---
Web-based login and administration utilizes werc's
built-in user authentication:
- http://domain.com/login
+ http://fqdn/login
After login, links to edit and delete will appear in
each post's meta data.
-
- Web-based administration requires that the src/
- directory and its sub-directories are writable by
- the web server process.
-
+
+ Web-based administration requires the following items
+ under the site root to be writable by the web server
+ process: tags, src/, and src/'s subdirectories.
+
+ --- no refunds ---
+
REQUIREMENTS
- Unix
- Plan9port or 9base are required. Site type
- image requires ImageMagick and curl. Site
- type url also requires curl if the user employs
- the option to download remote URLs. These
- utilities may be swapped out for others by
- altering the source.
-
+ BARF is a werc app, so werc must be installed.
+
+ PLAN 9
+ No additional requirements.
+
+ UNIX
+ Plan9port, 9base, or frontbase are required.
+ barf_type=image requires ImageMagick and curl.
+ barf_type=log also requires curl if the user
+ employs the option to download remote URLs.
+ These utilities may be swapped out for others
+ by altering the source. Note: The web server
+ process must be able to successfully run curl.
+
SOURCE
- http://plan9.stanleylieber.com/werc/apps/barf.tgz
- https://only9fans.com/sl/barf/HEAD/info.html
+ https://only9fans.com/sl/barf/HEAD/info.html # git repo
+ http://plan9.stanleylieber.com/werc/apps/barf.tgz # files
EXAMPLES
blog
@@ -137,7 +180,7 @@
paste
http://okturing.com
Public pastebin. No authentication required
- to post.
+ to post. Lots of spam.
url
http://url.stanleylieber.com
Private index of URL bookmarks, similar
@@ -153,7 +196,7 @@
BUGS
On Plan 9, if the web server process is run as user
- none (typically the case), directories used for entering
- posts or uploading/downloading files from the browser
- must be set world writable. This could prove problematic
- on multiuser systems.
+ none (typically the case), directories used for
+ entering posts or uploading/downloading files from the
+ browser must be set world writable. This will prove
+ problematic on multiuser systems.
--- a/barf/config
+++ /dev/null
@@ -1,9 +1,0 @@
-barf_type=blog # blog, image, log, paste, url
-site_tmp=_tmp # used by hoc on plan 9
-posts_per_page=10
-show_ascending=0
-show_footer=0
-show_header=0
-show_sidebar=0
-require_login=0 # if not logged in, redirect to /login
-allow_anon=1 # allow posts without logging in
--- a/barf/footer
+++ /dev/null
@@ -1,1 +1,0 @@
-THIS IS THE FOOTER.
--- a/barf/header
+++ /dev/null
@@ -1,1 +1,0 @@
-THIS IS THE HEADER.
--- a/barf/sidebar
+++ /dev/null
@@ -1,1 +1,0 @@
-THIS IS THE SIDEBAR.
--- a/bin/gk
+++ b/bin/gk
@@ -9,7 +9,7 @@
if(test -f $base/_known_tags)
rm $base/_known_tags
-for(i in `{cat $base/etc/tags}){+for(i in `{cat $base/tags}){grep -e '^.*\/'$i'$' $base/tags |
awk -F '/' '{print $3;}' |sort |
--- /dev/null
+++ b/examples/config
@@ -1,0 +1,8 @@
+barf_type=blog # blog, image, log, paste
+posts_per_page=10
+show_ascending=0
+show_footer=0
+show_header=0
+show_sidebar=0
+require_login=0
+allow_anon=1 # allow posts without logging in
--- /dev/null
+++ b/examples/footer
@@ -1,0 +1,1 @@
+THIS IS THE FOOTER.
--- /dev/null
+++ b/examples/header
@@ -1,0 +1,1 @@
+THIS IS THE HEADER.
--- /dev/null
+++ b/examples/items.blog
@@ -1,0 +1,5 @@
+body
+date
+link
+tags
+title
--- /dev/null
+++ b/examples/items.image
@@ -1,0 +1,4 @@
+date
+img
+link
+tags
--- /dev/null
+++ b/examples/items.log
@@ -1,0 +1,4 @@
+date
+link
+tags
+title
--- /dev/null
+++ b/examples/items.paste
@@ -1,0 +1,2 @@
+body
+date
--- /dev/null
+++ b/examples/sidebar
@@ -1,0 +1,1 @@
+THIS IS THE SIDEBAR.
--- /dev/null
+++ b/examples/src/1/body
@@ -1,0 +1,1 @@
+Trust, but verify.
--- /dev/null
+++ b/examples/src/1/date
@@ -1,0 +1,1 @@
+Thu Aug 25 18:35:52 CDT 2011
--- /dev/null
+++ b/examples/src/1/link
@@ -1,0 +1,1 @@
+http://plan9.stanleylieber.com/9front
--- /dev/null
+++ b/examples/src/1/title
@@ -1,0 +1,1 @@
+This is a BULGE demo post.
--- /dev/null
+++ b/examples/tags
@@ -1,0 +1,3 @@
+1/tags/theory
+1/tags/random
+1/tags/demo
--- a/src/1/body
+++ /dev/null
@@ -1,1 +1,0 @@
-Trust, but verify.
--- a/src/1/date
+++ /dev/null
@@ -1,1 +1,0 @@
-Thu Aug 25 18:35:52 CDT 2011
--- a/src/1/link
+++ /dev/null
@@ -1,1 +1,0 @@
-http://plan9.stanleylieber.com/9front
--- a/src/1/title
+++ /dev/null
@@ -1,1 +1,0 @@
-This is a BULGE demo post.
--- a/tags
+++ /dev/null
@@ -1,3 +1,0 @@
-1/tags/theory
-1/tags/random
-1/tags/demo