Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
GROFF_TMAC(5)		      File Formats Manual		 GROFF_TMAC(5)

NAME
       groff_tmac - macro files	in the roff typesetting	system

DESCRIPTION
       The  roff(7) type-setting system	provides a set of macro	packages suit-
       able 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  usu-
       ally  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
       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 (note that in recent versions of groff this	file is	called
       an.tmac instead).

       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  correspond-
       ing 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  in-
       flicted	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 contents	of the tmac directories.  For example,
       a file called tmac.anything or anything.tmac 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
       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
       name.tmac available as described	in the section NAMING.	If  this  file
       isn't found, tmac.name will be searched.

       It  is also possible to include the macro file into the document	by us-
       ing 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	searches the tmac path
       for the filename.  Additionally,	if the file name to  be	 included  has
       the  form name.tmac and it isn't	found, .mso will try to	open tmac.name
       instead and vice	versa.

       Note that in order to resolve the .so and .mso requests the  roff  pre-
       processor  soelim must be called	if the files to	be included needs pre-
       processing.  This can be	done either directly by	a pipeline on the com-
       mand line or by using the -s option of groff.

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

       For    example,	  suppose    a	  macro	   file	   is	 stored	    as
       /usr/share/tmac/macros.tmac   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 macros.tmac
       is used or
	      .so /usr/share/tmac/macros.tmac

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

CONVENTION
       There is	a convention that is supported by many modern  roff  type-set-
       ters: 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 abbrevia-
       tions for those preprocessor commands that should be run	 when  format-
       ting  the  document.  Mostly, only the letters corresponding to the op-
       tions 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
       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  whatever.tmac  (or
       tmac.whatever)  and put it in some directory of the tmac	path, cf. sec-
       tion 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 de-
	 layed command.

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

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

FILES
       All macro names must be named name.tmac or tmac.name to	use  the  tmac
       mechanism.

       The  macro files	are kept in the	tmac directories, all of which consti-
       tute the	tmac path.

       The elements of the search path for macro files are (in that order):

       o   the directories specified with troff's  resp.  groff's  -M  command
	   line	option

       o   the directories given in the	GROFF_TMAC_PATH	environment variable

       o   the	current	directory (only	if in unsafe mode using	the -U command
	   line	switch)

       o   the home directory

       o   a site-specific (platform-independent) directory,  a	 platform-spe-
	   cific directory, and	the main tmac directory:

	     /usr/share/tmac
	     /usr/share/tmac
	     /usr/share/tmac

ENVIRONMENT
       GROFF_TMAC_PATH
	      A	 colon	separated list of additional tmac directories in which
	      to search	for macro files.  See the previous section for	a  de-
	      tailed description.

BUGS
       The  groff documentation	is in evolution	at the moment.	It is possible
       that small inconsistencies between different documents exist  temporar-
       ily.

AUTHOR
       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
       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_mwww(7),
       groff_mdoc(7),	 groff_mdoc.samples(7),	   groff_me(7),	  groff_mm(7),
       groff_mmroff(7),	and groff_ms(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.17.2		 6 August 2001			 GROFF_TMAC(5)

NAME | DESCRIPTION | NAMING | INCLUSION | CONVENTION | WRITING A MACRO FILE | FILES | ENVIRONMENT | BUGS | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=tmac&sektion=5&manpath=FreeBSD+4.7-RELEASE>

home | help