From 2f6bd67a52d53ae628dd094d5d68792206f245c0 Mon Sep 17 00:00:00 2001
From: Hans Ulrich Niedermann <hun@n-dimensional.de>
Date: Fri, 30 Aug 2024 01:08:37 +0200
Subject: [PATCH 1/3] elf2tag: Add -h and --help arguments

---
 src/elf2tag | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/src/elf2tag b/src/elf2tag
index 28dde7b8..ed4993d2 100755
--- a/src/elf2tag
+++ b/src/elf2tag
@@ -10,14 +10,16 @@ for pgm in sort grep awk avr-objdump avr-nm; do
   hash $pgm 2>/dev/null || { echo "$progname: $pgm does not seem to be installed, exiting"; exit 1; }
 done
 
-if [ "$1" == "" ]; then
-cat <<END
+case "$1" in
+  "" | -h | --help )
+    cat <<END
 Syntax: $progname <file>.elf
 Function: output a tagfile suitable for the avrdude disasm -t=<tagfile> command
 Options: none
 END
-exit 1
-fi
+    exit 1
+    ;;
+esac
 
 echo "# Automatically generated tagfile via ${progname} ${1}"
 avr-objdump -d "$1" | grep '<.*>:' | awk '{

From eddb0d0ed5a3cfb70d19234e7c9290575fb778fd Mon Sep 17 00:00:00 2001
From: Hans Ulrich Niedermann <hun@n-dimensional.de>
Date: Fri, 30 Aug 2024 01:17:27 +0200
Subject: [PATCH 2/3] Add basic elf2tag(1) manpage

Add basic elf2tag(1) manpage using asciidoc/asciidoctor.

To update the elf2tag.1 file from elf2tag.1.adoc, run
the update-elf2tag-manpage script.

No CI or buildsystem or git precommit hook integration yet.
---
 src/elf2tag.1              |  62 ++++++++++++++++++++
 src/elf2tag.1.adoc         |  47 +++++++++++++++
 src/update-elf2tag-manpage | 115 +++++++++++++++++++++++++++++++++++++
 3 files changed, 224 insertions(+)
 create mode 100644 src/elf2tag.1
 create mode 100644 src/elf2tag.1.adoc
 create mode 100755 src/update-elf2tag-manpage

diff --git a/src/elf2tag.1 b/src/elf2tag.1
new file mode 100644
index 00000000..633d866f
--- /dev/null
+++ b/src/elf2tag.1
@@ -0,0 +1,62 @@
+'\" t
+.\"     Title: elf2tag
+.\"    Author: [see the "AUTHOR(S)" section]
+.\" Generator: Asciidoctor 2.0.20
+.\"      Date: 2024-11-23
+.\"    Manual: avrdude Manual
+.\"    Source: avrdude
+.\"  Language: English
+.\"
+.TH "ELF2TAG" "1" "2024-11-23" "avrdude" "avrdude Manual"
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.ss \n[.ss] 0
+.nh
+.ad l
+.de URL
+\fI\\$2\fP <\\$1>\\$3
+..
+.als MTO URL
+.if \n[.g] \{\
+.  mso www.tmac
+.  am URL
+.    ad l
+.  .
+.  am MTO
+.    ad l
+.  .
+.  LINKSTYLE blue R < >
+.\}
+.SH "NAME"
+elf2tag \- output a tagfile for the avrdude disasm command
+.SH "SYNOPSIS"
+.sp
+\fBelf2tag\fP <file.elf>
+.sp
+\fBelf2tag\fP [\fB\-h\fP | \fB\-\-help\fP]
+.SH "DESCRIPTION"
+.sp
+\fIelf2tag\fP generates a tagfile for use with the \fIavrdude disasm\fP command.
+.SH "OPTIONS"
+.sp
+\fB\-h\fP \fB\-\-help\fP
+.RS 4
+Prints the help message and exits.
+.RE
+.SH "EXAMPLES"
+.sp
+.if n .RS 4
+.nf
+.fam C
+$ elf2tag blink.elf > blink.tag
+$ avrdude \-qq \-c dryrun \-p m328p \-U blink.elf \-t
+avrdude> disasm \-t=blink.tag flash 0 512
+.fam
+.fi
+.if n .RE
+.SH "AUTHORS"
+.sp
+\fIelf2tag\fP was written by Johannes Bauer with small modifications by Stefan Rueger.
+.SH "SEE ALSO"
+.sp
+\fBavrdude(1)\fP, \fBavr\-nm(1)\fP, \fBavr\-objdump(1)\fP
diff --git a/src/elf2tag.1.adoc b/src/elf2tag.1.adoc
new file mode 100644
index 00000000..ca4a01e1
--- /dev/null
+++ b/src/elf2tag.1.adoc
@@ -0,0 +1,47 @@
+ELF2TAG(1)
+==========
+:doctype: manpage
+:man source: avrdude
+:man manual: avrdude Manual
+
+NAME
+----
+
+elf2tag - output a tagfile for the avrdude disasm command
+
+SYNOPSIS
+--------
+
+*elf2tag* <file.elf>
+
+*elf2tag* [*-h* | *--help*]
+
+DESCRIPTION
+-----------
+
+_elf2tag_ generates a tagfile for use with the _avrdude disasm_ command.
+
+OPTIONS
+-------
+
+*-h* *--help*::
+    Prints the help message and exits.
+
+EXAMPLES
+--------
+
+....
+$ elf2tag blink.elf > blink.tag
+$ avrdude -qq -c dryrun -p m328p -U blink.elf -t
+avrdude> disasm -t=blink.tag flash 0 512
+....
+
+AUTHORS
+-------
+
+_elf2tag_ was written by Johannes Bauer with small modifications by Stefan Rueger.
+
+SEE ALSO
+--------
+
+*avrdude(1)*, *avr-nm(1)*, *avr-objdump(1)*
diff --git a/src/update-elf2tag-manpage b/src/update-elf2tag-manpage
new file mode 100755
index 00000000..91a53d3f
--- /dev/null
+++ b/src/update-elf2tag-manpage
@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+
+# update-elf2tag-manpage - update the elf2tag.1 manpage from adoc source
+#
+# Usage:
+#    ./path/to/update-elf2tag-manpage
+#
+# Changes into the directory where update-elf2tag-manpage and
+# elf2tag.1.adoc are, runs asciidoctor to produce a man page elf2tag.1
+# from elf2tag.1.adoc, but only updates the elf2tag.1 file in the case
+# of actual changes.
+#
+# Just the asciidoctor version or the current date being different
+# from the last asciidoctor run is not considered an actual change.
+#
+# Requires asciidoctor to be installed.
+#
+# Environment variables used (if unset, uses the command from PATH):
+# ASCIIDOCTOR  the asciidoctor command to run
+# CMP          the cmp command to run (e.g. "busybox cmp")
+# SED          the sed command to run (e.g. "busybox sed")
+
+# This script uses the shell feature called "process substitution" which
+# is implemented by bash and busybox sh, but not by e.g. dash and can
+# therefore not be a /bin/sh script.
+
+set -e
+
+prog="$(basename "$0")"
+
+if test "$#" -gt 1; then
+  echo "$prog: Too many command line arguments"
+  exit 2
+fi
+
+if test "$#" -eq 1; then
+  case "$1" in
+    -h | --help )
+      ${SED-sed} -n '/^#\( .*\)$/,$p' "$0" \
+        | ${SED-sed} '/^#\( .*\)\?$/!q' \
+        | ${SED-sed} '/^$/d' \
+        | ${SED-sed} 's|^#$||; s|^# ||'
+      exit 0
+      ;;
+    * )
+      echo "$prog: Unhandled command line argument."
+      exit 2
+      ;;
+  esac
+fi
+
+cd "$(dirname "$0")"
+
+test -s elf2tag.1.adoc
+test -s elf2tag
+
+# Usage: normalize_manpage original.1 normalized.1
+#
+# Normalizes a man page generated by asciidoctor by replacing data not
+# present in the sources such as generation date, asciidoctor version.
+normalize_manpage() {
+  ${SED-sed} -f <(cat<<EOF
+#s|^\.\\\\|==TITLE==|
+s|^\.\\\\" Generator: Asciidoctor .*|.\\" Generator: GENERATOR|
+s|^\.\\\\"      Date: 20[0-9][0-9]-[0-1][0-9]-[0-3][0-9]|.\\"      Date: DATE|
+s|^\.TH "ELF2TAG" "1" "20[0-9][0-9]-[0-1][0-9]-[0-3][0-9]" "avrdude" "avrdude Manual"|\.\\" TH HEADER|
+EOF
+) < "$1" > "$2"
+}
+
+tmpdir="tmp$$"
+
+if ! ${ASCIIDOCTOR-asciidoctor} -b manpage -D "$tmpdir" elf2tag.1.adoc; then
+  echo "$prog: Error updating elf2tag.1"
+  rm -rf "$tmpdir"
+  exit 2
+fi
+
+# Have sed ensure a trailing newline character by appending empty string
+#
+# This is necessary as asciidoctor likes to create files without a
+# trailing newline, while it is good form for text editors to add one.
+if ${SED-sed} '$a\' < "$tmpdir/elf2tag.1" > "$tmpdir/elf2tag.1.newline"; then
+  mv -f "$tmpdir/elf2tag.1.newline" "$tmpdir/elf2tag.1"
+else
+  echo "$prog: Error ensuring trailing newline character"
+  rm -rf "$tmpdir"
+  exit 2
+fi
+
+if ! test -e elf2tag.1; then
+  echo "$prog: Generate elf2tag.1"
+  mv -f "$tmpdir/elf2tag.1" elf2tag.1
+  rmdir "$tmpdir"
+  exit 0
+fi
+
+normalize_manpage elf2tag.1           "$tmpdir/elf2tag.1.norm-old"
+normalize_manpage "$tmpdir/elf2tag.1" "$tmpdir/elf2tag.1.norm-new"
+
+if ${CMP-cmp} "$tmpdir/elf2tag.1.norm-old" "$tmpdir/elf2tag.1.norm-new" > /dev/null; then
+  echo "$prog: elf2tag.1 is up to date"
+  rm -f "$tmpdir/elf2tag.1"
+  rm -f "$tmpdir/elf2tag.1.norm-old"
+  rm -f "$tmpdir/elf2tag.1.norm-new"
+  rmdir "$tmpdir"
+  exit 0
+fi
+
+echo "Updating elf2tag.1"
+mv -f "$tmpdir/elf2tag.1" elf2tag.1
+rm -f "$tmpdir/elf2tag.1.norm-old"
+rm -f "$tmpdir/elf2tag.1.norm-new"
+rmdir "$tmpdir"
+exit 0

From f85a584067abf191c10cd1033485b6fcbb3c93fa Mon Sep 17 00:00:00 2001
From: Hans Ulrich Niedermann <hun@n-dimensional.de>
Date: Sat, 23 Nov 2024 03:30:29 +0100
Subject: [PATCH 3/3] ci: Check consistency of generated files

This makes the .github/workflows/check-sourcecode
more a "check-repo" than a "check-sourcecode".
---
 .github/workflows/check-sourcecode.yml | 18 ++++++++++++++
 src/update-elf2tag-manpage             | 33 ++++++++++++++++++++++----
 2 files changed, 47 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/check-sourcecode.yml b/.github/workflows/check-sourcecode.yml
index af24346d..f1d03719 100644
--- a/.github/workflows/check-sourcecode.yml
+++ b/.github/workflows/check-sourcecode.yml
@@ -22,3 +22,21 @@ jobs:
 
       - name: "Check the sourcecode"
         run: ./tools/check-sourcecode
+
+  check-generated:
+    name: "Check Generated Files"
+    runs-on: ubuntu-latest
+
+    steps:
+
+      - uses: actions/checkout@v4
+
+      - name: Install prerequisites
+        run: >-
+          sudo apt-get update
+
+          sudo apt-get install -y
+          asciidoctor
+
+      - name: "Verify elf2tag.1 consistency"
+        run: ./src/update-elf2tag-manpage --verify
diff --git a/src/update-elf2tag-manpage b/src/update-elf2tag-manpage
index 91a53d3f..09001c9b 100755
--- a/src/update-elf2tag-manpage
+++ b/src/update-elf2tag-manpage
@@ -4,20 +4,26 @@
 #
 # Usage:
 #    ./path/to/update-elf2tag-manpage
+#    ./path/to/update-elf2tag-manpage --verify
 #
-# Changes into the directory where update-elf2tag-manpage and
-# elf2tag.1.adoc are, runs asciidoctor to produce a man page elf2tag.1
-# from elf2tag.1.adoc, but only updates the elf2tag.1 file in the case
-# of actual changes.
+# Without a command line argument given, changes into the directory
+# where update-elf2tag-manpage and elf2tag.1.adoc are, runs
+# asciidoctor to produce a man page elf2tag.1 from elf2tag.1.adoc, but
+# only updates the elf2tag.1 file in the case of actual changes.
 #
 # Just the asciidoctor version or the current date being different
 # from the last asciidoctor run is not considered an actual change.
 #
+# With the --verify argument given, only verify that elf2tag.1 and
+# elf2tag.1.adoc are consistent with each other, i.e. elf2tag.1 would
+# not be changed.
+#
 # Requires asciidoctor to be installed.
 #
 # Environment variables used (if unset, uses the command from PATH):
 # ASCIIDOCTOR  the asciidoctor command to run
 # CMP          the cmp command to run (e.g. "busybox cmp")
+# DIFF         the diff command to run with -u (used with --verify only)
 # SED          the sed command to run (e.g. "busybox sed")
 
 # This script uses the shell feature called "process substitution" which
@@ -33,6 +39,7 @@ if test "$#" -gt 1; then
   exit 2
 fi
 
+verify=false
 if test "$#" -eq 1; then
   case "$1" in
     -h | --help )
@@ -42,6 +49,9 @@ if test "$#" -eq 1; then
         | ${SED-sed} 's|^#$||; s|^# ||'
       exit 0
       ;;
+    --verify )
+      verify=:
+      ;;
     * )
       echo "$prog: Unhandled command line argument."
       exit 2
@@ -89,6 +99,11 @@ else
 fi
 
 if ! test -e elf2tag.1; then
+  if "$verify"; then
+    echo "$prog: Cannot ensure consistency if there is no old elf2tag.1 file"
+    rm -rf "$tmpdir"
+    exit 1
+  fi
   echo "$prog: Generate elf2tag.1"
   mv -f "$tmpdir/elf2tag.1" elf2tag.1
   rmdir "$tmpdir"
@@ -107,6 +122,16 @@ if ${CMP-cmp} "$tmpdir/elf2tag.1.norm-old" "$tmpdir/elf2tag.1.norm-new" > /dev/n
   exit 0
 fi
 
+if "$verify"; then
+  echo "$prog: Error: src/elf2tag.1 is inconsistent with src/elf2tag.1.adoc"
+  ${DIFF-diff} -u "$tmpdir/elf2tag.1.norm-old" "$tmpdir/elf2tag.1.norm-new" ||:
+  rm -f "$tmpdir/elf2tag.1"
+  rm -f "$tmpdir/elf2tag.1.norm-old"
+  rm -f "$tmpdir/elf2tag.1.norm-new"
+  rmdir "$tmpdir"
+  exit 1
+fi
+
 echo "Updating elf2tag.1"
 mv -f "$tmpdir/elf2tag.1" elf2tag.1
 rm -f "$tmpdir/elf2tag.1.norm-old"