branch='trunk'
if ! command -v git >/dev/null 2>&1; then
echo 'byggsteg: git is not on this deployment PATH, so the clone cannot be updated' >&2
exit 1
fi
if ! cd "$dir"; then
echo "byggsteg: cannot enter the clone $dir" >&2
exit 1
fi
root=$(git rev-parse --show-toplevel 2>/dev/null)
if [ "$root" != "$(pwd -P)" ]; then
echo "byggsteg: $dir is not a git checkout; remove it and the next run clones it again" >&2
exit 1
fi
if ! origin=$(git remote get-url origin 2>/dev/null); then
echo "byggsteg: $dir has no origin remote to fetch $branch from" >&2
exit 1
fi
before=$(git rev-parse --short HEAD 2>/dev/null) || before=none
attempt=1
while :; do
if GIT_TERMINAL_PROMPT=0 git fetch --quiet origin "+refs/heads/$branch:refs/remotes/origin/$branch"; then
break
fi
if [ "$attempt" -ge 3 ]; then
echo "byggsteg: could not fetch $branch from $origin after 3 attempts; is the branch still there, and is the remote reachable?" >&2
exit 1
fi
echo "byggsteg: fetching $branch from $origin failed; retrying in $((attempt * 2))s" >&2
sleep $((attempt * 2))
attempt=$((attempt + 1))
done
if ! git checkout --quiet --force -B "$branch" FETCH_HEAD; then
echo "byggsteg: fetched $branch from $origin but could not check it out" >&2
exit 1
fi
after=$(git rev-parse --short HEAD)
if [ "$before" = "$after" ]; then
echo "byggsteg: $branch was already at $after"
else
echo "byggsteg: $branch moved from $before to $after"
fi
byggsteg: trunk moved from 52da37f to 78283e3
setupuname -a✓ succeeded1 lines · 0.0s
Linux wolk-jjba 7.2.11-gnu #1 SMP PREEMPT_DYNAMIC 1 x86_64 GNU/Linux
commit 78283e3b85d713489f784bcae56f816f395f3cd7
Author: Josep Bigorra <jjbigorra@gmail.com>
Date: Tue Nov 17 15:36:24 2026 +0100
fix(maak): run the launcher with sh in the docs task
bin/dokgen is a shell script, so handing it to guile failed on its shebang
comment and docs-check never reached the sources.
M maak.scm
runmaak version-check✓ succeeded16 lines · 1.1s
--------------------------------------------------------------
Maak 0.14.0: the infinitely extensible command runner
Loading tasks from Maak file: /etc/byggsteg/job-clone/guile-dokgen/trunk/maak.scm
Executing Maak tasks: version-check
--------------------------------------------------------------
=> Running Maak task: version-check
Fail when a file quotes a version other than the one the source states.
version 0.6.1 is consistent in 4 files;;; note: source file /etc/byggsteg/job-clone/guile-dokgen/trunk/maak.scm
;;; newer than compiled /root/.cache/guile/ccache/3.0-LE-8-4.6/etc/byggsteg/job-clone/guile-dokgen/trunk/maak.scm.go
;;; note: auto-compilation is enabled, set GUILE_AUTO_COMPILE=0
;;; or pass the --no-auto-compile argument to disable.
;;; compiling /etc/byggsteg/job-clone/guile-dokgen/trunk/maak.scm
;;; maak.scm:249:18: warning: non-literal format string
;;; maak.scm:250:16: warning: non-literal format string
;;; maak.scm:262:23: warning: non-literal format string
;;; compiled /root/.cache/guile/ccache/3.0-LE-8-4.6/etc/byggsteg/job-clone/guile-dokgen/trunk/maak.scm.go
testmaak check✓ succeeded31 lines · 5.3s
channels.scm:17:6: warning: channel 'jointhefreeworld' is not trusted
wrote `/tmp/tmp.xz5bpusz3Z'
wrote `/tmp/tmp.Mqi1W2Wrwn'
wrote `/tmp/tmp.OWy9XJjTO2'
wrote `/tmp/tmp.ENgWFamTon'
wrote `/tmp/tmp.0WkDGaMM5Y'
wrote `/tmp/tmp.iMFiYBomXl'
wrote `/tmp/tmp.ISRdUu67f3'
wrote `/tmp/tmp.2iVCwf829h'
wrote `/tmp/tmp.UaRvyp83fD'
wrote `/tmp/tmp.RAkM9A46iq'
wrote `/tmp/tmp.ktPhk7CrJQ'
wrote `/tmp/tmp.m9yTJOG4MO'
wrote `/tmp/tmp.2EsfhLVTVb'
wrote `/tmp/tmp.qIj6n9erI0'
WARNING: Use of `load' in declarative module (#{ g111}#). Add #:declarative? #f to your define-module invocation.
wrote `/tmp/tmp.A2Lulmuh0H'
--------------------------------------------------------------
Maak 0.14.0: the infinitely extensible command runner
Loading tasks from Maak file: /etc/byggsteg/job-clone/guile-dokgen/trunk/maak.scm
Executing Maak tasks: check
--------------------------------------------------------------
=> Running Maak task: check
Compile every source and test module, so a syntax error fails the build.
Each file is compiled on its own, which is what makes one broken file name
itself rather than a pile of them.
Execute command:
guix time-machine --channels=channels.scm -- shell -m manifest.scm -- sh -c 'set -eu
find src tests etc -name '\''*.scm'\'' -print0 | xargs -0 -n 1 sh -c '\''guild compile -L ./src -L . -o "$(mktemp)" "$1"'\'' sh'
Executing: guix time-machine --channels=channels.scm -- shell -m manifest.scm -- sh -c 'set -eu
find src tests etc -name '\''*.scm'\'' -print0 | xargs -0 -n 1 sh -c '\''guild compile -L ./src -L . -o "$(mktemp)" "$1"'\'' sh'
testmaak test✓ succeeded113 lines · 0.6s
channels.scm:17:6: warning: channel 'jointhefreeworld' is not trusted
*** Entering test group: (dokgen data) ***
*** Entering test group: [procedure] file-path->module-name ***
* PASS: Convert Scheme file path to module name (multi-module library).
* PASS: Convert Scheme file path to module name (single-module library).
*** Leaving test group: [procedure] file-path->module-name ***
*** Entering test group: [procedure] group-api-objects ***
* PASS: A «parameters» group exists when the API exports parameters.
* PASS: All parameters exported by the API are included in their group.
* PASS: All objects in the «parameters» group are actually parameters.
* PASS: Raise &residual-export-exception when unbound export is found.
*** Leaving test group: [procedure] group-api-objects ***
*** Leaving test group: (dokgen data) ***
*** Test suite finished. ***
*** # of expected passes : 6
*** Entering test group: (dokgen templates) ***
*** Entering test group: [procedure] api-binding ***
* PASS: Render a binding that holds a record type.
* PASS: Render a binding that holds a record.
* PASS: Render a parameterless procedure.
* PASS: Render a procedure containing @verbatim examples.
* PASS: Render undocumented procedure.
* PASS: Render a documented macro.
* PASS: Render an undocumented macro.
* PASS: Render a parameter.
*** Leaving test group: [procedure] api-binding ***
*** Entering test group: [procedure] module-description ***
* PASS: Render standard module commentary.
* PASS: Render block-commented module commentary.
*** Leaving test group: [procedure] module-description ***
*** Entering test group: [procedure] procedure-parameters ***
* PASS: Render empty parameters.
* XPASS: Render required parameters.
source-file: tests/test-templates-stexi.scm
source-line: 269
source-form: (test-equal
"Render required parameters."
"param1 param2 param3"
(stexi:procedure-parameters required-params))
expected-value: param1 param2 param3
expected-error: #f
actual-value: param1 param2 param3
actual-error: #f
* XPASS: Render optional parameters.
source-file: tests/test-templates-stexi.scm
source-line: 280
source-form: (test-equal
"Render optional parameters."
"OPT: opt1 opt2"
(stexi:procedure-parameters optional-params))
expected-value: OPT: opt1 opt2
expected-error: #f
actual-value: OPT: opt1 opt2
actual-error: #f
* PASS: Render keyword parameters.
* PASS: Render note when arbitrary keyword parameters are allowed.
* PASS: Render args parameter.
*** Leaving test group: [procedure] procedure-parameters ***
*** Leaving test group: (dokgen templates) ***
*** Test suite finished. ***
*** # of expected passes : 14
*** # of unexpected passes : 2
*** Entering test group: (dokgen utils) ***
*** Entering test group: [procedure] min-indent ***
* PASS: Find the shorter number of spaces used for indentation.
* PASS: The indentation of an empty string is zero.
* PASS: The indentation of a single-line string is zero.
*** Leaving test group: [procedure] min-indent ***
*** Entering test group: [procedure] tabs->spaces ***
* PASS: Replace tabs with default number of spaces.
* PASS: Replace tabs with custom number of spaces.
*** Leaving test group: [procedure] tabs->spaces ***
*** Entering test group: [procedure] trim ***
* PASS: Trim off N spaces.
* PASS: Trim off more than N spaces.
*** Leaving test group: [procedure] trim ***
*** Entering test group: [procedure] unindent ***
* PASS: Remove unwanted tab indentation.
* PASS: Remove unwanted space indentation.
* PASS: Leave desired tab indentation.
* PASS: Handle empty docstring.
* PASS: Handle one-line docstring.
*** Leaving test group: [procedure] unindent ***
*** Leaving test group: (dokgen utils) ***
*** Test suite finished. ***
*** # of expected passes : 12
--------------------------------------------------------------
Maak 0.14.0: the infinitely extensible command runner
Loading tasks from Maak file: /etc/byggsteg/job-clone/guile-dokgen/trunk/maak.scm
Executing Maak tasks: test
--------------------------------------------------------------
=> Running Maak task: test
Run every test file under tests/.
SRFI-64 never turns a failure into an exit status, so each file goes through
`etc/run-test.scm', which does. The `test-module-*' files are fixtures the
suites document, not suites.
Execute command:
guix time-machine --channels=channels.scm -- shell -m manifest.scm -- sh -c 'set -eu
status=0
for file in tests/test-*.scm; do
case $file in tests/test-module-*) continue ;; esac
guile -L ./src -L . etc/run-test.scm "$file" || status=1
done
rm -f ./*.log
exit $status'
Executing: guix time-machine --channels=channels.scm -- shell -m manifest.scm -- sh -c 'set -eu
status=0
for file in tests/test-*.scm; do
case $file in tests/test-module-*) continue ;; esac
guile -L ./src -L . etc/run-test.scm "$file" || status=1
done
rm -f ./*.log
exit $status'
runmaak docs-check✗ failed78 lines · 0.9s
channels.scm:17:6: warning: channel 'jointhefreeworld' is not trusted
;;; note: auto-compilation is enabled, set GUILE_AUTO_COMPILE=0
;;; or pass the --no-auto-compile argument to disable.
;;; compiling /etc/byggsteg/job-clone/guile-dokgen/trunk/bin/../src/dokgen/cli.scm
;;; compiling /etc/byggsteg/job-clone/guile-dokgen/trunk/bin/../src/dokgen/commands.scm
;;; compiling /etc/byggsteg/job-clone/guile-dokgen/trunk/bin/../src/dokgen/writer.scm
;;; compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/writer.scm.go
;;; compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/commands.scm.go
;;; compiled /root/.cache/guile/ccache/3.0-LE-8-4.7/etc/byggsteg/job-clone/guile-dokgen/trunk/src/dokgen/cli.scm.go
API documentation saved to manual/api
--------------------------------------------------------------
Maak 0.14.0: the infinitely extensible command runner
Loading tasks from Maak file: /etc/byggsteg/job-clone/guile-dokgen/trunk/maak.scm
Executing Maak tasks: docs-check
--------------------------------------------------------------
=> Running Maak task: docs-check
Fail when manual/api/index.texi is not what the sources generate.
The reference is generated, so a committed copy that differs from a fresh one
is a procedure that was changed without the documentation following.
Execute command:
guix time-machine --channels=channels.scm -- shell -m manifest.scm -- sh bin/dokgen api --destination manual/api ./src/dokgen
Executing: guix time-machine --channels=channels.scm -- shell -m manifest.scm -- sh bin/dokgen api --destination manual/api ./src/dokgen
diff --git a/manual/api/index.texi b/manual/api/index.texi
index 017dd93..cee0e5e 100644
--- a/manual/api/index.texi
+++ b/manual/api/index.texi
@@ -14,9 +14,8 @@ The following is the list of modules provided by this library.
@c %start of fragment
-This module defines the command-line interface of the
-@command{dokgen} program. See the @ref{CLI} section for additional
-information.
+This module defines the command-line interface of the @command{dokgen}
+program. See the @ref{CLI} section for additional information.
@c %end of fragment
@@ -95,9 +94,9 @@ following fields:
@c %start of fragment
This module defines procedures that are associated to every command
-provided by the command-line interface of the @command{dokgen}
-program. See the @ref{CLI} and @xref{dokgen_cli,(dokgen cli)}
-sections for additional information.
+provided by the command-line interface of the @command{dokgen} program.
+See the @ref{CLI} and @xref{dokgen_cli,(dokgen cli)} sections for
+additional information.
@c %end of fragment
@@ -125,8 +124,7 @@ directories. For example:
@strong{destination} (string): Optional path to a directory where the
final Texinfo files will be saved. If not provided,
-@var{DEFAULT_DOC_PATH} is used (see the module
-@ref{dokgen_commands}).
+@var{DEFAULT_DOC_PATH} is used (see the module @ref{dokgen_commands}).
@strong{Result}: The API documentation is saved to the @var{destination}
directory.
@@ -373,10 +371,10 @@ This record type has the following fields:
@c %start of fragment
-This module defines procedures that structure @ref{dokgen_data,API
-data} as @emph{stexi} (symbolic texinfo), which can later be translated
-into Texinfo and integrated with the rest of the Texinfo documentation
-of a given software project.
+This module defines procedures that structure @ref{dokgen_data,API data}
+as @emph{stexi} (symbolic texinfo), which can later be translated into
+Texinfo and integrated with the rest of the Texinfo documentation of a
+given software project.
@c %end of fragment
maak: error: command failed (exit code 1): git -C . diff --exit-code -- manual/api
hint: Fix the command above, or run `maak --dry-run' to inspect it first.