From: kopp Date: Sat, 30 Nov 2024 16:58:31 +0000 (+0100) Subject: fix wording in documentation to make it simpler to follow (#36) X-Git-Tag: ver3_3_2~1^2 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=d89f49956844c49892c6a44f1d1eb0083311d83a;p=thirdparty%2Ffcron.git fix wording in documentation to make it simpler to follow (#36) * fix wording in documentation to make it simpler to follow * further improve documentation by reacting to comments in https://github.com/yo8192/fcron/pull/36 * fix necessary dependencies for building documentation * further improve documentation by reacting to comments in https://github.com/yo8192/fcron/pull/36 --- diff --git a/README.md b/README.md index 9fac02b..4438bc2 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Alternatively, if you downloaded fcron as a tarball, see: If you cloned the git repo, you first need to build the documentation. On a Debian based system: ``` -$ sudo apt install -y docbook docbook-xsl docbook-xml docbook-utils manpages-dev +$ sudo apt install -y autoconf build-essential docbook docbook-xsl docbook-xml docbook-utils manpages-dev $ autoconf $ ./configure # optionally, use: --without-sendmail $ make updatedoc diff --git a/doc/en/fcron.8.sgml b/doc/en/fcron.8.sgml index 5c3ce05..653e8a2 100644 --- a/doc/en/fcron.8.sgml +++ b/doc/en/fcron.8.sgml @@ -121,9 +121,8 @@ compiled to run in foreground as default. num - Set to num the maximum number - of serial jobs which can run simultaneously. By default, - this value is set to &serialmaxrunning;. + Run at most num serial jobs + simultaneously. By default, this value is set to &serialmaxrunning;. &seealso; option &optserial; in &fcrontab;(5). @@ -131,8 +130,14 @@ compiled to run in foreground as default. num num - Set to n the number of jobs the serial queue and -the lavg queue can contain. + Sets the sizes of the queues that are used to manage serial + jobs and the lavg queue each to num. + This means that + (A) at most num serial jobs can be + in the waiting state and + (B) at most num jobs can wait until the + system average load drops below a certain value. + @@ -145,7 +150,7 @@ the lavg queue can contain. &etc;/&fcron.conf.location;. To interact with that running &fcron; process, &fcrontab; must use the same config file (which is defined by &fcrontab;'s option ). That way, several &fcron; processes -can run simultaneously on an only system (but each &fcron; process *must* have a +can run simultaneously on a single system (but each &fcron; process *must* have a different spool dir and pid file from the other processes). diff --git a/doc/en/fcron.conf.5.sgml b/doc/en/fcron.conf.5.sgml index afc25fe..efb0990 100644 --- a/doc/en/fcron.conf.5.sgml +++ b/doc/en/fcron.conf.5.sgml @@ -34,8 +34,8 @@ A copy of the license is included in gfdl.sgml. - Blank lines, line beginning by a hash sign (#) (which are - considered comments), leading blanks and tabs are ignored. Each line in a + Blank lines, lines beginning with a hash sign (#) (which are + considered as comments), leading blanks and tabs are ignored. Each line in a &fcron.conf; file is of the form
name = value diff --git a/doc/en/fcrondyn.1.sgml b/doc/en/fcrondyn.1.sgml index 2f207a0..3f762e1 100644 --- a/doc/en/fcrondyn.1.sgml +++ b/doc/en/fcrondyn.1.sgml @@ -72,7 +72,7 @@ and a list of commands. file instead of default config file &etc;/&fcron.conf.location;. To interact with a running &fcron; process, &fcrondyn; must use the same config file as the process. That -way, several &fcron; processes can run simultaneously on an only system. +way, several &fcron; processes can run simultaneously on a single system. diff --git a/doc/en/fcrontab.1.sgml b/doc/en/fcrontab.1.sgml index e8201fd..9b53f28 100644 --- a/doc/en/fcrontab.1.sgml +++ b/doc/en/fcrontab.1.sgml @@ -18,7 +18,7 @@ A copy of the license is included in gfdl.sgml. fcrontab manipulate per-user fcrontab - files + files which adhere to the format defined in &fcrontab;(5) @@ -53,33 +53,41 @@ A copy of the license is included in gfdl.sgml. linkend="fcron.8">&fcron;(8) daemon. As &fcron; internally uses a non-human readable format (this is needed because &fcron; saves more informations than the user gives, for example the time - and date of next execution), the user cannot edit directly his - &fcrontabf; (the one used by &fcron;). When a user + and date of next execution), the user cannot edit their &fcrontabf; + directly (the one used by &fcron;). When a user installs a &fcrontabf;, the source file is saved in the spool - directory (&fcrontabsdir;) to allow future - editions, and a formatted file is generated for the &fcron; daemon, - which is signaled once about ten seconds before the next minute for - all changes made previously. The daemon is not informed of the changes - immediately but at most once a minute + directory (&fcrontabsdir;) to allow it to be + edited, and a formatted file is generated for the &fcron; daemon. + This formatted (non human readable) file with all recent changes + included is then sent to the daemon. + The daemon is not informed of the changes immediately but after some time to keep ill disposed users from blocking the daemon by installing - &fcrontabf;s over and over (ie. denial of service attack). We will call + &fcrontabf;s over and over (i.e. denial of service attack). + By default, the file is sent once per minute (about ten seconds before + the full minute) to the daemon, the build time parameter + + can be used to specify a different maximum time to send this data. + We will call "fcrontab" the source file of the &fcrontabf; - in the following. A user can install a &fcrontabf; if - he is listed in the &etc;/&fcron.allow; and not - (unless by the keyword all) listed in + in the following. + The fcrontab files that a user modifies has to follow the format + defined in &fcrontab;(5) . + Users can install a &fcrontabf; if + they are listed in &etc;/&fcron.allow; and not listed in &etc;/&fcron.deny; (see section "files" below). If neither + linkend="fcrontab.1.files">files" below). + The keyword 'all' is a shorthand for all users. If neither fcron.allow nor fcron.deny exist, all users are allowed. None of these files have to exist, but if they do, the deny file takes precedence. The first form of the command is used to install a new &fcrontabf; file, from - any named file or from standard input if the pseudo-filename "-" is - given, replacing the previous one (if any): each user can have only + any named file or from standard input (if the pseudo-filename "-" is + given), replacing the previous one (if any). Each user can have only one &fcrontabf;. For instance, root can create a systemwide fcrontab file, say /etc/fcrontab, and run "fcrontab /etc/fcrontab" to install the new version after - each change of the file. Or (s)he can create a new fcrontab running + each change of the file. Or root can create a new fcrontab running a simple "fcrontab", and then maintain it using "fcrontab ". Same considerations apply to a non privileged user. @@ -154,7 +162,7 @@ A copy of the license is included in gfdl.sgml. file &etc;/&fcron.conf.location;. To interact with a running &fcron; process, &fcrontab; must use the same config file as the process. That way, several - &fcron; processes can run simultaneously on an only + &fcron; processes can run simultaneously on a single system. diff --git a/doc/en/fcrontab.5.sgml b/doc/en/fcrontab.5.sgml index a91f68d..a4fd450 100644 --- a/doc/en/fcrontab.5.sgml +++ b/doc/en/fcrontab.5.sgml @@ -19,7 +19,7 @@ A copy of the license is included in gfdl.sgml. fcrontab - tables for driving fcron + file format to define the jobs that fcron should run, and their schedules. @@ -27,7 +27,8 @@ A copy of the license is included in gfdl.sgml. A &fcrontabf; is a file containing all tables used by the &fcron;(8) daemon. In other words, it is the means for a user to tell the daemon "execute this command at this moment". Each user has their own &fcrontabf;, whose -commands are executed as their owner (only root can run a job as another using the +commands are executed on behalf of their owner (in particular with the users +permissions -- only root can run a job as another using the option &optrunas; (see below)). Blank lines, line beginning by a hash sign (#) (which are considered comments), leading blanks and tabs are ignored. Each line in a @@ -522,7 +523,7 @@ abbreviation. The options are (default value in parentheses): b boolean(false) - Run an &-line at &fcron;'s startup (or system's resume after suspend/hibernation) if it should + Run an &-line (i.e. based on date and time) at &fcron;'s startup (or system's resume after suspend/hibernation) if it should have run during system down time. diff --git a/doc/en/readme.sgml b/doc/en/readme.sgml index 780278c..e0a6fdc 100644 --- a/doc/en/readme.sgml +++ b/doc/en/readme.sgml @@ -17,16 +17,17 @@ A copy of the license is included in gfdl.sgml. Cron, so it implements most of its functionalities. But contrary to Vixie Cron, &fcron; does not need your system to be up 7 days a week, 24 hours a day: it also works -well with systems which are not running neither all the time nor regularly +well with systems which are neither running all the time nor regularly (contrary to anacrontab). In other words, &fcron; does both the job of Vixie Cron and anacron, but does even more and better :)) ... To do so, &fcron; allows you to use the standard mode in which you -tell it to execute one command at a given date and hour and to make it run a -command according to its time of execution, which is normally the same as system -up time. For example: +tell it to execute one command at a given date and time. Alternatively you can +instruct &fcron; to execute a command after a certain duration of &fcron;'s runtime +(which is normally the same as system up time because &fcron; is typically started +on boot). For example:
Run the task 'save /home/ directory' every 3h15 of system @@ -34,7 +35,7 @@ up time.
and, of course, in order to make it really useful, the time remaining until next execution is saved each time the system is stopped. You can also say: - +
run that command once between 2am and 5am
which will be done if the system is running at any