/users/phlogs/burrow/phlog/20180415-an-introduction-to-burrow on sdf.org

	----------------------------------------
	An introduction to burrow
	April 15th, 2018
	----------------------------------------

	What is burrow? It's a tool to help you manage a gopher hole. One
	of its primary functions in to help in writing phlog posts, just
	like this one.

	So how does it work?

	1. First, you need to download it. You can find the latest here [0].

	[0] burrow - latest version


	2. Install or use locally

	If you have root access on your machine you can install burrow
	with sudo make install from inside the downloaded repo, or the
	folder that is created from the zip you downloaded.

	If you do not have root access on your machine, you can run the
	burrow script from that directory as-is by typing ./burrow or
	path/to/burrow. You won't get the extra help from the man page or
	the tab completion this way, though.


	3. Make sure you have a gopher hole

	If you don't actually have a gopher hole set up somewhere, I
	recommend signing up for a free account here at SDF.org.


	4. Generate a configuration file

	The first thing you should run with burrow is "burrow
	create-config". This will generate a configuration file at
	~/.config/burrow/config. You'll want to open and edit this file
	right away and change the settings to match your gopher
	preferences and locations.

	At the minimum you will need to update these settings to match
	your system:

	config_dir_gopher="/absolute/path/to/your/gopherhole/"
	config_gopher_server="sdf.org"
	config_gopher_port="70" # if you don't know this, it's probably 70
	config_gopher_root="/users/tomasino/"


	5. Create a top-level gophermap

	Burrow is helpful in creating individual phlog posts, adding
	recipes, or making notes on topics. It does not create your
	top-level gophermap, though. There should be instructions on the best
	practices for creating a gophermap at the root of this gopherhole.


	6. Write a phlog entry

	Type "burrow phlog" and enter a title for your first post. This
	will launch your default system editor with a header
	pre-populated. If you're just writing text you can begin your work
	now. It's best practice to keep your widths under 75 characters
	wide (I use 67 wide) to render nicely on older clients.

	If you want to add links, you'll need to manually drop those in
	using gophermap formatting. Instructions for that can be found in
	other places on this gopher hole.

	Once your post is done, save and quit your editor. Burrow will
	transform it into the proper formatting for gopher, add links to
	the top of your phlog's gophermap, and even update the "Last
	Updated" date on your main gophermap if you have one.

	That's it! You're now joining the gopher club. Congratulations!


	Appendix A. Ask for help

	I hang out on irc at irc.sdf.org in #gopher. Feel free to ask me
	any questions you might have.