shithub: barf

Clone

Last commit

app.rc: barf/barf/config -> barf/examples/config

About

	BARF - emit HTML
	
	DESCRIPTION
		BARF utilizes rc(1) and command line tools to compile
		a structured directory of files into a burst of HTML.
		Pagination, tagging, and RSS 2.0 feeds have been
		implemented.

	SETUP
		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 configure BARF, create or copy the following files
		under the site root (example files have been included
		with this distribution under examples/):

		_werc/barf/config
			A list of variables that control various site options:
	
				barf_type=paste # 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

		_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
			the BARF content area.
	
		_werc/barf/header
			HTML or markdown that will appear at the head of
			the BARF content area.
	
		_werc/barf/sidebar
			HTML or markdown that will appear on one side of
			the BARF content area.

		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/ 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 has been included in this
		distribution under examples/src/1/):

			body
			date
			img/	# only required for barf_type=image
			link
			tags/
			title
	
		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, probably no longer works.)
		bin/gk
			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.  (Haha.)
		bin/gt
			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 BARF.

		--- continue at own risk ---
	
		Web-based login and administration utilizes werc's
		built-in user authentication:
	
			http://fqdn/login
	
		After login, links to edit and delete will appear in
		each post's meta data.

		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
		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
		https://only9fans.com/sl/barf/HEAD/info.html	# git repo
		http://plan9.stanleylieber.com/werc/apps/barf.tgz	# files
	
	EXAMPLES
		blog
			http://read.stanleylieber.com
			RSS feeds are converted by the utility rrss[0]
			and stored as individual blog posts.
		image
			http://img.stanleylieber.com
			Hybrid public/private image board. Requires
			standard werc authentication to post, but all
			posts are visible to the public.
		paste
			http://okturing.com
			Public pastebin. No authentication required
			to post.  Lots of spam.
		url
			http://url.stanleylieber.com
			Private index of URL bookmarks, similar
			in functionality to the old delicious.com.
			(In fact, most of the index was imported
			from delicious.)
	
	SEE ALSO
		[0] https://only9fans.com/sl/rrss/HEAD/info.html
	
	LICENSE
		Public domain.
	
	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 will prove
		problematic on multiuser systems.