

                TThhee GGrrooffff aanndd FFrriieennddss HHOOWWTTOO

                     _D_e_a_n _A_l_l_e_n _P_r_o_v_i_n_s
                   University of Calgary
                    address@hidden


11..  IInnttrroodduuccttiioonn

This  HOWTO  attempts  to  introduce the document formatting
system known as _g_r_o_f_f.  It isn't intended to be a  reference
document;   other  individuals  are  working on that.  It is
aimed at two groups:  firstly, the individuals who  are  new
to  UNIX, Linux or another UNIX variant, and are discovering
that operating system's enormous potential and  versatility;
and secondly, at those who are considering the use of a doc-
ument formatting system for producing high quality and  con-
sistently formatted papers, articles and possibly books.

_g_r_o_f_f  is  not the only document formatting system available
to writers.  In recent years there have been developed "What
You  See  Is What You Get" or WWYYSSIIWWYYGG types of programs such
as the many that are  available  under  Microsoft's  various
operating  systems.  Other  similar  programs  include those
available from Sun Microsystems or Applix.  In  fact,  these
are  not, or at least haven't been, document formatting pro-
grams so much as tools to generate shorter works, with their
emphasis  being on look, rather than content.  The only true
alternatives (known to this writer) are _t_r_o_f_f and the versa-
tile TeX system with its accompanying macro packages such as
LaTeX.

As this writer understands the history of  text  formatting,
the  predecessor to TeX was _t_r_o_f_f.  It was developed at AT&T
Bell Labs and was  in  use  from  about  1971  according  to
[Kernighan, Lesk, and Ossanna 1978].  _t_r_o_f_f and related pro-
grams were provided as part of the  DDooccuummeenntteerr''ss  WWoorrkkBBeenncchh,
an  optional  extra  for  those  purchasing a licence to use
UNIX.  In the late 1980's, the  Free  Software  Foundation's
version  of  these tools was developed, and was named _g_r_o_f_f.
At about the same time (possibly a little earlier), the  TeX
formatting system was developed.

Like  _t_r_o_f_f_/_g_r_o_f_f, TeX and subsequently LaTeX, use text for-
matting commands interspersed with document text to describe
how  a  page  is  to be formatted by a type setting device.1
-----------
  1 The  original  _t_r_o_f_f  program  was designed to
drive a specific machine, a Graphic Systems Incor-
porated   C/A/T   (Computer  Assisted  Typesetter)
[Kernighan, Lesk, and Ossanna 1978;  Sun Microsys-


December, 1999     Groff and Friends HOWTO  $Revision: 1.9 $


                             -2-


_t_r_o_f_f_/_g_r_o_f_f however, tend to be much more like typical  UNIX
applications in that the commands used to describe page for-
matting are terse.  These commands are typically  3  charac-
ters in length and may be combined in sometimes difficult to
read combinations (not unlike the regular  expressions  used
with  sseedd  or  ggrreepp).   The macro packages available for use
with _t_r_o_f_f_/_g_r_o_f_f are somewhat  more  easily  read,  but  are
still  brief.  The advantage offered by TeX is that the com-
mands are much more descriptive or readable.   Their  disad-
vantage  (in  the  opinion of this writer) is that they take
more time to type.  Both however offer writers the  opportu-
nity to focus on content, without the distraction of look.

While  the  early  systems  were  designed to drive specific
devices, this is no longer the case.  Both systems  generate
a  neutral  device-independent page description which subse-
quent processes format for specific devices.  This is  often
via  Postscript, which on UNIX or UNIX-clone systems is eas-
ily formatted for a wide variety of available  printing  and
plotting  devices,  but need not be.  Today, plain text, TeX
format, PCL5 (HP's printer description  language)  and  HTML
are available.

Although  I  have  acknowledged  the availability of TeX and
LaTeX, this document will not  dwell  on  them,  or  compare
_g_r_o_f_f  to  them.2 For further information on TeX, interested
readers are referred to  [Lamport 1985] and [Knuth 1986].

This document then will describe how one can profit  by  the
use  of _g_r_o_f_f to generate high quality articles, reports and
even books (many of which have been written using  _g_r_o_f_f  or
_t_r_o_f_f.   See  for  example  [Dougherty  and  O'Reilly  1987;
Kernighan and Plauger 1974; Kernighan and Plauger 1976]  and
[Sequin and Tompsett 1975] to name a few).

22..  DDiissccllaaiimmeerr

This  document  is intended to be one that assists new users
by introducing  them  to  _g_r_o_f_f  and  friends.   It  is  not
intended  to  be a definitive reference manual.  Other docu-
ments cover these subjects  very  well,  and  are  available
either  with the current distribution or at a web site iden-
tified in the sequel.  _g_r_o_f_f  comes  with  well-written  mmaann
ppaaggeess that describe the differences between _g_r_o_f_f and _t_r_o_f_f.
These with the aforementioned reference  documents  are  all
that  have  been available for some time.  Under development
however, are complete  reference  documents  for  the  _g_r_o_f_f
suite.

Given  the  nature of this document, and the availability of
other documentation, please do not hold me  responsible  for
-----------
tems 1988].
  2 At least not in this revision.


$Revision: 1.9 $   Groff and Friends HOWTO    December, 1999


                             -3-


any  damages  that  you  or your organization may incur as a
result of using the _g_r_o_f_f suite  or  this  HOWTO.   As  with
other  free  software,  you use it at your own risk.  No one
associated with this software, this document, or any  others
mentioned  herein  has  intended that you incur any damages.
All products described here are made available freely,  with
the  hope  that  they benefit you as much as they have bene-
fited us.

33..  CCrreeddiittss aanndd CCooppyyrriigghhtt

The _g_r_o_f_f document preparation suite was written by James J.
Clark  who  re-implemented  the  _t_r_o_f_f system in some 60,000
lines of C++ code.  Since then he has  gone  on  to  develop
SGML  parsers and related processors in both C and C++.  All
users of _g_r_o_f_f owe considerable thanks to his not  inconsid-
erable efforts.

The current suite of programs are being maintained by Werner
Lemberg and Ted Harding, with contributions by many  others.
As  this  document  is being written, the current release of
the suite, with enhancements for HTML and  graph  rendering,
is version 1.13.

Some  of the current and past contributors to this document,
either directly or  indirectly,  plus  contributors  to  the
_g_r_o_f_f suite in general are:

                CCoonnttrriibbuuttoorrss ttoo tthhee _g_r_o_f_f ssuuiittee
----------------------------------------------------------------
    James J. Clark   groff's author
  Jeffrey Copeland   duplex printing
       Paul Eggert   various patches including Y2K compliance
      Trent Fisher   tex.info format reference manual
       Thor M. Gil   Windows 95/98/NT binaries for _g_r_o_f_f
         Jrgen Hgg   new mmmm macros (version 1.32)
       Ted Harding   user assistance
       Larry Jones   Gxditview additions, including grey levels
Susan G. Kleinmann   Additional man pages
    Werner Lemberg   release coordination
      Eddie Maddox   web site maintainer
      Peter Miller   soelim path control
      Gaius Mulley   grohtml
   Bernhard Reiter   mail list manager

This  document  is  copyright by the author3, who grants all
readers a non-exclusive right to copy and to  distribute  it
without compensation under the terms of the GNU General Pub-
lic Licence.4

-----------
  3 (C) 1999 Dean Allen Provins
  4 For the terms of this licence,  see  the  file
COPYING that comes with the _g_r_o_f_f distribution.


December, 1999     Groff and Friends HOWTO  $Revision: 1.9 $


                             -4-


44..  mmss MMaaccrroo OOvveerrvviieeww

As  indicated  earlier,  there  are  seceral  _m_a_c_r_o packages
available for _g_r_o_f_f; but what is a macro package?  Think  of
it  as  a high level page description, which is written in a
low level page description language.  An analogy to a  macro
package might be a procedural language like C, which is rel-
atively easy to read, but which (when  compiled)  is  turned
into  a  low  level  language like assembler, and ultimately
machine instructions.  Few people code in assembly  language
any  more,5  preferring to use higher level instruction sets
(which incidentally greatly improves productivity).

In a similar manner, a macro package for _g_r_o_f_f such  as  the
package  of  _m_s macros6 is a collection of statements, which
when  interpreted  are  translated  into  low  level   _t_r_o_f_f
instructions.  You are welcome to use  only  the  low  level
instructions  in  your  documents,  but you will likely find
that the use of a package like _m_s greatly  facilitates  your
productivity.   On  the  other  hand,  you may find that the
macro packages available don't meet your specific formatting
needs,  and  you  may  wish to alter an existing package, or
write your own package.

In this document, you won't see any new macro package devel-
opment, but later I'll show you how one might customize some
of the _m_s commands.

When _g_r_o_f_f invokes the GNU version of _t_r_o_f_f, it  causes  the
replacement of the high level macro commands that you intro-
duce to describe how you  have  organized  your  text  (into
chapters, sections, tables and so on) into low level format-
ting commands.  These are interpreted by the code that actu-
ally  manipulates your text into an attractive document.  If
you're familiar with HHTTMMLL, which is a subset  of  Structured
Generalized  Markup  Language, or SSGGMMLL then you already know
about page  formatting  and  markup  languages.   The  _t_r_o_f_f
macros  (and  consequently  the _g_r_o_f_f macros) are simply the
earliest implementation of machine interpreted  markup  lan-
guages.

The  _m_s macros are designed to assist you in formatting let-
ters, proposals, memos, technical  papers  and  reports.   I
have used them for all of these purposes, and have also cre-
ated (admittedly short) books.  To meet my particular needs,
I  have added to the package, and also modified the supplied
-----------
  5 Some of us older folks found it rather  enjoy-
able.   It sort of set apart the men from the boys
so-to-speak.
  6 There  are  several  macro  packages available
with the _g_r_o_f_f distribution, including _m_a_n, _m_s, _m_m
and  _m_e:   see  for  example, 'man 7 groff_ms' and
'man 7 groff_me' for details.


$Revision: 1.9 $   Groff and Friends HOWTO    December, 1999


                             -5-


macros.   In  the sequel, I'll show some of these things7 so
that you are left with a  sufficiently  comfortable  feeling
about what you can do, and how you might go about it.

44..11..  AA SSiimmppllee EExxaammppllee

Suppose that we need to write a short report.  It requires a
title, some author information and an  abstract  to  precede
several  chapters (or sections), some of which may have sub-
sections.  We can format it as follows:

  1       .TL
  2       Our Important Report
  3       .AU
  4       Dean Provins
  5       .AI
  6       Noted Author and Hacker
  7       Student of Life and the University of Calgary
  8       .AB
  9       Noted author and hacker, Dean Provins reveals all in the much heralded
 10       HOWTO for \fIgroff\fP.  In this classic document, Provins describes the
 11       inner workings of one of the earliest machine document processing systems
 12       available.

 13       Readers are encouraged to try any or all the examples provided.
 14       .AE
 15       .NH
 16       Machine Document Processing
 17       .LP
 18       In this chapter, we see that computers have finally come into their own.
 19       No more must workers labour over Gutenberg presses, as they have for
 20       generations.
 21       .NH
 22       Macros
 23       .LP
 24       There are many macro packages available for \fIgroff\fP and friends.  There
 25       are even more available for its predecessor \fItroff\fP.
 26       .ds MS \fIms\fP
 27       .NH 2
 28       The \*[MS] Macro Package
 29       .LP
 30       The \*[MS] macros provide a much needed lift for those toiling with the
 31       basic \fItroff\fP commands.  They (the \*[MS] macros) are now used
 32       extensively by writers the world over.

The result looks like the following (I trimmed the bottom of
the page off for this display):


-----------
  7 I won't describe all, as some  are  embarrass-
ingly poor hacks!


December, 1999     Groff and Friends HOWTO  $Revision: 1.9 $


                             -6-

+----------------------------------------------------------+
+----------------------------------------------------------+

So  what  happened?  The _m_s macros which are introduced by a
period, followed by 2 uppercase letters in the example  text
were  interpreted  by  the  _t_r_o_f_f  processor as representing
_t_r_o_f_f commands.  These then controlled the formatting of the
final  result.   With  the  exception of line 26 (which is a
_t_r_o_f_f command to be explained later) all others  represented
font size changes, centering, emboldening and so on.

We start with the .TTLL command.  This is a macro for a ttiittllee.
It appears at the beginning of a document, centers the  fol-
lowing  text,  increases  the text size and sets it in bold.
The author is identified after line 3 (.AAUU) which  indicates
that  an  aauutthhoorr  nnaammee  (or several author's names) follows.
This macro sets the name in italics.

The author is further identified by lines of text  following
the  .AAII  macro  in line 5.  The aabbssttrraacctt is identified by a
.AABB macro call, and is terminated by a .AAEE which  presumably
means aabbssttrraacctt eenndd.

The  text of the document follows line 15, which indicates a
cchhaapptteerr or main sseeccttiioonn via the macro call  .NNHH.   The  sec-
tion/chapter title follows immediately, and is terminated by
.LLPP on line 17.  Until the next macro call on line  21,  all
text  is  read  and  after  setting  in the current font and
pitch, with line filling8 turned on, The text is  output  to
be  later  formatted  as  PostScript (or whatever format you
wish, and is available).

At line 21, another chapter is identified and text  is  read
in lines 24 and 25.

At  line  26,  the author thought he might take a short cut,
and declared a string expression  named  MMSS  as  '\fBms\fP'.
From  that  point on, the author could use the string expan-
sion expression '\*[MS]' to  represent  '\fBms\fP'.   Admit-
tedly,  this wasn't much of a saving, but it could have been
if the string definition was for '\fItroff\fP'  which  takes
more  keystrokes  than  '\*[MS]'.   The .ddss definition is an
example of a _t_r_o_f_f  command  inserted  into  a  document  to
facilitate text entry.

All  that  remains in the example is a ssuubbsseeccttiioonn definition
at line 27.  As you can see in the resulting text,  sections
receive  numeric  identifiers followed by a period.  Subsec-
tions received  subordinate  numeric  identifiers.   The  _m_s
macros allow for up to 4 levels of sections/subsections.
-----------
  8 If insufficient text is read on an input line,
more  text  from  the next and subsequent lines is
added to fill the output line.  This happens until
a blank line or another macro call is encountered.


$Revision: 1.9 $   Groff and Friends HOWTO    December, 1999


                             -7-


For  the  record, another macro command named .SSHH introduces
uunnnnuummbbeerreedd sseeccttiioonnss.

As you can see, using the _m_s macros  is  quite  straightfor-
ward.   There is no need for you to fill every line of text;
in fact, _g_r_o_f_f is quite happy with a single  word  per  line
(although you may find it difficult to read).  When entering
text, use your favourite text editor (vvii or eemmaaccss), and type
away.  If you need to add a few lines, just insert it at the
appropriate point.  With a text editor, it will be  unlikely
that  you  will  ever  encounter the formatting and overflow
problems that have plagued WYSIWYG word processing  programs
on  longer  documents.  They simply don't have the overhead;
just one more reason to use a document processing system!

Just a word about bbllaannkk lliinneess.  Blank  lines  terminate  the
filling  of  lines.   They  also  indicate the ends of para-
graphs.  Note that the  chapter/section/subsection  commands
generate  blank  lines  before  and  after  the chapter/sec-
tion/subsection title.

55..  TTaabblleess

Periodically, you may find that you need  to  set  out  some
text  in  a  tabular form.  Perhaps it's a list of names and
numbers, or perhaps it is much more complicated.  The  table
capabilities  of  the _g_r_o_f_f suite are handled by a processor
known as ttbbll.

To use ttbbll, one needs to describe  the  general  format  (it
needn't  be  fixed for the entire table), and then enter the
text in a manner that indicates which text belongs in  which
column.   While  I  describe  text as appearing in tables, I
know that equations can also be  entered.   Whether  figures
can  be  or  not,  is not something I have ever experimented
with.

The only limitation that I have ever encountered with tables
is  the  use  to footnotes.  As I recall, automatically num-
bered footnotes are incorrectly numbered; but we'll  see  if
that still holds in the following example.

Suppose that we have some names and telephone numbers of key
individuals, and that we would like to organize  them  in  a
table to be contained in a document.  The following might do
the job for an individual who uses _g_r_o_f_f to keep his diary:9

  1       .SH
  2       Another Day in the Life of Dean P.
  3       .LP
  4       Lately, my life has become more complicated.  Now the boss wants me to
-----------
  9 Let us assume  that  we  don't  need  numbered
chapters.


December, 1999     Groff and Friends HOWTO  $Revision: 1.9 $


                             -8-


  5       remember the names and telephone numbers of key suppliers, and selected
  6       contacts.  As if I don't already have enough to do.  Well my memory used
  7       to be up to the task, but in these declining years, if I want to hang on
  8       to this job, I better work smarter.  I think I'll use that new-fangled
  9       _g_r_o_f_f program.  I hear it's great!
 10       .TS
 11       center box tab (:);
 12       cb cb cb cb
 13       r | n | l | l.
 14       Telephone Number:Serial Number:Contact:Supplier
 15       _
 16       123-3456:123.:Jim:ABS Supplies
 17       123-5437:.456::Genco Paints
 18       557-234-3333:123.456:Suzy:HAL Computer Systems
 19       .TE
 20       Well that should do it.  As long as I have this diary, I'll never forget
 21       again.
 22       .SH
 23       The Next Day
 24       .LP
 25       Wow!  I sure impressed the boss today.  I got ABS Supplies contact name
 26       with just one small glance at my diary.  Now I'm in his good books!

And what is the result of this?

+----------------------------------------------------------+
+----------------------------------------------------------+

In this example, we used the section command .SSHH to  provide
unnumbered  section  titles  (lines  1-3).   Line 10 saw the
beginning of our table, which went to line 19.  As  you  can
see,  tables  begin  with  a .TTSS command, and end with a .TTEE
command.

The first line after .TTSS (up to  the  semi-colon)  describes
some  general  parameters.   I have indicated that the table
should be centered, enclosed in a box,  and  that  the  text
information will be divided into columns by a colon (the ttaabb
command).

The next line applies to the first line of the  table  data.
In  this  case  it says that there will be four columns, and
that the text for each column (if given) is to  be  centered
and  emboldened.   The  final line (up to the period on line
13) describes the subsequent lines of text which make up the
table.   Here  I  indicated  that the first column was to be
right justified (rr) and followed by  a  vertical  line  (||).
The next column will be treated as numeric data and the dec-
imal points will be aligned.  The last two columns  will  be
left  justified.   Vertical lines will separate all columns.
The period at the end of this line indicates that  the  for-
matting information is complete.

The   next  line  is  presumed  to  be  the  column  headers


$Revision: 1.9 $   Groff and Friends HOWTO    December, 1999


                             -9-


(corresponding to the first  line  of  format  description).
Then  comes  a  horizontal  line,  followed by the remaining
lines of text.  Notice the colons  separating  each  column,
and  notice  that line 17 lacks one column of data.  The ttbbll
program leaves space for missing data,  if  necessary.   The
ttaabb character (a colon here) can be any character not in the
text (a real TAB works fine too).

This is a very simple table example, but is useful to illus-
trate  how easy it is to generate one.  A very slightly more
complicated table might look like,

          +--------------------------------------+
          +--------------------------------------+
          |    AA TTaabbllee CCoonnttaaiinniinngg EEqquuaattiioonnss      |
          +--------------------------------------+
          |Equation 1             _a=_b2+_d___c3__        |
          |                                      |
          |Equation 2             _a_k=_i_N=1_C_i0_x2_k_d_x  |
          |Don't you wish there   Equations      |
          |were nnoo mmoorree                          |
          +--------------------------------------+
It was gen+e-r-a-t-e-d--b-y--m-e-a-n-s--o-f---------------------+

  1       .TS
  2       center doublebox delim (@#) tab ( );
  3       cb s
  4       l l.
  5       A Table Containing Equations
  6       _
  7       Equation 1    @a = sqrt {b sup 2 + c over {d sup 3}}#

  8       Equation 2    @a sub k = sum from i=1 to N C sub i  int from 0 to pi x sub k sup 2 dx#
  9       .T&
 10       r l.
 11       T{
 12       Don't you wish there were
 13       \fBno more\fP
 14       T}  Equations
 15       .TE

This  time  I  asked for a ddoouubblleebbooxx centered, with equation
delimiters of @ and #.10 and a TAB character as the  separa-
tor between the columns.11

In this example, I have  also  illustrated  inline  equation
-----------
  10 In my documents, for  historical  reasons,  I
set  these as the equation delimiters.  More typi-
cally, you would use two @ symbols.
  11 A  real  TAB  entered at this location on the
page causes the parentheses to appear separated by
this  amount.   At  another  location,  the amount
might be different.


December, 1999     Groff and Friends HOWTO  $Revision: 1.9 $


                            -10-


definitions.   As you can see, they are textual, which makes
them reasonably easy to read (and key in).

Between lines 7 and 8 there is a  blank  line  (unnumbered),
and  at  line 9, I have given a ttbbll command (.TT&&) which says
that I wish to restate the format of the  columns  (which  I
define on the next line, ending it in a period).

Just  for  fun,  and  to  illustrate  how one can enter long
strings of text (although mine is very short), I have illus-
trated  the  use of the text block entry commands TT{{ and TT}}.
These must appear as follows:

+o    Enter the TT{{ as the first  two  characters  immediately
     following  the  ttaabb, or the first two characters if the
     text block belongs in the first column.

+o    Place the TT}} on the line immediately following the last
     line  of text in the block.  If another column follows,
     enter the ttaabb and continue with that column's text.

The ttbbll program will wrap blocks of text into a single  col-
umn  for  you.   As you can see, ttbbll wraps the text where it
likes (not necessarily where you would like);  nevertheless,
text wrap, especially in the last column can be very useful.

66..  EEqquuaattiioonnss


77..  FFiigguurreess


88..  RReeffeerreenncceess


99..  UUsseeffuull SSccrriippttss


1100..  CCuussttoommiizziinngg tthhee mmss MMaaccrrooss


1111..  CCuussttoommiizziinngg EEqquuaattiioonnss aanndd RReeffeerreenncceess


1122..  AA SSaammppllee DDooccuummeenntt


$Revision: 1.9 $   Groff and Friends HOWTO    December, 1999


                            -11-


1133..  DDooccuummeenntt OOrrggaanniizzaattiioonn aanndd aa SSaammppllee MMaakkeeffiillee


1144..  FFoorrmmaattss OOtthheerr TThhaann PPoossttSSccrriipptt


1155..  QQuueessttiioonnss AAbboouutt _g_r_o_f_f;;  SSoommee WWiitthh AAnnsswweerrss


1155..11..  HHooww DDoo II CCoonnvveerrtt PPoossttSSccrriipptt ttoo AASSCCIIII oorr HHTTMMLL??

PostScript  to  ASCII  conversions  may  be  performed   via
_p_s_2_a_s_c_i_i.   This  program  is  a Ghostscript translator from
PostScript or PDF to ASCII (i.e. plain  text).   Apart  from
first  converting PostScript to ASCII, and then adding suit-
able formatting commands to generate HTML, I  have  no  idea
how one can convert directly to HTML.

1155..22..  IIss TThheerree aa _g_r_o_f_f _i_n_f_o FFiillee??

Trent  Fisher  has  contributed  a rudimentary groff.texinfo
file and this is now  a  part  of  the  _g_r_o_f_f  distribution.
Should  an  interested party wish to extend this work, their
assistance would be gratefully received.

1155..33..  HHooww ccaann II ddoo CCyyrriilllliicc wwiitthh _g_r_o_f_f??

Recently the following question was posed:

     On 29-Oct-99 Grigoriy Strokin wrote:
     > Hello,
     >
     > How do I prepare Cyrillic documents in PostScript
     > using groff, provided I have Cyrillic fonts for Ghostscript?
     >
     > In fact, some cyrillic letters appear as expected,
     > but some other are replaced by groff to funny characters
     > such as Thorn or multiply sign.

The following is a transcription of the response:

     I'm  not  familiar   with   Cyrillic   fonts   for
     Ghostscript, and these may possibly have a problem
     with missing characters, for all I know.  The fol-
     lowing  assumes  that  you  have a PostScript font
     with a complete Cyrillic character  set  (possibly
     from ghostscript, of course).

     Provided  you  have "copied" the Cyrillic fonts to
     groff (i.e.  you  have  installed  them  as  groff
     fonts  in ..../groff/fonts/devps) you could handle
     this according to some variant of one of  the  two


December, 1999     Groff and Friends HOWTO  $Revision: 1.9 $


                            -12-


     following methods.

     METHOD 1

     Look,  in  this  directory, at the font file for a
     particular font (e.g. I have a font which I pulled
     from  the Web called "College Cyrillic" whose font
     file I have called "CCy",  quite  arbitrarily,  to
     which the following applies).

     This  may start with a list of "kernpairs", but in
     any case you will come to a  line  with  the  word
     "charset".

     After  the  "charset"  line  you  will see several
     columns of  information  (the  number  of  columns
     depends  on the font), most of which is "font met-
     rics", one line for each character.  Some  charac-
     ters will be Latin, others Cyrillic.

     The  first  column  will  be either a single ASCII
     character, a groff  name  for  the  character,  or
     "---".  The  last  column but one will be an octal
     number of the form "0pqr". For instance, the stan-
     dard  octal  code for the letter "A" in English is
     "0101". In decimal, this  is  "65"  which  is  the
     ASCII  code  for "A". The rule for conversion from
     octal "0pqr" to decimal is 64*p + 8*q + r.

     You now need to identify which decimal codes  cor-
     respond to which Cyrillic characters (if they also
     have groff names,  so  much  the  better;  but  it
     doesn't matter). The most direct way to do this is
     to print out a table consisting (in  groff  input)
     of lines like

     241     \N'241'

     where  (in  this example) the "241" is the decimal
     form of the octal 0361.

     The groff escape  sequence  "\N'237'"  causes  the
     character  with  octal  code "0361" in the correct
     font to be printed. So you must make sure that the
     current  font  is  the  Cyrillic font when this is
     printed (e.g. by using "\f[...]", or  the  request
     ".ft  ..." on a line by itself, where "..." is the
     name of the font, i.e. the name of the  font  file
     you  were  looking  at above, such as "\f[CCy]" or
     ".ft CCy").

     Once you have got this information, you  can  then
     link this to your input.


$Revision: 1.9 $   Groff and Friends HOWTO    December, 1999


                            -13-


     Myself,  being  primarily  in  a Latin environment
     with Cyrillic being required exceptionally, I  use
     two  schemes.  One  is for single Russian words or
     very short pieces of Russian text, and is based on
     transliteration.  For  instance,  the Russian "YA"
     (looking  like  an  upper-case  reversed  "R")  is
     denoted  by  the  groff escape "\(YA".  Similarly,
     the lower-case version is "\(ya".

     This is pre-defined (in private macros) by

      .char \(YA \N'241'

     (This character is at 241 in most -- but  not  all
     --  of the Cyrillic PostScript fonts which I have.
     Therefore, if that is also the case with you,  you
     should switch to Cyrillic using a macro like

           .Cyr
           .fnt fontname
           .tr \(xx \N'nnn'
           .tr ...  ...
             ...
           .

     If  the  Cyrillic  character  encoding  depends on
     which font you are using, it might  be  better  to
     make the name of the macro the same as the name of
     the font. Then you can use font-specific  transla-
     tions.

     The  other  (for extended text where using escapes
     like "\(YA" throughout would be  too  tedious)  is
     based  on  a  similar  character translation which
     allows me to type  in  Latin  characters  using  a
     transliteration-like  convention (I can't be both-
     ered to fiddle with keyboards) like (using Russian
     alphabetical order)

           .tr A \N'225'           [Cyrillic char identical to Latin "A"]
           .tr B \N'226'           [Cyrillic char like large 'b']
           .tr V \N'247'           [Cyrillic char identical to Latin "B"]
           .tr G \N'231'           [Cyrillic char identical to Greek GAMMA]
           ..
           .tr \(YA \N'241'

     so  that, for instance, the word for "Probability"
     would be entered  as   "Vero\(yatnoste\(i:".  This
     reduces  the  use of escape sequences to the mini-
     mum. (The sequence "\(i:" stands for "i-kratkoi"

     You could also, of course,  Grigoriy,  define  the
     compound character


December, 1999     Groff and Friends HOWTO  $Revision: 1.9 $


                            -14-


      .char \(iy i\(i:

     so that your name would be typed "Grigor\(iy".


     METHOD 2 (which depends on info from Method 1)

     In your environment, which is presumably primarily
     Cyrillic, you will probably  be  using  a  Russian
     keyboard,  and a screen font based on the ISO font
     encoding  iso-8859-5  (Cyrillic)   where   various
     numerical  codes  above 128 correspond to Cyrillic
     characters.

     For the reasons given above, the iso-latin-5 char-
     acter encoding may differ from the encoding in the
     PostScript font you  are  using.   Therefore,  you
     should carry out the above check as to which deci-
     mal codes correspond to which  printed  characters
     in the Cyrillic PostScript font. Some of these may
     coincide with the iso-8859-5 encoding; others  may
     be different. In that case, what you need to do is
     to define a translation for the  anomalous  codes,
     as above, so that you can type the characters nor-
     mally using the keyboard,  they  will  print  cor-
     rectly,  and  you will also see them on the screen
     correctly.

     In the first place, this is a  lot  of  work;  but
     once  it has been done you will have an easy life!

     The best of luck, Ted.


1155..44..  WWhheerree ccaann II ggeett WWiinnddoowwss bbiinnaarriieess ooff _g_r_o_f_f??

Thor M. Gil has ported  _g_r_o_f_f  to  Microsoft's  most  recent
operating  systems (95, 98 and NT).  You can obtain it, plus
some          installation          information           at
hhttttpp::////wwwwww..ccss..vvuu..nnll//~~ttmmggiill//mmiisscc//wwiinnggrrooffff..hhttmmll.  Other recom-
mended software, such as WWiinnzziipp and GGSSvviieeww are  also  avail-
able at that site.

1155..55..   IIss  TThheerree  aa DDooccuummeenntt LLiikkee tthhee ""TTrrooffff UUsseerr''ss MMaannuuaall""
ffoorr _g_r_o_f_f??

One of the maintainers (Ted Harding) has embarked on such  a
document.   As this is not a trivial undertaking, it may not
be available for some time.  Readers are encouraged to  sub-
scribe  to the _g_r_o_f_f mail list to follow the development, or
to volunteer to assist Ted in order to speed it along.

For immediate use, are a series of overheads that  Ted  used
in  a  recent  presentation to his local Linux user's group.


$Revision: 1.9 $   Groff and Friends HOWTO    December, 1999


                            -15-


These foils, with their _g_r_o_f_f source  files,  are  available
from    the   following   European   site:   hhttttpp::////wwwwww..mmaann--
lluugg..mmcccc..aacc..uukk//1199999911112200//ttaallkk..ttaarr..ggzz.  See the  file  ttaallkk..ttxxtt
for a description of the contents.

1166..  OOtthheerr SSoouurrcceess ooff IInnffoorrmmaattiioonn

Several  of  the  references cited earlier are worth looking
at, if copies can be located in your local library.  In par-
ticular,  the  book  by  Dougherty  and  O'Reilly is useful,
although not particularly so  as  a  reference12.   The  Sun
Microsystems  document  is  very  good,  and is based on the
PostScript files mentioned below.

There  are  several documents available in PostScript format
which describe the use of _t_r_o_f_f and  associated  processors.
These  are  available at hhttttpp::////wwwwww..kkoohhaallaa..ccoomm//ssttaarrtt// in the
_t_r_o_f_f    _r_e_s_o_u_r_c_e_s    link    and     at     hhttttpp::////ccmm..bbeellll--
llaabbss..ccoomm//ccmm//ccss//ccssttrr..hhttmmll.

At   hhttttpp::////ppllaann99..bbeellll--llaabbss..ccoomm//77tthhEEddMMaann//iinnddeexx..hhttmmll  may  be
found the original _t_r_o_f_f sources for the documentation  that
was  shipped with the UUnniixx SSeevveenntthh EEddiittiioonn MMaannuuaall.  Included
is material on _t_r_o_f_f and related processors.

The _g_r_o_f_f maintainers have set up a  mailing  list  and  web
site  to  provide interested users with the latest releases,
bug fixes and problem solving facilities.   In  addition,  a
moderated newsgroup named ggnnuu..ggrrooffff..bbuugg is available.

To  subscribe  to  the  mmaaiill  lliisstt,  send an Email to ggrrooffff--
address@hidden@ffffiiii..oorrgg with  the  word  ssuubbssccrriibbee  in  either  the
header  or  the  mail body.  Then, to post to the list, send
your email to address@hidden@ffffiiii..oorrgg.  An  acknowledgement  of  your
request to join will be received, and you will be assigned a
password.  Mail received by the list  will  be  archived  at
hhttttpp::////ffffiiii..oorrgg//aarrcchhiivvee//mmaaiillss//ggrrooffff//.

The  web  site is hhttttpp::////ggrrooffff..ffffiiii..oorrgg//.  There, the latest
version of _g_r_o_f_f and friends is always available.

RReeffeerreenncceess

Dougherty and O'Reilly 1987.
     Dale Dougherty and Tim O'Reilly, _U_N_I_X _T_e_x_t  _P_r_o_c_e_s_s_i_n_g_,
     Hayden  Books, A Division of Howrd W. Sams and Company,
     Indianapolis, Indiana, U.S.A. (1987).

Kernighan, Lesk, and Ossanna 1978.
     B.W. Kernighan, M.E. Lesk, and J.F. Ossanna, Jr., "Doc-
     ument  Preparation," _T_h_e _B_e_l_l _S_y_s_t_e_m _T_e_c_h_n_i_c_a_l _J_o_u_r_n_a_l_,
-----------
  12 This writer finds the text too wordy, and the
index not sufficiently so.


December, 1999     Groff and Friends HOWTO  $Revision: 1.9 $


                            -16-


     57, 6, part 2, pp. 2115-2135,  American  Telephone  and
     Telegraph  Company,  Short  Hills,  New  Jersey, U.S.A.
     (July/August 1978).

Kernighan and Plauger 1974.
     B.W. Kernighan and P.J. Plauger, _T_h_e _E_l_e_m_e_n_t_s  _o_f  _P_r_o_-
     _g_r_a_m_m_i_n_g _S_t_y_l_e_, McGraw-Hill, New York, U.S.A. (1974).

Kernighan and Plauger 1976.
     B.W.  Kernighan and P.J. Plauger, _S_o_f_t_w_a_r_e _T_o_o_l_s_, Addi-
     son-Wesley, Reading Massechusetts, U.S.A. (1976).

Knuth 1986.
     Donald E.  Knuth,  _T_h_e  _T_e_X_b_o_o_k  _(_I_S_B_N  _0_-_2_0_1_-_1_3_4_4_7_-_0_)_,
     Addison-Wesley (1986).

Lamport 1985.
     Leslie  Lamport, _L_a_T_e_X _- _A _D_o_c_u_m_e_n_t _P_r_e_p_a_r_a_t_i_o_n _S_y_s_t_e_m_,
     Addison-Wesley (ISBN 0-201-15790-X) (1985).

Sequin and Tompsett 1975.
     C.H. Sequin and M.F. Tompsett, _C_h_a_r_g_e _T_r_a_n_s_f_e_r _D_e_v_i_c_e_s_,
     Academic Press, New York, U.S.A. (1975).

Sun Microsystems 1988.
     Sun Microsystems,   "Using  NROFF  and  TROFF"  in  _S_u_n
     _M_i_c_r_o_s_y_s_t_e_m_s  _S_y_s_t_e_m  _D_o_c_u_m_e_n_t_a_t_i_o_n_,  Sun  Microsystems
     (May 1988 Revision A).


$Revision: 1.9 $   Groff and Friends HOWTO    December, 1999