Package: at
Version: 3.2.5-2.1
Severity: minor
Tags: patch
* What led up to the situation?
Checking for defects with
test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z < "man page"
[Use "groff -e ' $' <file>" to find trailing spaces.]
["test-groff" is a script in the repository for "groff"; is not shipped]
(local copy and "troff" slightly changed by me).
[The fate of "test-nroff" was decided in groff bug #55941.]
* What was the outcome of this action?
troff: backtrace: file '<stdin>':246
troff:<stdin>:246: warning: trailing space in the line
* What outcome did you expect instead?
No output (no warnings).
-.-
General remarks and further material, if a diff-file exist, are in the
attachments.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.11.10-amd64 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1),
LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)
Versions of packages at depends on:
ii libc6 2.40-3
ii libpam-runtime 1.5.3-7
ii libpam0g 1.5.3-7+b1
ii libselinux1 3.7-3+b1
ii lsb-base 11.6
ii sysvinit-utils [lsb-base] 3.11-1
Versions of packages at recommends:
ii exim4-daemon-light [mail-transport-agent] 4.98-2
at suggests no packages.
-- Configuration Files:
/etc/at.deny [Errno 13] Permission denied: '/etc/at.deny'
-- no debconf information
Input file is at.1
Any program (person), that produces man pages, should check the output
for defects by using (both groff and nroff)
[gn]roff -mandoc -t -ww -b -z -K utf8 <man page>
The same goes for man pages that are used as an input.
For a style guide use
mandoc -T lint
-.-
So any 'generator' should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
This is just a simple quality control measure.
The 'generator' may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Input text line longer than 80 bytes.
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
Not beginning each input sentence on a new line.
Lines should thus be shorter.
See man-pages(7), item 'semantic newline'.
-.-
The difference between the formatted output of the original and patched file
can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -u <out1> <out2>
and for groff, using
"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -mandoc -Z - "
instead of 'nroff -mandoc'
Add the option '-t', if the file contains a table.
Read the output of 'diff -u' with 'less -R' or similar.
-.-.
If 'man' (man-db) is used to check the manual for warnings,
the following must be set:
The option "-warnings=w"
The environmental variable:
export MAN_KEEP_STDERR=yes (or any non-empty value)
or
(produce only warnings):
export MANROFFOPT="-ww -b -z"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-.
Output from "mandoc -T lint at.1 ": (shortened list)
1 input text line longer than 80 bytes
1 whitespace at end of input line
-.-.
Output from "test-groff -mandoc -t -ww -b -z at.1 ": (shortened list)
1 trailing space in the line
-.-.
Output from "mandoc -T lint at.1 ":
mandoc: at.1:82:87: STYLE: input text line longer than 80 bytes: executes
commands wh...
mandoc: at.1:246:14: STYLE: whitespace at end of input line
-.-.
Remove space characters at the end of lines.
Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".
246:Sends mail to
-.-.
Use the correct macro for the font change of a single argument or
split the argument into two.
34:.RB \-l
-.-.
Change a HYPHEN-MINUS (code 0x2D) to a minus(-dash) (\-),
if it
is in front of a name for an option,
is a symbol for standard input,
is a single character used to indicate an option,
or is in the NAME section (man-pages(7)).
N.B. - (0x2D), processed as a UTF-8 file, is changed to a hyphen
(0x2010, groff \[u2010] or \[hy]) in the output.
35:.RB [ -o
44:.RB [ -o
-.-.
Split lines longer than 80 characters into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
Line 82, length 87
executes commands when system load levels permit; in other words, when the load
average
-.-.
Split a punctuation from a single argument, if a two-font macro is meant
94:.B midnight,
95:.B noon,
109:.B year,
123:.I time-units,
125:.B minutes,
126:.B hours,
127:.B days,
135:.B tomorrow.
262:.B atq.
266:.B atrm.
270:.B atrm.
-.-.
Two or more space charaters between printable characters.
When the distance is between sentences,
start the beginning of the second one on a separate line
("semantic newline", see man-pages(7)).
75:case, everybody's jobs are listed. The format of the output lines (one
88:specifications, extending the POSIX.2 standard. It accepts times
145:the past, the job will run as soon as possible. For example, if it is
175:are also not exported. This may change in the future. As a workaround,
227:Queues with higher letters run with increased niceness. The special
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":
troff: backtrace: file '<stdin>':246
troff:<stdin>:246: warning: trailing space in the line
--- at.1 2024-12-02 01:03:41.042845450 +0000
+++ at.1.new 2024-12-02 01:36:01.587349321 +0000
@@ -27,24 +27,22 @@ at, batch, atq, atrm \- queue, examine,
.br
.B "at \-c"
.I job
-[...\&]
+[...]
.br
.B at
.RB [ \-V ]
-.RB \-l
-.RB [ -o
+.B \-l
+.RB [ \-o
.IR timeformat ]
-.I [job
-.IR ... ]
+.RI [ job " ...]
.br
.B atq
.RB [ \-V ]
.RB [ \-q
.IR queue ]
-.RB [ -o
+.RB [ \-o
.IR timeformat ]
-.I [job
-.IR ... ]
+.RI [ job " ...]
.br
.B at
.RB [ \-rd ]
@@ -54,7 +52,7 @@ at, batch, atq, atrm \- queue, examine,
.B atrm
.RB [ \-V ]
.I job
-[...\&]
+[...]
.br
.B batch
.br
@@ -63,36 +61,43 @@ at, batch, atq, atrm \- queue, examine,
.B at
and
.B batch
-read commands from standard input or a specified file which are to
-be executed at a later time, using
+read commands from standard input
+or a specified file
+which are to be executed at a later time,
+using
.BR /bin/sh .
.TP 8
.B at
executes commands at a specified time.
.TP 8
.B atq
-lists the user's pending jobs, unless the user is the superuser; in that
-case, everybody's jobs are listed. The format of the output lines (one
-for each job) is: Job number, date, hour, queue, and username.
+lists the user's pending jobs,
+unless the user is the superuser;
+in that case, everybody's jobs are listed.
+The format of the output lines (one for each job) is:
+Job number, date, hour, queue, and username.
.TP 8
.B atrm
deletes jobs, identified by their job number.
.TP 8
.B batch
-executes commands when system load levels permit; in other words, when the
load average
-drops below 1.5, or the value specified in the invocation of
+executes commands
+when system load levels permit;
+in other words,
+when the load average drops below 1.5,
+or the value specified in the invocation of
.BR atd .
.PP
.B At
-allows fairly complex time
-specifications, extending the POSIX.2 standard. It accepts times
-of the form
+allows fairly complex time specifications,
+extending the POSIX.2 standard.
+It accepts times of the form
.B HH:MM
to run a job at a specific time of day.
(If that time is already past, the next day is assumed.)
You may also specify
-.B midnight,
-.B noon,
+.BR midnight ,
+.BR noon ,
or
.B teatime
(4pm)
@@ -106,7 +111,7 @@ by giving a date in the form
.B month-name
.B day
with an optional
-.B year,
+.BR year ,
or giving a date of the form
.IR MMDD [ CC ] YY ,
.IR MM / DD /[ CC ] YY ,
@@ -120,11 +125,11 @@ You can also give times like
.B now
.B +
.I count
-.I time-units,
+.IR time-units ,
where the time-units can be
-.B minutes,
-.B hours,
-.B days,
+.BR minutes ,
+.BR hours ,
+.BR days ,
or
.B weeks
and you can tell
@@ -132,18 +137,24 @@ and you can tell
to run the job today by suffixing the time with
.B today
and to run the job tomorrow by suffixing the time with
-.B tomorrow.
+.BR tomorrow .
.PP
-For example, to run a job at 4pm three days from now, you would do
+For example,
+to run a job at 4pm three days from now,
+you would do
.B at 4pm + 3 days,
-to run a job at 10:00am on July 31, you would do
+to run a job at 10:00am on July 31,
+you would do
.B at 10am Jul 31
-and to run a job at 1am tomorrow, you would do
+and to run a job at 1am tomorrow,
+you would do
.B at 1am tomorrow.
.PP
If you specify a job to absolutely run at a specific time and date in
-the past, the job will run as soon as possible. For example, if it is
-8pm and you do a
+the past,
+the job will run as soon as possible.
+For example,
+if it is 8pm and you do a
.B at 6pm today,
it will run more likely at 8:05pm.
.PP
@@ -152,8 +163,8 @@ The definition of the time specification
.PP
For both
.BR at " and " batch ,
-commands are read from standard input or the file specified
-with the
+commands are read from standard input
+or the file specified with the
.B \-f
option and executed.
The working directory, the environment (except for the variables
@@ -170,9 +181,12 @@ and the umask are retained from the time
As
.B at
-is currently implemented as a setuid program, other environment variables
(e.g.,
+is currently implemented as a setuid program,
+other environment variables (e.g.,
.BR LD_LIBRARY_PATH " or " LD_PRELOAD )
-are also not exported. This may change in the future. As a workaround,
+are also not exported.
+This may change in the future.
+As a workaround,
set these variables explicitly in your job.
An
@@ -182,18 +196,21 @@ or
command invoked from a
.BR su (1)
shell will retain the current userid.
-The user will be mailed standard error and standard output from his
-commands, if any.
+The user will be mailed standard error
+and standard output from his commands,
+if any.
Mail will be sent using the command
.BR /usr/sbin/sendmail .
If
.B at
is executed from a
.BR su (1)
-shell, the owner of the login shell will receive the mail.
+shell,
+the owner of the login shell will receive the mail.
.PP
The superuser may use these commands in any case.
-For other users, permission to use at is determined by the files
+For other users,
+permission to use at is determined by the files
.I /etc/at.allow
and
.IR /etc/at.deny .
@@ -207,8 +224,8 @@ prints the version number to standard er
.TP 8
.BI \-q " queue"
uses the specified queue.
-A queue designation consists of a single letter; valid queue designations
-range from
+A queue designation consists of a single letter;
+valid queue designations range from
.B a
to
.B z
@@ -224,26 +241,29 @@ and the
.B b
queue for
.BR batch .
-Queues with higher letters run with increased niceness. The special
-queue "=" is reserved for jobs which are currently running.
+Queues with higher letters run with increased niceness.
+The special queue "=" is reserved for jobs which are currently running.
.P
-If a job is submitted to a queue designated with an uppercase letter, the
-job is treated as if it were submitted to batch at the time of the job.
-Once the time is reached, the batch processing rules with respect to load
-average apply.
+If a job is submitted to a queue designated with an uppercase letter,
+the job is treated
+as if it were submitted to batch at the time of the job.
+Once the time is reached,
+the batch processing rules with respect to load average apply.
If
.B atq
-is given a specific queue, it will only show jobs pending in that queue.
+is given a specific queue,
+it will only show jobs pending in that queue.
.TP 8
.B \-m
-Send mail to the user when the job has completed even if there was no
-output.
+Send mail to the user
+when the job has completed
+even if there was no output.
.TP 8
.B \-M
Never send mail to the user.
.TP 8
.BI \-u " username"
-Sends mail to
+Sends mail to
.I username
rather than the current user.
.TP 8
@@ -259,15 +279,15 @@ given in the format [[CC]YY]MMDDhhmm[.ss
.TP 8
.B \-l
Is an alias for
-.B atq.
+.BR atq .
.TP
.B \-r
Is an alias for
-.B atrm.
+.BR atrm .
.TP
.B \-d
Is an alias for
-.B atrm.
+.BR atrm .
.TP
.B \-b
is an alias for
@@ -314,21 +334,23 @@ type directory mounted on
.PP
If the file
.I /var/run/utmp
-is not available or corrupted, or if the user is not logged on at the
-time
+is not available or corrupted,
+or if the user is not logged on at the time
.B at
-is invoked, the mail is sent to the userid found
-in the environment variable
+is invoked,
+the mail is sent to the userid found in the environment variable
.BR LOGNAME .
-If that is undefined or empty, the current userid is assumed.
+If that is undefined or empty,
+the current userid is assumed.
.PP
.B At
and
.B batch
-as presently implemented are not suitable when users are competing for
-resources.
-If this is the case for your site, you might want to consider another
-batch system, such as
+as presently implemented are not suitable
+when users are competing for resources.
+If this is the case for your site,
+you might want to consider another batch system,
+ such as
.BR nqs .
.SH AUTHOR
At was mostly written by Thomas Koenig.
