RE: [Groff] PS and "page background"

[Ted Harding]

On 17-Oct-05 mikkel meinike wrote:
> Ciao!
> 
> I'd bean on this list less than 30 ours. I don't even new the
> typesetting languish you are discussing here and already I am posting
> an off-topic question. But I am trying to get an overview of my
> possibility's and I think that maybe some of you gays might be clever
> on this subject.
> 
> (I found out my version of groff is 1.11.)
> 
> After what I have fount about groff (google :-)) it does not support
> grafic (images).

Not so -- provided you are using PostScript output you can include
PS graphic code in your groff. The usual starting point is to
have the PS grpahic in EPS (Encapsulated PostScript) format, which
basically means that it needs to have a line in it:

%%BoundingBox llx lly urx ury

where llx, lly are the coordinates (in points) of the bottom lefthand
corner, and urx, ury of the top righthand corner,  of a box which
includes the graphic. Software which generates EPS will do this
automatically, but it is always possible to edit such a line
into an aribtrary PS file.

> But i found something about programming postscript
> and "compile" it with Ghostscript. Do you thing it would be possible
> after I have made my ps file with groff to open it in an ordinary
> editor and "sneak in" some little pice of code that will apply the
> paper with an  an images as "paper background" as i is called in
> Abiword a "watermark" it is called in MS WORD?

This looks a bit round-about. It is more straightforward than
that. There are basically 3 methods.

1. Use the

.PSPIC

(see "man grops" for details).

2. Use the groff escape-sequence

\X'ps: import ... '

(again see "man grops)

3. Use the groff string-definition command

.ds watermark [PostScript Code]

to define something which will be evoked whenever you imsert
the "\*[watermark]" name of the string. This is suitable for
simple PS code.

4. Use

\X'ps: def ... '

to plant a PS definition of the graphic in the document Prologue,
so that it will be available throughout the document (this can
save a lot of bytes for something like a watermark, or a logo
for the top of a page, which would appear on every page, since
methods 1 and 2 embed the PS code in the file at every place
where it is used, while planting the definition in the Prologue
means that the code is embedded once only, and is printed by
simply calling it by name).

> If yes I would like to know:
> 
> 1. What should the code be?

PostScript code

> 2. Where should the code be placed?

See above and examples below

> 3. Which format should the image be?

EPS (PS with bounding box). Groff does not handle other graphics
formats, so you would need to pre-convert say a GIF or JPEG
into EPS before you start.

> 4. Is there specific demands on the seise of the image?

Not really, though you need to watch it to get the result you
want!

> 5. Which commands do I need to process it trough ghostscript?

Not necessary for using groff, though useful in checking your
results. Since groff produces PS output, say in a file

  output.ps

you can view this using ghostscript with

  gs output.ps

I prefer the "gv" front-end to gs, since you can use it as

  gv -watch output.ps &

where the "&" detaches it from the initiating terminal,
and the "-watch" means the gv will re-read the PS file
whenever it changes, so you can repeated run groff,
generating a new version of the file, and the changes
will immediately show up in gv (this is as close as you
get to "WYSIWYG" usage of groff).

Examples:

A. Case of (3) above. Your groff source file is


.ds LH "\X'ps: exec gsave \
/Times-Roman findfont 96 scalefont setfont \
170  508  moveto 315 rotate 0.85 1 -1 scale \
setgray (D R A F T) show \
grestore'
\*[LH]
.LP
This is some text which we want to print out with a
\(lqDRAFT\(rq `watermark' background.
.br
This is some text which we want to print out with a
\(lqDRAFT\(rq `watermark' background.
....
[about 80 of these]


This defines a string named "LH", groff name \*[LH],
which consists of PS code to print "D R A F T"
diagonally in large type on the page, in a somewhat
pale grey.

If you use the "ms" macros, the "LH" string is the
"Left Header" part of the 3-part header 'LH'CH'RH'
which is printed at the top of every page *except*
the first. This is why, in the above, there is an
explicit "\*[LH]" for the first page, before the
".LP" which initiates the actual text to be printed
on the page. For subsequent pages, this is not needed.

The result is that the "D R A F T" watermark will be
printed first, and then the text (lots of repetitions
of "This is some text ... ") will be printed on top
of it.

(And this is why it needs to go into "LH", if you are
using this mechanism, since while the corresponding
part of the footer, "LF", will be printed on every
page including the first, the string \*[LF] would
over-print the text, which might not be what you want).

NOTE: the coordinates, rotation and scaling in the
PS code above take account of the fact that when groff
generates its own PS code, it inverts the y-axis, i.e.
measuring distance from the TOP of the page, while
raw PS measures from the BOTTOM of the page. Compare
example D below.

B. Case of (4) above. At the start of your groff source
file, enter a PS definition.

\X'ps: def /wmk {gsave \
/Times-Roman findfont 96 scalefont setfont \
170  508  moveto 315 rotate 0.85 1 -1 scale \
setgray (D R A F T) show \
grestore} def'

(Note the slight difference from the preceding: "exec"
replaced by "def").

This defines, once and for all, a PS procedure called "wmk".
So, every time you have

\X'ps: exec wmk'

in your groff source file, the procedure "wmk" will be
executed.

So, for one page only, a groff source file


\X'ps: def /wmk {gsave \
/Times-Roman findfont 96 scalefont setfont \
170  508  moveto 315 rotate 0.85 1 -1 scale \
setgray (D R A F T) show \
grestore} def'
\X'ps: exec wmk'
.LP
This is some text which we want to print out with a
\(lqDRAFT\(rq `watermark' background.
.br
This is some text which we want to print out with a
\(lqDRAFT\(rq `watermark' background.
.br
....
[about 80 of these]


will first print "D R A F T" as before, and then overprint
the text. To get it on every page, you either need to repeat
the "\X'ps: exec wmk'" each time, or else define this as the
"LH" string but still put it explicitly on the first page.



C. Case  of (2) above (\X'ps: import ... ') using an
   external EPS file.

First create the same code as am EPS file. This means working
out what the bounding box should be, and also including the
canonical first line. The file watermark.eps contains:

%!PS-Adobe-2.0
%%BoundingBox 0 0 594 765
/Times-Roman findfont 96 scalefont setfont
170 157 moveto 40 rotate 1 1 scale
0.85 setgray (D R A F T) show
showpage


Now have

\X'ps: import watermark.eps 0 0 594 765 594000 765000'

as the first line (before any text starts) and define
it as the "LH" string for subsequent pages, as above.

NOTE that the coordinates etc. in this PS code are changed
from those in example A, since this code has to be defined
relative to the default PS coordinate space where vertical
distance is measured from the BOTTOM of the page.


D. Case of (1) above, using PSPIC. PSPIC is best suited
for putting diagrams and pictures into text as illustrations,
since its use is tightly bound to the current printing
position. Also, since the printing position moves on after
PSPIC has been used so as to lie below the graphic, it is
awkward to use it for a watermark (where you would have to
move back to the top of the page before printing the main
text).

Therefore use methods 2,3 or 4, as illustrated in A, B and C,
for things like watermarks.

However, if say you are a property agent and have a digital
photo of house you are selling, first convert this to EPS
(on Linux you can use the 'convert' program in ImageMagick
if your system will support it). so that you have a file

  house.eps

Then you can write your document:

.LP
.ce
\f[BI]\s[20]Desirable Residence at Øresund\s0\fP
.sp
.LP
This attractive house near the beach at Øresund ...
[some tempting stuff]
.PSPIC house.eps 152c
.ce
\fBFrontal Elevation of the Property\fP
[lots more temoting stuff]


which will cause the picture of the house to occur at that
place in the document [you may have to take special measures
if there is not room for it at the bottom of thepage],
following the text [some tempting stuff], centred, and of
width 12cm. The text [lots more tempting stuff] will follow
on below the picture.


Hoping this outline is helpful to get you started.

All best wishes,
Ted.


--------------------------------------------------------------------
E-Mail: (Ted Harding) <address@hidden>
Fax-to-email: +44 (0)870 094 0861
Date: 17-Oct-05                                       Time: 13:36:13
------------------------------ XFMail ------------------------------