Format code blocks and variable/path notations

Add markdown backticks for commands, variable names and path as well
as code blocks for better readability.

This fixes #97.

1 files changed, 70 insertions, 52 deletions

diff --git a/guide.md b/guide.md
index a3195b08..6be11b13 100644
--- a/guide.md
+++ b/guide.md
@@ -16,14 +16,14 @@ Current size is about 10k LoC C, and about 4k LoC shell.
 OpenRC is known to work on Linux, many BSDs (FreeBSD, OpenBSD, DragonFlyBSD at 
 least) and HURD.
 
-Services are stateful (i.e. start; start will lead to "it's already started")
+Services are stateful (i.e. `start`; `start` will lead to "it's already started")
 
 # Startup
 
-Usually PID1 (aka. init) calls the OpenRC binary ("/sbin/openrc" by default).
+Usually PID1 (aka. `init`) calls the OpenRC binary (`/sbin/openrc` by default).
 (The default setup assumes sysvinit for this)
 
-openrc scans the runlevels (default: "/etc/runlevels") and builds a dependency 
+openrc scans the runlevels (default: `/etc/runlevels`) and builds a dependency
 graph, then starts the needed service scripts, either serialized (default) or in 
 parallel.
 
@@ -32,29 +32,29 @@ daemon. (Integration with tools like monit, runit or s6 can be done)
 
 # Shutdown
 
-On change to runlevel 0/6 or running "reboot", "halt" etc., openrc stops all 
-services that are started and runs the services in the "shutdown" runlevel.
+On change to runlevel 0/6 or running `reboot`, `halt` etc., openrc stops all
+services that are started and runs the services in the `shutdown` runlevel.
 
 # Modifying Service Scripts
 
 Any service can, at any time, be started/stopped/restarted by executing 
-"rc-service someservice start", "rc-service someservice stop", etc.
+`rc-service someservice start`, `rc-service someservice stop`, etc.
 Another, less preferred method, is to run the service script directly,
-e.g. "/etc/init.d/service start", "/etc/init.d/service stop", etc.
+e.g. `/etc/init.d/service start`, `/etc/init.d/service stop`, etc.
 
 OpenRC will take care of dependencies, e.g starting apache will start network 
 first, and stopping network will stop apache first.
 
-There is a special command "zap" that makes OpenRC 'forget' that a service is 
+There is a special command `zap` that makes OpenRC 'forget' that a service is
 started; this is mostly useful to reset a crashed service to stopped state 
 without invoking the (possibly broken) stop function of the service script.
 
-Calling "openrc" without any arguments will try to reset all services so
+Calling `openrc` without any arguments will try to reset all services so
 that the current runlevel is satisfied; if you manually started apache it will be 
 stopped, and if squid died but is in the current runlevel it'll be restarted.
 
-There is a "service" helper that emulates the syntax seen on e.g. older Redhat 
-and Ubuntu ("service nginx start" etc.)
+There is a `service` helper that emulates the syntax seen on e.g. older Redhat
+and Ubuntu (`service nginx start` etc.)
 
 # Runlevels
 
@@ -65,100 +65,112 @@ own if needed. This allows, for example, to have a default runlevel with
 "everything" enabled, and a "powersaving" runlevel where some services are 
 disabled.
 
-The "rc-status" helper will print all currently active runlevels and the state 
+The `rc-status` helper will print all currently active runlevels and the state
 of init scripts in them:
 
+```
 # rc-status
  * Caching service dependencies ... [ ok ]
 Runlevel: default
  modules                     [  started  ]
  lvm                         [  started  ]
+```
 
-All runlevels are represented as folders in /etc/runlevels/ with symlinks to 
+All runlevels are represented as folders in `/etc/runlevels/` with symlinks to 
 the actual init scripts.
 
-Calling openrc with an argument ("openrc default") will switch to that
+Calling openrc with an argument (`openrc default`) will switch to that
 runlevel; this will start and stop services as needed.
 
-Managing runlevels is usually done through the "rc-update" helper, but could of 
+Managing runlevels is usually done through the `rc-update` helper, but could of 
 course be done by hand if desired.
-e.g. "rc-update add nginx default" - add nginx to the default runlevel
-Note: This will not auto-start nginx! You'd still have to trigger "rc" or run 
+e.g. `rc-update add nginx default` - add nginx to the default runlevel
+Note: This will not auto-start nginx! You'd still have to trigger `rc` or run 
 the initscript by hand.
 
 FIXME: Document stacked runlevels
 
-The default startup uses the runlevels "boot", "sysinit" and "default", in that 
-order. Shutdown uses the "shutdown" runlevel.
+The default startup uses the runlevels `boot`, `sysinit` and `default`, in that 
+order. Shutdown uses the `shutdown` runlevel.
 
 
 # Syntax of Service Scripts
 
 Service scripts are shell scripts. OpenRC aims at using only the standardized 
 POSIX sh subset for portability reasons. The default interpreter (build-time 
-toggle) is /bin/sh, so using for example mksh is not a problem.
+toggle) is `/bin/sh`, so using for example mksh is not a problem.
 
 OpenRC has been tested with busybox sh, ash, dash, bash, mksh, zsh and possibly 
 others. Using busybox sh has been difficult as it replaces commands with 
 builtins that don't offer the expected features.
 
-The interpreter for initscripts is #!/sbin/openrc-run
+The interpreter for initscripts is `#!/sbin/openrc-run`.
 Not using this interpreter will break the use of dependencies and is not 
-supported. (iow: if you insist on using #!/bin/sh you're on your own)
+supported. (iow: if you insist on using `#!/bin/sh` you're on your own)
 
-A "depend" function declares the dependencies of this service script.
+A `depend` function declares the dependencies of this service script.
 All scripts must have start/stop/status functions, but defaults are provided.
 Extra functions can be added easily:
 
+```
 extra_commands="checkconfig"
 checkconfig() {
 	doSomething
 }
+```
 
-This exports the checkconfig function so that "/etc/init.d/someservice 
-checkconfig" will be available, and it "just" runs this function.
+This exports the checkconfig function so that `/etc/init.d/someservice 
+checkconfig` will be available, and it "just" runs this function.
 
-While commands defined in extra_commands are always available, commands
-defined in extra_started_commands will only work when the service is started
-and those defined in extra_stopped_commands will only work when the service is
+While commands defined in `extra_commands` are always available, commands
+defined in `extra_started_commands` will only work when the service is started
+and those defined in `extra_stopped_commands` will only work when the service is
 stopped. This can be used for implementing graceful reload and similar
 behaviour.
 
 Adding a restart function will not work, this is a design decision within 
 OpenRC. Since there may be dependencies involved (e.g. network -> apache) a 
 restart function is in general not going to work. 
-restart is internally mapped to stop() + start() (plus handling dependencies).
+restart is internally mapped to `stop()` + `start()` (plus handling dependencies).
 If a service needs to behave differently when it is being restarted vs
-started or stopped, it should test the $RC_CMD variable, for example:
-
-    [ "$RC_CMD" = restart ] && do_something
+started or stopped, it should test the `$RC_CMD` variable, for example:
 
+```
+[ "$RC_CMD" = restart ] && do_something
+```
 
 # The Depend Function
 
 This function declares the dependencies for a service script. This
 determines the order the service scripts start.
 
+```
 depend() {
 	need net
 	use dns logger netmount
 	want coolservice
 }
+```
 
-"need" declares a hard dependency - net always needs to be started before this 
+`need` declares a hard dependency - net always needs to be started before this 
 	service does
-"use" is a soft dependency - if dns, logger or netmount is in this runlevel 
+
+`use` is a soft dependency - if dns, logger or netmount is in this runlevel 
 	start it before, but we don't care if it's not in this runlevel.
-	"want" is between need and use - try to start coolservice if it is
+	`want` is between need and use - try to start coolservice if it is
 	installed on the system, regardless of whether it is in the
 	runlevel, but we don't care if it starts.
-"before" declares that we need to be started before another service
-"after" declares that we need to be started after another service, without 
+
+`before` declares that we need to be started before another service
+
+`after` declares that we need to be started after another service, without 
 	creating a dependency (so on calling stop the two are independent)
-"provide" allows multiple implementations to provide one service type, e.g.:
-	'provide cron' is set in all cron-daemons, so any one of them started 
+
+`provide` allows multiple implementations to provide one service type, e.g.:
+	`provide cron` is set in all cron-daemons, so any one of them started 
 	satisfies a cron dependency
-"keyword" allows platform-specific overrides, e.g. "keyword -lxc" makes this 
+
+`keyword` allows platform-specific overrides, e.g. `keyword -lxc` makes this 
 	service script a noop in lxc containers. Useful for things like keymaps, 
 	module loading etc. that are either platform-specific or not available 
 	in containers/virtualization/...
@@ -169,31 +181,36 @@ FIXME: Anything missing in this list?
 
 All service scripts are assumed to have the following functions:
 
+```
 start()
 stop()
 status()
+```
 
-There are default implementations in rc/sh/openrc-run.sh - this allows very 
+There are default implementations in `lib/rc/sh/openrc-run.sh` - this allows very 
 compact service scripts. These functions can be overridden per service script as 
 needed.
 
 The default functions assume the following variables to be set in the service 
 script:
 
+```
 command=
 command_args=
 pidfile=
+``
 
 Thus the 'smallest' service scripts can be half a dozen lines long
 
-# The Magic of Conf.d
+# The Magic of `conf.d`
 
 Most service scripts need default values. It would be fragile to
-explicitly source some arbitrary files. By convention openrc-run will source
-the matching file in /etc/conf.d/ for any script in /etc/init.d/
+explicitly source some arbitrary files. By convention `openrc-run` will source
+the matching file in `/etc/conf.d/` for any script in `/etc/init.d/`
 
 This allows you to set random startup-related things easily. Example:
 
+```
 conf.d/foo:
 START_OPTS="--extraparameter sausage"
 
@@ -201,6 +218,7 @@ init.d/foo:
 start() {
 	/usr/sbin/foo-daemon ${STARTOPTS}
 }
+```
 
 The big advantage of this split is that most of the time editing of the init 
 script can be avoided.
@@ -213,34 +231,34 @@ mostly syntax-compatible to Debian's s-s-d, but has been rewritten from scratch.
 It helps with starting daemons, backgrounding, creating PID files and many 
 other convenience functions related to managing daemons.
 
-# /etc/rc.conf
+# `/etc/rc.conf`
 
 This file manages the default configuration for OpenRC, and it has examples of 
 per-service-script variables.
 
-Among these are rc_parallel (for parallelized startup), rc_log (logs all boot 
+Among these are `rc_parallel` (for parallelized startup), `rc_log` (logs all boot 
 messages to a file), and a few others.
 
 # ulimit and CGroups
 
-Setting ulimit and nice values per service can be done through the rc_ulimit 
+Setting `ulimit` and `nice` values per service can be done through the `rc_ulimit`
 variable.
 
 Under Linux, OpenRC can optionally use CGroups for process management.
 By default each service script's processes are migrated to their own CGroup.
 
-By changing certain values in the conf.d file limits can be enforced per 
+By changing certain values in the `conf.d` file limits can be enforced per 
 service. It is easy to find orphan processes of a service that persist after 
-stop(), but by default these will NOT be terminated.
-To change this add rc_cgroup_cleanup="yes" in the conf.d files for services 
+`stop()`, but by default these will NOT be terminated.
+To change this add `rc_cgroup_cleanup="yes"` in the `conf.d` files for services 
 where you desire this functionality.
 
 # Caching
 
 For performance reasons OpenRC keeps a cache of pre-parsed initscript metadata
-(e.g. depend). The default location for this is /${RC_SVCDIR}/cache.
+(e.g. `depend`). The default location for this is `/${RC_SVCDIR}/cache`.
 
-The cache uses mtime to check for file staleness. Should any service script
+The cache uses `mtime` to check for file staleness. Should any service script
 change it'll re-source the relevant files and update the cache
 
 # Convenience functions