*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->NetBSD man pages -> groff_tmac (5)              
Title
Content
Arch
Section
 

GROFF_TMAC(5)

Contents


NAME    [Toc]    [Back]

       groff_tmac - macro files in the roff typesetting system

DESCRIPTION    [Toc]    [Back]

       The  roff(7)  type-setting  system provides a set of macro
       packages suitable for special kinds  of  documents.   Each
       macro  package stores its macros and definitions in a file
       called the package's tmac file.  The name is deduced  from
       `Troff MACros'.

       The  tmac  files  are normal roff source documents, except
       that they usually contain only definitions and setup  commands,
  but  no text.  All tmac files are kept in a single
       or a small number of directories, the tmac directories.

NAMING    [Toc]    [Back]

       In classical  roff  systems,  there  was  a  funny  naming
       scheme.   If  the name of a macro package started with `m'
       this letter was omitted, e.g., the macro package  for  the
       man pages man was called an and its macro file tmac.an.

       By  a similar reasoning, macro packages that did not start
       with an `m' were often referred to by adding an `m',
        e.g., the package corresponding to  tmac.doc  was  called
       mdoc because the command-line for activating it reads

              troff -mdoc.

       Actual  versions  of  groff(1) provide both naming schemes
       for the inflicted macro packages,  with  and  without  the
       leading  `m'.  So  in  groff, the man macro package may be
       specified as

              groff -m man,
              groff -man,
              groff -mman, or
              groff -m an.

       The easiest way to  find  out  which  macro  packages  are
       available  on a system is to check the content of the tmac
       directories.  For example,  a  file  called  tmac.anything
       determines a macro package named anything.

       In  groff,  most macro packages are described in man pages
       called groff_<name>(7), with a leading `m' for the classical
 packages.

INCLUSION    [Toc]    [Back]

       There  are  several  ways  to use a macro package in documents.
  At run-time, the groff option  -m name  makes  the
       definitions  in  the  macro  file  tmac.name  available as
       described in the section NAMING.

       It is also possible to include the  macro  file  into  the
       document  by using the groff requests .so or .mso. For .so
       the full filename of the macro file must be  specified  --
       including  the  directory  where it is kept.  If the macro
       file is stored in one of the tmac directories it  is  more
       convenient  to  use  .mso  instead because it additionally
       searches the tmac path for the filename.

       Note that in order to resolve the .so  and  .mso  requests
       the  roff preprocessor soelim must be called.  This can be
       done either directly by a pipeline on the command line  or
       by using the -s option of groff.

       You  can  also  supply  the letter `s' in the preprocessor
       word as described in section CONVENTION.

       For  example,  suppose  a  macro   file   is   stored   as
       /usr/share/groff/tmac/tmac.macros and is used in some document
 called docu.roff.

       At run-time, the formatter call for this is

              groff -m macros docu.roff

       To include the macro file directly in the document either
              .mso tmac.macros
       is used or
              .so /usr/share/groff/tmac/tmac.macros

       In both cases, the formatter is called with
              groff -s docu.roff

CONVENTION    [Toc]    [Back]

       There is a convention that is  supported  by  many  modern
       roff  type-setters: the preprocessor word described in the
       following.

       If the first line in a document is a  comment,  the  first
       word  (after  the  comment characters and a blank) constitutes
 the preprocessor word.  That means that the  letters
       of  this  word  are interpreted as abbreviations for those
       preprocessor commands that should be run  when  formatting
       the  document.   Mostly, only the letters corresponding to
       the options for the  preprocessors  are  recognized,  `e',
       `G', `g', `p', `R', `s', and `t' (see roff(7)).

       Besides  being  a good reminder for the user, some formatters
 (like the man(1) program) are even able to  automatically
  start the preprocessors specified in the preprocessor
 word, but do not bet on this.

WRITING A MACRO FILE    [Toc]    [Back]

       Writing a groff macro file  is  easy.   Design  a  set  of
       macros,  strings,  registers, etc.  Store them in a single
       file.  Documents that use the macros  include  this  macro
       file  with  the  .so request as described in the INCLUSION
       section.

       To  use  the  tmac  functionality,  call  the  macro  file
       tmac.whatever  and  put  it  in some directory of the tmac
       path, cf. section FILES.  Then documents  can  include  it
       with  the .mso request or the groff -m option as described
       in the INCLUSION section.

       If your macros might be of general usage contact the groff
       maintainers  to  have  them  included in the groff contrib
       source directory.

       Some  general  guidelines  might  be  helpful  in  writing
       macros.

       o Double all functional backslashes, `\' -> `\\'.

       o All printable backslashes must be written as `\e'.

       o Escape all dots, `.' -> `\.'.

       o Make  ample  use  of the non-printable character `\&' in
         text parts, esp. before `\' and at the  beginning  of  a
         line, but not before a delayed command.

       o Use the character `@' in temporary variable names.

       o Test  your  macros for text and graphical devices, e.g.,
         latin1 and ps.

FILES    [Toc]    [Back]

       All macro names that want to use the tmac  mechanism  must
       be named according to the form tmac.name.

       The  macro  files are kept in the tmac directories, all of
       which constitue the tmac path.   In  accordance  with  the
       Filesystem  Hierarchy  Standard  (FHS),  the standard tmac
       directory location for groff is  /usr/share/groff/tmac,  a
       local  installation  will use /usr/local/share/groff/tmac.
       Older systems used a subdirectory of  /usr/lib.   Independently
  of  the  default tmac path, the tmac path actually
       used by a document can always be set by a  shell  environment
 variable, cf. section ENVIRONMENT.

ENVIRONMENT    [Toc]    [Back]

       GROFF_TMAC_PATH
              A colon separated list of tmac directories in which
              to search for macro files, the tmac path.  If unset
              a  default path is used as is outlined in the FILES
              section.

BUGS    [Toc]    [Back]

       The groff documentation is in evolution at the moment.  It
       is  possible  that small inconsistencies between different
       documents exist temporarily.

AUTHOR    [Toc]    [Back]

       This document is part of groff, the GNU roff distribution.
       It was written by Bernd Warken <bwarken@mayn.de>.

       It  is  distributed  under  the terms of the FDL (GNU Free
       Documentation License) version 1.1 or later.   You  should
       have received a copy of the FDL on your system, it is also
       available on-line under

              <http://www.gnu.org/copyleft/fdl.html>.

SEE ALSO    [Toc]    [Back]

      
      
       The authoritative source of information for all details of
       the groff system is the groff info(1) file.

       For  a  groff overview, see roff(7) and the file README in
       the groff source package.

       The  groff   tmac   macro   packages   are   groff_man(7),
       groff_markup(7),   groff_mdoc(7),   groff_mdoc.samples(7),
       groff_me(7),  groff_mm(7),  groff_mmroff(7),  groff_ms(7),
       groff_msafer(7).

       The  groff  language is described in groff(7) and the formatters
 in groff(1), troff(1).

       The Filesystem Hierarchy Standard (FHS)  is  available  at
       http://www.pathname.com/fhs/.




Groff Version 1.16.1      April 8, 2001             GROFF_TMAC(5)
[ Back ]
 Similar pages
Name OS Title
roff NetBSD a survey of the roff typesetting system
roff FreeBSD concepts and history of roff typesetting
m4 Tru64 Preprocesses files, expanding macro definitions
zsoelim Linux satisfy .so requests in roff input
groff FreeBSD a short reference for the GNU roff language
ditroff FreeBSD classical device independent roff
groff NetBSD a short reference for the GNU roff language
pod2man OpenBSD Convert POD data to formatted *roff input
pod2man Linux Convert POD data to formatted *roff input
uucp Tru64 Copies files from one system to another (UNIX-toUNIX system copy)
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service