From b034ee2aeb08451a8a34d1efa484ead74ac3c891 Mon Sep 17 00:00:00 2001
From: obarun <eric@obarun.org>
Date: Mon, 20 Apr 2020 13:02:27 +1100
Subject: [PATCH] update doc
---
doc/html/66-enable.html | 8 +++++---
doc/html/66-parser.html | 27 +++++++++++++++++++++------
doc/html/frontend.html | 18 ++++++++++--------
doc/man/66-enable.1.scd | 9 ++++++---
doc/man/66-frontend.5.scd | 36 +++++++++++++++++++++++++++++++++++-
doc/man/66-parser.1.scd | 12 ++++++++----
6 files changed, 85 insertions(+), 25 deletions(-)
diff --git a/doc/html/66-enable.html b/doc/html/66-enable.html
index c61f5036..15f02010 100644
--- a/doc/html/66-enable.html
+++ b/doc/html/66-enable.html
@@ -23,7 +23,7 @@
<h2> Interface </h2>
<pre>
- 66-enable [ -h ] [ -z ] [ -v <em>verbosity</em> ] [ -l <em>live</em> ] [ -t <em>tree</em> ] [ -f|F ] [ -c|C ] [ -S ] <em>service(s)</em>
+ 66-enable [ -h ] [ -z ] [ -v <em>verbosity</em> ] [ -l <em>live</em> ] [ -t <em>tree</em> ] [ -f|F ] [ -c|m|C ] [ -S ] <em>service(s)</em>
</pre>
<p>
@@ -68,12 +68,14 @@
<tt>-F </tt> : same as <tt>-f</tt> but also reenables it dependencies.
</li>
<li>
- <tt>-c </tt> : merge it environment configuration file from <em>frontend</em> file.
+ <tt>-c </tt> : only appends new <tt>key=value</tt> pairs at environment configuration file from <em>frontend</em> file.
+ </li>
+ <li>
+ <tt>-m </tt> : appends new <tt>key=value</tt> and merge existing one at environment configuration file from <em>frontend</em> file.
</li>
<li>
<tt>-C </tt> : overwrite it environment configuration file from <em>frontend</em> file.
</li>
-
<li>
<tt>-S </tt> : starts the <em>service</em> on the fly directly after enabling it. If the state of the <em>service</em> is already up, this option
will have no effect unless the <tt>-f</tt> option is used to reload it.
diff --git a/doc/html/66-parser.html b/doc/html/66-parser.html
index 98d4e046..1304f01b 100644
--- a/doc/html/66-parser.html
+++ b/doc/html/66-parser.html
@@ -24,7 +24,7 @@
<h2>Interface</h2>
<pre>
- 66-parser [ -h ] [ -z ] [ -v <em>verbosity</em> ] [ -f ] [ -c|C ] service destination</em>
+ 66-parser [ -h ] [ -z ] [ -v <em>verbosity</em> ] [ -f ] [ -c|m|C ] service destination</em>
</pre>
<ul>
@@ -54,12 +54,15 @@
<tt>2</tt>: Also print warning messages.
<tt>3</tt>: Also print tracing messages.
<tt>4</tt>: Also print debugging messages.
- </li>
- <li>
- <tt><b>-f</b></tt> : force. Owerwrite an existing parsing result at <em>destination</em>.
+ </li>
+ <li>
+ <tt><b>-f </b></tt> : force. Owerwrite an existing parsing result at <em>destination</em>.
</li>
<li>
- <tt>-c </tt> : merge it environment configuration file from <em>frontend</em> file.
+ <tt>-c </tt> : only appends new <tt>key=value</tt> pairs at environment configuration file from <em>frontend</em> file.
+ </li>
+ <li>
+ <tt>-m </tt> : appends new <tt>key=value</tt> and merge existing one at environment configuration file from <em>frontend</em> file.
</li>
<li>
<tt>-C </tt> : overwrite it environment configuration file from <em>frontend</em> file.
@@ -69,7 +72,19 @@
<h2>Notes</h2>
<p>
- 66-parser will not try to read and parse any services declared under the <em>@depends</em> key of the given frontend file. This tool is mainly intended for debugging purposes and to see the result of a parsing process before actually enabling the service on the system. The tool uses the exact same parser as <a href="66-enable.html">66‑enable</a> which by default writes the configuration file to <tt>%%service_admconf%%/<em>service_name</em></tt>. As a consequence any corresponding existing file will be overwritten. To avoid this, it writes the configuration file at <em>destination/env/</em> directory and adjust the resulting <tt>run/finish</tt> file to match the configuration file path.
+ 66-parser will not try to read and parse any services declared
+ under the <em>@contents</em>, <em>@depends</em>, <em>@optsdepends</em>
+ or <em>@extdepends</em> key of the given frontend file even for
+ a service <em>module</em> type. This tool is mainly intended for
+ debugging purposes and to see the result of a parsing process
+ before actually enabling the service on the system. The tool
+ uses the exact same parser as <a href="66-enable.html">66‑enable</a>
+ which by default writes the configuration file to
+ <tt>%%service_admconf%%/<em>service_name</em></tt>. As a consequence
+ any corresponding existing file will be overwritten. To avoid this,
+ it writes the configuration file at <em>destination/env/</em> directory
+ and adjust the resulting <tt>run/finish</tt> file to match the
+ configuration file path.
</p>
</body>
diff --git a/doc/html/frontend.html b/doc/html/frontend.html
index aaaf194c..94d5fa6d 100644
--- a/doc/html/frontend.html
+++ b/doc/html/frontend.html
@@ -16,7 +16,7 @@
<h1>The frontend service file</h1>
<p>
- The <a href="https://skarnet.org/software/s6">s6</a> and <a href="https://skarnet.org/software/s6">s6-rc</a> programs each handle and use several kinds of services and different files. It is quite complex to understand and manage the relationship between all those files and services. If you're interested in the details you should read <a href="https://skarnet.org/software/s6/servicedir.html">the documentation for the s6 servicedir</a> and also about <a href="https://skarnet.org/software/s6/servicedir.html"><em>classic</em></a>, <a href="https://skarnet.org/software/s6-rc/s6-rc-compile.html"> <em>oneshot</em>, <em>longrun</em> (also called <em>atomic</em> services), <em>bundle</em></a> and <a href="#module"><em>module</em></a> services on Obarun. The frontend service file of 66 tools allows you to deal with all these different services in a centralized manner in one single place.
+ The <a href="https://skarnet.org/software/s6">s6</a> and <a href="https://skarnet.org/software/s6">s6-rc</a> programs each handle and use several kinds of services and different files. It is quite complex to understand and manage the relationship between all those files and services. If you're interested in the details you should read <a href="https://skarnet.org/software/s6/servicedir.html">the documentation for the s6 servicedir</a> and also about <a href="https://skarnet.org/software/s6/servicedir.html"><em>classic</em></a>, <a href="https://skarnet.org/software/s6-rc/s6-rc-compile.html"> <em>oneshot</em>, <em>longrun</em> (also called <em>atomic</em> services), <em>bundle</em></a> and <a href="#module"><em>module</em></a> services. The frontend service file of 66 tools allows you to deal with all these different services in a centralized manner in one single place.
<br>
By default 66 tools expects to find any service files in <tt>%%service_system%%</tt> and <tt>%%service_adm%%</tt> for root user. For regular users, *$HOME/%%service_user%%</tt> will take priority over the previous ones. Although this can be changed at compile time by passing the <tt>--with-system-service=<em>DIR</em></tt>, <tt>--with-sysadmin-service=<em>DIR</em></tt> and <tt>--with-user-service=<em>DIR</em></tt>option to <tt>./configure.</tt>
</p>
@@ -30,14 +30,15 @@
<h3>File name examples</h3>
- <pre>/etc/66/service/dhcpcd</pre>
- <pre>/etc/66/service/very_long_name</pre>
+ <pre>%%service_system%%/dhcpcd</pre>
+ <pre>%%service_system%%/very_long_name</pre>
-<h3>File content examples</h3>
+<h3>File content example</h3>
<pre> [main]
@type = classic
- @description = "ntpd daemon"
+ @description = "ntpd daemon"
+ @version = 0.1.0
@user = ( root )
@options = ( log env )
@@ -1116,7 +1117,8 @@ for it in your <tt>@execute</tt> field.</p>
<pre>
[main]
@type = classic,bundle,longrun,oneshot,module
- @name =
+ @name =
+ @version =
@description = ""
@depends = ()
@optsdepends = ()
@@ -1164,8 +1166,8 @@ for it in your <tt>@execute</tt> field.</p>
[regex]
@configure="arguments to pass to configure script"
- @directories=(key=value)
- @files=(key=value)
+ @directories=(key=value key=value)
+ @files=(key=value key=value)
@infiles=(:filename:key=value ::key=value)
</pre>
</body></html>
diff --git a/doc/man/66-enable.1.scd b/doc/man/66-enable.1.scd
index f1090c1f..d010c865 100644
--- a/doc/man/66-enable.1.scd
+++ b/doc/man/66-enable.1.scd
@@ -6,7 +6,7 @@
# SYNOPSIS
-66-enable [ *-h* ] [ *-z* ] [ *-v* _verbosity_ ] [ *-l* _live_ ] [ *-t* _tree_ ] [ *-f|F* ] [ *-c|C* ] [ *-S* ] _service_...
+66-enable [ *-h* ] [ *-z* ] [ *-v* _verbosity_ ] [ *-l* _live_ ] [ *-t* _tree_ ] [ *-f|F* ] [ *-c|*m*|C* ] [ *-S* ] _service_...
# DESCRIPTION
@@ -60,10 +60,13 @@ Multiple _services_ can be enabled by seperating their names with a space.
Same as *-f* but also reenables it dependencies.
*-c*
- merge it environment configuration file from frontend file.
+ only appends new _key=value_ pairs at environment configuration file from _frontend_ file.
+
+*-m*
+ appends new _key=value_ and merge existing one at environment configuration file from _frontend_ file.
*-C*
- overwrite it environment configuration file from frontend file.
+ overwrite it environment configuration file from _frontend_ file.
*-S*
Starts the _service_ on the fly directly after enabling it. If the state of
diff --git a/doc/man/66-frontend.5.scd b/doc/man/66-frontend.5.scd
index eae3bea7..6f62d2eb 100644
--- a/doc/man/66-frontend.5.scd
+++ b/doc/man/66-frontend.5.scd
@@ -11,7 +11,7 @@ and different files. It is quite complex to understand and manage the
relationship between all those files and services. If you're interested
in the details you should read the documentation for the s6 servicedir
and also about _classic_,_oneshot_,_longrun_ (also called _atomic_ services),
-_bundle_ and _module_(see module below) services on Obarun.
+_bundle_ and _module_(see module below) services.
The frontend service file of 66 tools allows you to deal with all these
different services in a centralized manner in one single place.
@@ -31,6 +31,33 @@ The file is made of _sections_ which can contain one or more _key value_ pairs
where the _key_ name can contain special characters like *-* (_hyphen_) or
*\_* (_low line_) except the character *@* (_commercial at_) which is reserved.
+## File name examples
+
+```
+%%service_system%%/dhcpcd
+%%service_system%%/very_long_name
+```
+
+## File content example
+
+```
+[main]
+@type = classic
+@description = "ntpd daemon"
+@version = 0.1.0
+@user = ( root )
+@options = ( log env )
+
+[start]
+@build = auto
+@execute = ( foreground { mkdir -p -m 0755 ${RUNDIR} }
+execl-cmdline -s { ntpd ${CMD_ARGS} } )
+
+[environment]
+dir_run=!/run/openntpd
+cmd_args=!-d -s
+```
+
The parser will not accept any empty _value_. If a _key_ is set, the _value_
cannot be empty. Comments are allowed using the number sign *#*. Empty lines
are also allowed.
@@ -978,6 +1005,7 @@ This prototype contain all valid *section* with all valid _key_*=*_value_ pair.
[main]
@type = classic,bundle,longrun,oneshot
@name =
+@version =
@description = ""
@depends = ()
@optsdepends = ()
@@ -1022,4 +1050,10 @@ This prototype contain all valid *section* with all valid _key_*=*_value_ pair.
[environment]
MYKEY=!myvalue
ANOTHERKEY=!antohervalue
+
+[regex]
+@configure="arguments to pass to configure script"
+@directories=(key=value key=value)
+@files=(key=value key=value)
+@infiles=(:filename:key=value ::key=value)
```
diff --git a/doc/man/66-parser.1.scd b/doc/man/66-parser.1.scd
index 39755ba4..19c53ce8 100644
--- a/doc/man/66-parser.1.scd
+++ b/doc/man/66-parser.1.scd
@@ -6,7 +6,7 @@
# SYNOPSIS
-66-parser [ *-h* ] [ *-z* ] [ *-v* _verbosity_ ] [ *-f* ] [ *-c* | *-C* ] _service destination_
+66-parser [ *-h* ] [ *-z* ] [ *-v* _verbosity_ ] [ *-f* ] [ *-c* | *-m* | *-C* ] _service destination_
# DESCRIPTION
@@ -35,14 +35,18 @@ An absolute path is expected for _service_ and _destination_.
Force. Owerwrite an existing parsing result at _destination_.
*-c*
- merge it environment configuration file from frontend file.
+ only appends new _key=value_ pairs at environment configuration file from _frontend_ file.
+
+*-m*
+ appends new _key=value_ and merge existing one at environment configuration file from _frontend_ file.
*-C*
- overwrite it environment configuration file from frontend file.
+ overwrite it environment configuration file from _frontend_ file.
# NOTES
-*66-parser* will not try to read and parse any services declared under *@depends*
+*66-parser* will not try to read and parse any services declared under *@contents*,
+*@depends*,*@optsdepends* or *@extdepends* even for a service _module_ type.
key of the given frontend file. This tool is maily intended for debugging
purpose and to see the result of a parsing process before actually enabling
the service on the system. This tool use the exact same parser as *66-enable*
--
GitLab