doc: rewrite sample.conf in the block format

This is what 'initctl create' and 'initctl edit -c' put in front of a
user writing their first .conf file, so it is also the whole of the
"initctl emits the new format" work: neither command generates syntax,
they copy this file and open an editor on it.

The ASCII diagram naming eight positional fields goes with it.  A
block has no positions to explain.

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>

src/sample.conf

@@ -1,62 +1,88 @@
-# sample.conf: template cgroup/run/task/service stanza for finit
+# sample.conf: template run/task/service stanza for finit
+#
+# A .conf file is a series of blocks.  Every setting is a key inside
+# one, so nothing has to be memorised by position:
+#
+#   service NAME {
+#       description = "What it is"
+#       runlevel    = "2345"           # default: 234
+#       conditions  = { "net/lo/up" }  # wait for these
+#       envfile     = "-/etc/default/daemon"
+#       command     = "/usr/sbin/daemon ARGS"
+#   }
+#
+# A leading '-' on a path means carry on if it is missing, so the
+# envfile above is optional.  Debian and Buildroot keep those files in
+# /etc/default, Alpine in /etc/conf.d.
+#
+# There are four kinds of stanza:
+#
+# - run     : one-shot, wait for it before continuing with the next
+# - task    : one-shot, started in parallel with the next
+# - service : supervised daemon, run in foreground, restarted if it crashes
+# - sysv    : /etc/init.d style script, start/stop/restart
 #
 # The top-level cgroups can be defined anywhere, but share the same
 # namespace.  It is up to the user to ensure groups are defined only
-# once, otherwise the last read .conf wins.  See below for assigning
-# run/task/services to cgroups.  The below example creates the cgroup
-# NAME with the following cpu and memory settings:
+# once, otherwise the last read .conf wins:
 #
-#   cgroup NAME cpu.weight:1000 mem.max:65
+#   cgroup NAME {
+#       cpu.weight = 1000
+#       memory.max = 65M
+#   }
 #
-# The one-shot commands 'run' and 'task' are called only once per
-# runlevel.  Finit does not restart them when they exit.
+# A service joins one by naming it, and may override settings for
+# itself alone.  Here foo and bar share the group foo, baz has its own:
 #
-# - run     : wait for completion before continuing with next stanza
-# - task    : like run but started in background, parallel with other stanzas
-# - service : supervised daemon, run in foreground, restarted if it crashes
-#
-# The env: is an optional path to a file with environment variables to
-# adjust the behavior of daemons.  Debian and Buildroot use /etc/default
-# while Alpine use /etc/conf.d -- ensure your Finit is built correctly.
-# The leading '-' determines if its OK to start the service even if the
-# env file is missing.
-#
-#     run [LVLS] <COND> log command ARGS -- Command
-#    task [LVLS] <COND> log command ARGS -- Command
-# service [LVLS] <COND> log env:[-]/etc/default/daemon daemon ARGS -- Daemon daemon
-# ^       ^      ^      ^   ^                          ^              ^       ^
-# |       |      |      |   |                          |              |        `-- Optional description
-# |       |      |      |   |                          |              `----------- Daemon arguments
-# |       |      |      |   |                          `-------------------------- Path to daemon
-# |       |      |      |    `---------------------------------------------------- Optional env. file
-# |       |      |       `-------------------------------------------------------- Redirect output to log
-# |       |       `--------------------------------------------------------------- Optional conditions
-# |        `---------------------------------------------------------------------- Optional Runlevels
-#  `------------------------------------------------------------------------------ Monitored application
-#
-# Each stanza can also hold a 'cgroup' argument, or be prefixed with
-# cgroup.NAME to place all following stanzas in the same group.  In
-# the following example, foo and bar share the cgroup foo but baz
-# runs in its own cgroup baz:
-#
-#   cgroup.foo
-#   service cgroup:cpu.weight:250,mem.max:655350 foo args -- foo desc
-#   service cgroup:cpu.weight:150,mem.max:655350 bar args -- bar desc
-#   service cgroup.baz:cpu.weight:300 baz args -- baz desc
+#   service foo { cgroup foo {}                   command = "foo args" }
+#   service bar { cgroup foo { cpu.weight = 150 } command = "bar args" }
+#   service baz { cgroup baz { cpu.weight = 300 } command = "baz args" }
 
 # Debian GNU/Linux: start SSH daemon as soon as basic networking comes up
-#service [2345] <net/lo/up> env:-/etc/default/ssh /usr/sbin/sshd -D $SSHD_OPTS -- OpenSSH daemon
+#service sshd {
+#    description = "OpenSSH daemon"
+#    runlevel    = "2345"
+#    conditions  = { "net/lo/up" }
+#    envfile     = "-/etc/default/ssh"
+#    command     = "/usr/sbin/sshd -D $SSHD_OPTS"
+#}
 
 # Alpine Linux: Oneshot task to run once at bootstrap, yes pipes are possible :)
-#task [S] env:/etc/conf.d/loadkmap zcat $KEYMAP | loadkmap -- Loading keymap
+#run kmap {
+#    description = "Loading keymap"
+#    runlevel    = "S"
+#    envfile     = "/etc/conf.d/loadkmap"
+#    command     = "zcat $KEYMAP | loadkmap"
+#}
 
 # Alpine Linux: start SSH daemon with $DROPBEAR_OPTS from /etc/conf.d
-#service [2345] cgroup.user env:-/etc/conf.d/dropbear dropbear -R -F $DROPBEAR_OPTS -- Dropbear SSH daemon
+#service dropbear {
+#    description = "Dropbear SSH daemon"
+#    runlevel    = "2345"
+#    envfile     = "-/etc/conf.d/dropbear"
+#    cgroup user {}
+#    command     = "dropbear -R -F $DROPBEAR_OPTS"
+#}
 
 # Handle PWR button to shutdown/reboot -- useful in Qemu (virt-manager)
-# Depends on syslogd having started. Redirect any output to log.
-#service [2345] <pid/syslogd> cgroup:mem.max:32000,cpu.max:1000 log acpid -f -- ACPI daemon
+# Depends on syslogd having started.  Redirect any output to the log.
+#service acpid {
+#    description = "ACPI daemon"
+#    runlevel    = "2345"
+#    conditions  = { "pid/syslogd" }
+#    cgroup system {
+#        memory.max = 32M
+#        cpu.max    = 1000
+#    }
+#    log { }
+#    command = "acpid -f"
+#}
 
 # Start rsyslogd as soon as possible, should always run
 # Provides pid/syslogd condition
-#service [S12345] name:syslogd env:-/etc/default/rsyslog rsyslogd -n $RSYSLOGD_OPTIONS -- Reliable syslog daemon
+#service syslogd {
+#    description = "Reliable syslog daemon"
+#    runlevel    = "S12345"
+#    envfile     = "-/etc/default/rsyslog"
+#    command     = "rsyslogd -n $RSYSLOGD_OPTIONS"
+#}