[flashrom] [PATCH] Pimp the manpage to create nicer hyperlinks and HTML output.
Stefan Tauner
stefan.tauner at alumni.tuwien.ac.at
Fri Dec 25 21:08:21 CET 2015
Also, add a target to the makefile to build a flashrom.8.html with groff.
FIXME: svn:ignore for the html
Signed-off-by: Stefan Tauner <stefan.tauner at alumni.tuwien.ac.at>
---
Makefile | 5 ++-
flashrom.8.tmpl | 101 ++++++++++++++++++++++++++++++++++++--------------------
2 files changed, 69 insertions(+), 37 deletions(-)
diff --git a/Makefile b/Makefile
index c439d8d..6e9dc19 100644
--- a/Makefile
+++ b/Makefile
@@ -799,7 +799,7 @@ TAROPTIONS = $(shell LC_ALL=C tar --version|grep -q GNU && echo "--owner=root --
# This includes all frontends and libflashrom.
# We don't use EXEC_SUFFIX here because we want to clean everything.
clean:
- rm -f $(PROGRAM) $(PROGRAM).exe libflashrom.a *.o *.d $(PROGRAM).8
+ rm -f $(PROGRAM) $(PROGRAM).exe libflashrom.a *.o *.d $(PROGRAM).8 $(PROGRAM).8.html
@+$(MAKE) -C util/ich_descriptors_tool/ clean
distclean: clean
@@ -1054,6 +1054,9 @@ endif
@$(DIFF) -q .features.tmp .features >/dev/null 2>&1 && rm .features.tmp || mv .features.tmp .features
@rm -f .featuretest.c .featuretest$(EXEC_SUFFIX)
+$(PROGRAM).8.html: $(PROGRAM).8
+ @groff -mandoc -Thtml $< >$@
+
$(PROGRAM).8: $(PROGRAM).8.tmpl
@sed -e '1 s#".*".*#"$(shell ./util/getrevision.sh -d $(PROGRAM).8.tmpl 2>/dev/null)" "$(VERSION)"#' <$< >$@
diff --git a/flashrom.8.tmpl b/flashrom.8.tmpl
index 8b5f98c..1be8698 100644
--- a/flashrom.8.tmpl
+++ b/flashrom.8.tmpl
@@ -1,3 +1,38 @@
+.\" Load the www device when using groff; provide a fallback for groff's MTO macro that formats email addresses.
+.ie \n[.g] \
+. mso www.tmac
+.el \
+. de MTO \\$2 \(la\\$1 \(ra\\$3
+..
+.\" Create wrappers for .MTO and .URL that print only text on systems w/o groff or if not outputting to a HTML
+.\" device. To that end we need to distinguish HTML output on groff from other configurations first.
+.nr groffhtml 0
+.if \n[.g] \
+. if "\*[.T]"html" \
+. nr groffhtml 1
+.\" For code reuse create a generic wrapper that gets its target macro as first parameter.
+.de FKGRF
+. ds cmd \\$1
+. shift
+. ie (\n[groffhtml]==1) \{\
+. \\*[cmd] \\$@
+. \}
+. el \{\
+. ie "\\$2"" \{\
+. BR "\\$1" "\\$3"
+. \}
+. el \{\
+. RB "\\$2 \(la" "\\$1" "\(ra\\$3"
+. \}
+. \}
+..
+.de URLB
+. FKGRF URL \\$@
+..
+.\" Likewise for the MTO macro. FIXME: can these be combined?
+.de MTOB
+. FKGRF MTO \\$@
+..
.TH FLASHROM 8 "" ""
.SH NAME
flashrom \- detect, read, write, verify and erase flash chips
@@ -160,9 +195,8 @@ if you have proper means to recover from failure!
Same as
.BR \-\-list\-supported ,
but outputs the supported hardware in MediaWiki syntax, so that it can be
-easily pasted into the wiki page at
-.nh
-.BR http://www.flashrom.org/ .
+easily pasted into the
+.URLB https://www.flashrom.org/Supported_hardware "supported hardware wiki page" .
Please note that MediaWiki output is not compiled in by default.
.TP
.B "\-p, \-\-programmer <name>[:parameter[,parameter[,parameter]]]"
@@ -453,9 +487,9 @@ unusable (see also the
.B BUGS
section). The embedded controller (EC) in these
machines often interacts badly with flashing.
-.nh
-.B http://www.flashrom.org/Laptops
-has more information. For example the EC firmware sometimes resides on the same
+More information is
+.URLB http://www.flashrom.org/Laptops "in the wiki" .
+For example the EC firmware sometimes resides on the same
flash chip as the host firmware. While flashrom tries to change the contents of
that memory the EC might need to fetch new instructions or data from it and
could stop working correctly. Probing for and reading from the chip may also
@@ -628,8 +662,7 @@ syntax where
.B addr
will be interpreted as usual (leading 0x (0) for hexadecimal (octal) values, or else decimal).
For more information please see
-.nh
-.B http://flashrom.org/VT6421A
+.URLB http://flashrom.org/VT6421A "its wiki page" .
.SS
.BR "nicintel_eeprom " programmer
This is the first programmer module in flashrom that does not provide access to NOR flash chips but EEPROMs
@@ -733,9 +766,9 @@ where
.B state
can be
.BR on " or " off .
-More information about the Bus Pirate pull-up resistors and their purpose is available at
-.nh
-.BR "http://dangerousprototypes.com/docs/Practical_guide_to_Bus_Pirate_pull-up_resistors " .
+More information about the Bus Pirate pull-up resistors and their purpose is available
+.URLB "http://dangerousprototypes.com/docs/Practical_guide_to_Bus_Pirate_pull-up_resistors" \
+"in a guide by dangerousprototypes" .
Only the external supply voltage (Vpu) is supported as of this writing.
.SS
.BR "pickit2_spi " programmer
@@ -842,17 +875,13 @@ can be
STK200/300, " wiggler " for the Macraigor Wiggler, or " xilinx " for the Xilinx Parallel Cable III (DLC 5)."
.sp
More information about the RayeR hardware is available at
-.nh
-.BR "http://rayer.ic.cz/elektro/spipgm.htm " .
+.URLB "http://rayer.g6.cz/elektro/spipgm.htm" "RayeR's website" .
The Altera ByteBlasterMV datasheet can be obtained from
-.nh
-.BR "http://www.altera.co.jp/literature/ds/dsbytemv.pdf " .
+.URLB "http://www.altera.co.jp/literature/ds/dsbytemv.pdf" Altera .
For more information about the Macraigor Wiggler see
-.nh
-.BR "http://www.macraigor.com/wiggler.htm " .
+.URLB "http://www.macraigor.com/wiggler.htm" "their company homepage" .
The schematic of the Xilinx DLC 5 was published in
-.nh
-.BR "http://www.xilinx.com/support/documentation/user_guides/xtp029.pdf " .
+.URLB "http://www.xilinx.com/support/documentation/user_guides/xtp029.pdf" "a Xilinx user guide" .
.SS
.BR "pony_spi " programmer
The serial port (like /dev/ttyS0, /dev/ttyUSB0 on Linux or COM3 on windows) is
@@ -865,8 +894,7 @@ named "serbang". The optional
parameter accepts the values "si_prog" (default) or "serbang".
.sp
Information about the SI-Prog adapter can be found at
-.nh
-.BR "http://www.lancos.com/siprogsch.html " .
+.URLB "http://www.lancos.com/siprogsch.html" "its website" .
.sp
An example call to flashrom is
.sp
@@ -1022,7 +1050,7 @@ needs TCP access to the network or userspace access to a serial port.
.B buspirate_spi
needs userspace access to a serial port.
.sp
-.BR dediprog ", " ft2232_spi " and " usbblaster_spi and " pickit2_spi
+.BR dediprog ", " ft2232_spi ", " usbblaster_spi " and " pickit2_spi
need access to the USB device via libusb.
.sp
.B dummy
@@ -1032,7 +1060,7 @@ needs no access permissions at all.
.BR gfxnvidia ", " drkaiser ", " satasii ", " satamv ", " atahpt" and " atavia
have to be run as superuser/root, and need additional raw access permission.
.sp
-.BR serprog ", " buspirate_spi ", " dediprog ", " usbblaster_spi " and " ft2232_spi and " pickit2_spi
+.BR serprog ", " buspirate_spi ", " dediprog ", " usbblaster_spi ", " ft2232_spi " and " pickit2_spi
can be run as normal user on most operating systems if appropriate device
permissions are set.
.sp
@@ -1045,23 +1073,22 @@ in
.B "/etc/rc.securelevel"
and rebooting, or rebooting into single user mode.
.SH BUGS
-Please report any bugs to the flashrom mailing list at
-.B "<flashrom at flashrom.org>"
+Please report any bugs to the
+.MTOB "flashrom at flashrom.org" "flashrom mailing list" .
.sp
We recommend to subscribe first at
-.sp
-.B " http://www.flashrom.org/mailman/listinfo/flashrom"
+.URLB "http://www.flashrom.org/mailman/listinfo/flashrom" "" .
.sp
Many of the developers communicate via the
.B "#flashrom"
IRC channel on
.BR chat.freenode.net .
+If you don't have an IRC client, you can use the
+.URLB http://webchat.freenode.net/?channels=flashrom "freenode webchat" .
You are welcome to join and ask questions, send us bug and success reports there
too. Please provide a way to contact you later (e.g.\& a mail address) and be
-patient if there is no immediate reaction. Also, we provide a pastebin service
-at
-.nh
-.B http://paste.flashrom.org
+patient if there is no immediate reaction. Also, we provide a
+.URLB http://paste.flashrom.org "pastebin service"
that is very useful when you want to share logs etc.\& without spamming the
channel.
.SS
@@ -1076,8 +1103,8 @@ paragraph in the
.B internal programmer
subsection of the
.B PROGRAMMER-SPECIFIC INFORMATION
-section and the information in our wiki at
-.BR "http://www.flashrom.org/Laptops " .
+section and the information
+.URLB "http://www.flashrom.org/Laptops" "in our wiki" .
.SS
One-time programmable (OTP) memory and unique IDs
.sp
@@ -1172,8 +1199,10 @@ Yinghai Lu
.br
some others, please see the flashrom svn changelog for details.
.br
-All still active authors can be reached via email at <flashrom at flashrom.org>.
+All still active authors can be reached via
+.MTOB "flashrom at flashrom.org" "the mailing list" .
.PP
-This manual page was written by Uwe Hermann <uwe at hermann-uwe.de>,
-Carl-Daniel Hailfinger and others.
+This manual page was written by
+.MTOB "uwe at hermann-uwe.de" "Uwe Hermann" ,
+Carl-Daniel Hailfinger, Stefan Tauner and others.
It is licensed under the terms of the GNU GPL (version 2 or later).
--
Kind regards, Stefan Tauner
More information about the flashrom
mailing list