From: Kevin Day Date: Sun, 8 Jan 2023 17:33:47 +0000 (-0600) Subject: Update: Documentation and build settings, adding remaining man pages for programs. X-Git-Tag: 0.6.3~17 X-Git-Url: https://git.kevux.org/?a=commitdiff_plain;h=0355bb7043ae4ec49ca84e8f76ef3631f38222af;p=fll Update: Documentation and build settings, adding remaining man pages for programs. This includes any updates to the existing program man pages already added. --- diff --git a/build/stand_alone/byte_dump.settings b/build/stand_alone/byte_dump.settings index da5928f..480058a 100644 --- a/build/stand_alone/byte_dump.settings +++ b/build/stand_alone/byte_dump.settings @@ -48,6 +48,8 @@ build_sources_program fll/level_2/program.c fll/level_2/program/common.c fll/lev build_sources_program program/byte_dump/byte_dump.c program/byte_dump/common.c program/byte_dump/private-common.c program/byte_dump/private-byte_dump.c build_sources_program program/byte_dump/main.c +build_sources_documentation man + build_script yes build_shared yes build_static no diff --git a/build/stand_alone/fake.settings b/build/stand_alone/fake.settings index d6d0efd..a31a91e 100644 --- a/build/stand_alone/fake.settings +++ b/build/stand_alone/fake.settings @@ -73,6 +73,8 @@ build_sources_program program/fake/private-fake.c program/fake/private-fake-path build_sources_program program/fake/main.c +build_sources_documentation man + build_script yes build_shared yes build_static no diff --git a/build/stand_alone/firewall.settings b/build/stand_alone/firewall.settings index c1598b2..85a4e47 100644 --- a/build/stand_alone/firewall.settings +++ b/build/stand_alone/firewall.settings @@ -63,7 +63,9 @@ build_sources_program fll/level_2/program.c fll/level_2/program/common.c fll/lev build_sources_program program/firewall/firewall.c program/firewall/common.c program/firewall/private-common.c program/firewall/private-firewall.c build_sources_program program/firewall/main.c -build_sources_setting default-blacklist default-whitelist example-device-firewall firewall-first firewall-last firewall-other +build_sources_documentation man + +build_sources_setting network build_script yes build_shared yes diff --git a/build/stand_alone/utf8.settings b/build/stand_alone/utf8.settings index a3febc1..fe603ac 100644 --- a/build/stand_alone/utf8.settings +++ b/build/stand_alone/utf8.settings @@ -49,6 +49,8 @@ build_sources_program program/utf8/utf8.c program/utf8/common.c program/utf8/pri build_sources_program program/utf8/main.c +build_sources_documentation man + build_script yes build_shared yes build_static no diff --git a/level_3/byte_dump/data/build/settings b/level_3/byte_dump/data/build/settings index eaf4d92..7672eaf 100644 --- a/level_3/byte_dump/data/build/settings +++ b/level_3/byte_dump/data/build/settings @@ -28,6 +28,8 @@ build_sources_program main.c build_sources_headers byte_dump.h common.h +build_sources_documentation man + build_script yes build_shared yes build_static no diff --git a/level_3/byte_dump/data/documentation/man/man1/byte_dump.1 b/level_3/byte_dump/data/documentation/man/man1/byte_dump.1 new file mode 100644 index 0000000..ea3e318 --- /dev/null +++ b/level_3/byte_dump/data/documentation/man/man1/byte_dump.1 @@ -0,0 +1,104 @@ +.TH BYTE_DUMP "1" "January 2023" "FLL - Byte Dump 0.6.3" "User Commands" +.SH NAME +byte_dump \- Print bytes of a given file in a more human-friendly format similar to programs like \fBhexdump\fR. +.SH SYNOPSIS +.B byte_dump +[\fI\,OPTIONS\/\fR] [\fI\,FILENAMES\/\fR] +.SH DESCRIPTION +.PP +When using the \fB\-\-text\fR option, some UTF-8 characters may be replaced by your instance and cause display alignment issues. + +Special UTF-8 characters and non-spacing UTF-8 characters may be replaced with a space (or a placeholder when the \fB\-\-placeholder\fR option is used). + +UTF-8 "Combining" characters might have a space appended to allow a proper display but this may cause copy and paste issues. + +When \fB\-\-last\fR is used, any UTF-8 sequences will still be printed in full should any part is found within the requested range. + +When using the \fB\-\-unicode\fR option, invalid Unicode will fallback to being displayed using one of the other modes. +.SH OPTIONS +.TP +\fB\{+h, ++help\fR +Print the help message. +.TP +\fB+d, ++dark\fR +Output using colors that show up better on dark backgrounds +.TP +\fB+l, ++light\fR +Output using colors that show up better on light backgrounds. +.TP +\fB+n, ++no_color\fR +Do not print using color. +.TP +\fB+Q, ++quiet\fR +Decrease verbosity, silencing most output. +.TP +\fB+E, ++error\fR +Decrease verbosity, using only error output. +.TP +\fB+N, ++normal\fR +Set verbosity to normal. +.TP +\fB+V, ++verbose\fR +Increase verbosity beyond normal output. +.TP +\fB+D, ++debug\fR +Enable debugging, significantly increasing verbosity beyond normal output. +.TP +\fB+v, ++version\fR +Print only the version number. +.TP +\fB\-b, \-\-binary\fR +Display binary representation. +.TP +\fB\-d, \-\-decimal\fR +Display decimal representation. +.TP +\fB\-D, \-\-duodecimal\fR +Display duodecimal representation. +.TP +\fB\-x, \-\-hexidecimal\fR +Display hexadecimal representation. +.TP +\fB\-o, \-\-octal\fR +Display octal representation. +.TP +\fB\-U, \-\-unicode\fR +Display using Unicode representation for valid Unicode (like: U+0000). +.TP +\fB\-f, \-\-first\fR +Start reading at this byte offset. +.TP +\fB\-l, \-\-last\fR +Stop reading at this (inclusive) byte offset. +.TP +\fB\-N, \-\-narrow\fR +Use narrow display, resulting in 1*width reducing size of the text columns. +.TP +\fB\-p, \-\-placeholder\fR +Use a placeholder character instead of a space for placeholders. +.TP +\fB\-t, \-\-text\fR +Include a column of text when displaying the bytes. +.TP +\fB\-W, \-\-wide\fR +Use wide display, resulting in 2*width allowing for space for wide characters in the text columns. +.TP +\fB\-w, \-\-width\fR +Set number of columns of Bytes to display. +.TP +\-\-normal\fR +Display UTF-8 symbols for ASCII control codes. +.TP +\-\-simple\fR +Display spaces for ASCII control codes. +.TP +\-\-classic\fR +Display periods for ASCII control codes. +.SH FILENAMES +.TP +Any number of files to read. +.SH AUTHOR +Written by Kevin Day. +.SH COPYRIGHT +.PP +Copyright \(co 2007-2023 Kevin Day, GNU LGPL Version 2.1 or later. diff --git a/level_3/control/data/build/settings b/level_3/control/data/build/settings index e7c7cef..c6dc568 100644 --- a/level_3/control/data/build/settings +++ b/level_3/control/data/build/settings @@ -28,6 +28,8 @@ build_sources_program main.c build_sources_headers control.h common.h +build_sources_documentation man + build_script yes build_shared yes build_static no diff --git a/level_3/control/data/documentation/man/man1/control.1 b/level_3/control/data/documentation/man/man1/control.1 new file mode 100644 index 0000000..f80d48d --- /dev/null +++ b/level_3/control/data/documentation/man/man1/control.1 @@ -0,0 +1,66 @@ +.TH CONTROL "1" "January 2023" "FLL - Control 0.6.3" "User Commands" +.SH NAME +control \- Give commands or make requests to the \fBcontroller\fR program. +.SH SYNOPSIS +.B control +[\fI\,OPTIONS\/\fR] [\fI\,ACTION\/\fR] +.SH DESCRIPTION +.PP +When the \fB\-\-socket\fR parameter represents a directory path then the file name is generated from either the \fB\-\-name\fR parameter or from the control settings file. + +A rule action allows for either the full rule path, such as '\fBboot/root\fR' as a single parameter or two parameters with the first representing the rule directory path '\fBboot\fR' and the second representing the rule base name '\fBroot\fR'. + +The \fB\-\-return\fR parameter is intended to be used for scripting and is of the form "\fBresponse [type] [action] [status]\fR". +Be sure to use the \fB++quiet\fR parameter to suppress output when using this in scripting. +No response is returned on program errors, especially those errors that prevent communicating to the controller. +.SH OPTIONS +.TP +\fB\{+h, ++help\fR +Print the help message. +.TP +\fB+d, ++dark\fR +Output using colors that show up better on dark backgrounds +.TP +\fB+l, ++light\fR +Output using colors that show up better on light backgrounds. +.TP +\fB+n, ++no_color\fR +Do not print using color. +.TP +\fB+Q, ++quiet\fR +Decrease verbosity, silencing most output. +.TP +\fB+E, ++error\fR +Decrease verbosity, using only error output. +.TP +\fB+N, ++normal\fR +Set verbosity to normal. +.TP +\fB+V, ++verbose\fR +Increase verbosity beyond normal output. +.TP +\fB+D, ++debug\fR +Enable debugging, significantly increasing verbosity beyond normal output. +.TP +\fB+v, ++version\fR +Print only the version number. +.TP +\fB\-n, \-\-name\fR +Specify the name of the controller socket file. +.TP +\fB\-R, \-\-return\fR +Print a message about the response packet. +.TP +\fB\-s, \-\-settings\fR +Specify a directory path or a full path to the control settings file. +.TP +\fB\-k, \-\-socket\fR +Specify a directory path or a full path to the controller socket file. +.SH ACTION +.TP +The action to perform. +.SH AUTHOR +Written by Kevin Day. +.SH COPYRIGHT +.PP +Copyright \(co 2007-2023 Kevin Day, GNU LGPL Version 2.1 or later. diff --git a/level_3/controller/data/build/settings b/level_3/controller/data/build/settings index 42799c6..44233e9 100644 --- a/level_3/controller/data/build/settings +++ b/level_3/controller/data/build/settings @@ -38,6 +38,8 @@ build_sources_program main.c main-common.c build_sources_headers controller.h common.h +build_sources_documentation man + build_sources_setting controller build_script yes diff --git a/level_3/controller/data/documentation/man/man1/controller.1 b/level_3/controller/data/documentation/man/man1/controller.1 new file mode 100644 index 0000000..51a2ad9 --- /dev/null +++ b/level_3/controller/data/documentation/man/man1/controller.1 @@ -0,0 +1,698 @@ +.TH CONTROLLER "1" "January 2023" "FLL - Controller 0.6.3" "User Commands" +.SH NAME +controller \- Perform a series of operations in a manner similar to that of an init program. +.SH SYNOPSIS +.B controller +[\fI\,OPTIONS\/\fR] [\fI\,ENTRY\/\fR] +.SH DESCRIPTION +.PP +This program performs a series of operations described by an \fBentry\fR file. +This includes error handling. + +The \fBentry\fR file consists of several rules defined in individual \fBrule\fR files. +Thee \fBrule\fR file allows for both programs and scripts to be executed. +Any scripting language whose program supports piping commands to it are effectively supported scripting languages. + +Upon completion, this program may optionally process an \fBexit\fR file whose name is identical to the \fBentry\fR used. + +When both the \fB\-\-simulate\fR parameter and the \fB\-\-validate\fR parameter are specified, then additional information on each would be executed rule is printed but no simulation is performed. + +The default interrupt behavior is to operate as if the \fB\-\-interruptible\fR parameter is passed. + +Specify an empty string for the \fB\-\-pid\fR parameter to disable pid file creation for this program. +.SH OPTIONS +.TP +\fB\{+h, ++help\fR +Print the help message. +.TP +\fB+d, ++dark\fR +Output using colors that show up better on dark backgrounds +.TP +\fB+l, ++light\fR +Output using colors that show up better on light backgrounds. +.TP +\fB+n, ++no_color\fR +Do not print using color. +.TP +\fB+Q, ++quiet\fR +Decrease verbosity, silencing most output. +.TP +\fB+E, ++error\fR +Decrease verbosity, using only error output. +.TP +\fB+N, ++normal\fR +Set verbosity to normal. +.TP +\fB+V, ++verbose\fR +Increase verbosity beyond normal output. +.TP +\fB+D, ++debug\fR +Enable debugging, significantly increasing verbosity beyond normal output. +.TP +\fB+v, ++version\fR +Print only the version number. +.TP +\fB\-c, \-\-cgroup\fR +Specify a custom control group file path, such as '/sys/fs/cgroup/'. +.TP +\fB\-d, \-\-daemon\fR +Run in daemon only mode (do not process the entry). +.TP +\fB\-I, \-\-init\fR +The program will run as an init replacement. +.TP +\fB\-i, \-\-interruptible\fR +Designate that this program can be interrupted by a signal. +.TP +\fB\-p, \-\-pid\fR +Specify a custom pid file path, such as 'controller/run/default.pid'. +.TP +\fB\-s, \-\-settings\fR +Specify a custom settings path, such as 'controller/'. +.TP +\fB\-S, \-\-simulate\fR +Run as a simulation. +.TP +\fB\-k, \-\-socket\fR +Specify a custom socket file path, such as 'controller/run/default.socket'. +.TP +\fB\-U, \-\-uninterruptible\fR +Designate that this program cannot be interrupted by a signal. +.TP +\fB\-v, \-\-validate\fR +Validate the settings (entry and rules) without running (does not simulate). +.SH ENTRY +.TP +The name of an \fBentry\fR. +.SH ACTIONS SPECIFICATION +.PP +This describes the intent and purpose of the actions provided for individual Rules (or things related to a Rule). + +Each Action represents a specific intent and purpose but many of these actions are customizable via the rule file. +One should expect an Action to operate as described here but the system administrator or distributor is fully capable of doing something different. +For those doing something different, appropriate documentation is suggested. + +These actions should be usable by any \fBcontrol\fR program that communicates with this \fBcontroller\fR program. +Should any \fBcontrol\fR or \fBcontroller\fR program implementation not support any particular Action for any reason, one should report that the Action is unsupported. + +Freeze Action: + The Freeze Action is an extension of a Control Group. + This is internal to the \fBcontroller\fR program and is not customizable via any Rule file. + For a customizable \fBfreeze\fR-like capability, look into the Pause and Resume Actions. + This is the complement of the Thaw Action. + + This designates that a processes Control Group is to be frozen. + All Rules (or any process not controlled by the \fBcontroller\fR) that is within the same Control Group will be frozen. + + This must not attempt to freeze (or unfreeze) the Control Group that the \fBcontroller\fR belongs to. + Therefore, if a Rule does not specify a Control Group, then it is likely that the Freeze Action will be unsupported for that Rule/Control Group. + +Kill Action: + Forcefully terminate some process controlled by the \fBcontroller\fR. + This action cannot be blocked and it is recommended to use a Stop Action instead for a more proper termination. + +Pause Action: + The Pause Action will pause (or freeze) the process controlled by the Rule. + Although similar to the Freeze Action, this is intended to communicate to an individual process and inform to Pause. + This is complemented by the Resume Action. + +Restart Action: + The Restart Action will either perform a Stop Action and then a Restart Action or it will perform the Restart Action designated in some Rule file. + Ideally this should inform some process to perform its own restart routines. + +Resume Action: + The Resume Action will unpause (or unfreeze) the process controlled by the Rule. + Although similar to the Thaw Action, this is intended to communicate to an individual process and inform to Resume. + This is complemented by the Pause Action. + +Reload Action: + The Reload Action will perform the Reload Action designated in some Rule file. + Ideally this should inform some process to perform its own reload routines. + Many programs often differentiate the concept \fBreload\fR from the concept "restart" in that the program remains running during a \fBreload\fR. + +Start Action: + The Start Action will perform the Start Action designated in some Rule file. + This action should be used to start some program or script. + This is the action called by Entry file. + This is complemented by the Stop Action. + +Stop Action: + The Stop Action will perform the Stop Action designated in some Rule file. + This action should be used to stop some program or script. + This is the action called for all running controlled processes on shutdown. + This is complemented by the Start Action. + +Thaw Action: + The Thaw Action is an extension of a Control Group. + This is internal to the \fBcontroller\fR program and is not customizable via any Rule file. + For a customizable \fBthaw\fR-like capability, look into the \fBpause\fR and \fBresume\fR Actions. + This is complemented by the Freeze Action. + + This designates that a processes Control Group is to be unfrozen. + All Rules (or any process not controlled by the \fBcontroller\fR) that is within the same Control Group will be unfrozen. + + This must not attempt to thaw (or unthaw) the Control Group that the \fBcontroller\fR belongs to. + Therefore, if a Rule does not specify a Control Group, then it is likely that the Thaw Action will be unsupported for that Rule/Control Group. +.SH ENTRY SPECIFICATION +.PP +This describes the intent and purpose of an Entry file. + +An Entry file, such as \fBdefault.entry\fR, is intended to store a set of rules in which the controller will process on execution. +These are used to run some set of commands, such as booting a system. + +The \fBmain\fR Item Object is always executed first (Therefore \fBmain\fR is both reserved and required). +All other Basic List Objects are not executed unless either an \fBitem\fR or a \fBfailsafe\fR specifies a valid Item name. +Execution of all Items is top-down. + +The \fBsettings\fR item Object: + Represents Entry settings and is not an \fBitem\fR that can be executed. + A number of settings are supported, but if this Item Object is not specified, then defaults are used. + The following settings are available: \fBcontrol\fR, \fBcontrol_group\fR, \fBcontrol_mode\fR, \fBcontrol_user\fR, \fBdefine\fR, \fBmode\fR, \fBparameter\fR, \fBpid\fR, \fBpid_file\fR, \fBsession\fR, \fBshow\fR. + + The \fBcontrol\fR setting: + Represents the path to the socket file in which the Controller uses to communicate over with clients such as a Control program. + A relative path is relative to the Controller PID directory. + An absolute path is treated exactly as the path given. + If no socket setting is specified, then no socket will be made available. + This socket file is only created once \fBready\fR mode is achieved. + + Providing \fBreadonly\fR after the socket path instructs the Controller program not to create or delete the Socket file because the file system is assumed to be readonly. + The socket file itself must therefore already exist. + This should be possible in the cases of file systems that have pre-created a socket file at the designated path. + When \fBreadonly\fR, the group, mode, and user are also not processed effectively resulting in the \fBcontrol_group\fR, \fBcontrol_mode\fR, and \fBcontrol_user\fR settings being ignored. + + Future versions might expand this into supporting network addresses in addition to socket files. + + The \fBcontrol_group\fR setting: + Represents the group name or group ID to assign to the socket file as the group. + + The \fBcontrol_mode\fR setting: + Represents the file mode assigned to the socket file. + This could either be the string version that might look like \fBu+rw-x,g+r-wx,o-rwx\fR or a numeric value like \fB0750\fR. + + The \fBcontrol_user\fR setting: + Represents the user name or user ID to assign to the socket file as the owner. + + The \fBdefine\fR setting: + Use this to define an environment variable (this overwrites any existing environment variable with this name). + A define is both exported as an environment variable as well as exposed as an IKI variable. + Example IKI variable substitution: for \fBdefine PATH /bin:/sbin\fR, the associated IKI variable would look like: PATH. + + All environment variables, including those defined using this, must be in the \fBenvironment\fR list in any given Rule to be exported to the executed process. + Environment variables added here that are not added to the environment are still exposed as an IKI variable. + + This is only expanded within any Rule operated on by this Entry. + + The \fBmode\fR setting: + Represents the mode in which the Entry is operating in. + The following modes are supported: \fBprogram\fR and \fBservice\fR. + + The \fBprogram\fR mode: + Designates that the Entry operates as a program and exits when complete. + Will call the \fBexit\fR with the same name as this Entry, but with the extension \fBexit\fR, such as \fBdefault.exit\fR. + Supports the Item Action \fBexecute\fR to execute a program (switching the \fBcontroller\fR program entirely with the executed process). + + The \fBservice\fR mode: + Designates that the Entry operates as a service and will sit and wait for control commands when complete. + Will call the \fBexit\fR with the same name as this Entry, but with the extension \fBexit\fR, such as \fBdefault.exit\fR. + Does not support the Item Action \fBexecute\fR. + This is the default mode. + + The \fBparameter\fR setting: + Use this to define an IKI variable name and value. + These do not conflict with environment variables and are not exposed as environment variables. + Example IKI variable substitution: for \fBparameter hello world\fR, the associated IKI variable would look like: hello. + + This is only expanded within any Rule operated on by this Entry. + + The \fBpid\fR setting: + Represents how the Entry PID file is generated or not. + The following modes are supported: \fBdisable\fR, \fBrequire\fR, and \fBready\fR. + For \fBdisable\fR, not PID file representing the Entry is created. + For \fBrequire\fR, check to see if the PID file exists for an Entry at startup and then when \fBready\fR create a PID file, display error on PID file already exists or on failure and then fail. + For \fBready\fR, when \fBready\fR create a PID file, display error on failure and then fail (does not check if PID file exists). + + The \fBpid_file\fR setting: + When \fBpid\fR is not disabled this represents the path to the PID file. + If \fB-p\fR or \fB--pid\fR is passed to the controller program, then this value is ignored in favor of the value passed along the command line. + + The \fBsession\fR setting: + Represents the default way in which child processes are executed. + This default can be overridden by individual Rules. + For \fBnew\fR, Execute Rule processes in a new session setting the process group to the executed process' id (making the executed process a \fBcontrolling terminal\fR). + For \fBsame\fR, Execute Rule processes in the same session where the process group is set to the parent process id. + + The \fBshow\fR setting: + Represents the way Entry processing presents information to the screen. + This applies only to the Entry and Rule processing itself and does not handle the output of programs and scripts being executed by some Entry or Rule. + The following show options are supported: \fBnormal\fR and \fBinit\fR. + For \fBnormal\fR, will not report the start or stop of some Entry or Rule execution but will report any errors or warnings as appropriate. + For \fBinit\fR, will report when starting programs and may include reporting success and failure status. + + The \fBtimeout\fR setting: + Represents the default timeouts for the Entry. + See the \fBtimeout\fR Action below for details. + +The \fBmain\fR item Object: + Each \fBitem\fR supports the following Action Names: \fBconsider\fR, \fBexecute\fR, \fBfailsafe\fR, \fBfreeze\fR, \fBitem\fR, \fBkill\fR, \fBpause\fR, \fBreload\fR, \fBrestart\fR, \fBready\fR, \fBresume\fR, \fBstart\fR, \fBstop\fR, and \fBtimeout\fR. + Of those types, the following are considered a \fBrule\fR Action: \fBfreeze\fR, \fBkill\fR, \fBpause\fR, \fBreload\fR, \fBrestart\fR, \fBresume\fR, \fBstart\fR, \fBstop\fR, and \fBthaw\fR. + + The \fBconsider\fR Item Action: + A special case of a \fBrule\fR Action. + All Action Parameters are the same as with the \fBrule\fR Action Parameters. + The difference is that \fBconsider\fR is only processed (instead of being processed and executed) and when some \fBrule\fR Action designates that this consideration is required (via \fBneed\fR), wanted (via \fBwant\fR), or wished for (via \fBwish\fR) from the within the Rule file. + If this is determined to be executed, then this is immediately executed when needed, wanted or wished for and applies all properties as appropriate (such as \fBasynchronous\fR, for example). + If this is determined not to be executed, then this \fBconsider\fR is ignored as if it was never there in the first place. + + The \fBexecute\fR Item Action: + Execute into the specified program. + On successful execution, the controller program will no longer be running and will be replaced with the designated program. + This Item Action is only supported when operating in \fBprogram\fR mode. + + The \fBfailsafe\fR Item Action: + Accepts only a valid Item Name in which will be executed when a failure is detected. + Only a single \fBfailsafe\fR Item Action may function at a time. + Each successive \fBfailsafe\fR Item Action specified replaces the previously defined \fBfailsafe\fR Item Action (in a top-down manner). + When operating in \fBfailsafe\fR, the \fBrequire\fR Item Action is ignored (given that it is meaningless once operating in \fBfailsafe\fR mode). + + The \fBfreeze\fR Item Action: + A \fBrule\fR Action for freezing some Control Group. + This Item Action will process the \fBfreeze\fR inner Content of the named Rule. + This is specific to Control Groups and is not yet fully implemented. + Once implemented this documentation will need to be updated and clarified. + + The \fBitem\fR Item Action: + Accepts only a valid Item Name in which will be immediately executed. + Any valid Item Name, except for the reserved \fBmain\fR, may be used. + + The \fBkill\fR Item Action: + A \fBrule\fR Action for forcibly terminating some process. + This Item Action will process the \fBkill\fR inner Content of the named Rule. + + The \fBpause\fR Item Action: + A \fBrule\fR Action for pausing some process. + This Item Action will process the \fBpause\fR inner Content of the named Rule. + + The \fBreload\fR Item Action: + A \fBrule\fR Action for pausing some process. + This Item Action will process the \fBreload\fR inner Content of the named Rule. + + The \fBrestart\fR Item Action: + A \fBrule\fR Action for pausing some process. + This Item Action will process the \fBrestart\fR inner Content of the named Rule. + + The \fBresume\fR Item Action: + A \fBrule\fR Action for pausing some process. + This Item Action will process the \fBresume\fR inner Content of the named Rule. + + The \fBready\fR Item Action: + Instructs the controller program when it is safe to perform normal tasks, such as creating the PID file. + When not specified, the state is always assumed to be ready. + For example, the controller program may be used as a full blown \fBinit\fR replacement and therefore may need to mount the /var/run/ directory. + If the PID file is created at program start, then the /var/run/controller.pid would be written before the /var/run/ directory is ready. + This could be a problem, such as on a read-only file system the PID creation fails and controller bails out on error. + Adding \fBready\fR essentially specifies a point in time in the Entry in which things are expected to be safe for such basic operations. + When the optional \fBwait\fR is provided, then \fBready\fR will wait for all currently started asynchronous processes to complete before operating. + + The \fBstart\fR Item Action: + A \fBrule\fR Action for pausing some process. + This Item Action will process the \fBstart\fR inner Content of the named Rule. + + The \fBstop\fR Item Action: + A \fBrule\fR Action for pausing some process. + This Item Action will process the \fBstop\fR inner Content of the named Rule. + + The \fBthaw\fR Item Action: + A \fBrule\fR Action for unfreezing some Control Group. + This Item Action will process the \fBthaw\fR inner Content of the named Rule. + This is specific to Control Groups and is not yet fully implemented. + Once implemented this documentation will need to be updated and clarified. + + The \fBtimeout\fR Item Action: + (This is not currently fully implemented, only \fBexit\fR is implemented.) + Provides default global settings for each of the four special situations: \fBexit\fR, \fBkill\fR, \fBstart\fR, and \fBstop\fR. + Each of these may only have a single one exist at a time (one \fBexit\fR, one \fBkill\fR, one \fBstart\fR, and one \fBstop\fR). + Each successive \fBtimeout\fR Item Action, specific to each Action Name (such as \fBstart\fR), specified replaces the previously defined \fBtimeout\fR Action (in a top-down manner). + The second Content for each of these, when specified, may be a 0 or greater whole number representing the number of MegaTime (MT) (equivalent to milliseconds). + For \fBkill\fR, this represents the number of MegaTime to wait after stopping some Rule and that Rule has not yet stopped to forcefully stop the Rule (aka kill the Rule). + For \fBstart\fR, this represents the number of MegaTime to wait after starting some Rule before assuming something went wrong and the Rule is returned as failed. + For \fBstop\fR, this represents the number of MegaTime to wait after stopping some Rule before assuming something went wrong and the Rule is returned as failed. + If the second Content is not specified, then this disables the type (prevents the specified timeout action). + For \fBexit\fR, this represents the number of MegaTime to wait when the Controller program is exiting (such as having received a terminate signal). + In this case, a terminate signal is sent to all child processes. + The \fBexit\fR timeout represents the amount of time to wait after sending the terminate signal before sending a kill signal to each child process still running. + When disabled, the program will not send a kill signal will continue running until all child processes to terminate. + The \fBexit\fR timeout does not get applied to any Rule. +.SH EXIT SPECIFICATION +.PP +This describes the intent and purpose of an Exit file. + +An Exit file, such as \fBdefault.exit\fR, is intended to store a set of rules in which the controller will process on execution. +These are used to run some set of commands, such as shutting down a system. + +An Exit is a special variation or subset of an Entry. + +The \fBsettings\fR Item Object: + Represents Exit settings and is not an \fBitem\fR that can be executed. + A number of settings are supported, but if this Item Object is not specified, then defaults are used. + The following settings are available: \fBpid\fR and \fBshow\fR. + + The \fBdefine\fR setting: + Use this to define an environment variable (this overwrites any existing environment variable with this name). + A define is both exported as an environment variable as well as exposed as an IKI variable. + Example IKI variable substitution: for \fBdefine PATH /bin:/sbin\fR, the associated IKI variable would look like: PATH. + + All environment variables, including those defined using this, must be in the \fBenvironment\fR list in any given Rule to be exported to the executed process. + Environment variables added here that are not added to the environment are still exposed as an IKI variable. + + This is only expanded within any Rule operated on by this Exit. + + The \fBparameter\fR setting: + Use this to define an IKI variable name and value. + These do not conflict with environment variables and are not exposed as environment variables. + Example IKI variable substitution: for \fBparameter hello world\fR, the associated IKI variable would look like: hello. + + This is only expanded within any Rule operated on by this Exit. + + The \fBpid\fR setting: + Represents how the Exit PID file is generated or not. + The following modes are supported: \fBdisable\fR, \fBrequire\fR, and \fBready\fR. + For \fBdisable\fR, not PID file representing the Exit is created. + For \fBrequire\fR, check to see if the PID file exists for an Exit at startup and then when \fBready\fR create a PID file, display error on PID file already exists or on failure and then fail. + For \fBready\fR, when \fBready\fR create a PID file, display error on failure and then fail (does not check if PID file exists). + + The \fBshow\fR setting: + Represents the way Exit processing presents information to the screen. + This applies only to the Exit and Rule processing itself and does not handle the output of programs and scripts being executed by some Exit or Rule. + The following show options are supported: \fBnormal\fR and \fBinit\fR. + For \fBnormal\fR, will not report the start or stop of some Exit or Rule execution but will report any errors or warnings as appropriate. + For \fBinit\fR, will report when starting programs and may include reporting success and failure status. + + The \fBtimeout\fR setting: + Represents the default timeouts for the Exit. + See the \fBtimeout\fR Action below for details. + +The \fBmain\fR Item Object: + Is always executed first (Therefore \fBmain\fR is both reserved and required). + All other Basic List Objects are not executed unless either an \fBitem\fR or a \fBfailsafe\fR specifies a valid Item name. + Execution of all Items are top-down. + + Each \fBitem\fR supports the following Action Names: \fBconsider\fR, \fBexecute\fR, \fBfailsafe\fR, \fBfreeze\fR, \fBitem\fR, \fBkill\fR, \fBpause\fR, \fBreload\fR, \fBrestart\fR, \fBready\fR, \fBresume\fR, \fBstart\fR, \fBstop\fR, and \fBtimeout\fR. + Of those types, the following are considered a \fBrule\fR Action: \fBfreeze\fR, \fBkill\fR, \fBpause\fR, \fBreload\fR, \fBrestart\fR, \fBresume\fR, \fBstart\fR, \fBstop\fR, and \fBthaw\fR. + + The \fBconsider\fR Item Action: + A special case of a \fBrule\fR Action. + All Action Parameters are the same as with the \fBrule\fR Action Parameters. + The difference is that \fBconsider\fR is only processed (instead of being processed and executed) and when some \fBrule\fR Action designates that this consideration is required (via \fBneed\fR), wanted (via \fBwant\fR), or wished for (via \fBwish\fR) from the within the Rule file. + If this is determined to be executed, then this is immediately executed when needed, wanted or wished for and applies all properties as appropriate (such as \fBasynchronous\fR, for example). + If this is determined not to be executed, then this \fBconsider\fR is ignored as if it was never there in the first place. + + The \fBexecute\fR Item Action: + Execute into the specified program. + On successful execution, the controller program will no longer be running and will be replaced with the designated program. + This Item Action is only supported when operating in \fBprogram\fR mode. + + The \fBfailsafe\fR Item Action: + Accepts only a valid Item Name in which will be executed when a failure is detected. + Only a single \fBfailsafe\fR Item Action may function at a time. + Each successive \fBfailsafe\fR Item Action specified replaces the previously defined \fBfailsafe\fR Item Action (in a top-down manner). + When operating in \fBfailsafe\fR, the \fBrequire\fR Item Action is ignored (given that it is meaningless once operating in \fBfailsafe\fR mode). + + The \fBfreeze\fR Item Action: + A \fBrule\fR Action for freezing some Control Group. + This Item Action will process the \fBfreeze\fR inner Content of the named Rule. + This is specific to Control Groups and is not yet fully implemented. + Once implemented this documentation will need to be updated and clarified. + + The \fBitem\fR Item Action: + Accepts only a valid Item Name in which will be immediately executed. + Any valid Item Name, except for the reserved \fBmain\fR, may be used. + + The \fBkill\fR Item Action: + A \fBrule\fR Action for forcibly terminating some process. + This Item Action will process the \fBkill\fR inner Content of the named Rule. + + The \fBpause\fR Item Action: + A \fBrule\fR Action for pausing some process. + This Item Action will process the \fBpause\fR inner Content of the named Rule. + + The \fBreload\fR Item Action: + A \fBrule\fR Action for pausing some process. + This Item Action will process the \fBreload\fR inner Content of the named Rule. + + The \fBrestart\fR Item Action: + A \fBrule\fR Action for pausing some process. + This Item Action will process the \fBrestart\fR inner Content of the named Rule. + + The \fBresume\fR Item Action: + A \fBrule\fR Action for pausing some process. + This Item Action will process the \fBresume\fR inner Content of the named Rule. + + The \fBready\fR Action: + Instructs the controller program when it is safe to perform normal tasks, such as creating the PID file. + When not specified, the state is always assumed to be ready. + For example, the controller program may be used as a full blown \fBinit\fR replacement and therefore may need to mount the /var/run/ directory. + If the PID file is created at program start, then the /var/run/controller.pid would be written before the /var/run/ directory is ready. + This could be a problem, such as on a read-only file system the PID creation fails and controller bails out on error. + Adding \fBready\fR essentially specifies a point in time in the Exit in which things are expected to be safe for such basic operations. + When the optional \fBwait\fR is provided, then \fBready\fR will wait for all currently started asynchronous processes to complete before operating. + + The \fBstart\fR Item Action: + A \fBrule\fR Action for pausing some process. + This Item Action will process the \fBstart\fR inner Content of the named Rule. + + The \fBstop\fR Item Action: + A \fBrule\fR Action for pausing some process. + This Item Action will process the \fBstop\fR inner Content of the named Rule. + + The \fBthaw\fR Item Action: + A \fBrule\fR Action for unfreezing some Control Group. + This Item Action will process the \fBthaw\fR inner Content of the named Rule. + This is specific to Control Groups and is not yet fully implemented. + Once implemented this documentation will need to be updated and clarified. + + The \fBtimeout\fR Item Action: + (This is not currently fully implemented, only \fBexit\fR is implemented.) + Provides default global settings for each of the four special situations: \fBexit\fR, \fBkill\fR, \fBstart\fR, and \fBstop\fR. + Each of these may only have a single one exist at a time (one \fBexit\fR, one \fBkill\fR, one \fBstart\fR, and one \fBstop\fR). + Each successive \fBtimeout\fR Item Action, specific to each Action Name (such as \fBstart\fR), specified replaces the previously defined \fBtimeout\fR Action (in a top-down manner). + The second Content for each of these, when specified, may be a 0 or greater whole number representing the number of MegaTime (MT) (equivalent to milliseconds). + For \fBkill\fR, this represents the number of MegaTime to wait after stopping some Rule and that Rule has not yet stopped to forcefully stop the Rule (aka kill the Rule). + For \fBstart\fR, this represents the number of MegaTime to wait after starting some Rule before assuming something went wrong and the Rule is returned as failed. + For \fBstop\fR, this represents the number of MegaTime to wait after stopping some Rule before assuming something went wrong and the Rule is returned as failed. + If the second Content is not specified, then this disables the type (prevents the specified timeout action). + + For \fBexit\fR, this represents the number of MegaTime to wait when the Controller program is exiting (such as having received a terminate signal). + In this case, a terminate signal is sent to all child processes. + The \fBexit\fR timeout represents the amount of time to wait after sending the terminate signal before sending a kill signal to each child process still running. + When disabled, the program will not send a kill signal will continue running until all child processes to terminate. + The \fBexit\fR timeout does not get applied to any Rule. +.SH PACKET SPECIFICATION +.PP +Describes how a packet is designed and intended to be used. + +The \fBpacket\fR is the general category in which multiple types of packets belong. +This describes the different packets based on their \fBtype\fR. + +Each packet begins with a control block and a size block followed by a payload block. + + The control block: + The leading bit (starting from the left) designates the the format of the payload, which is 0 for string and 1 for binary. + The second bit (starting from the left) designates the the byte order for the rest of the packet, which 0 is for little endian and 1 is for big endian. + The remaining 6-bits are reserved for future use. + + The size block: + The size block represents the size of the entire packet (the control block, the size blocks, and the payload block). + This number is a single 32-bit unsigned integer. + + Example packet structure: + [ Control Block ] [ Size Block ] [ Payload Block ] + [ 0b10000000 ] [ 0b00000000 0b00000000 0b00000100 0b11010010 ] [ size: 1229 (1234 \- 5) ] + + The payload block: + This block is represented by the \fBFSS-000E (Payload)\fR specification and its structure ad use is described in the next sections. + + The following types of payload are received or sent: + 1) controller payload. + 2) error payload. + 3) init payload. + +The controller payload: + Commands being sent to the controller and their respective responses utilize a \fBcontroller\fR payload. + These are pre-defined commands to rules or the controller program itself. + Commands such as starting or stopping some rule, for example. + A controller payload is also sent in response to a controller payload request to represent a success. + + The \fBnow\fR condition designates that the kexec, reboot, or shutdown is to begin immediately. + The \fBat\fR condition designates that the kexec, reboot, or shutdown is to begin once a specific date and time is reached by the system clock. + The \fBin\fR condition designates that the kexec, reboot, or shutdown is to begin once a specific amount of time is passed by the system clock since the execution of this command started. + + For these \fBtime\fR conditions, different units of time should be supported, such as \fBseconds\fR, \fBdays\fR, \fByears\fR as standard time, Time, or UNIX Time (Epoch Time). + + The normal \fBcontroller\fR payload commands are any valid Rule Action that performs some action. + This does not include Actions that provide some setting or configuration (such as \fBwith_pid\fR). + Some of the supported commands are: \fBfreeze\fR, \fBkill\fR, \fBpause\fR, \fBreload\fR, \fBrerun\fR, \fBrestart\fR, \fBresume\fR, \fBstart\fR, \fBstop\fR, or \fBthaw\fR. + Multiple commands may be sent multiple \fBaction\fR headers. + The \fBaction\fR headers are order sensitive, executing from top to bottom, and one does not start until the previous successfully completes. + + Multiple \fBstatus\fR headers may exist in the response so long as they each match an \fBaction\fR in the request. + + The \fBpayload\fR is expected to be empty and have a length of 0 for a request. + The \fBpayload\fR may have an \fBFSS-0000 (Basic)\fR format containing a single Object \fBmessage\fR to represent a message associated with an action. + Multiple \fBmessage\fR may exist in the response so long as they each match an \fBaction\fR in the request. + +The error payload: + The error payload is intended to communicate some sort of failure. + The error payload is only sent in response to some request (and not in response to another response). + The control (the client) is not expected to send error payloads and the controller (the service) should send an error in response to an error payload or ignore it entirely. + The \fBstatus\fR from the \fBheader\fR designates the status code as either a status code name string or a status code number (where a number may have error and warning bits). + The \fBpayload\fR will contain a NULL terminated string representing the message used to describe the error. + +The init payload: + The init payload is intended exclusively for the \fBinit\fR operation mode and is expected to only be available when running as \fBinit\fR. + This is used to provide special actions, namely \fBkexec\fR, \fBreboot\fR, and \fBshutdown\fR. + + The \fBkexec\fR is for booting into another kernel, which may effectively be the same as a \fBreboot\fR ("kexec" is currently neither supported nor implemented). + The \fBreboot\fR is for rebooting the machine (currently not implemented). + The \fBshutdown\fR is for shutting down the machine (currently not implemented). + These three commands are configurable to fire off based on conditions. +.SH RULE SPECIFICATION +.PP +This describes the intent and purpose of a Rule file. + +A Rule file, such as \fBssh.rule\fR, is intended to designate what to execute. + +The rule file is read top-down, except for the outer most list \fBsettings\fR, which is intended to store setting data for this rule. +Multiple outer most list Objects may be specified and they are executed as provided, in a top-down manner. + +The \fBsettings\fR Rule Type has the following \fBFSS-0001 (Extended)\fR Content: + \fBaffinity\fR: Define one or more processors to restrict this rule by with each number representing a specific processor by its id (starting at 0). + \fBcapability\fR: Define a set of capabilities in which to use, using the capability \fBtext\fR format (such as \fB= cap_chown+ep\fR). + \fBcgroup\fR: Define a cgroup (control group) in which everything within this rule executes under. + \fBdefine\fR: A single environment variable name and its associated value that is automatically exposed to processes executed within this rule. + \fBengine\fR: An executable name of a script, such as \fBbash\fR, to use for the \fBscript\fR Rule Type (which likely defaults to \fBbash\fR if not specified). + \fBenvironment\fR: A set of environment variables to expose to the processes executed within this rule (PATH is always exposed). + \fBgroup\fR: A set of group names or IDs to execute as with the first group being the primary group and all remaining being supplementary groups. + \fBlimit\fR: Define a resource limit to use (multiple limits may be specified, but only once for each type). + \fBname\fR: A name used to represent this rule, which is printed to the user, screen, logs, etc... + \fBnice\fR: A single niceness value to run all processes executed within this rule as (-20 gets to be greediest in CPU usage and 19 being the nicest in CPU usage). + \fBon\fR: Define a Rule Action in which a specified dependency is needed, wanted, or wished for. + \fBparameter\fR: An IKI name and its associated value for use in this rule file. + \fBpath\fR: A single Content used to set a custom PATH environment variable value. + \fBscheduler\fR: A valid name of a scheduler to use followed by an optional priority number. + \fBtimeout\fR: A set of timeouts to wait for in which to perform a set action or to consider failure. + \fBuser\fR: A single user name or ID to execute as. + +The \fBcapability\fR setting: + If the user the controller program is run as does not have the desired capabilities already, they cannot be added. + This essentially maintains or reduces the capabilities already available. + Due to capabilities only being a draft in the POSIX standard, one may expect \fBcapabilities\fR support may not be available and in such a case this setting will do nothing. + If the dependent project (f_capability) does not have libcap support enabled, then capabilities will be unsupported by the compilation of this project. + +The \fBcontrol\fR setting: + The first argument is either \fBexisting\fR or \fBnew\fR, where for \fBexisting\fR the process is run inside the existing control used by the parent and when \fBnew\fR the process is executed within a new control group namespace entirely. + +The \fBdefine\fR setting: + Use this to define an environment variable (this overwrites any existing environment variable with this name). + A define is both exported as an environment variable as well as exposed as an IKI variable. + Example IKI variable substitution: for \fBdefine PATH /bin:/sbin\fR, the associated IKI variable would look like: PATH. + + All environment variables, including those defined using this, must be in the \fBenvironment\fR list to be exported to the executed process. + Environment variables added here that are not added to the environment are still exposed as an IKI variable. + +The \fBengine\fR setting: + This engine is used for both \fBscript\fR and \fButility\fR Rule Types. + The program that engine refers to must accept a standard input pipe to be supported. + Additional parameters may be passed to the engine. + +The \fBgroup\fR and \fBuser\fR settings: + Only users and groups that the user the controller program is being run as is allowed to use may be used. + +The \fBlimit\fR setting: + The first parameter must be one of: \fBas\fR, \fBcore\fR, \fBcpu\fR, \fBdata\fR, \fBfsize\fR, \fBlocks\fR, \fBmemlock\fR, \fBmsgqueue\fR, \fBnice\fR, \fBnofile\fR, \fBnproc\fR, \fBrss\fR, \fBrtprio\fR, \fBrttime\fR, \fBsigpending\fR, or \fBstack\fR. + The second parameter represents the soft limit. + The third parameter represents the hard limit. + This may be specified multiply times, but only once for each type. + +The \fBon\fR setting: + The first parameter represents the Action the dependency exists under and must be one of: \fBfreeze\fR, \fBkill\fR, \fBpause\fR, \fBreload\fR, \fBrestart\fR, \fBresume\fR, \fBstart\fR, \fBstop\fR, or \fBthaw\fR. + The second parameter represents how the dependency is required and must be one of: \fBneed\fR, \fBwant\fR, or \fBwish\fR. + The third parameter is a partial path to the rule file. + The fourth parameter represents the name of the rule file. + + In the case of the second parameter: + A \fBneed\fR designates that the dependent rule is required to be executed (must exist and must succeed). + A \fBwant\fR designates that the dependent rule is to be executed (may exist and if it does, then it must succeed). + A \fBwish\fR designates that the dependent rule is to be executed (may exist and if it does, but it does not need to succeed). + + In the case of \fBwant\fR and \fBwish\fR, if the desired rule is either not found or is otherwise disabled, then this will not fail or otherwise block the wanting or wishing rule. + +The \fBpath\fR setting: + When specified, the \fBPATH\fR environment variable is automatically added to the \fBenvironment\fR setting. + +The \fBparameter\fR setting: + Use this to define an IKI variable name and value. + These do not conflict with environment variables and are not exposed as environment variables. + Example IKI variable substitution: for \fBparameter hello world\fR, the associated IKI variable would look like: hello. + +The \fBscheduler\fR setting: + The valid range of the priority number is dependent on the scheduler. + For example, non-real-time schedulers (such as \fBidle\fR) only support a value of 0 whereas real-time schedulers (such as \fBfifo\fR) only support an inclusive range of 1 to 99. + Supported non-real-time schedulers are: \fBbatch\fR, \fBidle\fR, and \fBother\fR (aka: normal/default). + Supported real-time schedulers are: \fBdeadline\fR, \fBfifo\fR, \fBround_robin\fR. + +The \fBtimeout\fR setting: + (This is not currently implemented.) + Provides settings for each of the three special situations: \fBkill\fR, \fBstart\fR, and \fBstop\fR. + Each of these may only have a single one exist at a time (one \fBkill\fR, one \fBstart\fR, and one \fBstop\fR). + Each successive \fBtimeout\fR Item Action, specific to each Action Name (such as \fBstart\fR), specified replaces the previously defined \fBtimeout\fR Action (in a top-down manner). + The second Content for each of these, when specified, may be a 0 or greater whole number representing the number of MegaTime (MT) (equivalent to milliseconds). + For \fBkill\fR, this represents the number of MegaTime to wait after stopping some Rule and that Rule has not yet stopped to forcefully stop the Rule (aka kill the Rule). + For \fBstart\fR, this represents the number of MegaTime to wait after starting some Rule before assuming something went wrong and the Rule is returned as failed. + For \fBstop\fR, this represents the number of MegaTime to wait after stopping some Rule before assuming something went wrong and the Rule is returned as failed. + If the second Content is not specified, then this disables the type (prevents the specified timeout action). + +There are four available Rule Types to choose from: \fBcommand\fR, \fBservice\fR, \fBscript\fR, and \fButility\fR. + +The \fBcommand\fR Rule Type provides a simple command to run under the different circumstances: \fBstart\fR, \fBstop\fR, \fBrestart\fR, and \fBreload\fR. +A \fBcommand\fR always operates in the foreground. + +The \fBservice\fR Rule Type provides a \fBcommand\fR accompanied with a PID file (Process Identifier file). + +The \fBscript\fR Rule Type provides a series of lines to be executed by some engine, such as GNU Bash. +This \fBscript\fR operates in the foreground, but individual things done within the script may operate in foreground or background. +The last return state is treated as an error, so be sure to finish the script with a return code of 0 to designate no error and any other whole number, such a 1, to designate an error. +Therefore passing \fBexit 1\fR would return as an error and passing \fBexit 0\fR would return as a success. +A \fBscript\fR is assumed to be in GNU Bash, which is the default expected behavior, but the specification does not explicitly require this. +Another scripting language can be used but changing this incurs the responsibility to ensure all rules are updated to the appropriate scripting language. + +The \fButility\fR Rule Type provides a \fBscript\fR accompanied with a PID file (Process Identifier file). + +There are nine Rule Actions used to execute ("freeze", \fBkill\fR, \fBpause\fR, \fBreload\fR, \fBrestart\fR, \fBresume\fR, \fBstart\fR, \fBstop\fR, and \fBthaw\fR): + When \fBrestart\fR Object's Content is not provided, then \fBstart\fR and \fBstop\fR is called when the rule is executed using the restart Action, if both \fBstart\fR and \fBstop\fR are provided. + When \fBreload\fR, \fBstart\fR, or \fBstop\fR Object's Content are not provided, then no respective Action is performed. + + Commands are conditionally available depending on the presence of these, such as if \fBstop\fR is not provided then \fBstop\fR (and \fBrestart\fR) will not be available for the \fBcontrol\fR program(s) to use. + +Thee are additional Rule Actions not used to execute ("pid_file", \fBrerun\fR, and \fBwith\fR): + The \fBpid_file\fR Object's Content designates the path to the PID file created by the called program. + + The \fBrerun\fR Object's Content designates how to re-run a given execution Rule type. + The first Content represents the execution type, which may be one of: \fBfreeze\fR, \fBkill\fR, \fBpause\fR, \fBreload\fR, \fBrestart\fR, \fBresume\fR, \fBstart\fR, \fBstop\fR, and \fBthaw\fR. + + The second Content represents when to run this re-run is triggered, which is either \fBsuccess\fR (return code of 0) or \fBfailure\fR (return code is not 0). + + The third Content and more represent additional options for fine tuning how the re-run is Performed: + When \fBdelay\fR, followed by a number of MegaTime (MT) (equivalent to milliseconds) in which to wait before attempting the re-run. + When \fBmax\fR, followed by a positive number or the number 0 designating the maximum number of re-runs to perform. + When \fBreset\fR, the \fBmax\fR re-run counter is reset for the opposite re-run when this re-run is triggered, such as: + A \fBrerun start success reset\fR and a \fBrerun failure max 10\fR, the failure counter would reset to 0 when the \fBsuccess\fR re-run is performed and not when the \fBfailure\fR re-run is performed. + + A \fBmax\fR of 0 designates that the re-run will happen infinitely. + + The \fBwith\fR Object's Content designates special flags designating very specific behavior to be applied to any single Rule Type. +.SH AUTHOR +Written by Kevin Day. +.SH COPYRIGHT +.PP +Copyright \(co 2007-2023 Kevin Day, GNU LGPL Version 2.1 or later. diff --git a/level_3/fake/data/build/settings b/level_3/fake/data/build/settings index db58853..f75f822 100644 --- a/level_3/fake/data/build/settings +++ b/level_3/fake/data/build/settings @@ -38,6 +38,8 @@ build_sources_program main.c build_sources_headers fake.h common.h +build_sources_documentation man + build_script yes build_shared yes build_static no diff --git a/level_3/fake/data/documentation/man/man1/fake.1 b/level_3/fake/data/documentation/man/man1/fake.1 new file mode 100644 index 0000000..bb1b6d4 --- /dev/null +++ b/level_3/fake/data/documentation/man/man1/fake.1 @@ -0,0 +1,805 @@ +.TH FAKE "1" "January 2023" "FLL - Featureless Make 0.6.3" "User Commands" +.SH NAME +fake \- Build or compile software similar to GNU Make. +.SH SYNOPSIS +.B fake +[\fI\,OPTIONS\/\fR] [\fI\,OPERATIONS\/\fR] +.SH DESCRIPTION +.PP +The Featureless Make program, called \fBfake\fR, is a replacement to the GNU Make program. +A goal of this program is to provide a simpler and more human-friendly syntax than that of GNU Make. +Programs like \fBautoconf\fR and \fBautomake\fR should not be needed. + +This program has a \fBfakefile\fR rather than having a \fBMakefile\fR. +In addition, there is a \fBsettings\fR file that utilizes hard-coded functionality to simplify common compilation processes such as with programming languages like C and C++. +The use of a \fBsettings\fR file can greatly simplify or even obviate the need for a \fBfakefile\fR in some limited cases. + +The default operation, called the \fBmake\fB operation, operates against this \fBfakefile\fR. +The \fBbuild\fR operation utilises the \fBsettings\fR file. + +When performing the build operation, the \fB\-\-mode\fR parameter specifies a name (limited to alpha-numeric, underscore, and dash) to be used in addition to the global. +For example, when a mode of '\fBfll_monolithic\fR' is specified, build libraries from both '\fBbuild_libraries\fR' and '\fBbuild_libraries\-fll_monolithic\fR' are used (but not '\fBbuild_libraries\-fll_level\fR'). + +When specifying the fakefile or the settings parameters, the project root is seached first and then the build data director is searched when the given file does not contain a directory separator. +For example, with '\fB\-\-fakefile my_fakefile\fR' the fakefile at '\fB./my_fakefile\fR' is used if found, but if it is not found then '\fB./data/build/my_fakefile\fR' is used if found. +For example, with '\fB\-\-fakefile ./my_fakefile\fR' the fakefile at '\fB./my_fakefile\fR' is used if found, but if it is not found then no other paths are attempted. + +When piping data to this program, the piped data is treated as if it were prepended to the fakefile or the settings, depending on the operation. + +A section name from the fakefile that does not conflict with an operation name may be specified when performing the make operation. +.SH OPTIONS +.TP +\fB\{+h, ++help\fR +Print the help message. +.TP +\fB+d, ++dark\fR +Output using colors that show up better on dark backgrounds +.TP +\fB+l, ++light\fR +Output using colors that show up better on light backgrounds. +.TP +\fB+n, ++no_color\fR +Do not print using color. +.TP +\fB+Q, ++quiet\fR +Decrease verbosity, silencing most output. +.TP +\fB+E, ++error\fR +Decrease verbosity, using only error output. +.TP +\fB+N, ++normal\fR +Set verbosity to normal. +.TP +\fB+V, ++verbose\fR +Increase verbosity beyond normal output. +.TP +\fB+D, ++debug\fR +Enable debugging, significantly increasing verbosity beyond normal output. +.TP +\fB+v, ++version\fR +Print only the version number. +.TP +\fB\-d, \-\-define\fR +Append an additional define after defines from settings file. +.TP +\fB\-f, \-\-fakefile\fR +Use this fakefile. +.TP +\fB\-m, \-\-mode\fR +Use this mode when processing the build settings. +.TP +\fB\-p, \-\-process\fR +Process name for storing build states. +.TP +\fB\-s, \-\-settings\fR +Use this settings file. +.TP +\fB\-b, \-\-build\fR +Specify a custom build directory. +.TP +\fB\-D, \-\-data\fR +Specify a custom path to the data files. +.TP +\fB\-S, \-\-sources\fR +Specify a custom path to the source files. +.TP +\fB\-w, \-\-work\fR +Use includes/libraries/programs from this directory instead of system. +.TP +\fB\-\-disable-doc\fR +Forcibly do not build documents files. +.TP +\fB\-\-enable-doc\fR +Forcibly do build documents files. +.TP +\fB\-\-disable-shared\fR +Forcibly do not build shared files. +.TP +\fB\-\-enable-shared\fR +Forcibly do build shared files. +.TP +\fB\-\-disable-static\fR +Forcibly do not build static files. +.TP +\fB\-\-enable-static\fR +Forcibly do build static files. +.SH OPERATIONS +.TP +\fBbuild\fR +Build or compile the code based on build settings file. +.TP +\fBclean\fR +Delete all build files. +.TP +\fBmake\fR +Build or compile the code based on fakefile (default). +.TP +\fBskeleton\fR +Build a skeleton directory structure. +.SH FAKEFILE SPECIFICATION +.PP +The fakefile file follows the \fBFSS-0005 (Somewhat Basic List)\fR format with a sub-format of \fBIKI-0002 (Simple Script)\fR. + +A fakefile is broken up into multiple Basic Lists, referred to as Sections, with two special purpose reserved Sections. +The Sections are broken up into multiple Extended Objects and their respective Contents, referred to as Section Operations. + +Each of these non-reserved Sections acts as a set to perform some set of Section Operations. +Each of these Section Operations perform a single command or action based on a set of reserved Section Operation types. +Each of these Section Operations have a set of Arguments associated with them. + +How these Arguments are interpreted and processed are specific to each Operation type. +The Section Operations are represented by the Extended Object name and the Extended Content represents the Operation Arguments. +Each of these Section Operations support IKI variable substitution within their respective Arguments. +The Operation Extended Object does not support IKI variable substitution. +The reserved Settings Section does not support IKI variable substitution. + +The \fBIKI-0002 (Simple Script)\fR vocabulary context is further clarified as follows: + \fBcontext\fR: The value is case-sensitive variable name. + \fBdefine\fR: The value must be a case-sensitive valid environment variable name (alpha-numeric or underscore, but no leading digits). + \fBparameter\fR: The value is a case-sensitive variable name. + Many parameters also support \fB:option\fR and \fB:value\fR appended at the end of the value. + +The reserved Section Objects are: + \fBsettings\fR: contains a list of Settings Objects and Content in \fBFSS-0001 (Extended)\fR format. + \fBmain:\fR contains a list of Operation Objects and Content in \fBFSS-0001 (Extended)\fR format. + +The Settings Objects are: + \fBcompiler\fR: Only one Content, which must only be a valid filename. + \fBdefine\fR: First Content represents variable name (case-sensitive), remaining Content represents the value. + \fBenvironment\fR: Zero or more Content representing valid environment variable names (alpha-numeric with underscore, but cannot begin with a number). + \fBfail\fR: Only one Content, which must be either \fBexit\fR, \fBwarn\fR or \fBignore\fR (quotes not required) (case-sensitive). + \fBimport\fR: Only one Content, which must only be a valid filename. + \fBindexer\fR: Only one Content, which must only be a valid filename. + \fBindexer_arguments: Zero or more arguments supported by the indexer specified in code:\fRbuild_indexer". + \fBload_build\fR: Only one Content, which must be either \fByes\fR or \fBno\fR (quotes not required) (case-sensitive). + \fBparameter\fR: First Content represents variable name (case-sensitive), remaining Content represents the value. + +The build settings may also be specified in the Settings Section. + +The Section Operation Objects are: + \fBand\fR: One or more Content. First Content is the condition or \fBno_dereference\fR (when \fBno_dereference\fR, then the second Content is the condition, etc..), remaining Content are specific to the condition. + \fBbreak\fR: Zero or one Content. If specified, First Content must be one of \fBsuccess\fR or \fBfailure\fR. + \fBbuild\fR: Zero or more Content. First Content represents file name of the settings file to use, second Content and on represent custom modes to use. + \fBclean\fR: Zero Content. + \fBclone\fR: Two or more Content representing paths to files. + \fBcompile\fR: One or more Content as parameters to compiler. + \fBcopy\fR: Two or more Content representing paths to files. + \fBdefine\fR: First Content represents variable name (case-sensitive), remaining Content represents the value. + \fBdelete\fR: One or more Content representing paths to files. + \fBdeletes\fR: One or more Content representing paths to files. + \fBelse\fR: Zero Content. + \fBexit\fR: Zero or one Content. If specified, first Content must be one of \fBsucceed\fR or \fBfail\fR. + \fBfail\fR: One Content. First Content must be one of \fBexit\fR, \fBwarn\fR, or \fBignore\fR (case-sensitive). + \fBgroup\fR: Two or more Content. First Content is group name, number, or \fBno_dereference\fR (when \fBno_dereference\fR, then the second Content is the group name or number, etc..), remaining Content are paths to files. + \fBgroups\fR: Two or more Content. First Content is group name, number, or \fBno_dereference\fR (when \fBno_dereference\fR, then the second Content is the group name or number, etc..), remaining Content are paths to files. + \fBif\fR: One or more Content. First Content is the condition or is \fBno_dereference\fR (when \fBno_dereference\fR, then the second Content is the condition, etc..), remaining Content are specific to the condition. + \fBindex\fR: One or more Content. + \fBlink\fR: Two to Four Content. The first and second Content may be either \fBforce\fR or \fBstrict\fR, the second to last Content is the link target file, and the last Content is the pointer file (the link). + \fBmode\fR: Two or more Content. First Content is the mode, remaining Content are paths to files. + \fBmodes\fR: Two or more Content. First Content is the mode, remaining Content are paths to files. + \fBmove\fR: Two or more Content representing paths to files. + \fBoperate\fR: One Content. First Content is the name of a valid Section Object, except for the reserved Section Objects. + \fBor\fR: One or more Content. First Content is the condition or \fBno_dereference\fR (when \fBno_dereference\fR, then the second Content is the condition, etc..), remaining Content are specific to the condition. + \fBowner\fR: Two or more Content. First Content is owner name, number, or \fBno_dereference\fR (when \fBno_dereference\fR, then the second Content is the owner name or number, etc..), remaining Content are paths to files. + \fBowners\fR: Two or more Content. First Content is owner name, number, or \fBno_dereference\fR (when \fBno_dereference\fR, then the second Content is the owner name or number, etc..), remaining Content are paths to files. + \fBparameter\fR: First Content represents variable name (case-sensitive), remaining Content represents the value. + \fBpop\fR: Zero Content. + \fBprint\fR: Zero or more Content. + \fBrun\fR: One or more Content. First Content is the name of the program (or script) and all remaining Content are passed as arguments to the named program (or script). + \fBshell\fR: One or more Content. First Content is the file path of the program (or script) and all remaining Content are passed as arguments to the named program (or script). + \fBskeleton\fR: Zero Content. + \fBto\fR: One Content. First Content is the directory path. + \fBtop\fR: Zero Content. + \fBtouch\fR: Two or more Content. First Content is one of \fBfile\fR or \fBdirectory\fR, remaining Content are paths to files. + \fBwrite\fR: One or more Content. First Content the file to write to, remaining Content represent the string to write. + + The \fBif\fR Section Operation conditions are: + \fB==\fR: Two or more Content. + \fB>\fR: Two or more Content. + \fB<\fR: Two or more Content. + \fB>=\fR: Two or more Content. + \fB<=\fR: Two or more Content. + \fB<>\fR: Two or more Content. + \fBdefine\fR: One or more Content are valid environment variable name. + \fBexist\fR: One or more Content representing the files to check the existence of. + \fBfailure\fR: has no other Content. + \fBgroup\fR: First Content is the name of a group. Second or more Content are paths to files. + \fBis\fR: First Content is a list of \fBblock\fR, \fBcharacter\fR, \fBno_dereference\fR, \fBdirectory\fR, \fBfifo\fR, \fBlink\fR, \fBregular\fR , or \fBsocket\fR followed by "for" and then the remaining Content that are paths to files. + \fBmode\fR: First Content is either \fBhas\fR, \fBis\fR, or \fBno_dereference\fR. Second Content is a valid file mode. Third or more Content are paths to files. + \fBno_dereference\fR: A non-condition inserted before any of \fBexist\fR, \fBis\fR, and \fBmode\fR (then the second Content is the actual condition followed by any Content associated with that condition). + \fBnot\fR: First Content is one of \fBdefine\fR, \fBexist\fR, \fBgroup\fR, \fBis\fR, \fBmode\fR, \fBno_dereference\fR, \fBowner\fR, or \fBparameter\fR and all remaining Content are based on the first Content's \fBif\fR Section Operation Content rules. + \fBowner\fR: First Content is the name of an owner. Second or more Content are paths to files. + \fBparameter\fR: One or more Content are valid IKI names. + \fBsuccess\fR: has no other Content. + +The \fBif\fR Section Operation conditions and numbers: + The numbers may be represented in any of the forms: + \fBdecimal\fR: all numbers without a base-type prefix are of base-type 10, referred to as decimal. + \fBbinary\fR: all numbers with the prefix \fB0b\fR (uppercase or lowercase \fBb\fR) are of base-type 2, referred to as binary. + \fBoctal\fR: all numbers with the prefix \fB0o\fR (that is zero followed by the letter \fBo\fR, uppercase or lowercase \fBo\fR) are of base-type 8, referred to as octal. + \fBduodecimal\fR: all numbers with the prefix \fB0d\fR (uppercase or lowercase \fBd\fR) are of base-type 12, referred to as duodecimal. + \fBhexadecimal\fR: all numbers with the prefix \fB0x\fR (uppercase or lowercase \fBx\fR) are of base-type 16, referred to as hexadecimal. + + (At this time) The numbers may be of a max value of 2^64, or 18446744073709551615, positive or negative. + (At this time) The numbers may only be whole numbers. + Note: There are plans to impose no limits on the number size or any decimal values, but this requires significant work is not to be implemented at this time. + Once this restriction is lifted, it should be conditional upon an implementation for what the maximum supported numbers or digits may be. + + Only the following \fBif\fR Section Operation conditions use these operators: + \fB>\fR + \fB<\fR + \fB>=\fR + \fB<=\fR + +The \fBif\fR Section Operation condition \fBparameter\fR: + The following reserved words are available for parameter names: \fBbuild\fR, \fBcolor\fR, \fBcurrent\fR, \fBdata\fR, \fBdefine\fR, \fBfakefile\fR, \fBmode\fR, \fBprocess\fR, \fBreturn\fR, \fBsettings\fR, \fBsources\fR, \fBtop\fR, \fBverbosity\fR, and \fBwork\fR. + Each of the reserved words supports having \fB:option\fR and \fB:value\fR appended, such as: \fBwork:value\fR. +Fakefile Specification: +.SH SETTINGS SPECIFICATION +.PP +This describes intent and purposes of the build settings file settings. +The settings file is designed for very simple compilations that represent a single named program and/or a single named library. +For specific details on the allowed formatting, see the settings.txt under the specifications folder. + +\fBbuild_compiler\fR: + This represents the name of the compiler program to use, such as \fBgcc\fR. + + This defaults to \fBgcc\fR (the GNU C Compiler). + + The programs \fBgcc\fR and \fBclang\fR are known to work. + Many of the parameters in the settings file can be changed if not using GCC, but there may be certain hard-coded functionality that may need to be changed. + +\fBbuild_indexer\fR: + This represents the name of the indexer program to use, such as \fBar\fR. + An indexer is often called a linker. + + This defaults to \fBar\fR (the GNU \fBar\fR program). + Similar to \fBbuild_compiler\fR, any linker that supports the \fBar\fR program parameters is effectively supported. + +\fBbuild_indexer_arguments\fR: + This represents arguments needed to build an archive file from object files, such as \fBrcs\fR. + These arguments are placed immediately before the object files passed to the \fBindexer\fR program. + +\fBbuild_language\fR: + The programming language to build with. + The languages \fBc\fR and \fBc++\fR are supported (with \fBbash\fR as a consideration for support). + The \fBbash\fR language is not currently implemented and needs some consideration because there is nothing to compile. + The \fBbash\fR language will likely build a set of individual scripts, and perhaps script dependencies, into a single Bash script. + +\fBbuild_libraries\fR: + A collection of libraries to be linked against. + This should include the compiler specific parameter parts, such as the \fB-l\fR prefix in \fB-lc\fR. + The order of these may matter if the compiler (such as GCC or a linker via GCC) is order sensitive. + +\fBbuild_libraries_shared\fR: + A collection of libraries to be linked against. + This should include the compiler specific parameter parts, such as the \fB-l\fR prefix in \fB-lc\fR. + The order of these may matter if the compiler (such as GCC or a linker via GCC) is order sensitive. + These are applied to only shared builds. + +\fBbuild_libraries_static\fR: + A collection of libraries to be linked against. + This should include the compiler specific parameter parts, such as the \fB-l\fR prefix in \fB-lc\fR. + The order of these may matter if the compiler (such as GCC or a linker via GCC) is order sensitive. + These are applied to only static builds. + +\fBbuild_objects_library\fR: + A collection of object files to be compile with when building libraries. + These are intended to represent already compiled object files. + These paths are relative to the \fBpath_object_script\fR, \fBpath_object_shared\fR, or \fBpath_object_static\fR. + The order of these may matter if the compiler (such as GCC or a linker via GCC) is order sensitive. + +\fBbuild_objects_library_shared\fR: + A collection of object files to be compile with when building shared libraries. + These are intended to represent already compiled object files. + These paths are relative to the \fBpath_object_shared\fR. + The order of these may matter if the compiler (such as GCC or a linker via GCC) is order sensitive. + These are applied to only shared builds. + +\fBbuild_objects_library_static\fR: + A collection of object files to be compile with when building static libraries. + These are intended to represent already compiled object files. + These paths are relative to the \fBpath_object_static\fR. + The order of these may matter if the compiler (such as GCC or a linker via GCC) is order sensitive. + These are applied to only static builds. + +\fBbuild_objects_program\fR: + A collection of object files to be compile with when building programs. + These are intended to represent already compiled object files. + These paths are relative to the \fBpath_object_script\fR, \fBpath_object_shared\fR, or \fBpath_object_static\fR. + The order of these may matter if the compiler (such as GCC or a linker via GCC) is order sensitive. + +\fBbuild_objects_program_shared\fR: + A collection of object files to be compile with when building shared programs. + These are intended to represent already compiled object files. + These paths are relative to the \fBpath_object_shared\fR. + The order of these may matter if the compiler (such as GCC or a linker via GCC) is order sensitive. + These are applied to only shared builds. + +\fBbuild_objects_program_static\fR: + A collection of object files to be compile with when building static programs. + These are intended to represent already compiled object files. + These paths are relative to the \fBpath_object_static\fR. + The order of these may matter if the compiler (such as GCC or a linker via GCC) is order sensitive. + These are applied to only static builds. + +\fBbuild_name\fR: + The name of the build, which often represent the project name. + If program sources are specified, then this will be used as the program name. + If library sources are specified, then this will be used in the library name, such as \fBlibX.so\fR where \fBX\fR would be the \fBbuild_name\fR value. + +\fBbuild_script\fR: + When \fByes\fR, the build process will build any scripts, such as a Bash script. + + This is neither implemented nor supported by Featureless Make 0.6.x and earlier. + +\fBbuild_shared\fR: + When \fByes\fR, the build process will compile any source code for any supported language that supports shared library linking. + +\fBbuild_sources_documentation\fR: + A collection of documentation files. + These are documentation files used by the project and are simply copied over to the build directory. + Unless a pre-process script (or in theory post-process script) is configured to alter these, they are not modified. + +\fBbuild_sources_headers\fR: + A collection of header files. + May include a relative sub-path to each individual header (such as: \fBlevel_0/a.h level_0/b.h level_1/c.h\fR). + The order of these may matter if the compiler (such as GCC or a linker via GCC) is order sensitive. + +\fBbuild_sources_headers_shared\fR: + A collection of header files. + May include a relative sub-path to each individual header (such as: \fBlevel_0/a.h level_0/b.h level_1/c.h\fR). + The order of these may matter if the compiler (such as GCC or a linker via GCC) is order sensitive. + Be careful not to have any conflicting names between this and build_sources_headers_static in case of when static and shared builds are both enabled. + These are applied to only shared builds. + +\fBbuild_sources_headers_static\fR: + A collection of header files. + May include a relative sub-path to each individual header (such as: \fBlevel_0/a.h level_0/b.h level_1/c.h\fR). + The order of these may matter if the compiler (such as GCC or a linker via GCC) is order sensitive. + These files are used when compiling the library. + Be careful not to have any conflicting names between this and build_sources_headers_shared in case of when static and shared builds are both enabled. + These are applied to only static builds. + +\fBbuild_sources_library\fR: + A collection of library related source files. + May include a relative sub-path to each individual source file (such as: \fBlevel_0/a.c level_0/b.c level_1/c.c\fR). + The order of these may matter if the compiler (such as GCC or a linker via GCC) is order sensitive. + +\fBbuild_sources_library_shared\fR: + A collection of library related source files. + May include a relative sub-path to each individual source file (such as: \fBlevel_0/a.c level_0/b.c level_1/c.c\fR). + The order of these may matter if the compiler (such as GCC or a linker via GCC) is order sensitive. + These are applied to only shared builds. + +\fBbuild_sources_library_static\fR: + A collection of library related source files. + May include a relative sub-path to each individual source file (such as: \fBlevel_0/a.c level_0/b.c level_1/c.c\fR). + The order of these may matter if the compiler (such as GCC or a linker via GCC) is order sensitive. + These are applied to only static builds. + +\fBbuild_sources_object\fR: + A single source file used for generating an object file. + The source file is located within the path designated by \fBpath_sources_object\fR. + The built object does not get linked and therefore no linker arguments apply. + The built object file is named using the \fBbuild_name\fR with the \fB.o\fR extension. + May include a relative sub-path to each individual source file (such as: \fBlevel_0/a.c\fR). + +\fBbuild_sources_object_shared\fR: + A single source file used for generating an object file. + The source file is located within the path designated by \fBpath_sources_object\fR. + The built object does not get linked and therefore no linker arguments apply. + The built object file is named using the \fBbuild_name\fR with the \fB.o\fR extension. + May include a relative sub-path to each individual source file (such as: \fBlevel_0/a.c\fR). + These are applied to only shared builds. + +\fBbuild_sources_object_static\fR: + A single source file used for generating an object file. + The source file is located within the path designated by \fBpath_sources_object\fR. + The built object does not get linked and therefore no linker arguments apply. + The built object file is named using the \fBbuild_name\fR with the \fB.o\fR extension. + May include a relative sub-path to each individual source file (such as: \fBlevel_0/a.c\fR). + These are applied to only static builds. + +\fBbuild_sources_program\fR: + A collection of program related source files. + May include a relative sub-path to each individual source file (such as: \fBlevel_0/a.c level_0/b.c level_1/c.c\fR). + The order of these may matter if the compiler (such as GCC or a linker via GCC) is order sensitive. + These files are used when compiling the program. + +\fBbuild_sources_program_shared\fR: + A collection of program related source files. + May include a relative sub-path to each individual source file (such as: \fBlevel_0/a.c level_0/b.c level_1/c.c\fR). + The order of these may matter if the compiler (such as GCC or a linker via GCC) is order sensitive. + These files are used when compiling the program for shared builds. + +\fBbuild_sources_program_static\fR: + A collection of program related source files. + May include a relative sub-path to each individual source file (such as: \fBlevel_0/a.c level_0/b.c level_1/c.c\fR). + The order of these may matter if the compiler (such as GCC or a linker via GCC) is order sensitive. + These files are used when compiling the program for static builds. + +\fBbuild_sources_script\fR: + A collection of script files. + These are script files used by the project and are simply copied over to the build directory. + Unless a pre-process script (or in theory post-process script) is configured to alter these, they are not modified. + Unlike the \fBcompile_language\fR setting \fBbash\fR, this is not for built Bash script, but is instead for any valid scripting language (including Bash). + These could be in any language. + +\fBbuild_sources_setting\fR: + A collection of settings files. + These are settings files used by the project and are simply copied over to the build directory. + Unless a pre-process script (or in theory post-process script) is configured to alter these, they are not modified. + +\fBbuild_static\fR: + When \fByes\fR, the build process will compile any source code for any supported language that supports static library linking. + +\fBdefines\fR: + A collection of macro names. + This includes the any compiler specific parameters required by the \fBbuild_compiler\fR, such as the \fB-D\fR used by \fBgcc\fR and \fBclang\fR. + These will be appended to the compiler for compiled languages such as \fBC\fR and \fBC++\fR. + These are applied to both shared and static builds. + +\fBdefines_library\fR: + A collection of macro names. + This includes the any compiler specific parameters required by the \fBbuild_compiler\fR, such as the \fB-D\fR used by \fBgcc\fR and \fBclang\fR. + These will be appended to the compiler for compiled languages such as \fBC\fR and \fBC++\fR. + These are applied to only library builds. + +\fBdefines_library_shared\fR: + A collection of macro names. + This includes the any compiler specific parameters required by the \fBbuild_compiler\fR, such as the \fB-D\fR used by \fBgcc\fR and \fBclang\fR. + These will be appended to the compiler for compiled languages such as \fBC\fR and \fBC++\fR. + These are applied to only shared library builds. + +\fBdefines_library_static\fR: + A collection of macro names. + This includes the any compiler specific parameters required by the \fBbuild_compiler\fR, such as the \fB-D\fR used by \fBgcc\fR and \fBclang\fR. + These will be appended to the compiler for compiled languages such as \fBC\fR and \fBC++\fR. + These are applied to only static library builds. + +\fBdefines_object\fR: + A collection of macro names. + This includes the any compiler specific parameters required by the \fBbuild_compiler\fR, such as the \fB-D\fR used by \fBgcc\fR and \fBclang\fR. + These will be appended to the compiler for compiled languages such as \fBC\fR and \fBC++\fR. + These are applied to only object builds. + +\fBdefines_object_shared\fR: + A collection of macro names. + This includes the any compiler specific parameters required by the \fBbuild_compiler\fR, such as the \fB-D\fR used by \fBgcc\fR and \fBclang\fR. + These will be appended to the compiler for compiled languages such as \fBC\fR and \fBC++\fR. + These are applied to only shared object builds. + +\fBdefines_object_static\fR: + A collection of macro names. + This includes the any compiler specific parameters required by the \fBbuild_compiler\fR, such as the \fB-D\fR used by \fBgcc\fR and \fBclang\fR. + These will be appended to the compiler for compiled languages such as \fBC\fR and \fBC++\fR. + These are applied to only static object builds. + +\fBdefines_program\fR: + A collection of macro names. + This includes the any compiler specific parameters required by the \fBbuild_compiler\fR, such as the \fB-D\fR used by \fBgcc\fR and \fBclang\fR. + These will be appended to the compiler for compiled languages such as \fBC\fR and \fBC++\fR. + These are applied to only program builds. + +\fBdefines_program_shared\fR: + A collection of macro names. + This includes the any compiler specific parameters required by the \fBbuild_compiler\fR, such as the \fB-D\fR used by \fBgcc\fR and \fBclang\fR. + These will be appended to the compiler for compiled languages such as \fBC\fR and \fBC++\fR. + These are applied to only shared program builds. + +\fBdefines_program_static\fR: + A collection of macro names. + This includes the any compiler specific parameters required by the \fBbuild_compiler\fR, such as the \fB-D\fR used by \fBgcc\fR and \fBclang\fR. + These will be appended to the compiler for compiled languages such as \fBC\fR and \fBC++\fR. + These are applied to only shared program builds. + +\fBdefines_shared\fR: + A collection of macro names. + This includes the any compiler specific parameters required by the \fBbuild_compiler\fR, such as the \fB-D\fR used by \fBgcc\fR and \fBclang\fR. + These will be appended to the compiler for compiled languages such as \fBC\fR and \fBC++\fR. + These are applied to only shared builds. + +\fBdefines_static\fR: + A collection of macro names. + This includes the any compiler specific parameters required by the \fBbuild_compiler\fR, such as the \fB-D\fR used by \fBgcc\fR and \fBclang\fR. + These will be appended to the compiler for compiled languages such as \fBC\fR and \fBC++\fR. + These are applied to only static builds. + +\fBenvironment\fR: + A collection of environment names to pass from the callers environment into the executed programs environment. + When provided, all environment variables are removed when calling user-space programs, such as \fBgcc\fR. + To remove all environment variables define this with no Content. + When not provided, all environment variables are loaded. + +\fBflags\fR: + A collection of any flag supported by the \fBbuild_compiler\fR, such as \fBgcc\fR. + This includes the any compiler specific parameters to defined this, such as the \fB-f\fR used by \fBgcc\fR and \fBclang\fR. + These are applied to both shared and static builds. + +\fBflags_library\fR: + A collection of any flag supported by the \fBbuild_compiler\fR, such as \fBgcc\fR. + This includes the any compiler specific parameters to defined this, such as the \fB-f\fR used by \fBgcc\fR and \fBclang\fR. + These are applied when building a library. + +\fBflags_library_shared\fR: + A collection of any flag supported by the \fBbuild_compiler\fR, such as \fBgcc\fR. + This includes the any compiler specific parameters to defined this, such as the \fB-f\fR used by \fBgcc\fR and \fBclang\fR. + These are applied to only library shared builds. + +\fBflags_library_static\fR: + A collection of any flag supported by the \fBbuild_compiler\fR, such as \fBgcc\fR. + This includes the any compiler specific parameters to defined this, such as the \fB-f\fR used by \fBgcc\fR and \fBclang\fR. + These are applied to only library static builds. + +\fBflags_object\fR: + A collection of any flag supported by the \fBbuild_compiler\fR, such as \fBgcc\fR. + This includes the any compiler specific parameters to defined this, such as the \fB-f\fR used by \fBgcc\fR and \fBclang\fR. + These are applied when building an object. + +\fBflags_object_shared\fR: + A collection of any flag supported by the \fBbuild_compiler\fR, such as \fBgcc\fR. + This includes the any compiler specific parameters to defined this, such as the \fB-f\fR used by \fBgcc\fR and \fBclang\fR. + These are applied to only object shared builds. + +\fBflags_object_static\fR: + A collection of any flag supported by the \fBbuild_compiler\fR, such as \fBgcc\fR. + This includes the any compiler specific parameters to defined this, such as the \fB-f\fR used by \fBgcc\fR and \fBclang\fR. + These are applied to only object static builds. + +\fBflags_program\fR: + A collection of any flag supported by the \fBbuild_compiler\fR, such as \fBgcc\fR. + This includes the any compiler specific parameters to defined this, such as the \fB-f\fR used by \fBgcc\fR and \fBclang\fR. + These are applied when building a program. + +\fBflags_program_shared\fR: + A collection of any flag supported by the \fBbuild_compiler\fR, such as \fBgcc\fR. + This includes the any compiler specific parameters to defined this, such as the \fB-f\fR used by \fBgcc\fR and \fBclang\fR. + These are applied to only program shared builds. + +\fBflags_program_static\fR: + A collection of any flag supported by the \fBbuild_compiler\fR, such as \fBgcc\fR. + This includes the any compiler specific parameters to defined this, such as the \fB-f\fR used by \fBgcc\fR and \fBclang\fR. + These are applied to only program static builds. + +\fBflags_shared\fR: + A collection of any flag supported by the \fBbuild_compiler\fR, such as \fBgcc\fR. + This includes the any compiler specific parameters to defined this, such as the \fB-f\fR used by \fBgcc\fR and \fBclang\fR. + These are applied to only shared builds. + +\fBflags_static\fR: + A collection of any flag supported by the \fBbuild_compiler\fR, such as \fBgcc\fR. + This includes the any compiler specific parameters to defined this, such as the \fB-f\fR used by \fBgcc\fR and \fBclang\fR. + These are applied to only static builds. + +\fBhas_path_standard\fR: + When \fByes\fR, the sources path will be built using the sources path with the language, such as \fBsources/c/\fR. + When \fBno\fR, the default sources path structure is not used and instead \fBpath_sources\fR is used. + When the parameter \fB-S/--sources\fR is specified, such as \fB-S xxx\fR, then when this is set to \fByes\fR is used then the path would be \fBxxx/c/\fR and when this is set to \fBno\fR then the path would be \fBxxx/\fR. + + This defaults to \fByes\fR. + +\fBimport\fR: + Load this settings file at this point in the settings file. + This can be an absolute or a relative path. + This is intended to reduce repition and likely should be placed at the top of the settings file. + This a non-recursive operation and the imported file itself cannot perform an import. + Loaded values are processed as if they are in the file at the spot where the import setting is specified. + Relative paths are relative to the importing file. + Absolute paths that start with "./" are relative to the project root rather than the importing file. + Absolute paths that start with "/" are treated normally. + + This is neither implemented nor supported by Featureless Make 0.6.x and earlier. + +\fBmodes\fR: + A collection of available build modes. + Build modes provide custom variants of the build process where certain settings are appended onto others. + See the settings.txt specification for a list of which setting names this applies to. + +\fBmodes_default\fR: + The name of the default mode to use when no mode is specified. + This must be one of the modes specified in the \fBmodes\fR setting. + +\fBpath_headers\fR: + A sub-path in which headers are to be installed under. + For example, the Featureless Linux Library project might use the \fBlevel_0\fR, \fBlevel_1\fR, etc.. headers without requiring that structure within the source. + A resulting build destination for a \fBpath_headers\fR of \fBlevel_0\fR would be something like \fBbuild/includes/level_0/\fR. + If \fBpath_headers\fR is \fBlevel_0\fR, \fBpreserve_path_headers\fR is \fByes\fR, and \fBbuild_sources_headers\fR has \fBxxx/a.h yyy/zzz/b.h\fR, then the headers would be at: \fBbuild/includes/level_0/xxx/a.h build/includes/level_0/yyy/zzz/b.h\fR + +\fBpath_language\fR: + A sub-path in which to find the source files for the currently defined language. + If the \fBbuild_language\fR is changed, it is recommended to change this as well to match. + +\fBpath_library_script\fR: + A sub-path representing the destination where the built library script files are placed. + + This defaults to \fBscript\fR. + + This is neither implemented nor supported by Featureless Make 0.6.x and earlier. + +\fBpath_library_shared\fR: + A sub-path representing the destination where the built shared library files are placed. + + This defaults to \fBshared\fR. + +\fBpath_library_static\fR: + A sub-path representing the destination where the built shared library files are placed. + + This defaults to \fBstatic\fR. + +\fBpath_object_script\fR: + A sub-path representing the destination where the built object script files are placed. + + This defaults to \fBscript\fR. + + This is neither implemented nor supported by Featureless Make 0.6.x and earlier. + +\fBpath_object_shared\fR: + A sub-path representing the destination where the built object library files are placed. + + This defaults to \fBshared\fR. + +\fBpath_object_static\fR: + A sub-path representing the destination where the built object library files are placed. + + This defaults to \fBstatic\fR. + +\fBpath_program_script\fR: + A sub-path representing the destination where the built program script files are placed. + + This defaults to \fBscript\fR. + + This is neither implemented nor supported by Featureless Make 0.6.x and earlier. + +\fBpath_program_shared\fR: + A sub-path representing the destination where the built shared program files are placed. + + This defaults to \fBshared\fR. + +\fBpath_program_static\fR: + A sub-path representing the destination where built shared program files are placed. + + This defaults to \fBstatic\fR. + +\fBpath_sources\fR: + A sub-path representing where the source files are found. + + This defaults to \fBsources\fR. + +\fBpath_sources_object\fR: + A sub-path representing where the object source files are found. + This is used by \fBbuild_sources_object\fR. + + This defaults to \fBsources\fR. + +\fBpreserve_path_headers\fR: + When this is \fByes\fR, then the relative directory structure in the source (as defined in \fBbuild_sources_headers\fR) is preserved. + If the \fBbuild_sources_headers\fR has the header files \fBxxx/a.h yyy/zzz/b.h\fR and this is \fByes\fR, then the directories \fBxxx/\fR and \fByyy/zzz/\fR are created and the files are stored within them. + If the \fBbuild_sources_headers\fR has the header files \fBxxx/a.h yyy/zzz/b.h\fR and this is \fBno\fR, then the directories \fBxxx/\fR and \fByyy/zzz/\fR are stripped before installing. + When this is \fBno\fR and the \fBbuild_sources_headers\fR has header files \fBxxx/a.h yyy/a.h\fR, then one of the \fBa.h\fR files will be overwritten, depending on order they were supplied. + +\fBprocess_post\fR: + The filename (relative to the data/build/ directory) of a script to execute after the \fBbuild\fR operation successfully completes. + A small subset of parameters from the main execution are passed to this script during execution as parameters (using short parameter codes): + Color context parameters, such as: \fB+l\fR, \fB+n\fR, and \fB+d\fR. + Operation mode, such as: \fBbuild\fR, \fBclean\fR, \fBmake\fR, or \fBskeleton\fR. + Verbosity parameters, such as: \fB+q\fR, \fB+D\fR, or \fB+V\fR. + Define parameters, such as \fB-d X\fR or \fB-d Y\fR, whereas \fBX\fR or \fBY\fR are any valid argument associated with \fB-d\fR. + Process parameter, such as \fB-p X\fR, whereas \fBX\fR is any valid argument associated with \fB-p\fR. + Settings parameter, such as \fB-s X', whereas code:\fRX" is any valid argument associated with \fB-s\fR. + Build Path parameter, such as \fB-b X', whereas code:\fRX" is any valid argument associated with \fB-b\fR. + Data Path parameter, such as \fB-D X', whereas code:\fRX" is any valid argument associated with \fB-D\fR. + Sources Path parameter, such as \fB-S X', whereas code:\fRX" is any valid argument associated with \fB-S\fR. + Work Path parameter, such as \fB-w X', whereas code:\fRX" is any valid argument associated with \fB-w\fR. + +\fBprocess_pre\fR: + The filename (relative to the data/build/ directory) of a script to execute before the \fBbuild\fR operation is executed. + A small subset of parameters from the main execution are passed to this script during execution as parameters (using short parameter codes): + Color context parameters, such as: \fB+l\fR, \fB+n\fR, and \fB+d\fR. + Operation mode, such as: \fBbuild\fR, \fBclean\fR, \fBmake\fR, or \fBskeleton\fR. + Verbosity parameters, such as: \fB+q\fR, \fB+D\fR, or \fB+V\fR. + Define parameters, such as \fB-d X\fR or \fB-d Y\fR, whereas \fBX\fR or \fBY\fR are any valid argument associated with \fB-d\fR. + Process parameter, such as \fB-p X\fR, whereas \fBX\fR is any valid argument associated with \fB-p\fR. + Settings parameter, such as \fB-s X', whereas code:\fRX" is any valid argument associated with \fB-s\fR. + Build Path parameter, such as \fB-b X', whereas code:\fRX" is any valid argument associated with \fB-b\fR. + Data Path parameter, such as \fB-D X', whereas code:\fRX" is any valid argument associated with \fB-D\fR. + Sources Path parameter, such as \fB-S X', whereas code:\fRX" is any valid argument associated with \fB-S\fR. + Work Path parameter, such as \fB-w X', whereas code:\fRX" is any valid argument associated with \fB-w\fR. + +\fBsearch_exclusive\fR: + When \fByes\fR, the search path during compile for shared libraries will only include shared library paths. + When \fBno\fR, the search path during compile time for shared libraries will include shared library paths followed by static library paths. + Setting this to \fByes\fR helps prevent static libraries from ending up in shared libraries (very useful when bootstrapping a system). + Setting this to \fBno\fR allows for including static libraries if no shared libraries are found but static are. + This does not alter search paths introduced automatically by the \fBbuild_compiler\fR or \fBbuild_indexer\fR, so it is still possible for static libraries to end up even when this is set to \fByes\fR. + +\fBsearch_shared\fR: + When \fByes\fR, shared library paths are searched during compile. + Both this and \fBsearch_static\fR cannot be \fBno\fR at the same time. + + This defaults to \fByes\fR. + +\fBsearch_shared\fR: + When \fByes\fR, static library paths are searched during compile. + Both this and search_shared cannot be \fBno\fR at the same time. + +\fBversion_file\fR: + Designates which version should be used when building the symbolic links. + Any version prefixes are used as defined. + A Symbolic link is created against this created file such that \fBlibX.so\fR is a link to \fBlibX.so.A\fR. + For all files other than when file is \fBmajor\fR, another symbolic link is created against this such that \fBlibX.so.A\fR is a link to \fBlibX.so.A.X\fR such that X is the respective \fBB\fR, \fBB.C', or code:\fRB.C.D" as described below. + The default file is \fBmajor\fR. + When \fBmajor\fR is used, the file created is \fBlibX.so.A\fR, whereas \fBX\fR is the \fBbuild_name\fR and \fBA\fR is the major version. + When \fBminor\fR is used, the file created is \fBlibX.so.A.B\fR, whereas \fBX\fR is the \fBbuild_name\fR and \fBA.B\fR is the major and minor versions, respectively. + When \fBmicro\fR is used, the file created is \fBlibX.so.A.B.C\fR, whereas \fBX\fR is the \fBbuild_name\fR and \fBA.B.C\fR is the major, minor, and micro versions, respectively. + When \fBnano\fR is used, the file created is \fBlibX.so.A.B.C.D\fR, whereas \fBX\fR is the \fBbuild_name\fR and \fBA.B.C.D\fR is the major, minor, micro, and nano versions, respectively. + +\fBversion_major\fR: + The major version number (or in theory any characters allowed in a filename). + This should generally be a positive number or 0. + Anything else is currently untested but allowed. + With a structure of \fBA.B.C\fR, the major version would be the \fBA\fR. + +\fBversion_major_prefix\fR: + The version major prefix is the character used to designate the start of the major version. + This can zero or more characters. + With a structure of \fBA.B.C\fR, the major version prefix would be before the \fBA\fR. + This is only added if \fBversion_major\fR is not empty. + + This defaults to the ASCII period character \fB.\fR. + +\fBversion_minor\fR: + The minor version number (or in theory any characters allowed in a filename). + This should generally be a positive number or 0. + Anything else is currently untested but allowed. + With a structure of \fBA.B.C\fR, the minor version would be the \fBB\fR. + +\fBversion_minor_prefix\fR: + The version minor prefix is the character used to separate the major from the minor. + This can zero or more characters. + With a structure of \fBA.B.C\fR, the minor version prefix would be the \fB.\fR before the \fBB\fR. + This is only added if \fBversion_minor\fR is not empty. + + This defaults to the ASCII period character \fB.\fR. + +\fBversion_micro\fR: + The micro version number (or in theory any characters allowed in a filename). + This should generally be a positive number or 0. + Anything else is currently untested but allowed. + With a structure of \fBA.B.C\fR, the micro version would be the \fBC\fR. + +\fBversion_micro_prefix\fR: + The version micro prefix is the character used to separate the minor from the micro. + This can zero or more characters. + With a structure of \fBA.B.C\fR, the micro version prefix would be the \fB.\fR before the \fBC\fR. + This is only added if \fBversion_micro\fR is not empty. + + This defaults to the ASCII period character \fB.\fR. + +\fBversion_nano\fR: + The nano version number (or in theory any characters allowed in a filename). + This should generally be a positive number or 0. + Anything else is currently untested but allowed. + With a structure of \fBA.B.C.D\fR, the micro version prefix would be the \fB.\fR before the \fBD\fR. + +\fBversion_nano_prefix\fR: + The version nano prefix is the character used to separate the micro from the nano. + This can zero or more characters. + With a structure of \fBA.B.C.D\fR, the minor version would be the \fB.\fR before the \fBD\fR. + This is only added if \fBversion_nano\fR is not empty. + + This defaults to the ASCII period character \fB.\fR. + +\fBversion_target\fR: + Designates which version should be used when linking the shared library. + Any version prefixes are used as defined. + The default target is \fBmicro\fR. + When \fBmajor\fR is used, a shared library is generated with \fB-Wl,-soname,libX.so.A\fR, whereas \fBX\fR is the \fBbuild_name\fR and \fBA\fR is the major version. + When \fBminor\fR is used, a shared library is generated with \fB-Wl,-soname,libX.so.A.B\fR, whereas \fBX\fR is the \fBbuild_name\fR and \fBA.B\fR is the major and minor versions, respectively. + When \fBmicro\fR is used, a shared library is generated with \fB-Wl,-soname,libX.so.A.B.C\fR, whereas \fBX\fR is the \fBbuild_name\fR and \fBA.B.C\fR is the major, minor, and micro versions, respectively. + When \fBnano\fR is used, a shared library is generated with \fB-Wl,-soname,libX.so.A.B.C.D\fR, whereas \fBX\fR is the \fBbuild_name\fR and \fBA.B.C.D\fR is the major, minor, micro, and nano versions, respectively. +.SH AUTHOR +Written by Kevin Day. +.SH COPYRIGHT +.PP +Copyright \(co 2007-2023 Kevin Day, GNU LGPL Version 2.1 or later. diff --git a/level_3/firewall/data/build/settings b/level_3/firewall/data/build/settings index 6894f06..c9d9fbd 100644 --- a/level_3/firewall/data/build/settings +++ b/level_3/firewall/data/build/settings @@ -28,6 +28,8 @@ build_sources_program main.c build_sources_headers firewall.h common.h +build_sources_documentation man + build_sources_setting network build_script yes diff --git a/level_3/firewall/data/documentation/man/man1/firewall.1 b/level_3/firewall/data/documentation/man/man1/firewall.1 new file mode 100644 index 0000000..e52608b --- /dev/null +++ b/level_3/firewall/data/documentation/man/man1/firewall.1 @@ -0,0 +1,60 @@ +.TH FIREWALL "1" "January 2023" "Kevux - Firewall 0.6.3" "User Commands" +.SH NAME +firewall \- A basic iptables based firewall manager for the Kevux distribution. +.SH SYNOPSIS +.B firewall +[\fI\,OPTIONS\/\fR] [\fI\,COMMAND\/\fR] +.SH DESCRIPTION +.PP +.SH OPTIONS +.TP +\fB\{+h, ++help\fR +Print the help message. +.TP +\fB+d, ++dark\fR +Output using colors that show up better on dark backgrounds +.TP +\fB+l, ++light\fR +Output using colors that show up better on light backgrounds. +.TP +\fB+n, ++no_color\fR +Do not print using color. +.TP +\fB+Q, ++quiet\fR +Decrease verbosity, silencing most output. +.TP +\fB+E, ++error\fR +Decrease verbosity, using only error output. +.TP +\fB+N, ++normal\fR +Set verbosity to normal. +.TP +\fB+V, ++verbose\fR +Increase verbosity beyond normal output. +.TP +\fB+D, ++debug\fR +Enable debugging, significantly increasing verbosity beyond normal output. +.TP +\fB+v, ++version\fR +Print only the version number. +.SH COMMAND +.TP +\fBstart\fR +Turn on the firewall. +.TP +\fBstop\fR +Turn off the firewall. +.TP +\fBrestart\fR +Turn off and then turn on the firewall. +.TP +\fBlock\fR +Prevent all communication. +.TP +\fBshow\fR +Show active firewall settings. +.SH AUTHOR +Written by Kevin Day. +.SH COPYRIGHT +.PP +Copyright \(co 2007-2023 Kevin Day, GNU LGPL Version 2.1 or later. diff --git a/level_3/fss_basic_list_read/data/build/settings b/level_3/fss_basic_list_read/data/build/settings index d62fd59..9fa1d28 100644 --- a/level_3/fss_basic_list_read/data/build/settings +++ b/level_3/fss_basic_list_read/data/build/settings @@ -28,6 +28,8 @@ build_sources_program main.c build_sources_headers fss_basic_list_read.h common.h +build_sources_documentation man + build_script yes build_shared yes build_static no diff --git a/level_3/fss_basic_list_read/data/documentation/man/man1/fss_basic_list_read.1 b/level_3/fss_basic_list_read/data/documentation/man/man1/fss_basic_list_read.1 new file mode 100644 index 0000000..703ddb3 --- /dev/null +++ b/level_3/fss_basic_list_read/data/documentation/man/man1/fss_basic_list_read.1 @@ -0,0 +1,136 @@ +.TH FSS_BASIC_LIST_READ "1" "January 2023" "FLL - FSS Basic List Read 0.6.3" "User Commands" +.SH NAME +fss_basic_list_read \- Read data in \fBFSS-0003 (Basic List)\fR format. +.SH SYNOPSIS +.B fss_basic_list_read +[\fI\,OPTIONS\/\fR] [\fI\,FILENAMES\/\fR] +.SH DESCRIPTION +.PP +This program will print the Content associated with the given Object and Content main based on the \fBFSS-0002 Basic List\fR standard. + +All numeric positions (indexes) start at 0 instead of 1. +For example, a file of 17 lines would range from 0 to 16. + +When using the \fB\-\-depth\fR option, an order of operations is enforced on the parameters. +When this order of operations is in effect, parameters to the right of a depth parameter are influenced by that depth parameter: + \fB\-\-at\fR: An Object index at the specified depth. + \fB\-\-depth\fR: A new depth within the specified depth, indexed from the root. + \fB\-\-name\fR: An Object name at the specified depth. + +The parameter \fB\-\-depth\fR must be in numeric order, but values in between may be skipped. + ('\fB\-d 0 \-a 1 \-d 2 \-a 2\fR' would specify index 1 at depth 0, any index at depth 1, and index 2 at depth 2.) + ('\fB\-d 2 \-a 1 \-d 0 \-a 2\fR' would be invalid because depth 2 is before depth 1.) + +The parameter \fB\-\-select\fR selects a Content column. + +Specify both \fB\-\-object\fR and the \fB\-\-total\fR parameters to get the total objects. + +When both \fB\-\-at\fR and \fB\-\-name\fR parameters are specified (at the same depth), the \fB\-\-at\fR parameter value will be treated as a position relative to the specified \fB\-\-name\fR parameter value. + +This program may support parameters, such as \fB\-\-depth\fR or \fB\-\-select\fR, even if not supported by the standard. +This is done to help ensure consistency for scripting. + +For parameters like \fB\-\-depth\fR, if the standard doesn't support nested Content, then only a depth of 0 would be valid. +For parameters like \fB\-\-select\fR, if the standard doesn't support multiple Content groups, then only a select of 0 would be valid. + +The parameter \fB\-\-trim\fR will remove leading and trailing white spaces when selecting objects or when printing objects. + +When specifying both the \fB\-\-object\fR parameter and the \fB\-\-content\fR parameter, the entire Object and Content are printed, including the formatting. +Both the Object and Content printed are already escaped. +Both the Object and Content are separated by a New Line character '\fB\\n\fR' (U+000A). + +The parameter \fB\-\-delimit\fR accepts the following: + \fBnone\fR: Do not apply delimits. + \fBall\fR: (default) Apply all delimits. + \fBobject\fR: Apply delimits for Objects. + \fBA number, 0 or greater\fR: apply delimits for Content at the specified depth. + \fBA number, 0 or greater, followed by a +\fR: (such as '1+') apply delimits for Content at the specified depth and any greater depth (numerically). + \fBA number, 0 or lesser, followed by a \-\fR: (such as '1\-') apply delimits for Content at the specified depth and any lesser depth (numerically). + +The \fB\-\-delimit\fR parameter may be specified multiple times to customize the delimit behavior. +The \fB\-\-delimit\fR values none and all, overrule all other delimit values. + +The parameters \fB\-\-columns\fR and \fB\-\-select\fR refer to a Content column. +The word '\fBcolumn\fR' is being loosely defined to refer to a specific Content. +This is not to be confused with a depth. +.SH OPTIONS +.TP +\fB\{+h, ++help\fR +Print the help message. +.TP +\fB+d, ++dark\fR +Output using colors that show up better on dark backgrounds +.TP +\fB+l, ++light\fR +Output using colors that show up better on light backgrounds. +.TP +\fB+n, ++no_color\fR +Do not print using color. +.TP +\fB+Q, ++quiet\fR +Decrease verbosity, silencing most output. +.TP +\fB+E, ++error\fR +Decrease verbosity, using only error output. +.TP +\fB+N, ++normal\fR +Set verbosity to normal. +.TP +\fB+V, ++verbose\fR +Increase verbosity beyond normal output. +.TP +\fB+D, ++debug\fR +Enable debugging, significantly increasing verbosity beyond normal output. +.TP +\fB+v, ++version\fR +Print only the version number. +.TP +\fB\-a, \-\-at\fR +Select Object at this numeric index. +.TP +\fB\-c, \-\-content\fR +Print the Content (default). +.TP +\fB\-C, \-\-columns\fR +Print the total number of columns. +.TP +\fB\-D, \-\-delimit\fR +Designate how to handle applying delimits. +.TP +\fB\-d, \-\-depth\fR +Select Object at this numeric depth. +.TP +\fB\-e, \-\-empty\fR +Include empty Content when processing. +.TP +\fB\-l, \-\-line\fR +Print only the Content at the given line. +.TP +\fB\-n, \-\-name\fR +Select Object with this name. +.TP +\fB\-o, \-\-object\fR +Print the Object. +.TP +\fB\-p, \-\-pipe\fR +Print using the special pipe format. +.TP +\fB\-O, \-\-original\fR +Print with the original quotes and escapes. +.TP +\fB\-s, \-\-select\fR +Select sub-Content at this index. +.TP +\fB\-t, \-\-total\fR +Print the total number of lines. +.TP +\fB\-T, \-\-trim\fR +Trim Object names on select or print. +.SH FILENAMES +.TP +Any number of files to read. +.SH AUTHOR +Written by Kevin Day. +.SH COPYRIGHT +.PP +Copyright \(co 2007-2023 Kevin Day, GNU LGPL Version 2.1 or later. diff --git a/level_3/fss_basic_list_write/data/build/settings b/level_3/fss_basic_list_write/data/build/settings index ea5feed..a68c8f8 100644 --- a/level_3/fss_basic_list_write/data/build/settings +++ b/level_3/fss_basic_list_write/data/build/settings @@ -28,6 +28,8 @@ build_sources_program main.c build_sources_headers fss_basic_list_write.h common.h +build_sources_documentation man + build_script yes build_shared yes build_static no diff --git a/level_3/fss_basic_list_write/data/documentation/man/man1/fss_basic_list_write.1 b/level_3/fss_basic_list_write/data/documentation/man/man1/fss_basic_list_write.1 new file mode 100644 index 0000000..1613c7d --- /dev/null +++ b/level_3/fss_basic_list_write/data/documentation/man/man1/fss_basic_list_write.1 @@ -0,0 +1,81 @@ +.TH FSS_BASIC_LIST_WRITE "1" "January 2023" "FLL - FSS Basic List Write 0.6.3" "User Commands" +.SH NAME +fss_basic_list_write \- Write data in \fBFSS-0001 (Basic List)\fR format. +.SH SYNOPSIS +.B fss_basic_list_write +[\fI\,OPTIONS\/\fR] +.SH DESCRIPTION +.PP +The pipe uses the Backspace character '\fB\\b\fR' (U+0008) to designate the start of a Content. +The pipe uses the Form Feed character '\fB\\f\fR' (U+000C) to designate the end of the last Content. +The pipe uses the Vertical Line character '\fB\\v\fR' (U+000B) is used to ignore a Content range, which does nothing in this program. +For the pipe, an Object is terminated by either a Backspace character '\fB\\b\fR' (U+0008) or a Form Feed character '\fB\\f\fR' (U+000C). +The end of the pipe represents the end of any Object or Content. + +The \fBFSS-0002 (Basic List)\fR specification does not support quoted names, therefore the parameters '\fB\-\-single\fR' and '\fB\-\-double\fR' do nothing. + +This program does not use the parameter '\fB\-\-ignore\fR', which therefore does nothing. +This parameter requires two values. +.SH OPTIONS +.TP +\fB\{+h, ++help\fR +Print the help message. +.TP +\fB+d, ++dark\fR +Output using colors that show up better on dark backgrounds +.TP +\fB+l, ++light\fR +Output using colors that show up better on light backgrounds. +.TP +\fB+n, ++no_color\fR +Do not print using color. +.TP +\fB+Q, ++quiet\fR +Decrease verbosity, silencing most output. +.TP +\fB+E, ++error\fR +Decrease verbosity, using only error output. +.TP +\fB+N, ++normal\fR +Set verbosity to normal. +.TP +\fB+V, ++verbose\fR +Increase verbosity beyond normal output. +.TP +\fB+D, ++debug\fR +Enable debugging, significantly increasing verbosity beyond normal output. +.TP +\fB+v, ++version\fR +Print only the version number. +.TP +\fB\-c, \-\-content\fR +The Content to write. +.TP +\fB\-d, \-\-double\fR +Use double quotes (default). +.TP +\fB\-f, \-\-file\fR +Specify a file to send data to. +.TP +\fB\-I, \-\-ignore\fR +Ignore a given range within a Content. +.TP +\fB\-o, \-\-object\fR +The Object to write. +.TP +\fB\-p, \-\-partial\fR +Do not write a complete Object and Content set. +.TP +\fB\-P, \-\-prepend\fR +Prepend the given white space characters to the start of each multi-line Content. +.TP +\fB\-s, \-\-single\fR +Use single quotes. +.TP +\fB\-T, \-\-trim\fR +Trim Object names. +.SH AUTHOR +Written by Kevin Day. +.SH COPYRIGHT +.PP +Copyright \(co 2007-2023 Kevin Day, GNU LGPL Version 2.1 or later. diff --git a/level_3/fss_basic_read/data/build/settings b/level_3/fss_basic_read/data/build/settings index bd56a55..e275973 100644 --- a/level_3/fss_basic_read/data/build/settings +++ b/level_3/fss_basic_read/data/build/settings @@ -28,6 +28,8 @@ build_sources_program main.c build_sources_headers fss_basic_read.h common.h +build_sources_documentation man + build_script yes build_shared yes build_static no diff --git a/level_3/fss_basic_read/data/documentation/man/man1/fss_basic_read.1 b/level_3/fss_basic_read/data/documentation/man/man1/fss_basic_read.1 new file mode 100644 index 0000000..7212398 --- /dev/null +++ b/level_3/fss_basic_read/data/documentation/man/man1/fss_basic_read.1 @@ -0,0 +1,136 @@ +.TH FSS_BASIC_READ "1" "January 2023" "FLL - FSS Basic Read 0.6.3" "User Commands" +.SH NAME +fss_basic_read \- Read data in \fBFSS-0000 (Basic)\fR format. +.SH SYNOPSIS +.B fss_basic_read +[\fI\,OPTIONS\/\fR] [\fI\,FILENAMES\/\fR] +.SH DESCRIPTION +.PP +This program will print the Content associated with the given Object and Content main based on the \fBFSS-0000 Basic\fR standard. + +All numeric positions (indexes) start at 0 instead of 1. +For example, a file of 17 lines would range from 0 to 16. + +When using the \fB\-\-depth\fR option, an order of operations is enforced on the parameters. +When this order of operations is in effect, parameters to the right of a depth parameter are influenced by that depth parameter: + \fB\-\-at\fR: An Object index at the specified depth. + \fB\-\-depth\fR: A new depth within the specified depth, indexed from the root. + \fB\-\-name\fR: An Object name at the specified depth. + +The parameter \fB\-\-depth\fR must be in numeric order, but values in between may be skipped. + ('\fB\-d 0 \-a 1 \-d 2 \-a 2\fR' would specify index 1 at depth 0, any index at depth 1, and index 2 at depth 2.) + ('\fB\-d 2 \-a 1 \-d 0 \-a 2\fR' would be invalid because depth 2 is before depth 1.) + +The parameter \fB\-\-select\fR selects a Content column. + +Specify both \fB\-\-object\fR and the \fB\-\-total\fR parameters to get the total objects. + +When both \fB\-\-at\fR and \fB\-\-name\fR parameters are specified (at the same depth), the \fB\-\-at\fR parameter value will be treated as a position relative to the specified \fB\-\-name\fR parameter value. + +This program may support parameters, such as \fB\-\-depth\fR or \fB\-\-select\fR, even if not supported by the standard. +This is done to help ensure consistency for scripting. + +For parameters like \fB\-\-depth\fR, if the standard doesn't support nested Content, then only a depth of 0 would be valid. +For parameters like \fB\-\-select\fR, if the standard doesn't support multiple Content groups, then only a select of 0 would be valid. + +The parameter \fB\-\-trim\fR will remove leading and trailing white spaces when selecting objects or when printing objects. + +When specifying both the \fB\-\-object\fR parameter and the \fB\-\-content\fR parameter, the entire Object and Content are printed, including the formatting. +Both the Object and Content printed are already escaped. +Both the Object and Content are separated by a space. + +The parameter \fB\-\-delimit\fR accepts the following: + \fBnone\fR: Do not apply delimits. + \fBall\fR: (default) Apply all delimits. + \fBobject\fR: Apply delimits for Objects. + \fBA number, 0 or greater\fR: apply delimits for Content at the specified depth. + \fBA number, 0 or greater, followed by a +\fR: (such as '1+') apply delimits for Content at the specified depth and any greater depth (numerically). + \fBA number, 0 or lesser, followed by a \-\fR: (such as '1\-') apply delimits for Content at the specified depth and any lesser depth (numerically). + +The \fB\-\-delimit\fR parameter may be specified multiple times to customize the delimit behavior. +The \fB\-\-delimit\fR values none and all, overrule all other delimit values. + +The parameters \fB\-\-columns\fR and \fB\-\-select\fR refer to a Content column. +The word '\fBcolumn\fR' is being loosely defined to refer to a specific Content. +This is not to be confused with a depth. +.SH OPTIONS +.TP +\fB\{+h, ++help\fR +Print the help message. +.TP +\fB+d, ++dark\fR +Output using colors that show up better on dark backgrounds +.TP +\fB+l, ++light\fR +Output using colors that show up better on light backgrounds. +.TP +\fB+n, ++no_color\fR +Do not print using color. +.TP +\fB+Q, ++quiet\fR +Decrease verbosity, silencing most output. +.TP +\fB+E, ++error\fR +Decrease verbosity, using only error output. +.TP +\fB+N, ++normal\fR +Set verbosity to normal. +.TP +\fB+V, ++verbose\fR +Increase verbosity beyond normal output. +.TP +\fB+D, ++debug\fR +Enable debugging, significantly increasing verbosity beyond normal output. +.TP +\fB+v, ++version\fR +Print only the version number. +.TP +\fB\-a, \-\-at\fR +Select Object at this numeric index. +.TP +\fB\-c, \-\-content\fR +Print the Content (default). +.TP +\fB\-C, \-\-columns\fR +Print the total number of columns. +.TP +\fB\-D, \-\-delimit\fR +Designate how to handle applying delimits. +.TP +\fB\-d, \-\-depth\fR +Select Object at this numeric depth. +.TP +\fB\-e, \-\-empty\fR +Include empty Content when processing. +.TP +\fB\-l, \-\-line\fR +Print only the Content at the given line. +.TP +\fB\-n, \-\-name\fR +Select Object with this name. +.TP +\fB\-o, \-\-object\fR +Print the Object. +.TP +\fB\-p, \-\-pipe\fR +Print using the special pipe format. +.TP +\fB\-O, \-\-original\fR +Print with the original quotes and escapes. +.TP +\fB\-s, \-\-select\fR +Select sub-Content at this index. +.TP +\fB\-t, \-\-total\fR +Print the total number of lines. +.TP +\fB\-T, \-\-trim\fR +Trim Object names on select or print. +.SH FILENAMES +.TP +Any number of files to read. +.SH AUTHOR +Written by Kevin Day. +.SH COPYRIGHT +.PP +Copyright \(co 2007-2023 Kevin Day, GNU LGPL Version 2.1 or later. diff --git a/level_3/fss_basic_write/data/build/settings b/level_3/fss_basic_write/data/build/settings index 12ef475..d9641c6 100644 --- a/level_3/fss_basic_write/data/build/settings +++ b/level_3/fss_basic_write/data/build/settings @@ -28,6 +28,8 @@ build_sources_program main.c build_sources_headers fss_basic_write.h common.h +build_sources_documentation man + build_script yes build_shared yes build_static no diff --git a/level_3/fss_basic_write/data/documentation/man/man1/fss_basic_write.1 b/level_3/fss_basic_write/data/documentation/man/man1/fss_basic_write.1 new file mode 100644 index 0000000..b469a7b --- /dev/null +++ b/level_3/fss_basic_write/data/documentation/man/man1/fss_basic_write.1 @@ -0,0 +1,80 @@ +.TH FSS_BASIC_WRITE "1" "January 2023" "FLL - FSS Basic Write 0.6.3" "User Commands" +.SH NAME +fss_basic_write \- Write data in \fBFSS-0000 (Basic)\fR format. +.SH SYNOPSIS +.B fss_basic_write +[\fI\,OPTIONS\/\fR] +.SH DESCRIPTION +.PP +The pipe uses the Backspace character '\fB\\b\fR' (U+0008) to designate the start of a Content. +The pipe uses the Form Feed character '\fB\\f\fR' (U+000C) to designate the end of the last Content. +The pipe uses the Vertical Line character '\fB\\v\fR' (U+000B) is used to ignore a Content range, which does nothing in this program. +For the pipe, an Object is terminated by either a Backspace character '\fB\\b\fR' (U+0008) or a Form Feed character '\fB\\f\fR' (U+000C). +The end of the pipe represents the end of any Object or Content. + +The \fBFSS-0000 (Basic)\fR specification does not support multi-line Content, therefore the parameter '\fB\-\-prepend\fR' does nothing. + +This program does not use the parameter '\fB\-\-ignore\fR', which therefore does nothing. +.SH OPTIONS +.TP +\fB\{+h, ++help\fR +Print the help message. +.TP +\fB+d, ++dark\fR +Output using colors that show up better on dark backgrounds +.TP +\fB+l, ++light\fR +Output using colors that show up better on light backgrounds. +.TP +\fB+n, ++no_color\fR +Do not print using color. +.TP +\fB+Q, ++quiet\fR +Decrease verbosity, silencing most output. +.TP +\fB+E, ++error\fR +Decrease verbosity, using only error output. +.TP +\fB+N, ++normal\fR +Set verbosity to normal. +.TP +\fB+V, ++verbose\fR +Increase verbosity beyond normal output. +.TP +\fB+D, ++debug\fR +Enable debugging, significantly increasing verbosity beyond normal output. +.TP +\fB+v, ++version\fR +Print only the version number. +.TP +\fB\-c, \-\-content\fR +The Content to write. +.TP +\fB\-d, \-\-double\fR +Use double quotes (default). +.TP +\fB\-f, \-\-file\fR +Specify a file to send data to. +.TP +\fB\-I, \-\-ignore\fR +Ignore a given range within a Content. +.TP +\fB\-o, \-\-object\fR +The Object to write. +.TP +\fB\-p, \-\-partial\fR +Do not write a complete Object and Content set. +.TP +\fB\-P, \-\-prepend\fR +Prepend the given white space characters to the start of each multi-line Content. +.TP +\fB\-s, \-\-single\fR +Use single quotes. +.TP +\fB\-T, \-\-trim\fR +Trim Object names. +.SH AUTHOR +Written by Kevin Day. +.SH COPYRIGHT +.PP +Copyright \(co 2007-2023 Kevin Day, GNU LGPL Version 2.1 or later. diff --git a/level_3/fss_embedded_list_read/data/build/settings b/level_3/fss_embedded_list_read/data/build/settings index 0b033cd..2d5fb00 100644 --- a/level_3/fss_embedded_list_read/data/build/settings +++ b/level_3/fss_embedded_list_read/data/build/settings @@ -28,6 +28,8 @@ build_sources_program main.c build_sources_headers fss_embedded_list_read.h common.h +build_sources_documentation man + build_script yes build_shared yes build_static no diff --git a/level_3/fss_embedded_list_read/data/documentation/man/man1/fss_embedded_list_read.1 b/level_3/fss_embedded_list_read/data/documentation/man/man1/fss_embedded_list_read.1 new file mode 100644 index 0000000..791ca49 --- /dev/null +++ b/level_3/fss_embedded_list_read/data/documentation/man/man1/fss_embedded_list_read.1 @@ -0,0 +1,135 @@ +.TH FSS_EMBEDDED_LIST_READ "1" "January 2023" "FLL - FSS Embedded List Read 0.6.3" "User Commands" +.SH NAME +fss_embedded_list_read \- Read data in \fBFSS-0008 (Embedded List)\fR format. +.SH SYNOPSIS +.B fss_embedded_list_read +[\fI\,OPTIONS\/\fR] [\fI\,FILENAMES\/\fR] +.SH DESCRIPTION +.PP +This program will print the Content associated with the given Object and Content main based on the \fBFSS-0008 Embedded List\fR standard. + +All numeric positions (indexes) start at 0 instead of 1. +For example, a file of 17 lines would range from 0 to 16. + +When using the \fB\-\-depth\fR option, an order of operations is enforced on the parameters. +When this order of operations is in effect, parameters to the right of a depth parameter are influenced by that depth parameter: + \fB\-\-at\fR: An Object index at the specified depth. + \fB\-\-depth\fR: A new depth within the specified depth, indexed from the root. + \fB\-\-name\fR: An Object name at the specified depth. + +The parameter \fB\-\-depth\fR must be in numeric order, but values in between may be skipped. + (\fB'\-d 0 \-a 1 \-d 2 \-a 2\fR' would specify index 1 at depth 0, any index at depth 1, and index 2 at depth 2.) + (\fB'\-d 2 \-a 1 \-d 0 \-a 2\fR' would be invalid because depth 2 is before depth 1.) + +The parameter \fB\-\-select\fR selects a Content column. + +Specify both \fB\-\-object\fR and the \fB\-\-total\fR parameters to get the total objects. + +When both \fB\-\-at\fR and \fB\-\-name\fR parameters are specified (at the same depth), the \fB\-\-at\fR parameter value will be treated as a position relative to the specified \fB\-\-name\fR parameter value. + +This program may support parameters, such as \fB\-\-depth\fR or \fB\-\-select\fR, even if not supported by the standard. +This is done to help ensure consistency for scripting. + +For parameters like \fB\-\-depth\fR, if the standard doesn't support nested Content, then only a depth of 0 would be valid. +For parameters like \fB\-\-select\fR, if the standard doesn't support multiple Content groups, then only a select of 0 would be valid. + +The parameter \fB\-\-trim\fR will remove leading and trailing white spaces when selecting objects or when printing objects. + +When specifying both the \fB\-\-object\fR parameter and the \fB\-\-content\fR parameter, the entire Object and Content are printed, including the formatting. +Both the Object and Content printed are already escaped. +Both the Object and Content are separated by a New Line character '\fB\\n\fR' (U+000A). + +The parameter \fB\-\-delimit\fR accepts the following: + \fBnone\fR: Do not apply delimits. + \fBall\fR: (default) Apply all delimits. + \fBA number, 0 or greater\fR: apply delimits for Content at the specified depth. + \fBA number, 0 or greater, followed by a +\fR: (such as '1+') apply delimits for Content at the specified depth and any greater depth (numerically). + \fBA number, 0 or lesser, followed by a \-\fR: (such as '1\-') apply delimits for Content at the specified depth and any lesser depth (numerically). + +The \fB\-\-delimit\fR parameter may be specified multiple times to customize the delimit behavior. +The \fB\-\-delimit\fR values none and all, overrule all other delimit values. + +The parameters \fB\-\-columns\fR and \fB\-\-select\fR refer to a Content column. +The word '\fBcolumn\fR' is being loosely defined to refer to a specific Content. +This is not to be confused with a depth. +.SH OPTIONS +.TP +\fB\{+h, ++help\fR +Print the help message. +.TP +\fB+d, ++dark\fR +Output using colors that show up better on dark backgrounds +.TP +\fB+l, ++light\fR +Output using colors that show up better on light backgrounds. +.TP +\fB+n, ++no_color\fR +Do not print using color. +.TP +\fB+Q, ++quiet\fR +Decrease verbosity, silencing most output. +.TP +\fB+E, ++error\fR +Decrease verbosity, using only error output. +.TP +\fB+N, ++normal\fR +Set verbosity to normal. +.TP +\fB+V, ++verbose\fR +Increase verbosity beyond normal output. +.TP +\fB+D, ++debug\fR +Enable debugging, significantly increasing verbosity beyond normal output. +.TP +\fB+v, ++version\fR +Print only the version number. +.TP +\fB\-a, \-\-at\fR +Select Object at this numeric index. +.TP +\fB\-c, \-\-content\fR +Print the Content (default). +.TP +\fB\-C, \-\-columns\fR +Print the total number of columns. +.TP +\fB\-D, \-\-delimit\fR +Designate how to handle applying delimits. +.TP +\fB\-d, \-\-depth\fR +Select Object at this numeric depth. +.TP +\fB\-e, \-\-empty\fR +Include empty Content when processing. +.TP +\fB\-l, \-\-line\fR +Print only the Content at the given line. +.TP +\fB\-n, \-\-name\fR +Select Object with this name. +.TP +\fB\-o, \-\-object\fR +Print the Object. +.TP +\fB\-p, \-\-pipe\fR +Print using the special pipe format. +.TP +\fB\-O, \-\-original\fR +Print with the original quotes and escapes. +.TP +\fB\-s, \-\-select\fR +Select sub-Content at this index. +.TP +\fB\-t, \-\-total\fR +Print the total number of lines. +.TP +\fB\-T, \-\-trim\fR +Trim Object names on select or print. +.SH FILENAMES +.TP +Any number of files to read. +.SH AUTHOR +Written by Kevin Day. +.SH COPYRIGHT +.PP +Copyright \(co 2007-2023 Kevin Day, GNU LGPL Version 2.1 or later. diff --git a/level_3/fss_embedded_list_write/data/build/settings b/level_3/fss_embedded_list_write/data/build/settings index 3985ba1..cd6d303 100644 --- a/level_3/fss_embedded_list_write/data/build/settings +++ b/level_3/fss_embedded_list_write/data/build/settings @@ -25,8 +25,11 @@ build_libraries-monolithic -lfll build_sources_library fss_embedded_list_write.c common.c private-common.c private-write.c build_sources_program main.c + build_sources_headers fss_embedded_list_write.h common.h +build_sources_documentation man + build_script yes build_shared yes build_static no diff --git a/level_3/fss_embedded_list_write/data/documentation/man/man1/fss_embedded_list_write.1 b/level_3/fss_embedded_list_write/data/documentation/man/man1/fss_embedded_list_write.1 new file mode 100644 index 0000000..9bba346 --- /dev/null +++ b/level_3/fss_embedded_list_write/data/documentation/man/man1/fss_embedded_list_write.1 @@ -0,0 +1,83 @@ +.TH FSS_EMBEDDED_LIST_WRITE "1" "January 2023" "FLL - FSS Embedded List Write 0.6.3" "User Commands" +.SH NAME +fss_embedded_list_write \- Write data in \fBFSS-0008 (Embedded List)\fR format. +.SH SYNOPSIS +.B fss_embedded_list_write +[\fI\,OPTIONS\/\fR] +.SH DESCRIPTION +.PP +The pipe uses the Backspace character '\fB\\b\fR' (U+0008) to designate the start of a Content. +The pipe uses the Form Feed character '\fB\\f\fR' (U+000C) to designate the end of the last Content. +The pipe uses the Vertical Line character '\fB\\v\fR' (U+000B) is used to ignore a Content range (use this both before and after the range). +For the pipe, an Object is terminated by either a Backspace character '\fB\\b\fR' (U+0008) or a Form Feed character '\fB\\f\fR' (U+000C). +The end of the pipe represents the end of any Object or Content. + +The \fBFSS-0008 (Embedded List)\fR specification does not support quoted names, therefore the parameters '\fB\-\-single\fR' and '\fB\-\-double\fR' do nothing. + +The parameter '\fB\-\-ignore\fR' designates to not escape any valid nested Object or Content within some Content. +This parameter requires two values. +This parameter is not used for ignoring anything from the input pipe. +This parameter must be specified after a '\fB\-\-content\fR' parameter and this applies only to the Content represented by that specific '\fB\-\-content\fR' parameter. +.SH OPTIONS +.TP +\fB\{+h, ++help\fR +Print the help message. +.TP +\fB+d, ++dark\fR +Output using colors that show up better on dark backgrounds +.TP +\fB+l, ++light\fR +Output using colors that show up better on light backgrounds. +.TP +\fB+n, ++no_color\fR +Do not print using color. +.TP +\fB+Q, ++quiet\fR +Decrease verbosity, silencing most output. +.TP +\fB+E, ++error\fR +Decrease verbosity, using only error output. +.TP +\fB+N, ++normal\fR +Set verbosity to normal. +.TP +\fB+V, ++verbose\fR +Increase verbosity beyond normal output. +.TP +\fB+D, ++debug\fR +Enable debugging, significantly increasing verbosity beyond normal output. +.TP +\fB+v, ++version\fR +Print only the version number. +.TP +\fB\-c, \-\-content\fR +The Content to write. +.TP +\fB\-d, \-\-double\fR +Use double quotes (default). +.TP +\fB\-f, \-\-file\fR +Specify a file to send data to. +.TP +\fB\-I, \-\-ignore\fR +Ignore a given range within a Content. +.TP +\fB\-o, \-\-object\fR +The Object to write. +.TP +\fB\-p, \-\-partial\fR +Do not write a complete Object and Content set. +.TP +\fB\-P, \-\-prepend\fR +Prepend the given white space characters to the start of each multi-line Content. +.TP +\fB\-s, \-\-single\fR +Use single quotes. +.TP +\fB\-T, \-\-trim\fR +Trim Object names. +.SH AUTHOR +Written by Kevin Day. +.SH COPYRIGHT +.PP +Copyright \(co 2007-2023 Kevin Day, GNU LGPL Version 2.1 or later. diff --git a/level_3/fss_extended_list_read/data/build/settings b/level_3/fss_extended_list_read/data/build/settings index 46fbcba..e1f745c 100644 --- a/level_3/fss_extended_list_read/data/build/settings +++ b/level_3/fss_extended_list_read/data/build/settings @@ -28,6 +28,8 @@ build_sources_program main.c build_sources_headers fss_extended_list_read.h common.h +build_sources_documentation man + build_script yes build_shared yes build_static no diff --git a/level_3/fss_extended_list_read/data/documentation/man/man1/fss_extended_list_read.1 b/level_3/fss_extended_list_read/data/documentation/man/man1/fss_extended_list_read.1 new file mode 100644 index 0000000..9384aa7 --- /dev/null +++ b/level_3/fss_extended_list_read/data/documentation/man/man1/fss_extended_list_read.1 @@ -0,0 +1,136 @@ +.TH FSS_EMBEDDED_LIST_READ "1" "January 2023" "FLL - FSS Embedded List Write 0.6.3" "User Commands" +.SH NAME +fss_extended_list_read \- Read data in \fBFSS-0003 (Extended List)\fR format. +.SH SYNOPSIS +.B fss_extended_list_read +[\fI\,OPTIONS\/\fR] [\fI\,FILENAMES\/\fR] +.SH DESCRIPTION +.PP +This program will print the Content associated with the given Object and Content main based on the \fBFSS-0003 Extended List\fR standard. + +All numeric positions (indexes) start at 0 instead of 1. +For example, a file of 17 lines would range from 0 to 16. + +When using the \fB\-\-depth\fR option, an order of operations is enforced on the parameters. +When this order of operations is in effect, parameters to the right of a depth parameter are influenced by that depth parameter: + \fB\-\-at\fR: An Object index at the specified depth. + \fB\-\-depth\fR: A new depth within the specified depth, indexed from the root. + \fB\-\-name\fR: An Object name at the specified depth. + +The parameter \fB\-\-depth\fR must be in numeric order, but values in between may be skipped. + ('\fB\-d 0 \-a 1 \-d 2 \-a 2\fR' would specify index 1 at depth 0, any index at depth 1, and index 2 at depth 2.) + ('\fB\-d 2 \-a 1 \-d 0 \-a 2\fR' would be invalid because depth 2 is before depth 1.) + +The parameter \fB\-\-select\fR selects a Content column. + +Specify both \fB\-\-object\fR and the \fB\-\-total\fR parameters to get the total objects. + +When both \fB\-\-at\fR and \fB\-\-name\fR parameters are specified (at the same depth), the \fB\-\-at\fR parameter value will be treated as a position relative to the specified \fB\-\-name\fR parameter value. + +This program may support parameters, such as \fB\-\-depth\fR or \fB\-\-select\fR, even if not supported by the standard. +This is done to help ensure consistency for scripting. + +For parameters like \fB\-\-depth\fR, if the standard doesn't support nested Content, then only a depth of 0 would be valid. +For parameters like \fB\-\-select\fR, if the standard doesn't support multiple Content groups, then only a select of 0 would be valid. + +The parameter \fB\-\-trim\fR will remove leading and trailing white spaces when selecting objects or when printing objects. + +When specifying both the \fB\-\-object\fR parameter and the \fB\-\-content\fR parameter, the entire Object and Content are printed, including the formatting. +Both the Object and Content printed are already escaped. +Both the Object and Content are separated by a New Line character '\fB\\n\fR' (U+000A). + +The parameter \fB\-\-delimit\fR accepts the following: + \fBnone\fR: Do not apply delimits. + \fBall\fR: (default) Apply all delimits. + \fBobject\fR: Apply delimits for Objects. + \fBA number, 0 or greater\fR: apply delimits for Content at the specified depth. + \fBA number, 0 or greater, followed by a +\fR: (such as '1+') apply delimits for Content at the specified depth and any greater depth (numerically). + \fBA number, 0 or lesser, followed by a \-\fR: (such as '1\-') apply delimits for Content at the specified depth and any lesser depth (numerically). + +The \fB\-\-delimit\fR parameter may be specified multiple times to customize the delimit behavior. +The \fB\-\-delimit\fR values none and all, overrule all other delimit values. + +The parameters \fB\-\-columns\fR and \fB\-\-select\fR refer to a Content column. +The word '\fBcolumn\fR' is being loosely defined to refer to a specific Content. +This is not to be confused with a depth. +.SH OPTIONS +.TP +\fB\{+h, ++help\fR +Print the help message. +.TP +\fB+d, ++dark\fR +Output using colors that show up better on dark backgrounds +.TP +\fB+l, ++light\fR +Output using colors that show up better on light backgrounds. +.TP +\fB+n, ++no_color\fR +Do not print using color. +.TP +\fB+Q, ++quiet\fR +Decrease verbosity, silencing most output. +.TP +\fB+E, ++error\fR +Decrease verbosity, using only error output. +.TP +\fB+N, ++normal\fR +Set verbosity to normal. +.TP +\fB+V, ++verbose\fR +Increase verbosity beyond normal output. +.TP +\fB+D, ++debug\fR +Enable debugging, significantly increasing verbosity beyond normal output. +.TP +\fB+v, ++version\fR +Print only the version number. +.TP +\fB\-a, \-\-at\fR +Select Object at this numeric index. +.TP +\fB\-c, \-\-content\fR +Print the Content (default). +.TP +\fB\-C, \-\-columns\fR +Print the total number of columns. +.TP +\fB\-D, \-\-delimit\fR +Designate how to handle applying delimits. +.TP +\fB\-d, \-\-depth\fR +Select Object at this numeric depth. +.TP +\fB\-e, \-\-empty\fR +Include empty Content when processing. +.TP +\fB\-l, \-\-line\fR +Print only the Content at the given line. +.TP +\fB\-n, \-\-name\fR +Select Object with this name. +.TP +\fB\-o, \-\-object\fR +Print the Object. +.TP +\fB\-p, \-\-pipe\fR +Print using the special pipe format. +.TP +\fB\-O, \-\-original\fR +Print with the original quotes and escapes. +.TP +\fB\-s, \-\-select\fR +Select sub-Content at this index. +.TP +\fB\-t, \-\-total\fR +Print the total number of lines. +.TP +\fB\-T, \-\-trim\fR +Trim Object names on select or print. +.SH FILENAMES +.TP +Any number of files to read. +.SH AUTHOR +Written by Kevin Day. +.SH COPYRIGHT +.PP +Copyright \(co 2007-2023 Kevin Day, GNU LGPL Version 2.1 or later. diff --git a/level_3/fss_extended_list_write/data/build/settings b/level_3/fss_extended_list_write/data/build/settings index 5fc2618..c2602bd 100644 --- a/level_3/fss_extended_list_write/data/build/settings +++ b/level_3/fss_extended_list_write/data/build/settings @@ -28,6 +28,8 @@ build_sources_program main.c build_sources_headers fss_extended_list_write.h common.h +build_sources_documentation man + build_script yes build_shared yes build_static no diff --git a/level_3/fss_extended_list_write/data/documentation/man/man1/fss_extended_list_write.1 b/level_3/fss_extended_list_write/data/documentation/man/man1/fss_extended_list_write.1 new file mode 100644 index 0000000..e534fae --- /dev/null +++ b/level_3/fss_extended_list_write/data/documentation/man/man1/fss_extended_list_write.1 @@ -0,0 +1,83 @@ +.TH FSS_EXTENDED_LIST_WRITE "1" "January 2023" "FLL - FSS Extended List Write 0.6.3" "User Commands" +.SH NAME +fss_extended_list_write \- Write data in \fBFSS-0003 (Extended List)\fR format. +.SH SYNOPSIS +.B fss_extended_list_write +[\fI\,OPTIONS\/\fR] +.SH DESCRIPTION +.PP +The pipe uses the Backspace character '\fB\\b\fR' (U+0008) to designate the start of a Content. +The pipe uses the Form Feed character '\fB\\f\fR' (U+000C) to designate the end of the last Content. +The pipe uses the Vertical Line character '\fB\\v\fR' (U+000B) is used to ignore a Content range (use this both before and after the range). +For the pipe, an Object is terminated by either a Backspace character '\fB\\b\fR' (U+0008) or a Form Feed character '\fB\\f\fR' (U+000C). +The end of the pipe represents the end of any Object or Content. + +The \fBFSS-0003 (Extended List)\fR specification does not support quoted names, therefore the parameters '\fB\-\-single\fR' and '\fB\-\-double\fR' do nothing. + +The parameter '\fB\-\-ignore\fR' designates to not escape any valid nested Object or Content within some Content. +This parameter requires two values. +This parameter is not used for ignoring anything from the input pipe. +This parameter must be specified after a '\fB\-\-content\fR' parameter and this applies only to the Content represented by that specific '\fB\-\-content\fR' parameter. +.SH OPTIONS +.TP +\fB\{+h, ++help\fR +Print the help message. +.TP +\fB+d, ++dark\fR +Output using colors that show up better on dark backgrounds +.TP +\fB+l, ++light\fR +Output using colors that show up better on light backgrounds. +.TP +\fB+n, ++no_color\fR +Do not print using color. +.TP +\fB+Q, ++quiet\fR +Decrease verbosity, silencing most output. +.TP +\fB+E, ++error\fR +Decrease verbosity, using only error output. +.TP +\fB+N, ++normal\fR +Set verbosity to normal. +.TP +\fB+V, ++verbose\fR +Increase verbosity beyond normal output. +.TP +\fB+D, ++debug\fR +Enable debugging, significantly increasing verbosity beyond normal output. +.TP +\fB+v, ++version\fR +Print only the version number. +.TP +\fB\-c, \-\-content\fR +The Content to write. +.TP +\fB\-d, \-\-double\fR +Use double quotes (default). +.TP +\fB\-f, \-\-file\fR +Specify a file to send data to. +.TP +\fB\-I, \-\-ignore\fR +Ignore a given range within a Content. +.TP +\fB\-o, \-\-object\fR +The Object to write. +.TP +\fB\-p, \-\-partial\fR +Do not write a complete Object and Content set. +.TP +\fB\-P, \-\-prepend\fR +Prepend the given white space characters to the start of each multi-line Content. +.TP +\fB\-s, \-\-single\fR +Use single quotes. +.TP +\fB\-T, \-\-trim\fR +Trim Object names. +.SH AUTHOR +Written by Kevin Day. +.SH COPYRIGHT +.PP +Copyright \(co 2007-2023 Kevin Day, GNU LGPL Version 2.1 or later. diff --git a/level_3/fss_extended_read/data/build/settings b/level_3/fss_extended_read/data/build/settings index 6558c77..6b1987c 100644 --- a/level_3/fss_extended_read/data/build/settings +++ b/level_3/fss_extended_read/data/build/settings @@ -28,6 +28,8 @@ build_sources_program main.c build_sources_headers fss_extended_read.h common.h +build_sources_documentation man + build_script yes build_shared yes build_static no diff --git a/level_3/fss_extended_read/data/documentation/man/man1/fss_extended_read.1 b/level_3/fss_extended_read/data/documentation/man/man1/fss_extended_read.1 new file mode 100644 index 0000000..7d656ad --- /dev/null +++ b/level_3/fss_extended_read/data/documentation/man/man1/fss_extended_read.1 @@ -0,0 +1,136 @@ +.TH FSS_EXTENDED_READ "1" "January 2023" "FLL - FSS Extended Read 0.6.3" "User Commands" +.SH NAME +fss_extended_read \- Read data in \fBFSS-0001 (Extended)\fR format. +.SH SYNOPSIS +.B fss_extended_read +[\fI\,OPTIONS\/\fR] [\fI\,FILENAMES\/\fR] +.SH DESCRIPTION +.PP +This program will print the Content associated with the given Object and Content main based on the \fBFSS-0001 Extended\fR standard. + +All numeric positions (indexes) start at 0 instead of 1. +For example, a file of 17 lines would range from 0 to 16. + +When using the \fB\-\-depth\fR option, an order of operations is enforced on the parameters. +When this order of operations is in effect, parameters to the right of a depth parameter are influenced by that depth parameter: + \fB\-\-at\fR: An Object index at the specified depth. + \fB\-\-depth\fR: A new depth within the specified depth, indexed from the root. + \fB\-\-name\fR: An Object name at the specified depth. + +The parameter \fB\-\-depth\fR must be in numeric order, but values in between may be skipped. + ('\fB\-d 0 \-a 1 \-d 2 \-a 2\fR' would specify index 1 at depth 0, any index at depth 1, and index 2 at depth 2.) + ('\fB\-d 2 \-a 1 \-d 0 \-a 2\fR' would be invalid because depth 2 is before depth 1.) + +The parameter \fB\-\-select\fR selects a Content column. + +Specify both \fB\-\-object\fR and the \fB\-\-total\fR parameters to get the total objects. + +When both \fB\-\-at\fR and \fB\-\-name\fR parameters are specified (at the same depth), the \fB\-\-at\fR parameter value will be treated as a position relative to the specified \fB\-\-name\fR parameter value. + +This program may support parameters, such as \fB\-\-depth\fR or \fB\-\-select\fR, even if not supported by the standard. +This is done to help ensure consistency for scripting. + +For parameters like \fB\-\-depth\fR, if the standard doesn't support nested Content, then only a depth of 0 would be valid. +For parameters like \fB\-\-select\fR, if the standard doesn't support multiple Content groups, then only a select of 0 would be valid. + +The parameter \fB\-\-trim\fR will remove leading and trailing white spaces when selecting objects or when printing objects. + +When specifying both the \fB\-\-object\fR parameter and the \fB\-\-content\fR parameter, the entire Object and Content are printed, including the formatting. +Both the Object and Content printed are already escaped. +Both the Object and Content are separated by a space. + +The parameter \fB\-\-delimit\fR accepts the following: + \fBnone\fR: Do not apply delimits. + \fBall\fR: (default) Apply all delimits. + \fBobject\fR: Apply delimits for Objects. + \fBA number, 0 or greater\fR: apply delimits for Content at the specified depth. + \fBA number, 0 or greater, followed by a +\fR: (such as '1+') apply delimits for Content at the specified depth and any greater depth (numerically). + \fBA number, 0 or lesser, followed by a \-\fR: (such as '1\-') apply delimits for Content at the specified depth and any lesser depth (numerically). + +The \fB\-\-delimit\fR parameter may be specified multiple times to customize the delimit behavior. +The \fB\-\-delimit\fR values none and all, overrule all other delimit values. + +The parameters \fB\-\-columns\fR and \fB\-\-select\fR refer to a Content column. +The word '\fBcolumn\fR' is being loosely defined to refer to a specific Content. +This is not to be confused with a depth. +.SH OPTIONS +.TP +\fB\{+h, ++help\fR +Print the help message. +.TP +\fB+d, ++dark\fR +Output using colors that show up better on dark backgrounds +.TP +\fB+l, ++light\fR +Output using colors that show up better on light backgrounds. +.TP +\fB+n, ++no_color\fR +Do not print using color. +.TP +\fB+Q, ++quiet\fR +Decrease verbosity, silencing most output. +.TP +\fB+E, ++error\fR +Decrease verbosity, using only error output. +.TP +\fB+N, ++normal\fR +Set verbosity to normal. +.TP +\fB+V, ++verbose\fR +Increase verbosity beyond normal output. +.TP +\fB+D, ++debug\fR +Enable debugging, significantly increasing verbosity beyond normal output. +.TP +\fB+v, ++version\fR +Print only the version number. +.TP +\fB\-a, \-\-at\fR +Select Object at this numeric index. +.TP +\fB\-c, \-\-content\fR +Print the Content (default). +.TP +\fB\-C, \-\-columns\fR +Print the total number of columns. +.TP +\fB\-D, \-\-delimit\fR +Designate how to handle applying delimits. +.TP +\fB\-d, \-\-depth\fR +Select Object at this numeric depth. +.TP +\fB\-e, \-\-empty\fR +Include empty Content when processing. +.TP +\fB\-l, \-\-line\fR +Print only the Content at the given line. +.TP +\fB\-n, \-\-name\fR +Select Object with this name. +.TP +\fB\-o, \-\-object\fR +Print the Object. +.TP +\fB\-p, \-\-pipe\fR +Print using the special pipe format. +.TP +\fB\-O, \-\-original\fR +Print with the original quotes and escapes. +.TP +\fB\-s, \-\-select\fR +Select sub-Content at this index. +.TP +\fB\-t, \-\-total\fR +Print the total number of lines. +.TP +\fB\-T, \-\-trim\fR +Trim Object names on select or print. +.SH FILENAMES +.TP +Any number of files to read. +.SH AUTHOR +Written by Kevin Day. +.SH COPYRIGHT +.PP +Copyright \(co 2007-2023 Kevin Day, GNU LGPL Version 2.1 or later. diff --git a/level_3/fss_extended_write/data/build/settings b/level_3/fss_extended_write/data/build/settings index a0ab81a..ffe5de9 100644 --- a/level_3/fss_extended_write/data/build/settings +++ b/level_3/fss_extended_write/data/build/settings @@ -28,6 +28,8 @@ build_sources_program main.c build_sources_headers fss_extended_write.h common.h +build_sources_documentation man + build_script yes build_shared yes build_static no diff --git a/level_3/fss_extended_write/data/documentation/man/man1/fss_extended_write.1 b/level_3/fss_extended_write/data/documentation/man/man1/fss_extended_write.1 new file mode 100644 index 0000000..1964e23 --- /dev/null +++ b/level_3/fss_extended_write/data/documentation/man/man1/fss_extended_write.1 @@ -0,0 +1,81 @@ +.TH FSS_EXTENDED_WRITE "1" "January 2023" "FLL - FSS Extended Write 0.6.3" "User Commands" +.SH NAME +fss_extended_write \- Write data in \fBFSS-0001 (Extended)\fR format. +.SH SYNOPSIS +.B fss_extended_write +[\fI\,OPTIONS\/\fR] +.SH DESCRIPTION +.PP +The pipe uses the Backspace character '\fB\\b\fR' (U+0008) to designate the start of a Content. +The pipe uses the Form Feed character '\fB\\f\fR' (U+000C) to designate the end of the last Content. +The pipe uses the Vertical Line character '\fB\\v\fR' (U+000B) is used to ignore a Content range, which does nothing in this program. +For the pipe, an Object is terminated by either a Backspace character '\fB\\b\fR' (U+0008) or a Form Feed character '\fB\\f\fR' (U+000C). +The end of the pipe represents the end of any Object or Content. + +The \fBFSS-0001 (Extended)\fR specification does not support multi-line Content, therefore the parameter '\fB\-\-prepend\fR' does nothing. + +This program does not use the parameter '\fB\-\-ignore\fR', which therefore does nothing. +This parameter requires two values. +.SH OPTIONS +.TP +\fB\{+h, ++help\fR +Print the help message. +.TP +\fB+d, ++dark\fR +Output using colors that show up better on dark backgrounds +.TP +\fB+l, ++light\fR +Output using colors that show up better on light backgrounds. +.TP +\fB+n, ++no_color\fR +Do not print using color. +.TP +\fB+Q, ++quiet\fR +Decrease verbosity, silencing most output. +.TP +\fB+E, ++error\fR +Decrease verbosity, using only error output. +.TP +\fB+N, ++normal\fR +Set verbosity to normal. +.TP +\fB+V, ++verbose\fR +Increase verbosity beyond normal output. +.TP +\fB+D, ++debug\fR +Enable debugging, significantly increasing verbosity beyond normal output. +.TP +\fB+v, ++version\fR +Print only the version number. +.TP +\fB\-c, \-\-content\fR +The Content to write. +.TP +\fB\-d, \-\-double\fR +Use double quotes (default). +.TP +\fB\-f, \-\-file\fR +Specify a file to send data to. +.TP +\fB\-I, \-\-ignore\fR +Ignore a given range within a Content. +.TP +\fB\-o, \-\-object\fR +The Object to write. +.TP +\fB\-p, \-\-partial\fR +Do not write a complete Object and Content set. +.TP +\fB\-P, \-\-prepend\fR +Prepend the given white space characters to the start of each multi-line Content. +.TP +\fB\-s, \-\-single\fR +Use single quotes. +.TP +\fB\-T, \-\-trim\fR +Trim Object names. +.SH AUTHOR +Written by Kevin Day. +.SH COPYRIGHT +.PP +Copyright \(co 2007-2023 Kevin Day, GNU LGPL Version 2.1 or later. diff --git a/level_3/fss_identify/data/build/settings b/level_3/fss_identify/data/build/settings index d99ba2a..6f30fd0 100644 --- a/level_3/fss_identify/data/build/settings +++ b/level_3/fss_identify/data/build/settings @@ -28,6 +28,8 @@ build_sources_program main.c build_sources_headers fss_identify.h common.h +build_sources_documentation man + build_script yes build_shared yes build_static no diff --git a/level_3/fss_identify/data/documentation/man/man1/fss_identify.1 b/level_3/fss_identify/data/documentation/man/man1/fss_identify.1 new file mode 100644 index 0000000..cf6fd64 --- /dev/null +++ b/level_3/fss_identify/data/documentation/man/man1/fss_identify.1 @@ -0,0 +1,72 @@ +.TH FSS_IDENTIFY "1" "January 2023" "FLL - FSS Identify 0.6.3" "User Commands" +.SH NAME +fss_identify \- Read data looking for the FSS header and parse out the FSS standard identifying information. +.SH SYNOPSIS +.B fss_identify +[\fI\,OPTIONS\/\fR] [\fI\,FILENAMES\/\fR] +.SH DESCRIPTION +.PP +The \fB\-\-line\fR parameter refers to the file lines and not the lines in a given file. + +If neither the \fB\-\-object\fR nor \fB\-\-content\fR are specified, then the default behavior is to print both. + +When specifying the \fB\-\-total\fR parameter, neither the \fB\-\-object\fR nor the \fB\-\-content\fR parameter may be specified. + +An FSS file is identified by the following format: '\fB# Object-Content\fR' where the Object, is a machine-name representing the name and may only consist of 'word' characters and the Content is a 4-digit hexidecimal number representing a particular variant of the Object. +This identifier, if provided, must exist on the first line in a file and must begin with the pound character: '\fB#\fR'. +Whitespace must follow this pound character. +There may be multiple Object and Content pairs, separated by white space, such as: '\fB# fss-0002 fss-0000 iki-0002\fR'. +.SH OPTIONS +.TP +\fB\{+h, ++help\fR +Print the help message. +.TP +\fB+d, ++dark\fR +Output using colors that show up better on dark backgrounds +.TP +\fB+l, ++light\fR +Output using colors that show up better on light backgrounds. +.TP +\fB+n, ++no_color\fR +Do not print using color. +.TP +\fB+Q, ++quiet\fR +Decrease verbosity, silencing most output. +.TP +\fB+E, ++error\fR +Decrease verbosity, using only error output. +.TP +\fB+N, ++normal\fR +Set verbosity to normal. +.TP +\fB+V, ++verbose\fR +Increase verbosity beyond normal output. +.TP +\fB+D, ++debug\fR +Enable debugging, significantly increasing verbosity beyond normal output. +.TP +\fB+v, ++version\fR +Print only the version number. +.TP +\fB\-c, \-\-content\fR +Print the Identifier content (the 4-digit hexidecimal type code). +.TP +\fB\-o, \-\-object\fR +Print the Identifier object (the name). +.TP +\fB\-l, \-\-line\fR +Print only the Identifier at the given line. +.TP +\fB\-n, \-\-name\fR +Select FSS using this full or partial type name or code. +.TP +\fB\-t, \-\-total\fR +Print the total Identifiers found. +.SH FILENAMES +.TP +Any number of files to read. +.SH AUTHOR +Written by Kevin Day. +.SH COPYRIGHT +.PP +Copyright \(co 2007-2023 Kevin Day, GNU LGPL Version 2.1 or later. diff --git a/level_3/fss_payload_read/data/build/settings b/level_3/fss_payload_read/data/build/settings index 64a96c7..951a739 100644 --- a/level_3/fss_payload_read/data/build/settings +++ b/level_3/fss_payload_read/data/build/settings @@ -28,6 +28,8 @@ build_sources_program main.c build_sources_headers fss_payload_read.h common.h +build_sources_documentation man + build_script yes build_shared yes build_static no diff --git a/level_3/fss_payload_read/data/documentation/man/man1/fss_payload_read.1 b/level_3/fss_payload_read/data/documentation/man/man1/fss_payload_read.1 new file mode 100644 index 0000000..f36715b --- /dev/null +++ b/level_3/fss_payload_read/data/documentation/man/man1/fss_payload_read.1 @@ -0,0 +1,141 @@ +.TH FSS_PAYLOAD_READ "1" "January 2023" "FLL - FSS Payload Read 0.6.3" "User Commands" +.SH NAME +fss_payload_read \- Read data in \fBFSS-000E (Payload)\fR format. +.SH SYNOPSIS +.B fss_payload_read +[\fI\,OPTIONS\/\fR] [\fI\,FILENAMES\/\fR] +.SH DESCRIPTION +.PP +This program will print the Content associated with the given Object and Content main based on the \fBFSS-000E Payload\fR standard. + +All numeric positions (indexes) start at 0 instead of 1. +For example, a file of 17 lines would range from 0 to 16. + +When using the \fB\-\-depth\fR option, an order of operations is enforced on the parameters. +When this order of operations is in effect, parameters to the right of a depth parameter are influenced by that depth parameter: + \fB\-\-at\fR: An Object index at the specified depth. + \fB\-\-depth\fR: A new depth within the specified depth, indexed from the root. + \fB\-\-name\fR: An Object name at the specified depth. + +The parameter \fB\-\-depth\fR must be in numeric order, but values in between may be skipped. + ('\fB\-d 0 \-a 1 \-d 2 \-a 2\fR' would specify index 1 at depth 0, any index at depth 1, and index 2 at depth 2.) + ('\fB\-d 2 \-a 1 \-d 0 \-a 2\fR' would be invalid because depth 2 is before depth 1.) + +The parameter \fB\-\-select\fR selects a Content column. + +Specify both \fB\-\-object\fR and the \fB\-\-total\fR parameters to get the total objects. + +When both \fB\-\-at\fR and \fB\-\-name\fR parameters are specified (at the same depth), the \fB\-\-at\fR parameter value will be treated as a position relative to the specified \fB\-\-name\fR parameter value. + +This program may support parameters, such as \fB\-\-depth\fR or \fB\-\-select\fR, even if not supported by the standard. +This is done to help ensure consistency for scripting. + +For parameters like \fB\-\-depth\fR, if the standard doesn't support nested Content, then only a depth of 0 would be valid. +For parameters like \fB\-\-select\fR, if the standard doesn't support multiple Content groups, then only a select of 0 would be valid. + +The parameter \fB\-\-trim\fR will remove leading and trailing white spaces when selecting objects or when printing objects. + +When specifying both the \fB\-\-object\fR parameter and the \fB\-\-content\fR parameter, the entire Object and Content are printed, including the formatting. +Both the Object and Content printed are already escaped. +Both the Object and Content are separated by a New Line character '\fB\\n\fR' (U+000A). + +The parameter \fB\-\-delimit\fR accepts the following: +- none: Do not apply delimits. +- all: (default) Apply all delimits. +- object: Apply delimits for Objects. +- A number, 0 or greater: apply delimits for Content at the specified depth. +- A number, 0 or greater, followed by a +: (such as '1+') apply delimits for Content at the specified depth and any greater depth (numerically). +- A number, 0 or lesser, followed by a \-: (such as '1\-') apply delimits for Content at the specified depth and any lesser depth (numerically). + +The \fB\-\-delimit\fR parameter may be specified multiple times to customize the delimit behavior. +The \fB\-\-delimit\fR values none and all, overrule all other delimit values. + +The parameters \fB\-\-columns\fR and \fB\-\-select\fR refer to a Content column. +The word "column" is being loosely defined to refer to a specific Content. +This is not to be confused with a depth. + +As an exceptional case, a \fB\-\-depth\fR of 1 applies only to the explicit Object of 'header'. +Content at this depth is processed as \fBFSS-0001 Extended\fR. + +The Content of the explicit Object of 'payload' will not contain any Content close pipe control codes when using \fB\-\-pipe\fR. +.SH OPTIONS +.TP +\fB\{+h, ++help\fR +Print the help message. +.TP +\fB+d, ++dark\fR +Output using colors that show up better on dark backgrounds +.TP +\fB+l, ++light\fR +Output using colors that show up better on light backgrounds. +.TP +\fB+n, ++no_color\fR +Do not print using color. +.TP +\fB+Q, ++quiet\fR +Decrease verbosity, silencing most output. +.TP +\fB+E, ++error\fR +Decrease verbosity, using only error output. +.TP +\fB+N, ++normal\fR +Set verbosity to normal. +.TP +\fB+V, ++verbose\fR +Increase verbosity beyond normal output. +.TP +\fB+D, ++debug\fR +Enable debugging, significantly increasing verbosity beyond normal output. +.TP +\fB+v, ++version\fR +Print only the version number. +.TP +\fB\-a, \-\-at\fR +Select Object at this numeric index. +.TP +\fB\-c, \-\-content\fR +Print the Content (default). +.TP +\fB\-C, \-\-columns\fR +Print the total number of columns. +.TP +\fB\-D, \-\-delimit\fR +Designate how to handle applying delimits. +.TP +\fB\-d, \-\-depth\fR +Select Object at this numeric depth. +.TP +\fB\-e, \-\-empty\fR +Include empty Content when processing. +.TP +\fB\-l, \-\-line\fR +Print only the Content at the given line. +.TP +\fB\-n, \-\-name\fR +Select Object with this name. +.TP +\fB\-o, \-\-object\fR +Print the Object. +.TP +\fB\-p, \-\-pipe\fR +Print using the special pipe format. +.TP +\fB\-O, \-\-original\fR +Print with the original quotes and escapes. +.TP +\fB\-s, \-\-select\fR +Select sub-Content at this index. +.TP +\fB\-t, \-\-total\fR +Print the total number of lines. +.TP +\fB\-T, \-\-trim\fR +Trim Object names on select or print. +.SH FILENAMES +.TP +Any number of files to read. +.SH AUTHOR +Written by Kevin Day. +.SH COPYRIGHT +.PP +Copyright \(co 2007-2023 Kevin Day, GNU LGPL Version 2.1 or later. diff --git a/level_3/fss_payload_write/data/build/settings b/level_3/fss_payload_write/data/build/settings index 46d9aee..ccc4015 100644 --- a/level_3/fss_payload_write/data/build/settings +++ b/level_3/fss_payload_write/data/build/settings @@ -28,6 +28,8 @@ build_sources_program main.c build_sources_headers fss_payload_write.h common.h +build_sources_documentation man + build_script yes build_shared yes build_static no diff --git a/level_3/fss_payload_write/data/documentation/man/man1/fss_payload_write.1 b/level_3/fss_payload_write/data/documentation/man/man1/fss_payload_write.1 new file mode 100644 index 0000000..3bbb97b --- /dev/null +++ b/level_3/fss_payload_write/data/documentation/man/man1/fss_payload_write.1 @@ -0,0 +1,81 @@ +.TH FSS_PAYLOAD_WRITE "1" "January 2023" "FLL - FSS Payload Write 0.6.3" "User Commands" +.SH NAME +fss_payload_write \- Write data in \fBFSS-000E (Payload)\fR format. +.SH SYNOPSIS +.B fss_payload_write +[\fI\,OPTIONS\/\fR] +.SH DESCRIPTION +.PP +The pipe uses the Backspace character '\fB\\b\fR' (U+0008) to designate the start of a Content. +The pipe uses the Form Feed character '\fB\\f\fR' (U+000C) to designate the end of the last Content. +The pipe uses the Vertical Line character '\fB\\v\fR' (U+000B) is used to ignore a Content range, which does nothing in this program. +For the pipe, an Object is terminated by either a Backspace character '\fB\\b\fR' (U+0008) or a Form Feed character '\fB\\f\fR' (U+000C). +The end of the pipe represents the end of any Object or Content. + +The \fBFSS-000E (Payload)\fR specification does not support quoted names, therefore the parameters '\fB\-\-single\fR' and '\fB\-\-double\fR' do nothing. + +This program does not use the parameter '\fB\-\-ignore\fR', which therefore does nothing. +This parameter requires two values. +.SH OPTIONS +.TP +\fB\{+h, ++help\fR +Print the help message. +.TP +\fB+d, ++dark\fR +Output using colors that show up better on dark backgrounds +.TP +\fB+l, ++light\fR +Output using colors that show up better on light backgrounds. +.TP +\fB+n, ++no_color\fR +Do not print using color. +.TP +\fB+Q, ++quiet\fR +Decrease verbosity, silencing most output. +.TP +\fB+E, ++error\fR +Decrease verbosity, using only error output. +.TP +\fB+N, ++normal\fR +Set verbosity to normal. +.TP +\fB+V, ++verbose\fR +Increase verbosity beyond normal output. +.TP +\fB+D, ++debug\fR +Enable debugging, significantly increasing verbosity beyond normal output. +.TP +\fB+v, ++version\fR +Print only the version number. +.TP +\fB\-f, \-\-file\fR +Specify a file to send data to. +.TP +\fB\-c, \-\-content\fR +The Content to write. +.TP +\fB\-d, \-\-double\fR +Use double quotes (default). +.TP +\fB\-I, \-\-ignore\fR +Ignore a given range within a Content. +.TP +\fB\-o, \-\-object\fR +The Object to write. +.TP +\fB\-p, \-\-partial\fR +Do not write a complete Object and Content set. +.TP +\fB\-P, \-\-prepend\fR +Prepend the given white space characters to the start of each multi-line Content. +.TP +\fB\-s, \-\-single\fR +Use single quotes. +.TP +\fB\-T, \-\-trim\fR +Trim Object names. +.SH AUTHOR +Written by Kevin Day. +.SH COPYRIGHT +.PP +Copyright \(co 2007-2023 Kevin Day, GNU LGPL Version 2.1 or later. diff --git a/level_3/fss_status_code/data/documentation/man/man1/fss_status_code.1 b/level_3/fss_status_code/data/documentation/man/man1/fss_status_code.1 index 27abf27..acb2bea 100644 --- a/level_3/fss_status_code/data/documentation/man/man1/fss_status_code.1 +++ b/level_3/fss_status_code/data/documentation/man/man1/fss_status_code.1 @@ -70,4 +70,4 @@ Either code strings, such as \fBF_none\fR, or digits, such as \fB197\fR. Written by Kevin Day. .SH STATUS CODES .PP -Copyright \(co 2023 Kevin Day, GNU LGPL Version 2.1 or later. +Copyright \(co 2007-2023 Kevin Day, GNU LGPL Version 2.1 or later. diff --git a/level_3/iki_read/data/documentation/man/man1/iki_read.1 b/level_3/iki_read/data/documentation/man/man1/iki_read.1 index c2688c8..f15b8df 100644 --- a/level_3/iki_read/data/documentation/man/man1/iki_read.1 +++ b/level_3/iki_read/data/documentation/man/man1/iki_read.1 @@ -109,4 +109,4 @@ Any number of files to read. Written by Kevin Day. .SH COPYRIGHT .PP -Copyright \(co 2023 Kevin Day, GNU LGPL Version 2.1 or later. +Copyright \(co 2007-2023 Kevin Day, GNU LGPL Version 2.1 or later. diff --git a/level_3/iki_write/data/build/settings b/level_3/iki_write/data/build/settings index 1ae6517..c06087b 100644 --- a/level_3/iki_write/data/build/settings +++ b/level_3/iki_write/data/build/settings @@ -16,6 +16,7 @@ build_compiler-clang clang build_indexer ar build_indexer_arguments rcs build_language c + build_libraries -lc build_libraries-individual -lfll_error -lfll_iki -lfll_print -lfll_program -lfl_iki -lfl_print -lfl_string -lf_color -lf_console -lf_conversion -lf_file -lf_iki -lf_memory -lf_pipe -lf_print -lf_signal -lf_string -lf_type_array -lf_utf build_libraries-level -lfll_2 -lfll_1 -lfll_0 diff --git a/level_3/iki_write/data/documentation/man/man1/iki_write.1 b/level_3/iki_write/data/documentation/man/man1/iki_write.1 index e772119..2cc382b 100644 --- a/level_3/iki_write/data/documentation/man/man1/iki_write.1 +++ b/level_3/iki_write/data/documentation/man/man1/iki_write.1 @@ -64,4 +64,4 @@ Use single quotes. Written by Kevin Day. .SH COPYRIGHT .PP -Copyright \(co 2023 Kevin Day, GNU LGPL Version 2.1 or later. +Copyright \(co 2007-2023 Kevin Day, GNU LGPL Version 2.1 or later. diff --git a/level_3/status_code/data/documentation/man/man1/status_code.1 b/level_3/status_code/data/documentation/man/man1/status_code.1 index 727aa7d..3d81b07 100644 --- a/level_3/status_code/data/documentation/man/man1/status_code.1 +++ b/level_3/status_code/data/documentation/man/man1/status_code.1 @@ -68,4 +68,4 @@ Either code strings, such as \fBF_none\fR, or digits, such as \fB197\fR. Written by Kevin Day. .SH COPYRIGHT .PP -Copyright \(co 2023 Kevin Day, GNU LGPL Version 2.1 or later. +Copyright \(co 2007-2023 Kevin Day, GNU LGPL Version 2.1 or later. diff --git a/level_3/utf8/data/documentation/man/man1/utf8.1 b/level_3/utf8/data/documentation/man/man1/utf8.1 index 5eb21e6..c84453e 100644 --- a/level_3/utf8/data/documentation/man/man1/utf8.1 +++ b/level_3/utf8/data/documentation/man/man1/utf8.1 @@ -88,4 +88,4 @@ Any number of characters representing either Unicode codepoints or byte sequence Written by Kevin Day. .SH COPYRIGHT .PP -Copyright \(co 2023 Kevin Day, GNU LGPL Version 2.1 or later. +Copyright \(co 2007-2023 Kevin Day, GNU LGPL Version 2.1 or later.