Document elf2tag script

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,63 @@
+'\" t
+.\"     Title: elf2tag
+.\"    Author: [see the "AUTHOR(S)" section]
+.\" Generator: Asciidoctor 2.0.20
+.\"      Date: 2024-09-04
+.\"    Manual: avrdude Manual
+.\"    Source: avrdude
+.\"  Language: English
+.\"
+.TH "ELF2TAG" "1" "2024-09-04" "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 file.elf > file.tag
+$ avrdude \-t ...
+avrdude> ...
+avrdude> disasm \-t=file.tag ...
+.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,48 @@
+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 file.elf > file.tag
+$ avrdude -t ...
+avrdude> ...
+avrdude> disasm -t=file.tag ...
+....
+
+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,82 @@
+#!/usr/bin/env bash
+
+# update-elf2tag-manpage - update the elf2tag.1 manpage from adoc source
+#
+# Usage: ./path/to/update-elf2tag-manpage
+#
+# Changes to the directory where update-elf2tag-manpage and elf2tag.1.adoc
+# are, runs elf2tag.1.adoc through asciidoctor to produce a man page, 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 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
+
+case "$1" in
+  -h | --help )
+    ${SED-sed} -n '/^#\( .*\)$/,$p' "$0" \
+      | ${SED-sed} '/^#\( .*\)\?$/!q' \
+      | ${SED-sed} '/^$/d' \
+      | ${SED-sed} 's|^#$||; s|^# ||'
+    exit 0
+    ;;
+esac
+
+cd "$(dirname "$0")"
+
+test -s elf2tag.1.adoc
+test -s elf2tag
+
+normalize_manpage() {
+  ${SED-sed} -f <(cat<<EOF
+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 "Error updating elf2tag.1"
+  exit 2
+fi
+
+if ! test -e elf2tag.1; then
+  echo "Generate elf2tag.1"
+  mv -f "$tmpdir/elf2tag.1" elf2tag.1
+  rmdir "$tmpdir"
+  exit 0
+fi
+
+normalize_manpage elf2tag.1           "$tmpdir/elf2tag.1.old"
+normalize_manpage "$tmpdir/elf2tag.1" "$tmpdir/elf2tag.1.new"
+
+if ${CMP-cmp} "$tmpdir/elf2tag.1.old" "$tmpdir/elf2tag.1.new" > /dev/null; then
+  echo "elf2tag.1 is up to date"
+  rm -f "$tmpdir/elf2tag.1"
+  rm -f "$tmpdir/elf2tag.1.old"
+  rm -f "$tmpdir/elf2tag.1.new"
+  rmdir "$tmpdir"
+  exit 0
+fi
+
+echo "Updating elf2tag.1"
+mv -f "$tmpdir/elf2tag.1" elf2tag.1
+rm -f "$tmpdir/elf2tag.1.old"
+rm -f "$tmpdir/elf2tag.1.new"
+rmdir "$tmpdir"
+exit 0