Permalink
Browse files

update README and man page

This adds a build-time dependency on ronn for documentation.
  • Loading branch information...
1 parent 557e4d8 commit 10e19a03e397b30f5d1a4e715b93aaa408971db2 @kr committed Apr 15, 2012
Showing with 129 additions and 91 deletions.
  1. +1 −0 .gitignore
  2. +4 −0 Makefile
  3. +11 −4 README
  4. +0 −87 doc/beanstalkd.1
  5. +113 −0 doc/beanstalkd.ronn
View
@@ -4,3 +4,4 @@ ct/_*
beanstalkd
beanstalkd-*.tar.gz
NEWS.md
+doc/*.1*
View
@@ -35,6 +35,7 @@ HFILES=\
CLEANFILES=\
vers.c\
$(TARG)-*.tar.gz\
+ doc/*.1*
include mk/cmd
include mk/tst
@@ -62,3 +63,6 @@ $(TARG)-$(VERS).tar:
$(TARG)-$(VERS).tar.gz: $(TARG)-$(VERS).tar
gzip -f $<
+
+doc/beanstalkd.1 doc/beanstalkd.1.html: doc/beanstalkd.ronn
+ ronn $<
View
15 README
@@ -1,23 +1,29 @@
This is beanstalkd, a fast, general-purpose work queue.
See http://kr.github.com/beanstalkd/ for general info.
+
QUICK START
$ make
$ ./beanstalkd
-also,
+also try,
+
+ $ ./beanstalkd -h
+ $ ./beanstalkd -VVV
$ make CFLAGS=-g
$ make CC=clang
$ make check
$ make install
$ make install PREFIX=/usr
-You might need to type "gmake"; our build requires GNU make.
Requires Linux (2.6.17 or later), Mac OS X, or FreeBSD.
See doc/protocol.txt for details of the network protocol.
+Uses ronn to generate the manual.
+See http://github.com/rtomayko/ronn.
+
SUBDIRECTORIES
@@ -33,7 +39,8 @@ TESTS
Unit tests are in *-test.c. See https://github.com/kr/ct for
information on how to write them.
-Copyright 2007-2011 the authors of beanstalkd.
+
+Copyright © 2007-2012 the authors of beanstalkd.
Copyright in contributions to beanstalkd is retained
by the original copyright holder of each contribution.
-See the COPYING file for terms of use.
+See file LICENSE for terms of use.
View
@@ -1,87 +0,0 @@
-.TH BEANSTALKD 1 "October 14, 2009"
-.SH NAME
-beastalkd \- A simple, fast work queue.
-.SH SYNOPSIS
-.B beanstalkd
-.RI [ options ]
-.br
-.SH DESCRIPTION
-This manual page documents briefly the
-.B beanstalkd
-work-queue service.
-The beanstalk interface is generic, but was originally
-designed for reducing the latency of page views in high-volume web applications
-by running time-consuming tasks asynchronously.
-.br
-.SH OPTIONS
-A summary of options is included below.
-.TP
-.B \-b <dir>
-Use a binlog to keep jobs on persistent storage in <dir>. Upon startup,
-beanstalkd will recover any binlog that is present in <dir>, then, during
-normal operation, append new jobs and changes in state to the binlog.
-.TP
-.B \-d
-Detach and run beanstalkd as a daemon.
-.TP
-.B \-V
-Increase verbosity. May be used more than once to produce even more
-verbose output. The output format is subject to change.
-.TP
-.B \-f <ms>
-Call
-.BR fsync (2)
-at most once every <ms> milliseconds. This will recuce disk activity
-and improve speed at the cost of safety. A power failure could result in the
-loss of up to <ms> milliseconds of history.
-
-A <ms> value of 0 will cause beanstalkd to call fsync every time it writes to
-the binlog.
-
-This option has no effect without the
-.B \-b
-option.
-.TP
-.B \-F
-Never call
-.BR fsync (2)
-function. This is like
-.B \-f
-with a <ms> value of infinity.
-
-This option has no effect without the
-.B \-b
-option.
-.TP
-.B \-h
-Show the command line help and summary of options.
-.TP
-.B \-l <addr>
-Listen on address <addr> (default is 0.0.0.0)
-.TP
-.B \-p <port>
-Listen on TCP port <port> (default is 11300).
-.TP
-.B \-s <bytes>
-The maximum size in bytes of each binlog file.
-
-This option has no effect without the
-.B \-b
-option.
-.TP
-.B \-u <user>
-Become the user <user> and its primary group.
-.TP
-.B \-z <bytes>
-The maximum size in bytes of a job.
-.SH LICENSE
-The beanstalkd daemon is copyright Keith Rarick and Philotic Inc. and is
-distributed under the GNU General Public License version 3 or later.
-.br
-.SH SEE ALSO
-The README file that comes with beanstalkd
-.br
-.B http://xph.us/software/beanstalkd/
-.SH AUTHOR
-The beanstalkd daemon was written by Keith Rarick and Philotic Inc.
-.br
View
@@ -0,0 +1,113 @@
+beanstalkd(1) -- simple, fast work queue
+========================================
+
+## SYNOPSIS
+
+`beanstalkd` [<options>]
+
+## DESCRIPTION
+
+`Beanstalkd` is a simple work-queue service. Its interface is
+generic, though it was originally designed for reducing the latency of
+page views in high-volume web applications by running time-consuming
+tasks asynchronously.
+
+When started, `beanstalkd` opens a socket (or uses a file descriptor
+provided by the init(1) system, see [ENVIRONMENT][]) and listens for
+incoming connections. For each connection, it reads a sequence of
+commands to create, reserve, delete, and otherwise manipulate "jobs",
+units of work to be done. See file `doc/protocol.txt` in the
+`beanstalkd` distribution for a thorough description of the meaning
+and format of the `beanstalkd` protocol.
+
+## OPTIONS
+
+* `-b` <path>:
+ Use a binlog to keep jobs on persistent storage in directory <path>.
+ Upon startup, `beanstalkd` will recover any binlog that is present
+ in <path>, then, during normal operation, append new jobs and
+ changes in state to the binlog.
+
+* `-c`:
+ Perform online, incremental compaction of binlog files. Negates
+ `-n`. This is the default behavior.
+
+ (Do not use this option, except to negate `-n`. Both `-c` and `-n`
+ will likely be removed in a future `beanstalkd` release.)
+
+* `-f` <ms>:
+ Call fsync(2) at most once every <ms> milliseconds. Larger values
+ for <ms> reduce disk activity and improve speed at the cost of
+ safety. A power failure could result in the loss of up to <ms>
+ milliseconds of history.
+
+ A <ms> value of 0 will cause `beanstalkd` to call fsync every time
+ it writes to the binlog.
+
+ (This option has no effect without `-b`.)
+
+* `-F`:
+ Never call fsync(2). Equivalent to `-f` with an infinite <ms> value.
+
+ This is the default behavior.
+
+ (This option has no effect without `-b`.)
+
+* `-h`:
+ Show a brief help message and exit.
+
+* `-l` <addr>:
+ Listen on address <addr> (default is 0.0.0.0).
+
+ (Option `-l` has no effect if sd-daemon(5) socket activation is
+ being used. See also [ENVIRONMENT][].)
+
+* `-n`:
+ Turn off binlog compaction, negating `-c`.
+
+ (Do not use this option. Both `-c` and `-n` will likely be removed
+ in a future `beanstalkd` release.)
+
+* `-p` <port>:
+ Listen on TCP port <port> (default is 11300).
+
+ (Option `-p` has no effect if sd-daemon(5) socket activation is
+ being used. See also [ENVIRONMENT][].)
+
+* `-s` <bytes>:
+ The size in bytes of each binlog file.
+
+ (This option has no effect without `-b`.)
+
+* `-u` <user>:
+ Become the user <user> and its primary group.
+
+* `-V`:
+ Increase verbosity. May be used more than once to produce more
+ verbose output. The output format is subject to change.
+
+* `-v`:
+ Print the version string and exit.
+
+* `-z` <bytes>:
+ The maximum size in bytes of a job.
+
+## ENVIRONMENT
+
+* `LISTEN_PID`, `LISTEN_FDS`:
+ These variables can be set by init(1). See sd_listen_fds(3) for
+ details.
+
+## SEE ALSO
+
+sd-daemon(5), sd_listen_fds(5)
+
+Files `README` and `doc/protocol.txt` in the `beanstalkd`
+distribution.
+
+<http://kr.github.com/beanstalkd/>
+
+## AUTHOR
+
+`Beanstalkd` is written and maintained by Keith Rarick with the help
+of many others.

0 comments on commit 10e19a0

Please sign in to comment.