[groff] 02/02: Define, and use registered trade mark strings.

[Keith Marshall]

keithmarshall pushed a commit to branch master
in repository groff.

commit 0d0298937f7ff385aa12d04545924bdfaed61b3d
Author: Keith Marshall <keith.d.marshall@ntlworld.com>
AuthorDate: Sat Aug 21 11:30:16 2021 +0100

    Define, and use registered trade mark strings.
---
 contrib/pdfmark/ChangeLog  |  9 ++++++
 contrib/pdfmark/pdfmark.ms | 73 ++++++++++++++++++++++++++--------------------
 2 files changed, 50 insertions(+), 32 deletions(-)

diff --git a/contrib/pdfmark/ChangeLog b/contrib/pdfmark/ChangeLog
index b9bbf7f..65ab4a0 100644
--- a/contrib/pdfmark/ChangeLog
+++ b/contrib/pdfmark/ChangeLog
@@ -1,5 +1,14 @@
 2021-08-21  Keith Marshall  <keith.d.marshall@ntlworld.com>
 
+       Define, and use registered trade mark strings.
+
+       * pdfmark.ms (Adobe, Acrobat, Distiller, PostScript, Microsoft):
+       Define as strings.  Each expands to its own name, followed by the
+       registered trademark symbol, as a superscript, and optional trailing
+       punctuation, below the superscript.  Use each as required.
+
+2021-08-21  Keith Marshall  <keith.d.marshall@ntlworld.com>
+
        Prefer "-ize" to "-ise" where etymology permits.
 
        * pdfmark.ms: For all verbs, and their derivative nouns, for which
diff --git a/contrib/pdfmark/pdfmark.ms b/contrib/pdfmark/pdfmark.ms
index 6c3e432..fdd3e44 100644
--- a/contrib/pdfmark/pdfmark.ms
+++ b/contrib/pdfmark/pdfmark.ms
@@ -63,6 +63,15 @@ Publishing with GNU Troff
 .\"
 .ds rg \*{\(rg\*}
 .\"
+.\" Define strings, to represent frequently used registered trade marks.
+.\"
+.ds Adobe "Adobe\Z'\\$1'\*(rg\"
+.ds Acrobat "Acrobat\Z'\\$1'\*(rg\"
+.ds Distiller "Distiller\Z'\\$1'\*(rg\"
+.ds PostScript "PostScript\Z'\\$1'\*(rg\"
+.
+.ds Microsoft "Microsoft\Z'\\$1'\*(rg\"
+.\"
 .\" Establish the page layout.
 .\"
 .nr PO  2.5c
@@ -121,20 +130,20 @@ Publishing with GNU Troff
 .if !dSN-NO-DOT .als SN-NO-DOT SN
 .LP
 It might appear that it is a fairly simple matter to
-produce documents in Adobe\*(rg\~\(lqPortable\~Document\~Format\(rq,
+produce documents in \*[Adobe]\~\(lqPortable\~Document\~Format\(rq,
 commonly known as PDF, using
 .CW groff ) GNU\~Troff\~(
 as the document formatter.
 Indeed,
 .CW groff 's
-default output format is the native Adobe\*(rg\~PostScript\*(rg format,
-which PDF producers such as Adobe\*(rg Acrobat\*(rg Distiller\*(rg,
+default output format is the native \*[Adobe]\~\*[PostScript] format,
+which PDF producers such as \*[Adobe] \*[Acrobat] \*[Distiller ,]
 or GhostScript, expect as their input format.
 Thus, the PDF production process would seem to entail simply
 formatting the document source with
 .CW groff ,
-to produce a PostScript\*(rg version of the document,
-which can subsequently be processed by Acrobat\*(rg Distiller\*(rg
+to produce a \*[PostScript] version of the document,
+which can subsequently be processed by \*[Acrobat] \*[Distiller]
 or GhostScript, to generate the final PDF document.
 .LP
 For many PDF production requirements,
@@ -143,14 +152,14 @@ However, this is a limited PDF production method,
 in which the resultant PDF document represents no more than
 an on screen image of the printed form of the document, if
 .CW groff 's
-PostScript\*(rg output were printed directly.
+\*[PostScript] output were printed directly.
 .LP
 The Portable Document Format provides a number of features,
 which significantly enhance the experience of reading a document on screen,
 but which are of little or no value to a document which is merely printed.
 It
 .EM is
-possible to exploit these PDF features, which are described in the Adobe\*(rg
+possible to exploit these PDF features, which are described in the \*[Adobe]
 .\"
 .de pdfmark-manual
 .\" This is an example of a resource reference specified by URI ...
@@ -169,10 +178,10 @@ possible to exploit these PDF features, which are 
described in the Adobe\*(rg
 with some refinement of the simple PDF production method, provided
 appropriate \(lqfeature implementing\(rq instructions can be embedded into
 .CW groff 's
-PostScript\*(rg rendering of the document.
+\*[PostScript] rendering of the document.
 This, of course, implies that the original document source, which
 .CW groff
-will process to generate the PostScript\*(rg description of the document,
+will process to generate the \*[PostScript] description of the document,
 must include appropriate markup to exploit the desired PDF features.
 It is this preparation of the
 .CW groff
@@ -194,16 +203,16 @@ such as:\(en
 .IP \(bu
 Selecting a default document view, which defines how the document will appear
 when opened in the reader application; for example, when this document is
-opened in Acrobat\*(rg\~Reader, it should display the top of the cover sheet,
+opened in \*[Acrobat]\~Reader, it should display the top of the cover sheet,
 in the document view pane, while a document outline should appear to the left,
 in the \(lqBookmarks\(rq pane.
 .IP \(bu
 Adding document identification \(lqmeta\(hydata\(rq,
-which can be accessed, in Acrobat\*(rg\~Reader,
+which can be accessed, in \*[Acrobat]\~Reader,
 by inspecting the \(lqFile\^/\^Document\~Properties\^/\^Summary\(rq.
 .IP \(bu
 Creating a document outline, which will be displayed in the \(lqBookmarks\(rq
-pane of Acrobat\*(rg\~Reader, such that readers may quickly navigate to any
+pane of \*[Acrobat]\~Reader, such that readers may quickly navigate to any
 section of the document, simply by clicking on the associated heading
 in the outline view.
 .IP \(bu
@@ -218,7 +227,7 @@ points within the PDF document.
 .LP
 All of the techniques described have been tested on
 .EM both
-GNU/Linux, and on Microsoft\*(rg Windows\(tm2000 operating platforms, using
+GNU/Linux, and on \*[Microsoft] Windows\(tm2000 operating platforms, using
 .CW groff
 .CW 1.19.1 ,\c
 .pdfhref L -D footnote1 -- \**
@@ -253,7 +262,7 @@ together with an appropriate text editor, for creating and 
marking up the
 .CW groff
 input files.
 These additional utilities are not provided, as standard,
-on the Microsoft\*(rg Windows\(tm platform,
+on the \*[Microsoft] Windows\(tm platform,
 but several third party implementations are available.
 Some worth considering include the MKS\*(rg\~Toolkit,\**
 .FS
@@ -271,7 +280,7 @@ POSIX
 .LG
 emulation environment and
 Unix\(tm
-toolkit for 32\(hybit Microsoft\*(rg Windows\(tm platforms; see
+toolkit for 32\(hybit \*[Microsoft] Windows\(tm platforms; see
 .pdfhref W http://cygwin.com
 for information and download.
 .FE
@@ -279,7 +288,7 @@ or MSYS.\**
 .FS
 Another free, but minimal suite of common
 Unix\(tm
-tools for 32\(hybit Microsoft\*(rg Windows\(tm, available for download from
+tools for 32\(hybit \*[Microsoft] Windows\(tm, available for download from
 .pdfhref W -A ; http://www.mingw.org
 it
 .EM does 
@@ -344,11 +353,11 @@ macros to add PDF features.
 .LP
 All PDF features are implemented by embedding instances of the
 .B \F[C]pdfmark\F[]
-operator, as described in the Adobe\*(rg
+operator, as described in the \*[Adobe]
 .pdfmark-manual ,
 into
 .CW groff 's
-PostScript\*(rg output stream.
+\*[PostScript] output stream.
 To facilitate the use of this operator, the
 .CW pdfmark
 macro package defines the primitive
@@ -356,7 +365,7 @@ macro package defines the primitive
 macro; it simply emits its argument list,
 as arguments to a
 .CW pdfmark
-operator, in the PostScript\*(rg output stream.
+operator, in the \*[PostScript] output stream.
 .LP
 .pdfhref M -N pdfmark-example
 To illustrate the use of the
@@ -419,7 +428,7 @@ the first page will be displayed,
 at the default magnification set for the reader,
 and outline and thumbnail views will be hidden.
 When using a PDF reader,
-such as Acrobat\*(rg\~Reader,
+such as \*[Acrobat]\~Reader,
 which supports the
 .CW /DOCVIEW
 class of the
@@ -433,7 +442,7 @@ For example
 .QP
 .CW ".pdfview /PageMode /UseOutlines"
 .LP
-will cause Acrobat\*(rg\~Reader to open the document outline view,
+will cause \*[Acrobat]\~Reader to open the document outline view,
 to the left of the normal page view,
 while
 .QP
@@ -460,7 +469,7 @@ for more information.
 .LP
 It should be noted that the view controlling meta\(hydata, defined by the
 .CW pdfview
-macro, is not written immediately to the PostScript\*(rg output stream,
+macro, is not written immediately to the \*[PostScript] output stream,
 but is stored in an internal meta\(hydata \(lqcache\(rq,
 (simply implemented as a
 .CW groff
@@ -523,7 +532,7 @@ the
 .CW /DOCINFO
 records specified with the
 .CW pdfinfo
-macro are not immediately written to the PostScript\*(rg output stream;
+macro are not immediately written to the \*[PostScript] output stream;
 they are stored in the same meta\(hydata cache as
 .CW /DOCVIEW
 specifications, until this cache is explicitly flushed,
@@ -538,7 +547,7 @@ macro,
 A PDF document outline comprises a table of references,
 to \(lqbookmarked\(rq locations within the document.
 When the document is viewed in an \(lqoutline\~aware\(rq PDF document reader,
-such as Adobe\*(rg Acrobat\*(rg Reader,
+such as \*[Adobe] \*[Acrobat] Reader,
 this table of \(lqbookmarks\(rq may be displayed in a document outline pane,
 or \(lqBookmarks\(rq pane, to the left of the main document view.
 Individual references in the outline view may then be selected,
@@ -697,7 +706,7 @@ value will be unknown, when defining the parent entry.
 To resolve this paradox, the
 .CW pdfhref
 macro creates the outline entry in two distinct phases \(em
-a destination marker is placed in the PostScript\*(rg output stream 
immediately,
+a destination marker is placed in the \*[PostScript] output stream immediately,
 when the outline reference is defined,
 but the actual outline entry is stored in an internal \(lqoutline cache\(rq,
 until its subordinate hierarchy has been fully defined;
@@ -807,7 +816,7 @@ Any alternative definition for
 .CW PDFBOOKMARK.VIEW
 .EM must
 be specified in terms of valid view specification parameters,
-as described in the Adobe\*(rg
+as described in the \*[Adobe]
 .pdfmark-manual .
 .LP
 Note the use of the register
@@ -829,7 +838,7 @@ and is followed, in the
 definition, by the
 .CW grops
 .CW u \(rq \(lq
-operator, to convert it to PostScript\*(rg units on output.
+operator, to convert it to \*[PostScript] units on output.
 It may be used in any redefined specification for
 .CW PDFBOOKMARK.VIEW ,
 (or in the analogous definition of
@@ -857,7 +866,7 @@ by providing
 page size specifications to
 .CW groff ,
 .CW grops
-and to the PostScript\*(rg to PDF converter employed,
+and to the \*[PostScript] to PDF converter employed,
 and avoiding any page length changes within the document source.
 .LP
 Also note that
@@ -960,13 +969,13 @@ has a uniquely named destination.
 .LP
 As the overall size of the PDF document increases,
 it may become convenient to divide it into smaller,
-individually formatted PostScript\*(rg components,
+individually formatted \*[PostScript] components,
 which are then assembled, in the appropriate order,
 to create a composite PDF document.
 While this strategy may simplify the overall process of creating and
 editing larger documents, it does introduce a problem in creating
 an overall document outline,
-since each individual PostScript\*(rg component will be assigned
+since each individual \*[PostScript] component will be assigned
 duplicated sequences of \(lqbookmark\(rq names,
 with each name ultimately referring to multiple locations in the composite 
document.
 To avoid such reference naming conflicts, the
@@ -1009,7 +1018,7 @@ capabilities to the standard
 .CW ms
 package,
 .XR using-spdf ), (
-the table of contents is collected into a separate PostScript\*(rg section
+the table of contents is collected into a separate \*[PostScript] section
 from the main body of the document.
 In the \(lqbody\(rq section, the document outline is \(lquntagged\(rq,
 but in the \(lqTable\~of\~Contents\(rq section, a modified version of the
@@ -2347,7 +2356,7 @@ macro, when used to create a document outline,
 .XR add-outline ), (
 do not immediately write their
 .CW pdfmark
-output to the PostScript\*(rg data stream;
+output to the \*[PostScript] data stream;
 instead, they cache their output, in a
 .CW groff
 diversion, in the case of the