From eddb0d0ed5a3cfb70d19234e7c9290575fb778fd Mon Sep 17 00:00:00 2001 From: Hans Ulrich Niedermann Date: Fri, 30 Aug 2024 01:17:27 +0200 Subject: [PATCH] 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 +.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* + +*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< "$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