Merge pull request #58 from marcows/pdf-features

Add PDF features to improve usability by marcows

doc/CMakeLists.txt

@@ -175,7 +175,9 @@ function(add_doc TARGET SOURCE DEPS)
         COMMAND
             sh ${CMAKE_CURRENT_SOURCE_DIR}/script/groff.sh
             -T ps                  # Output device
+            -d paper=a4 -P-pa4     # Consistent paper size
             -man                   # Macro Package man
+            -m pdfmark             # Macro Package pdfmark
             # Order of preprocessors may be important
             -t                     # Preprocess with tbl
             -s                     # Preprocess with soelim, with search paths:

doc/dictionaries/names.txt

@@ -91,6 +91,7 @@ oceanofthelost
 opensource
 Ozcelik
 patryks
+pdfmark
 Pilkington
 Pkzip
 Platon

doc/dictionaries/troff.txt

@@ -32,3 +32,7 @@ Pmkdir
 Ppacman
 Psrec
 Psudo
+pdfbookmark
+pdfinfo
+pdfsync
+pdfview

doc/etc/BUILDING.man

@@ -17,12 +17,18 @@
 .\"
 .TH Build SRecord SRecord "Reference Manual"
 .so etc/version.so
+.pdfinfo /Title SRecord Build Instructions
+.pdfinfo /Author Scott Finneran, Peter Miller
+.pdfinfo /Subject How to build SRecord version \*(V) [\*(G)]
+.pdfinfo /Keywords SRecord setup building testing installing packaging
+.pdfsync
+.\" ---------------------------------------------------------------------------
 .if n .hy 0
 .if n .ad l
 .if n .nr IN 8n
+.XX "" "How to build SRecord"
 .SH NAME
 How to build SRecord
-.XX "" "How to build SRecord"
 .SH SPACE REQUIREMENTS
 You will need about 3MB to unpack and build the
 .I SRecord

doc/etc/README.man

@@ -17,11 +17,17 @@
 .\"
 .TH "Read Me" SRecord SRecord "Reference Manual"
 .so etc/version.so
+.pdfinfo /Title SRecord Read Me
+.pdfinfo /Author Scott Finneran, Peter Miller
+.pdfinfo /Subject Overview of SRecord version \*(V) [\*(G)]
+.pdfinfo /Keywords SRecord README changelog releases
+.pdfsync
+.\" ---------------------------------------------------------------------------
 .hy 0
 .ad l
+.XX "" "The README file"
 .SH NAME
 SRecord \- manipulate EPROM load files
-.XX "" "The README file"
 .SH DESCRIPTION
 The \f[I]SRecord\fP package is a collection of powerful tools for
 manipulating EPROM load files.
@@ -421,8 +427,8 @@ Peter Miller;E\[hy]Mail:;[email protected]
 .TE
 .br
 .bp
-.SH RELEASE NOTES
 .XX "" "Release Notes"
+.SH RELEASE NOTES
 This section details the various features and bug fixes of the various
 releases.  For excruciating and complete detail, and also credits for
 those of you who have generously sent me suggestions and bug reports,

doc/etc/change_log.man

@@ -18,6 +18,12 @@
 .\"
 .TH "Change Log" SRecord SRecord "Change Log"
 .so etc/version.so
+.pdfinfo /Title SRecord Change Log
+.pdfinfo /Author Scott Finneran, Peter Miller
+.pdfinfo /Subject Release notes up to SRecord version \*(V) [\*(G)]
+.pdfinfo /Keywords SRecord changelog releases
+.pdfsync
+.\" ---------------------------------------------------------------------------
 .hy 0
 .ad l
 .SH RELEASE NOTES

doc/etc/new-file-format.so

@@ -17,9 +17,9 @@
 .\"     <http://www.gnu.org/licenses/>.
 .\"
 .TH "New Format" "SRecord" "SRecord" "Reference Manual"
+.XX "" "How to add a new file format"
 .SH NAME
 How to add a new file format
-.XX "" "How to add a new file format"
 .SH DESCRIPTION
 This section describes how to add a new file format.  It's mostly a
 set of reminders for the maintainer.  If you want a format added to

doc/etc/new-filter.so

@@ -17,9 +17,9 @@
 .\"     <http://www.gnu.org/licenses/>.
 .\"
 .TH "New Filter" "SRecord" "SRecord" "Reference Manual"
+.XX "" "How to add a new filter"
 .SH NAME
 How to add a new filter
-.XX "" "How to add a new filter"
 .SH DESCRIPTION
 This section describes how to add a new filter.  It's mostly a set
 of reminders for the maintainer.  If you want a filter added to the

doc/etc/ref-toc.so

@@ -22,6 +22,7 @@
 .\" arguments, first is the page title, the second is the page
 .\" description.  The current page number in the \n% register is
 .\" consulted to obtain the page number.
+.\" Also the PDF outline entries are inserted here.
 .\"
 .de XX
 .ds Page*Of*\\$1 \\n%
@@ -37,6 +38,8 @@
 .rm toc*num
 .ev
 .di
+.ie '\?\\$1\?'\?\?' .pdfbookmark 1 \\$2
+.el                 .pdfbookmark 1 \\$1 - \\$2
 ..
 .\" ----------  TC  -----------------------------------------------------------
 .\"

doc/etc/reference.man

@@ -115,11 +115,31 @@ with this program. If not, see <http://www.gnu.org/licenses/>.
 .\"
 .so etc/ref-parts.so
 .\"
+.\" ----------  Add the PDF metadata  -----------------------------------------
+.\"
+.\" After inclusion of README/BUILDING to overwrite their metadata.
+.pdfinfo /Title SRecord Reference Manual
+.pdfinfo /Author Scott Finneran, Peter Miller
+.pdfinfo /Subject Detailed description of SRecord version \*(V) [\*(G)]
+.pdfinfo /Keywords SRecord srec_cat srec_cmp srec_info
+.\"
+.\" Request to display the outline by default.
+.pdfview /PageMode /UseOutlines
+.\"
+.\" ----------  Flush the pdfmark cache ---------------------------------------
+.\"
+.\" Before the TOC to avoid wrong output when moving the TOC up with psselect:
+.\" - metadata would contain BUILDING's values otherwise
+.\" - the last PDF outline entry would wrongly be positioned at the beginning
+.pdfsync
+.\"
 .\" ----------  Include the Table of Contents  --------------------------------
 .\"
 .if o .bp \" because .TH is going to throw another one
 .nr % 1000
 .TH "Table of Contents" "SRecord" "SRecord" "Reference Manual"
+.pdfbookmark 1 Table of Contents
+.pdfsync
 .\"
 .\"     -----
 .\" This next section redefines the page footer to use roman numbering

doc/man1/srec_cat.1

@@ -18,11 +18,11 @@
 .\"
 .ds n) srec_cat
 .TH \*(n) 1 SRecord "Reference Manual"
-.SH NAME
-srec_cat \- manipulate EPROM load files
 .if require_index \{
 .XX "srec_cat(1)" "Manipulate EPROM load files"
 .\}
+.SH NAME
+srec_cat \- manipulate EPROM load files
 .SH SYNOPSIS
 .B \*(n)
 [

doc/man1/srec_cmp.1

@@ -17,11 +17,11 @@
 .\"
 .ds n) srec_cmp
 .TH \*(n) 1 SRecord "Reference Manual"
-.SH NAME
-srec_cmp \- compare two EPROM load files for equality
 .if require_index \{
 .XX "srec_cmp(1)" "Compare two EPROM load files for equality"
 .\}
+.SH NAME
+srec_cmp \- compare two EPROM load files for equality
 .SH SYNOPSIS
 .B \*(n)
 [

doc/man1/srec_examples.1

@@ -17,11 +17,11 @@
 .\"
 .ds n) srec_cat
 .TH srec_examples 1 SRecord "Reference Manual"i
-.SH NAME
-srec_examples \- examples of how to use SRecord
 .if require_index \{
 .XX "srec_examples(1)" "Examples of how to use SRecord"
 .\}
+.SH NAME
+srec_examples \- examples of how to use SRecord
 .SH DESCRIPTION
 The \f[I]srec_cat\fP command is very powerful, due to the ability to combine
 the the input filters in almost unlimited ways.

doc/man1/srec_info.1

@@ -18,11 +18,11 @@
 .\"
 .ds n) srec_info
 .TH \*(n) 1 SRecord "Reference Manual"
-.SH NAME
-srec_info \- information about EPROM load files
 .if require_index \{
 .XX "srec_info(1)" "Information about EPROM load files"
 .\}
+.SH NAME
+srec_info \- information about EPROM load files
 .SH SYNOPSIS
 .B \*(n)
 [

doc/man1/srec_input.1

@@ -17,11 +17,11 @@
 .\"
 .ds n) srec_input
 .TH \*(n) 1 SRecord "Reference Manual"
-.SH NAME
-\*(n) \- input file specifications
 .if require_index \{
 .XX "srec_input(1)" "Input file specifications"
 .\}
+.SH NAME
+\*(n) \- input file specifications
 .SH SYNOPSIS
 \f[B]srec_*\fP \f[I]filename\fP [ \f[I]format\fP ]
 .SH DESCRIPTION

doc/man1/srec_license.1

@@ -1,11 +1,11 @@
 .TH GPL GNU GPL GNU "Free Software Foundation"
+.if require_index \{
+.XX "srec_license(1)" "GNU General Public License"
+.\}
 .PP
 .ce 2
 GNU GENERAL PUBLIC LICENSE
 Version 3, 29 June 2007
-.if require_index \{
-.XX "srec_license(1)" "GNU General Public License"
-.\}
 .PP
 Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
 Everyone is permitted to copy and distribute verbatim copies

doc/man3/srecord.3

@@ -17,11 +17,11 @@
 .\"
 .ds n) srecord
 .TH \*(n) 3 SRecord "Reference Manual"
-.SH NAME
-srecord \- library to manipulate EPROM load files
 .if require_index \{
 .XX "srecord(3)" "Library to manipulate EPROM load files"
 .\}
+.SH NAME
+srecord \- library to manipulate EPROM load files
 .SH SYNOPSIS
 #include <srecord/\f[I]name\fP.h>
 .sp

doc/man3/srecord_license.3

@@ -1,14 +1,14 @@
 .TH LGPL 3 LGPL GNU "Free Software Foundation"
+.if require_index \{
+.XX "srecord_license(3)" "GNU Lesser General Public License"
+.\}
 .SH NAME
 LGPG \- GNU Lesser General Public License
 .SH DESCRIPTION
 .PP
 .ce 2
 GNU LESSER GENERAL PUBLIC LICENSE
 Version 3, 29 June 2007
-.if require_index \{
-.XX "srecord_license(3)" "GNU Lesser General Public License"
-.\}
 .PP
 Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
 .br

doc/man5/srec_aomf.5

@@ -18,11 +18,11 @@
 .\"
 .ds n) srec_aomf
 .TH \*(n) 5 SRecord "Reference Manual"
-.SH NAME
-srec_aomf \- Intel Absolute Object Module Format
 .if require_index \{
 .XX "srec_aomf(5)" "Intel Absolute Object Module Format"
 .\}
+.SH NAME
+srec_aomf \- Intel Absolute Object Module Format
 .SH DESCRIPTION
 The Absolute Object Module Format (AOMF) is a subset of the 8051 OMF.
 The structure of an absolute object file (the order of the records in

doc/man5/srec_ascii_hex.5

@@ -18,11 +18,11 @@
 .\"
 .ds n) srec_ascii_hex
 .TH \*(n) 5 SRecord "Reference Manual"
-.SH NAME
-srec_ascii_hex \- Ascii\[hy]Hex file format
 .if require_index \{
-.XX "srec_ascii_hex(5)" "Ascii\[hy]Hex file format"
+.XX "srec_ascii_hex(5)" "Ascii-Hex file format"
 .\}
+.SH NAME
+srec_ascii_hex \- Ascii\[hy]Hex file format
 .SH DESCRIPTION
 This format is also known as the \fIAscii\[hy]Space\[hy]Hex\fP or
 \fIAscii\[hy]Hex\[hy]Space\fP format.

doc/man5/srec_atmel_generic.5

@@ -18,11 +18,11 @@
 .\"
 .ds n) srec_atmel_generic
 .TH \*(n) 5 SRecord "Reference Manual"
-.SH NAME
-srec_atmel_generic \- Atmel Generic file format
 .if require_index \{
 .XX "srec_atmel_generic(5)" "Atmel Generic file format"
 .\}
+.SH NAME
+srec_atmel_generic \- Atmel Generic file format
 .SH DESCRIPTION
 This format is the output of the Atmel AVR assembler.
 The file contains two columns of hexadecimal coded values.

doc/man5/srec_binary.5

@@ -17,11 +17,11 @@
 .\"
 .ds n) srec_binary
 .TH srec_binary 5 SRecord "Reference Manual"
-.SH NAME
-srec_binary \- binary file format
 .if require_index \{
 .XX "srec_binary(5)" "Binary file format"
 .\}
+.SH NAME
+srec_binary \- binary file format
 .SH DESCRIPTION
 It is possible to read and write binary files using \f[I]srec_cat\fP(1).
 .SS File Holes

doc/man5/srec_brecord.5

@@ -18,11 +18,11 @@
 .\"
 .ds n) srec_brecord
 .TH \*(n) 5 SRecord "Reference Manual"
-.SH NAME
-srec_brecord \- Freescale MC68EZ328 Dragonball bootstrap record format
 .if require_index \{
 .XX "srec_brecord(5)" "Freescale MC68EZ328 Dragonball bootstrap record format"
 .\}
+.SH NAME
+srec_brecord \- Freescale MC68EZ328 Dragonball bootstrap record format
 .\" ------------------------------------------------------------------------
 .SH DESCRIPTION
 This data format is understood by Freescale MC68EZ328 Dragonball series

doc/man5/srec_coe.5

@@ -17,11 +17,11 @@
 .\"
 .ds n) srec_coe
 .TH \*(n) 5 SRecord "Reference Manual"
-.SH NAME
-srec_coe \- Xilinx Coefficient File Format
 .if require_index \{
 .XX "srec_coe(5)" "Xilinx Coefficient File Format"
 .\}
+.SH NAME
+srec_coe \- Xilinx Coefficient File Format
 .SH DESCRIPTION
 The Xilinx Coefficient File Format
 has a general syntax of the form:

doc/man5/srec_cosmac.5

@@ -18,11 +18,11 @@
 .\"
 .ds n) srec_cosmac
 .TH \*(n) 5 SRecord "Reference Manual"
-.SH NAME
-srec_cosmac \- RCA Cosmac Elf file format
 .if require_index \{
 .XX "srec_cosmac(5)" "RCA Cosmac Elf file format"
 .\}
+.SH NAME
+srec_cosmac \- RCA Cosmac Elf file format
 .SH DESCRIPTION
 This file takes the form of one or more RCA Cosmac Elf monitor commands,
 also known as the IDIOT/4 monitor.

doc/man5/srec_dec_binary.5

@@ -18,11 +18,11 @@
 .\"
 .ds n) srec_dec_binary
 .TH \*(n) 5 SRecord "Reference Manual"
-.SH NAME
-srec_dec_binary \- DEC Binary (XXDP) file format
 .if require_index \{
 .XX "srec_dec_binary(5)" "DEC Binary (XXDP) file format"
 .\}
+.SH NAME
+srec_dec_binary \- DEC Binary (XXDP) file format
 .SH DESCRIPTION
 The DEC Binary (XXDP) format was used on the PDP 11 series machines.
 This is a binary format, and is not readable or editable with a text editor.