Merge pull request #1916 from ndim/document-elf2tag

Document elf2tag script

.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

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 '{

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

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)*

src/update-elf2tag-manpage

@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+
+# update-elf2tag-manpage - update the elf2tag.1 manpage from adoc source
+#
+# Usage:
+#    ./path/to/update-elf2tag-manpage
+#    ./path/to/update-elf2tag-manpage --verify
+#
+# 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
+# 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
+
+verify=false
+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
+      ;;
+    --verify )
+      verify=:
+      ;;
+    * )
+      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
+  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"
+  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
+
+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"
+rm -f "$tmpdir/elf2tag.1.norm-new"
+rmdir "$tmpdir"
+exit 0