From 6932fed7f7e215073f73c5db44339d403e18fdbf 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 | 63 +++++++++++++++++++++++++++++ src/elf2tag.1.adoc | 49 +++++++++++++++++++++++ src/update-elf2tag-manpage | 82 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 194 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 000000000..765c3649c --- /dev/null +++ b/src/elf2tag.1 @@ -0,0 +1,63 @@ +'\" t +.\" Title: elf2tag +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 2.0.20 +.\" Date: 2024-09-01 +.\" Manual: elf2tag Manual +.\" Source: avrdude +.\" Language: English +.\" +.TH "ELF2TAG" "1" "2024-09-01" "avrdude" "elf2tag 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 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\fP, \fBavr\-objdump(1)\fP \ No newline at end of file diff --git a/src/elf2tag.1.adoc b/src/elf2tag.1.adoc new file mode 100644 index 000000000..eb7a770ff --- /dev/null +++ b/src/elf2tag.1.adoc @@ -0,0 +1,49 @@ +ELF2TAG(1) +========== +:doctype: manpage +:man source: avrdude +:man version: @PACKAGE_VERSION@ +:man manual: elf2tag 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 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*, *avr-objdump(1)* diff --git a/src/update-elf2tag-manpage b/src/update-elf2tag-manpage new file mode 100755 index 000000000..d299f7c1f --- /dev/null +++ b/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< "$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