commit: f5de5c3c6b3fda963433f8d02f7c61676ff012f4
parent ca0f06d0032427d52f90e89ed678050608304ebc
Author: Haelwenn (lanodan) Monnier <contact@hacktivis.me>
Date: Wed, 1 Nov 2023 03:46:21 +0100
Use soelim(1) to unify documentation related to lib/iso_parse
Diffstat:
9 files changed, 171 insertions(+), 144 deletions(-)
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: 2017-2022 Haelwenn (lanodan) Monnier <contact+utils@hacktivis.me>
+# SPDX-FileCopyrightText: 2017-2023 Haelwenn (lanodan) Monnier <contact+utils@hacktivis.me>
# SPDX-License-Identifier: MPL-2.0
/config.mk
@@ -7,6 +7,9 @@
!/cmd/*.c
!/cmd/*.ha
!/cmd/*.1
+!/cmd/*.1.in
+/cmd/date.1
+/cmd/touch.1
*.t.err
*.o
diff --git a/Makefile b/Makefile
@@ -3,7 +3,7 @@
include config.mk
-all: $(EXE)
+all: $(EXE) $(MAN1SO)
.c:
rm -f ${<:=.gcov} ${@:=.gcda} ${@:=.gcno}
@@ -19,7 +19,7 @@ check: all test-lib/strtodur
MALLOC_CHECK_=3 POSIX_ME_HARDER=1 POSIXLY_CORRECT=1 $(CRAM) test-cmd/*.t
.PHONY: lint
-lint:
+lint: $(MAN1SO)
$(SHELLCHECK) ./configure ./test_functions.sh
${FLAWFINDER} --error-level=4 .
$(MANDOC) -Tlint -Wunsupp,error,warning $(MAN1)
@@ -48,10 +48,16 @@ cmd/date: cmd/date.c lib/iso_parse.c Makefile
rm -f ${<:=.gcov} ${@:=.gcda} ${@:=.gcno}
$(CC) -std=c99 $(CFLAGS) -o $@ cmd/date.c lib/iso_parse.c $(LDFLAGS)
+cmd/date.1: cmd/date.1.in lib/iso_parse.mdoc Makefile
+ $(SOELIM) -r cmd/date.1.in > cmd/date.1
+
cmd/touch: cmd/touch.c lib/iso_parse.c Makefile
rm -f ${<:=.gcov} ${@:=.gcda} ${@:=.gcno}
$(CC) -std=c99 $(CFLAGS) -o $@ cmd/touch.c lib/iso_parse.c $(LDFLAGS)
+cmd/touch.1: cmd/touch.1.in lib/iso_parse.mdoc Makefile
+ $(SOELIM) -r cmd/touch.1.in > cmd/touch.1
+
cmd/sleep: cmd/sleep.c lib/strtodur.c Makefile
rm -f ${<:=.gcov} ${@:=.gcda} ${@:=.gcno}
$(CC) -std=c99 $(CFLAGS) -o $@ cmd/sleep.c lib/strtodur.c $(LDFLAGS)
diff --git a/README.md b/README.md
@@ -18,6 +18,7 @@ Tested on Linux(musl), FreeBSD, NetBSD, OpenBSD: <https://builds.sr.ht/~lanodan/
## Dependencies
- POSIX System
+- `soelim` (as present in GNU groff and mandoc)
- (optional, test) ATF: <https://github.com/jmmv/atf>
- (optional, test) Kyua: <https://github.com/jmmv/kyua>
- (optional, test) bwrap: <https://github.com/containers/bubblewrap/> For safely overlaying false files on the root filesystem
diff --git a/cmd/date.1 b/cmd/date.1
@@ -1,55 +0,0 @@
-.\" utils-std: Collection of commonly available Unix tools
-.\" Copyright 2017-2022 Haelwenn (lanodan) Monnier <contact+utils@hacktivis.me>
-.\" SPDX-License-Identifier: MPL-2.0
-.Dd 2023-06-03
-.Dt DATE 1
-.Os
-.Sh NAME
-.Nm date
-.Nd display date and time
-.Sh SYNOPSIS
-.Nm
-.Op Fl u
-.Op Fl d Ar datetime
-.Op Cm + Ns Ar format
-.Sh DESCRIPTION
-When
-.Nm
-is invoked without arguments it displays the current datetime
-Otherwise, depending on the options specified, will print the datetime in a user-defined way.
-.Bl -tag -width Ds
-.It Fl d Ar datetime
-.Ar datetime
-can contain the Unix timestamp (number of seconds before and after 1970-01-01T00:00:00Z) prefixed by an @ (at) symbol,
-or a date-time formatted as
-.Ql YYYY-MM-DDThh:mm:SS[frac][Z] ,
-see
-.Xr touch 1
-for more details on the format.
-.It Fl u
-Use UTC (coordinated universal time) instead of the local time.
-.El
-.Pp
-The plus operand
-.Pq Sq +
-specifies in which format the datetime should be displayed, the format string is specified in the
-.Xr strftime 3
-manual page.
-.Sh ENVIRONMENT
-Look at the manual page of
-.Xr strftime 3
-for the environment variables, typical ones are
-.Ev TZ ,
-.Ev LC_TIME and
-.Ev LC_ALL but that depends on your system.
-.Sh EXIT STATUS
-.Ex -std
-.Sh SEE ALSO
-.Xr strftime 3
-.Sh STANDARDS
-.Nm
-is mostly compliant with the
-.St -p1003.1-2008
-specification.
-.Sh AUTHORS
-.An Haelwenn (lanodan) Monnier Aq Mt contact@hacktivis.me
diff --git a/cmd/date.1.in b/cmd/date.1.in
@@ -0,0 +1,49 @@
+.\" utils-std: Collection of commonly available Unix tools
+.\" Copyright 2017-2022 Haelwenn (lanodan) Monnier <contact+utils@hacktivis.me>
+.\" SPDX-License-Identifier: MPL-2.0
+.Dd 2023-06-03
+.Dt DATE 1
+.Os
+.Sh NAME
+.Nm date
+.Nd display date and time
+.Sh SYNOPSIS
+.Nm
+.Op Fl u
+.Op Fl d Ar datetime
+.Op Cm + Ns Ar format
+.Sh DESCRIPTION
+When
+.Nm
+is invoked without arguments it displays the current datetime
+Otherwise, depending on the options specified, will print the datetime in a user-defined way.
+.Bl -tag -width Ds
+.It Fl d Ar datetime
+.so lib/iso_parse.mdoc
+.It Fl u
+Use UTC (coordinated universal time) instead of the local time.
+.El
+.Pp
+The plus operand
+.Pq Sq +
+specifies in which format the datetime should be displayed, the format string is specified in the
+.Xr strftime 3
+manual page.
+.Sh ENVIRONMENT
+Look at the manual page of
+.Xr strftime 3
+for the environment variables, typical ones are
+.Ev TZ ,
+.Ev LC_TIME and
+.Ev LC_ALL but that depends on your system.
+.Sh EXIT STATUS
+.Ex -std
+.Sh SEE ALSO
+.Xr strftime 3
+.Sh STANDARDS
+.Nm
+is mostly compliant with the
+.St -p1003.1-2008
+specification.
+.Sh AUTHORS
+.An Haelwenn (lanodan) Monnier Aq Mt contact@hacktivis.me
diff --git a/cmd/touch.1 b/cmd/touch.1
@@ -1,85 +0,0 @@
-.\" utils-std: Collection of commonly available Unix tools
-.\" Copyright 2023 Haelwenn (lanodan) Monnier <contact+utils@hacktivis.me>
-.\" SPDX-License-Identifier: MPL-2.0
-.Dd 2023-06-03
-.Dt TOUCH 1
-.Os
-.Sh NAME
-.Nm touch
-.Nd change file access and modification times
-.Sh SYNOPSIS
-.Nm
-.Op Fl achm
-.Op Fl d Ar datetime | Fl r Ar ref_file
-.Ar file...
-.Sh DESCRIPTION
-.Nm
-changes the date modification and access times on each
-.Ar file
-it is given.
-.Bl -tag -width Ds
-.It Fl a
-Change the access time, no changes to modification time unless
-.Fl m
-is also given.
-.It Fl c
-Do not create
-.Ar file .
-.It Fl h
-Do not follow symlinks.
-.It Fl m
-Change the modification time, no changes to access time unless
-.Fl a
-is also given.
-.It Fl d Ar datetime
-Use the specified
-.Ar datetime
-instead of the current time.
-Should be formatted as
-.Ql YYYY-MM-DDThh:mm:SS[frac][Z] ,
-where:
-.Bl -tag -width Ds
-.It Ql YYYY-MM-DD
-Corresponds to %Y-%m-%d of
-.Xr strptime 3 .
-.It Ql T
-Is either
-.Ql T
-or a space.
-.It Ql [frac]
-Is either empty, or fractional seconds starting with either a comma
-.Pq \&,
-or a period
-.Pq \&. .
-.It Ql [Z]
-Is either empty, signifying local time, or the letter
-.Qq Z ,
-signifying UTC.
-.El
-.Pp
-For example:
-.Ql 2003-06-02T13:37:42.713Z
-.It Fl r Ar ref_file
-Use the corresponding times of the file at
-.Ar ref_file
-instead of the current time.
-.El
-.Sh EXIT STATUS
-.Ex -std
-Note: Will exit with failure when
-.Fl c
-is given but the file doesn't exists.
-.Sh SEE ALSO
-.Xr stat 1 ,
-.Xr futimens 3
-.Sh STANDARDS
-.Nm
-is mostly compliant with the
-.St -p1003.1-2008
-specification.
-.Fl t
-is intentionally missing.
-.Fl h
-is an extension.
-.Sh AUTHORS
-.An Haelwenn (lanodan) Monnier Aq Mt contact@hacktivis.me
diff --git a/cmd/touch.1.in b/cmd/touch.1.in
@@ -0,0 +1,59 @@
+.\" utils-std: Collection of commonly available Unix tools
+.\" Copyright 2023 Haelwenn (lanodan) Monnier <contact+utils@hacktivis.me>
+.\" SPDX-License-Identifier: MPL-2.0
+.Dd 2023-06-03
+.Dt TOUCH 1
+.Os
+.Sh NAME
+.Nm touch
+.Nd change file access and modification times
+.Sh SYNOPSIS
+.Nm
+.Op Fl achm
+.Op Fl d Ar datetime | Fl r Ar ref_file
+.Ar file...
+.Sh DESCRIPTION
+.Nm
+changes the date modification and access times on each
+.Ar file
+it is given.
+.Bl -tag -width Ds
+.It Fl a
+Change the access time, no changes to modification time unless
+.Fl m
+is also given.
+.It Fl c
+Do not create
+.Ar file .
+.It Fl h
+Do not follow symlinks.
+.It Fl m
+Change the modification time, no changes to access time unless
+.Fl a
+is also given.
+.It Fl d Ar datetime
+.so lib/iso_parse.mdoc
+.It Fl r Ar ref_file
+Use the corresponding times of the file at
+.Ar ref_file
+instead of the current time.
+.El
+.Sh EXIT STATUS
+.Ex -std
+Note: Will exit with failure when
+.Fl c
+is given but the file doesn't exists.
+.Sh SEE ALSO
+.Xr stat 1 ,
+.Xr futimens 3
+.Sh STANDARDS
+.Nm
+is mostly compliant with the
+.St -p1003.1-2008
+specification.
+.Fl t
+is intentionally missing.
+.Fl h
+is an extension.
+.Sh AUTHORS
+.An Haelwenn (lanodan) Monnier Aq Mt contact@hacktivis.me
diff --git a/configure b/configure
@@ -19,6 +19,7 @@ Variables:
MSGFMT=BIN
CC=BIN
MAKE=BIN
+ SOELIM=BIN
MANDOC=BIN
SHELLCHECK=BIN
FLAWFINDER=BIN
@@ -63,7 +64,11 @@ gen_targets() {
printf '%s\n ' cmd/*.c | grep -v -f target_filter | sed 's;.c$;;' | tr -d '\n'
echo
- printf 'MAN1 = '
+ printf 'MAN1SO = '
+ printf '%s\n ' cmd/*.1.in | grep -v -f target_filter | sed 's;\.in$;;' | tr -d '\n'
+ echo
+
+ printf 'MAN1 = ${MAN1SO} '
printf '%s\n ' cmd/*.1 | grep -v -f target_filter | tr -d '\n'
echo
}
@@ -92,6 +97,7 @@ MAKE="${MAKE:-make}"
GCOV="${GCOV:-gcov}"
# -DDEBUG: Otherwise assert() does nothing, fine to be removed in production
CFLAGS="${CFLAGS:--g -O2 -DDEBUG}"
+SOELIM="${SOELIM:-soelim}"
MANDOC="${MANDOC:-mandoc}"
SHELLCHECK="${SHELLCHECK:-shellcheck}"
FLAWFINDER="${FLAWFINDER:-flawfinder}"
@@ -140,6 +146,7 @@ rm -f config.mk && echo '#' > target_filter ; or_die
check_cmd PKGCONFIG "$PKGCONFIG" || exit 1
check_cmd CC "$CC" || exit 1
check_cmd MAKE "$MAKE" || exit 1
+check_cmd SOELIM "$SOELIM" || exit 1
if check_cmd GCOV "$GCOV"
then
@@ -220,6 +227,7 @@ MANDIR = ${MANDIR}
PKGCONFIG = ${PKGCONFIG}
CC = ${CC}
MAKE = ${MAKE}
+SOELIM = ${SOELIM}
MANDOC = ${MANDOC}
SHELLCHECK = ${SHELLCHECK}
FLAWFINDER = ${FLAWFINDER}
diff --git a/lib/iso_parse.mdoc b/lib/iso_parse.mdoc
@@ -0,0 +1,41 @@
+.\" utils-std: Collection of commonly available Unix tools
+.\" Copyright 2023 Haelwenn (lanodan) Monnier <contact+utils@hacktivis.me>
+.\" SPDX-License-Identifier: MPL-2.0
+.\"
+.\" Example:
+.\" .Fl d Ar datetime
+.\" .so lib/iso_parse.mdoc
+.\"
+Should be formatted either with a leading @ (at) symbol followed by
+the Unix timestamp (number of seconds before and after 1970-01-01 00:00:00Z).
+for example
+.Ql @1698791420
+corresponds to 2023-10-31 23:30:20 UTC
+.Pp
+Or as
+.Ql YYYY-MM-DDThh:mm:SS[frac][Z] ,
+where:
+.Bl -tag -width Ds
+.It Ql YYYY-MM-DD
+Corresponds to %Y-%m-%d of
+.Xr strptime 3 .
+.It Ql T
+Is either
+.Ql T
+or a space.
+.It Ql [frac]
+Is either empty, or fractional seconds starting with either a comma
+.Pq \&,
+or a period
+.Pq \&. .
+.It Ql [Z]
+Is either empty, signifying local time, or the letter
+.Qq Z ,
+signifying UTC.
+.Pp
+This is the only part which disagrees with RFC3339 due to the lack of timezone-offset parsing in
+.St -p1003.1-2008
+.El
+.Pp
+For example:
+.Ql 2003-06-02T13:37:42.713Z
