1 \input texinfo @c -*-texinfo-*-
4 @c Please convert this manual with `texi2dvi -e groff.texinfo' due to a bug
5 @c in texinfo regarding expansion of user-defined macros.
8 @c %**start of header (This is for running Texinfo on a region.)
10 @settitle The GNU Troff Manual
11 @setchapternewpage odd
12 @footnotestyle separate
13 @c %**end of header (This is for running Texinfo on a region.)
16 @c We use the following indices:
22 @c kindex: commands in font files
23 @c pindex: programs and files
24 @c tindex: environment variables
27 @c glindex: glyph names
30 @c tindex and cindex are merged.
41 @c to avoid uppercasing in @deffn while converting to info, we define
44 @c due to a bug in makeinfo 4.0, macros are not expanded in @deffn (but
45 @c the macro definition is properly removed), so we have to define
46 @c @Var{} directly in TeX also
56 @c definition of requests
58 @macro Defreq{name, arg}
60 @deffn Request @t{.\name\} \arg\
63 @macro Defreqx{name, arg}
65 @deffnx Request @t{.\name\} \arg\
73 @c definition of escapes
75 @macro Defesc{name, delimI, arg, delimII}
77 @deffn Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\}
80 @macro Defescx{name, delimI, arg, delimII}
82 @deffnx Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\}
90 @c definition of registers
94 @deffn Register @t{\\n[\name\]}
99 @deffnx Register @t{\\n[\name\]}
107 @c definition of macros
109 @macro Defmac{name, arg}
111 @defmac @t{.\name\} \arg\
114 @macro Defmacx{name, arg}
116 @defmacx @t{.\name\} \arg\
124 @c definition of strings
126 @macro Defstr{name, arg}
128 @deffn String @t{\name\} \arg\
131 @macro Defstrx{name, arg}
133 @deffnx String @t{\name\} \arg\
154 @c We need special parentheses and brackets:
156 @c . Real parentheses in @deffn produce an error while compiling with
158 @c . Real brackets use the wrong font in @deffn, overriding @t{}.
160 @c This is true for texinfo 4.0.
193 @c XXX comment all examples
196 @dircategory Miscellaneous
198 * Groff: (groff). The GNU troff document formatting system.
211 This Info file documents GNU troff version 1.16.
213 Published by the Free Software Foundation
214 59 Temple Place, Suite 330
215 Boston, MA 02111-1307 USA
217 Copyright (C) 1994-2000 Free Software Foundation, Inc.
219 Permission is granted to make and distribute verbatim copies of this
220 manual provided the copyright notice and this permission notice are
221 preserved on all copies.
224 Permission is granted to process this file through TeX and print the
225 results, provided the printed document carries copying permission notice
226 identical to this one except for the removal of this paragraph (this
227 paragraph not being relevant to the printed manual).
230 Permission is granted to copy and distribute modified versions of this
231 manual under the conditions for verbatim copying, provided that the
232 entire resulting derived work is distributed under the terms of a
233 permission notice identical to this one.
235 Permission is granted to copy and distribute translations of this manual
236 into another language, under the above conditions for modified versions,
237 except that this permission notice may be stated in a translation
238 approved by the Foundation.
240 Permission is granted to copy and distribute modified versions of this
241 manual under the conditions for verbatim copying, provided also that the
242 section entitled ``GNU General Public License'' is included exactly as
243 in the original, and provided that the entire resulting derived work is
244 distributed under the terms of a permission notice identical to this
247 Permission is granted to copy and distribute translations of this manual
248 into another language, under the above conditions for modified versions,
249 except that the section entitled ``GNU General Public License'' may be
250 included in a translation approved by the Free Software Foundation
251 instead of in the original English.
257 @subtitle The GNU implementation of @code{troff}
258 @subtitle Edition 1.16
259 @subtitle Spring 2000
260 @author by Trent A.@w{ }Fisher
261 @author and Werner Lemberg
263 @c Include the Distribution inside the titlepage environment so
264 @c that headings are turned off. Headings on and off do not work.
267 @vskip 0pt plus 1filll
268 Copyright @copyright@w{ }1994-2000 Free Software Foundation,@w{ }Inc.
270 Version 1.16 of @code{groff}, @*
273 Published by the Free Software Foundation @*
274 59 Temple Place, Suite 330 @*
275 Boston, MA 02111-1307 USA
278 Permission is granted to make and distribute verbatim copies of this
279 manual provided the copyright notice and this permission notice are
280 preserved on all copies.
282 Permission is granted to copy and distribute modified versions of this
283 manual under the conditions for verbatim copying, provided also that the
284 section entitled ``GNU General Public License'' is included exactly as
285 in the original, and provided that the entire resulting derived work is
286 distributed under the terms of a permission notice identical to this
289 Permission is granted to copy and distribute translations of this manual
290 into another language, under the above conditions for modified versions,
291 except that the section entitled ``GNU General Public License'' may be
292 included in a translation approved by the Free Software Foundation
293 instead of in the original English.
295 Cover art by Etienne Suvasa.
301 @node Top, Copying, (dir), (dir)
304 This Info file documents groff version 1.16, the GNU implementation of
305 the troff typesetting system.
307 This is an in-progress document; contributions, comments, or
308 contributions are welcome. Send them to bug-groff@@gnu.org.
315 * Tutorial for Macro Users::
317 * Programming Tutorial::
329 * Font File Keyword Index::
330 * Program and File Index::
336 @node Copying, Introduction, Top, Top
338 @unnumbered GNU GENERAL PUBLIC LICENSE
339 @center Version 2, June 1991
342 Copyright @copyright{}@w{ }1989, 1991 Free Software Foundation, Inc.
343 59@w{ }Temple Place, Suite@w{ }330, Boston, MA@w{ }02111, USA
345 Everyone is permitted to copy and distribute verbatim copies of this
346 license document, but changing it is not allowed.
349 @unnumberedsec Preamble
351 The licenses for most software are designed to take away your freedom to
352 share and change it. By contrast, the GNU General Public License is
353 intended to guarantee your freedom to share and change free software --
354 to make sure the software is free for all its users. This General
355 Public License applies to most of the Free Software Foundation's
356 software and to any other program whose authors commit to using it.
357 (Some other Free Software Foundation software is covered by the GNU
358 Library General Public License instead.) You can apply it to your
361 When we speak of free software, we are referring to freedom, not price.
362 Our General Public Licenses are designed to make sure that you have the
363 freedom to distribute copies of free software (and charge for this
364 service if you wish), that you receive source code or can get it if you
365 want it, that you can change the software or use pieces of it in new
366 free programs; and that you know you can do these things.
368 To protect your rights, we need to make restrictions that forbid anyone
369 to deny you these rights or to ask you to surrender the rights. These
370 restrictions translate to certain responsibilities for you if you
371 distribute copies of the software, or if you modify it.
373 For example, if you distribute copies of such a program, whether gratis
374 or for a fee, you must give the recipients all the rights that you have.
375 You must make sure that they, too, receive or can get the source code.
376 And you must show them these terms so they know their rights.
378 We protect your rights with two steps: (1)@w{ }copyright the software,
379 and (2)@w{ }offer you this license which gives you legal permission to
380 copy, distribute and/or modify the software.
382 Also, for each author's protection and ours, we want to make certain
383 that everyone understands that there is no warranty for this free
384 software. If the software is modified by someone else and passed on, we
385 want its recipients to know that what they have is not the original, so
386 that any problems introduced by others will not reflect on the original
387 authors' reputations.
389 Finally, any free program is threatened constantly by software patents.
390 We wish to avoid the danger that redistributors of a free program will
391 individually obtain patent licenses, in effect making the program
392 proprietary. To prevent this, we have made it clear that any patent
393 must be licensed for everyone's free use or not licensed at all.
395 The precise terms and conditions for copying, distribution and
399 @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
402 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
407 This License applies to any program or other work which contains a
408 notice placed by the copyright holder saying it may be distributed under
409 the terms of this General Public License. The ``Program'', below,
410 refers to any such program or work, and a ``work based on the Program''
411 means either the Program or any derivative work under copyright law:
412 that is to say, a work containing the Program or a portion of it, either
413 verbatim or with modifications and/or translated into another language.
414 (Hereinafter, translation is included without limitation in the term
415 ``modification''.) Each licensee is addressed as ``you''.
417 Activities other than copying, distribution and modification are not
418 covered by this License; they are outside its scope. The act of running
419 the Program is not restricted, and the output from the Program is
420 covered only if its contents constitute a work based on the Program
421 (independent of having been made by running the Program). Whether that
422 is true depends on what the Program does.
425 You may copy and distribute verbatim copies of the Program's source code
426 as you receive it, in any medium, provided that you conspicuously and
427 appropriately publish on each copy an appropriate copyright notice and
428 disclaimer of warranty; keep intact all the notices that refer to this
429 License and to the absence of any warranty; and give any other
430 recipients of the Program a copy of this License along with the Program.
432 You may charge a fee for the physical act of transferring a copy, and
433 you may at your option offer warranty protection in exchange for a fee.
436 You may modify your copy or copies of the Program or any portion of it,
437 thus forming a work based on the Program, and copy and distribute such
438 modifications or work under the terms of Section@w{ }1 above, provided
439 that you also meet all of these conditions:
443 You must cause the modified files to carry prominent notices stating
444 that you changed the files and the date of any change.
447 You must cause any work that you distribute or publish, that in whole or
448 in part contains or is derived from the Program or any part thereof, to
449 be licensed as a whole at no charge to all third parties under the terms
453 If the modified program normally reads commands interactively when run,
454 you must cause it, when started running for such interactive use in the
455 most ordinary way, to print or display an announcement including an
456 appropriate copyright notice and a notice that there is no warranty (or
457 else, saying that you provide a warranty) and that users may
458 redistribute the program under these conditions, and telling the user
459 how to view a copy of this License. (Exception: if the Program itself
460 is interactive but does not normally print such an announcement, your
461 work based on the Program is not required to print an announcement.)
464 These requirements apply to the modified work as a whole. If
465 identifiable sections of that work are not derived from the Program, and
466 can be reasonably considered independent and separate works in
467 themselves, then this License, and its terms, do not apply to those
468 sections when you distribute them as separate works. But when you
469 distribute the same sections as part of a whole which is a work based on
470 the Program, the distribution of the whole must be on the terms of this
471 License, whose permissions for other licensees extend to the entire
472 whole, and thus to each and every part regardless of who wrote it.
474 Thus, it is not the intent of this section to claim rights or contest
475 your rights to work written entirely by you; rather, the intent is to
476 exercise the right to control the distribution of derivative or
477 collective works based on the Program.
479 In addition, mere aggregation of another work not based on the Program
480 with the Program (or with a work based on the Program) on a volume of a
481 storage or distribution medium does not bring the other work under the
482 scope of this License.
485 You may copy and distribute the Program (or a work based on it, under
486 Section@w{ }2) in object code or executable form under the terms of
487 Sections@w{ }1 and@w{ }2 above provided that you also do one of the
492 Accompany it with the complete corresponding machine-readable source
493 code, which must be distributed under the terms of Sections@w{ }1 and@w{
494 }2 above on a medium customarily used for software interchange; or,
497 Accompany it with a written offer, valid for at least three years, to
498 give any third party, for a charge no more than your cost of physically
499 performing source distribution, a complete machine-readable copy of the
500 corresponding source code, to be distributed under the terms of
501 Sections@w{ }1 and@w{ }2 above on a medium customarily used for software
505 Accompany it with the information you received as to the offer to
506 distribute corresponding source code. (This alternative is allowed only
507 for noncommercial distribution and only if you received the program in
508 object code or executable form with such an offer, in accord with
509 Subsection@w{ }b above.)
512 The source code for a work means the preferred form of the work for
513 making modifications to it. For an executable work, complete source
514 code means all the source code for all modules it contains, plus any
515 associated interface definition files, plus the scripts used to control
516 compilation and installation of the executable. However, as a special
517 exception, the source code distributed need not include anything that is
518 normally distributed (in either source or binary form) with the major
519 components (compiler, kernel, and so on) of the operating system on
520 which the executable runs, unless that component itself accompanies the
523 If distribution of executable or object code is made by offering access
524 to copy from a designated place, then offering equivalent access to copy
525 the source code from the same place counts as distribution of the source
526 code, even though third parties are not compelled to copy the source
527 along with the object code.
530 You may not copy, modify, sublicense, or distribute the Program except
531 as expressly provided under this License. Any attempt otherwise to
532 copy, modify, sublicense or distribute the Program is void, and will
533 automatically terminate your rights under this License. However,
534 parties who have received copies, or rights, from you under this License
535 will not have their licenses terminated so long as such parties remain
539 You are not required to accept this License, since you have not signed
540 it. However, nothing else grants you permission to modify or distribute
541 the Program or its derivative works. These actions are prohibited by
542 law if you do not accept this License. Therefore, by modifying or
543 distributing the Program (or any work based on the Program), you
544 indicate your acceptance of this License to do so, and all its terms and
545 conditions for copying, distributing or modifying the Program or works
549 Each time you redistribute the Program (or any work based on the
550 Program), the recipient automatically receives a license from the
551 original licensor to copy, distribute or modify the Program subject to
552 these terms and conditions. You may not impose any further restrictions
553 on the recipients' exercise of the rights granted herein. You are not
554 responsible for enforcing compliance by third parties to this License.
557 If, as a consequence of a court judgment or allegation of patent
558 infringement or for any other reason (not limited to patent issues),
559 conditions are imposed on you (whether by court order, agreement or
560 otherwise) that contradict the conditions of this License, they do not
561 excuse you from the conditions of this License. If you cannot
562 distribute so as to satisfy simultaneously your obligations under this
563 License and any other pertinent obligations, then as a consequence you
564 may not distribute the Program at all. For example, if a patent license
565 would not permit royalty-free redistribution of the Program by all those
566 who receive copies directly or indirectly through you, then the only way
567 you could satisfy both it and this License would be to refrain entirely
568 from distribution of the Program.
570 If any portion of this section is held invalid or unenforceable under
571 any particular circumstance, the balance of the section is intended to
572 apply and the section as a whole is intended to apply in other
575 It is not the purpose of this section to induce you to infringe any
576 patents or other property right claims or to contest validity of any
577 such claims; this section has the sole purpose of protecting the
578 integrity of the free software distribution system, which is implemented
579 by public license practices. Many people have made generous
580 contributions to the wide range of software distributed through that
581 system in reliance on consistent application of that system; it is up to
582 the author/donor to decide if he or she is willing to distribute
583 software through any other system and a licensee cannot impose that
586 This section is intended to make thoroughly clear what is believed to be
587 a consequence of the rest of this License.
590 If the distribution and/or use of the Program is restricted in certain
591 countries either by patents or by copyrighted interfaces, the original
592 copyright holder who places the Program under this License may add an
593 explicit geographical distribution limitation excluding those countries,
594 so that distribution is permitted only in or among countries not thus
595 excluded. In such case, this License incorporates the limitation as if
596 written in the body of this License.
599 The Free Software Foundation may publish revised and/or new versions of
600 the General Public License from time to time. Such new versions will be
601 similar in spirit to the present version, but may differ in detail to
602 address new problems or concerns.
604 Each version is given a distinguishing version number. If the Program
605 specifies a version number of this License which applies to it and ``any
606 later version'', you have the option of following the terms and
607 conditions either of that version or of any later version published by
608 the Free Software Foundation. If the Program does not specify a version
609 number of this License, you may choose any version ever published by the
610 Free Software Foundation.
613 If you wish to incorporate parts of the Program into other free programs
614 whose distribution conditions are different, write to the author to ask
615 for permission. For software which is copyrighted by the Free Software
616 Foundation, write to the Free Software Foundation; we sometimes make
617 exceptions for this. Our decision will be guided by the two goals of
618 preserving the free status of all derivatives of our free software and
619 of promoting the sharing and reuse of software generally.
629 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR
630 THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW@. EXCEPT WHEN
631 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
632 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER
633 EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
634 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE@.
635 THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH
636 YOU@. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
637 NECESSARY SERVICING, REPAIR OR CORRECTION.
640 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
641 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
642 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
643 DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
644 DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM
645 (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
646 INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF
647 THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR
648 OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
652 @heading END OF TERMS AND CONDITIONS
655 @center END OF TERMS AND CONDITIONS
660 @unnumberedsec How to Apply These Terms to Your New Programs
662 If you develop a new program, and you want it to be of the greatest
663 possible use to the public, the best way to achieve this is to make it
664 free software which everyone can redistribute and change under these
667 To do so, attach the following notices to the program. It is safest to
668 attach them to the start of each source file to most effectively convey
669 the exclusion of warranty; and each file should have at least the
670 ``copyright'' line and a pointer to where the full notice is found.
673 @var{one line to give the program's name and an idea of what it does.}
674 Copyright (C) 19@var{yy} @var{name of author}
676 This program is free software; you can redistribute it and/or modify
677 it under the terms of the GNU General Public License as published by
678 the Free Software Foundation; either version 2 of the License, or (at
679 your option) any later version.
681 This program is distributed in the hope that it will be useful, but
682 WITHOUT ANY WARRANTY; without even the implied warranty of
683 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE@. See the GNU
684 General Public License for more details.
686 You should have received a copy of the GNU General Public License
687 along with this program; if not, write to the Free Software
688 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
691 Also add information on how to contact you by electronic and paper mail.
693 If the program is interactive, make it output a short notice like this
694 when it starts in an interactive mode:
697 Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
698 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type
699 `show w'. This is free software, and you are welcome to redistribute
700 it under certain conditions; type `show c' for details.
703 The hypothetical commands @samp{show@w{ }w} and @samp{show@w{ }c} should
704 show the appropriate parts of the General Public License. Of course,
705 the commands you use may be called something other than @samp{show@w{
706 }w} and @samp{show@w{ }c}; they could even be mouse-clicks or menu items
707 -- whatever suits your program.
709 You should also get your employer (if you work as a programmer) or your
710 school, if any, to sign a ``copyright disclaimer'' for the program, if
711 necessary. Here is a sample; alter the names:
715 Yoyodyne, Inc., hereby disclaims all copyright interest
716 in the program `Gnomovision' (which makes passes at compilers)
717 written by James Hacker.
719 @var{signature of Ty Coon}, 1 April 1989
720 Ty Coon, President of Vice
724 This General Public License does not permit incorporating your program
725 into proprietary programs. If your program is a subroutine library, you
726 may consider it more useful to permit linking proprietary applications
727 with the library. If this is what you want to do, use the GNU Library
728 General Public License instead of this License.
732 @c =====================================================================
733 @c =====================================================================
735 @node Introduction, Invoking groff, Copying, Top
736 @chapter Introduction
739 GNU @code{troff} (or @code{groff}) is a system for typesetting
740 documents. @code{troff} is very flexible and has been in existence (and
741 use) for about 3@w{ }decades. It is quite widespread and firmly
742 entrenched in the @acronym{UNIX} community.
747 * groff Capabilities::
748 * Macro Package Intro::
749 * Preprocessor Intro::
750 * Output device intro::
755 @c =====================================================================
757 @node What Is groff?, History, Introduction, Introduction
758 @section What Is @code{groff}?
759 @cindex what is @code{groff}?
760 @cindex @code{groff} -- what is it?
762 @code{groff} belongs to an older generation of document preparation
763 systems, which operate more like compilers than the more recent
764 interactive @acronym{WYSIWYG}@footnote{What You See Is What You Get}
765 systems. @code{groff} and its contemporary counterpart, @TeX{}, both
766 work using a @dfn{batch} paradigm: The input (or @dfn{source}) files are
767 normal text files with embedded formatting commands. These files can
768 then be processed by @code{groff} to produce a typeset document on a
771 Likewise, @code{groff} should not be confused with a @dfn{word
772 processor}, since that term connotes an integrated system that includes
773 an editor and a text formatter. Also, many word processors follow the
774 @acronym{WYSIWYG} paradigm discussed earlier.
776 Although @acronym{WYSIWYG} systems may be easier to use, they have a
777 number of disadvantages compared to @code{troff}:
781 They must be used on a graphics display to work on a document.
784 Most of the @acronym{WYSIWYG} systems are either non-free or are not
788 @code{troff} is firmly entrenched in all @acronym{UNIX} systems.
791 It is difficult to have a wide range of capabilities available within
792 the confines of a GUI/window system.
795 It is more difficult to make global changes to a document.
799 ``GUIs normally make it simple to accomplish simple actions and
800 impossible to accomplish complex actions.'' --Doug Gwyn (22/Jun/91 in
801 @code{comp.unix.wizards})
805 @c =====================================================================
807 @node History, groff Capabilities, What Is groff?, Introduction
811 @cindex @code{runoff}
813 @code{troff} can trace its origins back to a formatting program called
814 @code{runoff}, written by J.@w{ }E.@w{ }Saltzer, which ran on MIT's CTSS
815 operating system in the mid-sixties. This name came from the common
816 phrase of the time ``I'll run off a document.'' Bob Morris ported it to
817 the 635 architecture and called the program @code{roff} (an abbreviation
818 of @code{runoff}). It was rewritten as @code{rf} for the @w{PDP-7}
819 (before having @acronym{UNIX}), and at the same time (1969), Doug
820 McIllroy rewrote an extended and simplified version of @code{roff} in
821 the @acronym{BCPL} programming language.
824 The first version of @acronym{UNIX} was developed on a @w{PDP-7} which
825 was sitting around Bell Labs. In 1971 the developers wanted to get a
826 @w{PDP-11} for further work on the operating system. In order to
827 justify the cost for this system, they proposed that they would
828 implement a document formatting system for the AT&T patents division.
829 This first formatting program was a reimplementation of McIllroy's
830 @code{roff}, written by J.@w{ }F.@w{ }Ossanna.
833 When they needed a more flexible language, a new version of @code{roff}
834 called @code{nroff} (``Newer @code{roff}'') was written. It had a much
835 more complicated syntax, but provided the basis for all future versions.
836 When they got a Graphic Systems CAT Phototypesetter, Ossanna wrote a
837 version of @code{nroff} that would drive it. It was dubbed
838 @code{troff}, for ``typesetter @code{roff}'', although many people have
839 speculated that it actually means ``Times @code{roff}'' because of the
840 use of the Times font family in @code{troff} by default. As such, the
841 name @code{troff} is pronounced `@w{t-roff}' rather than `trough'.
843 With @code{troff} came @code{nroff} (they were actually the same program
844 except for some @samp{#ifdef}s), which was for producing output for line
845 printers and character terminals. It understood everything @code{troff}
846 did, and ignored the commands which were not applicable (e.g.@: font
849 Since there are several things which cannot be done easily in
850 @code{troff}, work on several preprocessors began. These programs would
851 transform certain parts of a document into @code{troff}, which made a
852 very natural use of pipes in @acronym{UNIX}.
854 The @code{eqn} preprocessor allowed mathematical formul@ae{} to be
855 specified in a much simpler and more intuitive manner. @code{tbl} is a
856 preprocessor for formatting tables. The @code{refer} preprocessor (and
857 the similar program, @code{bib}) processes citations in a document
858 according to a bibliographic database.
860 Unfortunately, Ossanna's @code{troff} was written in @w{PDP-11} assembly
861 language and produced output specifically for the CAT phototypesetter.
862 He rewrote it in C, although it was now 7000@w{ }lines of uncommented
863 code and still dependent on the CAT. As the CAT became less common, and
864 was no longer supported by the manufacturer, the need to make it support
865 other devices became a priority. However, before this could be done,
866 Ossanna was killed in an auto accident.
869 @cindex @code{ditroff}
870 So, Brian Kernighan took on the task of rewriting @code{troff}. The
871 newly rewritten version produced a device independent code which was
872 very easy for postprocessors to read and translate to the appropriate
873 printer codes. Also, this new version of @code{troff} (called
874 @code{ditroff} for ``device independent @code{troff}'') had several
875 extensions, which included drawing functions.
877 Due to the additional abilities of the new version of @code{troff},
878 several new preprocessors appeared. The @code{pic} preprocessor
879 provides a wide range of drawing functions. Likewise the @code{ideal}
880 preprocessor did the same, although via a much different paradigm. The
881 @code{grap} preprocessor took specifications for graphs, but, unlike
882 other preprocessors, produced @code{pic} code.
884 James Clark began work on a GNU implementation of @code{ditroff} in
885 early@w{ }1989. The first version, @code{groff}@w{ }0.3.1, was released
886 June@w{ }1990. @code{groff} included:
890 A replacement for @code{ditroff} with many extensions.
893 The @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors.
896 Postprocessors for character devices, @acronym{PostScript}, @TeX{} DVI,
897 and X@w{ }windows. GNU @code{troff} also eliminated the need for a
898 separate @code{nroff} program with a postprocessor which would produce
899 @acronym{ASCII} output.
902 A version of the @file{me} macros and an implementation of the
906 Also, a front-end was included which could construct the, sometimes
907 painfully long, pipelines required for all the post- and preprocessors.
909 Development of GNU @code{troff} progressed rapidly, and saw the
910 additions of a replacement for @code{refer}, an implementation of the
911 @file{ms} and @file{mm} macros, and a program to deduce how to format a
912 document (@code{grog}).
914 It was declared a stable (i.e.@: non-beta) package with the release of
915 version@w{ }1.04 around November@w{ }1991.
917 Beginning in@w{ }1999, @code{groff} has new maintainers (the package was
918 an orphan for a few years). As a result, new features and programs like
919 @code{grn}, a preprocessor for gremlin images, and an output device to
920 produce @acronym{HTML} output have been added.
923 @c =====================================================================
925 @node groff Capabilities, Macro Package Intro, History, Introduction
926 @section @code{groff} Capabilities
927 @cindex @code{groff} capabilities
928 @cindex capabilities of @code{groff}
930 So what exactly is @code{groff} capable of doing? @code{groff} provides
931 a wide range of low-level text formatting operations. Using these, it
932 is possible to perform a wide range of formatting tasks, such as
933 footnotes, table of contents, multiple columns, etc. Here's a list of
934 the most important operations supported by @code{groff}:
938 text filling, adjusting, and centering
947 font and character size control
950 vertical spacing (i.e.@: double spacing)
953 line length and indenting
956 macros, strings, diversions, and traps
962 tabs, leaders, and fields
965 input and output conventions and character translation
968 overstrike, bracket, line drawing, and zero-width functions
971 local horizontal and vertical motions and the width function
977 output line numbering
980 conditional acceptance of input
983 environment switching
986 insertions from the standard input
989 input/output file switching
992 output and error messages
996 @c =====================================================================
998 @node Macro Package Intro, Preprocessor Intro, groff Capabilities, Introduction
999 @section Macro Packages
1000 @cindex macro packages
1002 Since @code{groff} provides such low-level facilities, it can be quite
1003 difficult to use by itself. However, @code{groff} provides a
1004 @dfn{macro} facility to specify how certain routine operations (e.g.@w{
1005 }starting paragraphs, printing headers and footers, etc.)@: should be
1006 done. These macros can be collected together into a @dfn{macro
1007 package}. There are a number of macro packages available; the most
1008 common (and the ones described in this manual) are @file{man},
1009 @file{mdoc}, @file{me}, @file{ms}, and @file{mm}.
1012 @c =====================================================================
1014 @node Preprocessor Intro, Output device intro, Macro Package Intro, Introduction
1015 @section Preprocessors
1016 @cindex preprocessors
1018 Although @code{groff} provides most functions needed to format a
1019 document, some operations would be unwieldy (e.g.@: to draw pictures).
1020 Therefore, programs called preprocessors were written which understand
1021 their own language and produce the necessary @code{groff} operations.
1022 These preprocessors are able to differentiate their own input from the
1023 rest of the document via markers.
1025 To use a preprocessor, @acronym{UNIX} pipes are used to feed the output
1026 from the preprocessor into @code{groff}. Any number of preprocessors
1027 may be used on a given document; in this case, the preprocessors are
1028 linked together into one pipeline. However, in @code{groff}, the user
1029 does not need to construct the pipe, but only tell @code{groff} what
1030 preprocessors to use.
1032 @code{groff} currently has preprocessors for producing tables
1033 (@code{tbl}), typesetting equations (@code{eqn}), drawing pictures
1034 (@code{pic} and @code{grn}), and for processing bibliographies
1035 (@code{refer}). An associated program which is useful when dealing with
1036 preprocessors is @code{soelim}.
1038 A free implementation of @code{grap}, a preprocessor for drawing graphs,
1039 can be obtained as an extra package; @code{groff} can use @code{grap}
1042 There are other preprocessors in existence, but, unfortunately, no free
1043 implementations are available. Among them are preprocessors for drawing
1044 mathematical pictures (@code{ideal}) and chemical structures
1048 @c =====================================================================
1050 @node Output device intro, Credits, Preprocessor Intro, Introduction
1051 @section Output Devices
1052 @cindex postprocessors
1053 @cindex output devices
1054 @cindex devices for output
1056 @code{groff} actually produces device independent code which may be fed
1057 into a postprocessor to produce output for a particular device.
1058 Currently, @code{groff} has postprocessors for @acronym{PostScript}
1059 devices, character terminals, X@w{ }Windows (for previewing), @TeX{} DVI
1060 format, HP LaserJet@w{ }4 and Canon LBP printers (which use
1061 @acronym{CAPSL}), and @acronym{HTML}.
1064 @c =====================================================================
1066 @node Credits, , Output device intro, Introduction
1070 Large portions of this manual were taken from existing documents, most
1071 notably, the manual pages for the @code{groff} package by James Clark,
1072 and Eric Allman's papers on the @file{me} macro package.
1074 The section on the @file{man} macro package is partly based on Susan@w{
1075 }G.@: Kleinmann's @file{groff_man} manual page written for the Debian
1081 @c =====================================================================
1082 @c =====================================================================
1084 @node Invoking groff, Tutorial for Macro Users, Introduction, Top
1085 @chapter Invoking @code{groff}
1086 @cindex invoking @code{groff}
1087 @cindex @code{groff} invocation
1089 This section focuses on how to invoke the @code{groff} front end. This
1090 front end takes care of the details of constructing the pipeline among
1091 the preprocessors, @code{gtroff} and the postprocessor.
1093 It has become a tradition that GNU programs get the prefix @samp{g} to
1094 distinguish it from its original counterparts provided by the host (see
1095 @ref{Environment}, for more details). Thus, for example, @code{geqn} is
1096 GNU @code{eqn}. On operating systems like Linux or the Hurd, which
1097 don't contain proprietary software, and on MS-DOS/MS-Windows, where
1098 @code{troff} and associated programs are not available at all, this
1099 prefix is omitted since GNU @code{troff} is the only used incarnation of
1100 @code{troff}. Exception: @code{groff} is never replaced by @code{roff}.
1105 * Invocation Examples::
1109 @c =====================================================================
1111 @node Groff Options, Environment, Invoking groff, Invoking groff
1124 @code{groff} normally runs the @code{gtroff} program and a postprocessor
1125 appropriate for the selected device. The default device is @samp{ps}
1126 (but it can be changed when @code{groff} is configured and built). It
1127 can optionally preprocess with any of @code{gpic}, @code{geqn},
1128 @code{gtbl}, @code{ggrn}, @code{grap}, @code{grefer}, or @code{gsoelim}.
1130 This section only documents options to the @code{groff} front end. Many
1131 of the arguments to @code{groff} are passed on to @code{gtroff},
1132 therefore those are also included. Arguments to pre- or postprocessors
1133 can be found in @ref{Invoking gpic}, @ref{Invoking geqn}, @ref{Invoking
1134 gtbl}, @ref{Invoking ggrn}, @ref{Invoking grefer}, @ref{Invoking
1135 gsoelim}, @ref{Invoking grotty}, @ref{Invoking grops}, @ref{Invoking
1136 grohtml}, @ref{Invoking grodvi}, @ref{Invoking grolj4}, @ref{Invoking
1137 grolbp}, and @ref{Invoking gxditview}.
1139 The command line format for @code{groff} is:
1142 groff [ -abeghilpstvzCEGNRSUVXZ ] [ -F@var{dir} ] [ -m@var{name} ]
1143 [ -T@var{def} ] [ -f@var{fam} ] [ -w@var{name} ] [ -W@var{name} ]
1144 [ -M@var{dir} ] [ -d@var{cs} ] [ -r@var{cn} ] [ -n@var{num} ]
1145 [ -o@var{list} ] [ -P@var{arg} ] [ -L@var{arg} ] [ -I@var{dir} ]
1146 [ @var{files}@dots{} ]
1149 The command line format for @code{gtroff} is as follows.
1152 gtroff [ -abivzCERU ] [ -w@var{name} ] [ -W@var{name} ] [ -d@var{cs} ]
1153 [ -f@var{fam} ] [ -m@var{name} ] [ -n@var{num} ]
1154 [ -o@var{list} ] [ -r@var{cn} ] [ -T@var{name} ]
1155 [ -F@var{dir} ] [ -M@var{dir} ] [ @var{files}@dots{} ]
1159 Obviously, many of the options to @code{groff} are actually passed on to
1162 Options without an argument can be grouped behind a single @option{-}.
1163 A filename of @file{-} denotes the standard input. It is possible to
1164 have whitespace between an option and its parameter.
1166 The @code{grog} command can be used to guess the correct @code{groff}
1167 command to format a file.
1169 Here's the description of the command-line options:
1171 @cindex command-line options
1174 Print a help message.
1177 Preprocess with @code{geqn}.
1180 Preprocess with @code{gtbl}.
1183 Preprocess with @code{ggrn}.
1186 Preprocess with @code{grap}.
1189 Preprocess with @code{gpic}.
1192 Preprocess with @code{gsoelim}.
1195 Preprocess with @code{grefer}. No mechanism is provided for passing
1196 arguments to @code{grefer} because most @code{grefer} options have
1197 equivalent commands which can be included in the file. @xref{grefer},
1202 Note that @code{gtroff} also accepts a @option{-R} option, which is not
1203 accessible via @code{groff}. This option prevents the loading of the
1204 @file{troffrc} and @file{troffrc-end} files.
1207 Make programs run by @code{groff} print out their version number.
1210 Print the pipeline on @code{stdout} instead of executing it.
1213 Suppress output from @code{gtroff}. Only error messages are printed.
1216 Do not postprocess the output of @code{gtroff}. Normally @code{groff}
1217 automatically runs the appropriate postprocessor.
1220 Pass @var{arg} to the postprocessor. Each argument should be passed
1221 with a separate @option{-P} option. Note that @code{groff} does not
1222 prepend @samp{-} to @var{arg} before passing it to the postprocessor.
1225 Send the output to a spooler for printing. The command used for this is
1226 specified by the @code{print} command in the device description file
1227 (see @ref{Font Files}, for more info). If not present, @option{-l} is
1231 Pass @var{arg} to the spooler. Each argument should be passed with a
1232 separate @option{-L} option. Note that @code{groff} does not prepend a
1233 @samp{-} to @var{arg} before passing it to the postprocessor. If the
1234 @code{print} keyword in the device description file is missing,
1235 @option{-L} is ignored.
1238 Prepare output for device @var{dev}. The default device is @samp{ps},
1239 unless changed when @code{groff} was configured and built. The
1240 following are the output devices currently available:
1244 For @acronym{PostScript} printers and previewers.
1247 For @TeX{} DVI format.
1250 For a 75@dmn{dpi} X11 previewer.
1253 For a 100@dmn{dpi} X11 previewer.
1256 For typewriter-like devices.
1259 For typewriter-like devices that support the @w{Latin-1} (@w{ISO
1260 8859-1}) character set.
1263 For typewriter-like devices which use the Unicode (@w{ISO 10646})
1264 character set with @w{UTF-8} encoding.
1267 @cindex @acronym{EBCDIC} encoding
1270 For typewriter-like devices which use the @acronym{EBCDIC} encoding IBM
1274 For an HP LaserJet4-compatible (or other PCL5-compatible) printer.
1277 For Canon @acronym{CAPSL} printers (@w{LBP-4} and @w{LBP-8} series laser
1281 @pindex post-grohtml
1282 @cindex @code{grohtml}
1284 To produce @acronym{HTML} output. Note that the @acronym{HTML} driver
1285 consists of two parts, a preprocessor (@code{pre-grohtml}) and a
1286 postprocessor (@code{post-grohtml}).
1291 The predefined @code{gtroff} string register @code{.T} contains the
1292 current output device; the read-only number register @code{.T} is set
1293 to@w{ }1 if this option is used (which is always true if @code{groff} is
1294 used to call @code{gtroff}). @xref{Built-in Registers}.
1296 The postprocessor to be used for a device is specified by the
1297 @code{postpro} command in the device description file. (@xref{Font
1298 Files}, for more info.) This can be overridden with the @option{-X}
1302 Preview with @code{gxditview} instead of using the usual postprocessor.
1303 This is unlikely to produce good results except with @option{-Tps}.
1305 Note that this is not the same as using @option{-TX75} or
1306 @option{-TX100} to view a document with @code{gxditview}: The former
1307 uses the metrics of the specified device, whereas the latter uses
1308 X-specific fonts and metrics.
1311 Don't allow newlines with @code{eqn} delimiters. This is the same as
1312 the @option{-N} option in @code{geqn}.
1315 Safer mode. Pass the @option{-S} option to @code{gpic} and disable the
1316 @code{open}, @code{opena}, @code{pso}, @code{sy}, and @code{pi}
1317 requests. For security reasons, this is enabled by default.
1320 Unsafe mode. Reverts to the old unsafe behaviour.
1324 Generate an @acronym{ASCII} approximation of the typeset output. The
1325 read-only register @code{.A} is then set to@w{ }1. @xref{Built-in
1326 Registers}. A typical example is
1329 groff -a -man -Tdvi troff.man | less
1333 which shows how lines are broken for the DVI device. Note that this
1334 option is rather useless today since graphic output devices are
1335 available virtually everywhere.
1338 Print a backtrace with each warning or error message. This backtrace
1339 should help track down the cause of the error. The line numbers given
1340 in the backtrace may not always be correct: @code{gtroff} can get
1341 confused by @code{as} or @code{am} requests while counting line numbers.
1344 Read the standard input after all the named input files have been
1348 Enable warning @var{name}. Available warnings are described in
1349 @ref{Debugging}. Multiple @option{-w} options are allowed.
1352 Inhibit warning @var{name}. Multiple @option{-W} options are allowed.
1355 Inhibit all error messages.
1358 Enable compatibility mode. @xref{Implementation Differences}, for the
1359 list of incompatibilities between @code{groff} and traditional Unix
1363 @itemx -d@var{name}=s
1364 Define @var{c} or @var{name} to be a string @var{s}. @var{c} must be a
1365 one-letter name; @var{name} can be of arbitrary length. All string
1366 assignments happen before loading any macro file (including the start-up
1370 Use @var{fam} as the default font family.
1373 Read in the file @file{@var{name}.tmac}. Normally @code{groff} searches
1374 for this in its macro directories. If it isn't found, it tries
1375 @file{tmac.@var{name}} (and searches in the same directories).
1377 @c XXX document local and system macro dirs
1380 Number the first page @var{num}.
1384 Output only pages in @var{list}, which is a comma-separated list of page
1385 ranges; @samp{@var{n}} means print page @var{n}, @samp{@var{m}-@var{n}}
1386 means print every page between @var{m} and @var{n}, @samp{-@var{n}}
1387 means print every page up to @var{n}, @samp{@var{n}-} means print every
1388 page beginning with @var{n}. @code{gtroff} exits after printing the
1389 last page in the list. All the ranges are inclusive on both ends.
1391 Within @code{gtroff}, this information can be extracted with the
1392 @samp{.P} register. @xref{Built-in Registers}.
1394 If your document restarts page numbering at the beginning of each
1395 chapter, then @code{gtroff} prints the specified page range for each
1399 @itemx -r@var{name}=@var{n}
1400 Set number register @var{c} or @var{name} to the value @var{n}. @var{c}
1401 must be a one-letter name; @var{name} can be of arbitrary length.
1402 @var{n} can be any @code{gtroff} numeric expression. All register
1403 assignments happen before loading any macro file (including the start-up
1407 Search @file{@var{dir}} for subdirectories @file{dev@var{name}}
1408 (@var{name} is the name of the device), for the @file{DESC} file, and
1409 for font files before looking in the standard directories.
1412 Search directory @file{@var{dir}} for macro files before the standard
1416 This option is as described in @ref{gsoelim}. It implies the
1421 @c =====================================================================
1423 @node Environment, Invocation Examples, Groff Options, Invoking groff
1424 @section Environment
1425 @cindex environment variables
1426 @cindex variables in environment
1428 There are also several environment variables (of the operating system,
1429 not within @code{gtroff}) which can modify the behavior of @code{groff}.
1432 @item GROFF_COMMAND_PREFIX
1433 @tindex GROFF_COMMAND_PREFIX, environment variable
1434 If this is set to @var{X}, then @code{groff} runs @code{@var{X}troff}
1435 instead of @code{gtroff}. This also applies to @code{tbl}, @code{pic},
1436 @code{eqn}, @code{grn}, @code{refer}, and @code{soelim}. It does not
1437 apply to @code{grops}, @code{grodvi}, @code{grotty}, @code{pre-grohtml},
1438 @code{post-grohtml}, @code{grolj4}, and @code{gxditview}.
1440 @c XXX document default values
1442 @item GROFF_TMAC_PATH
1443 @tindex GROFF_TMAC_PATH, environment variable
1444 A colon-separated list of directories in which to search for macro files
1445 (before the default directories are tried).
1447 @c XXX document local and system macro dirs
1449 @item GROFF_TYPESETTER
1450 @tindex GROFF_TYPESETTER, environment variable
1451 The default output device.
1453 @item GROFF_FONT_PATH
1454 @tindex GROFF_FONT_PATH, environment variable
1455 A colon-separated list of directories in which to search for the
1456 @code{dev}@var{name} directory (before the default directories are
1459 @item GROFF_BIN_PATH
1460 @tindex GROFF_BIN_PATH, environment variable
1461 This search path, followed by @code{PATH}, is used for commands executed
1465 @tindex GROFF_TMPDIR, environment variable
1466 @tindex TMPDIR, environment variable
1467 The directory in which @code{groff} creates temporary files. If this is
1468 not set and @env{TMPDIR} is set, temporary files are created in that
1469 directory. Otherwise temporary files are created in a system-dependent
1470 default directory (on Unix and GNU/Linux systems, this is usually
1471 @file{/tmp}). @code{grops}, @code{grefer}, @code{pre-grohtml}, and
1472 @code{post-grohtml} can create temporary files in this directory.
1475 Note that MS-DOS and MS-Windows ports of @code{groff} use semi-colons,
1476 rather than colons, to separate the directories in the lists described
1480 @c =====================================================================
1482 @node Invocation Examples, , Environment, Invoking groff
1483 @section Invocation Examples
1484 @cindex invocation examples
1485 @cindex examples of invocation
1487 This section lists several common uses of @code{groff} and the
1488 corresponding command lines.
1495 This command processes @file{file} without a macro package or a
1496 preprocessor. The output device is the default, @samp{ps}, and the
1497 output is sent to @code{stdout}.
1500 groff -t -mandoc -Tascii file | less
1504 This is basically what a call to the @code{man} program does.
1505 @code{gtroff} processes the manual page @file{file} with the
1506 @file{mandoc} macro file (which in turn either calls the @file{man} or
1507 the @file{mdoc} macro package), using the @code{tbl} preprocessor and
1508 the @acronym{ASCII} output device. Finally, the @code{less} pager
1509 displays the result.
1516 Preview @file{file} with @code{gxditview}, using the @file{me} macro
1517 package. Since no @option{-T} option is specified, use the default
1518 device (@samp{ps}). Note that you can either say @w{@samp{-m me}} or
1519 @w{@samp{-me}}; the latter is an anachronism from the early days of
1520 @acronym{UNIX}.@footnote{The same is true for the other main macro
1521 packages that come with @code{groff}: @file{man}, @file{mdoc},
1522 @file{ms}, @file{mm}, and @file{mandoc}. This won't work in general;
1523 for example, to load @file{trace.tmac}, either @samp{-mtrace} or
1524 @w{@samp{-m trace}} must be used.}
1527 groff -man -rD1 -z file
1531 Check @file{file} with the @file{man} macro package, forcing
1532 double-sided printing -- don't produce any output.
1534 @c ---------------------------------------------------------------------
1540 @node grog, , Invocation Examples, Invocation Examples
1541 @subsection @code{grog}
1544 @code{grog} reads files, guesses which of the @code{groff} preprocessors
1545 and/or macro packages are required for formatting them, and prints the
1546 @code{groff} command including those options on the standard output. It
1547 generates one or more of the options @option{-e}, @option{-man},
1548 @option{-me}, @option{-mm}, @option{-ms}, @option{-mdoc},
1549 @option{-mdoc-old}, @option{-p}, @option{-R}, @option{-g}, @option{-G},
1550 @option{-s}, and @option{-t}.
1552 A special file name @file{-} refers to the standard input. Specifying
1553 no files also means to read the standard input. Any specified options
1554 are included in the printed command. No space is allowed between
1555 options and their arguments. The only options recognized are
1556 @option{-C} (which is also passed on) to enable compatibility mode, and
1557 @option{-v} (if it is the only parameter) to print the version number.
1566 guesses the appropriate command to print @file{paper.ms} and then prints
1567 it to the command line after adding the @option{-Tdvi} option. For
1568 direct execution, enclose the call to @code{grog} in backquotes at the
1569 @acronym{UNIX} shell prompt:
1572 `grog -Tdvi paper.ms` > paper.dvi
1576 As seen in the example, it is still necessary to redirect the output to
1577 something meaningful (i.e.@: either a file or a pager program like
1582 @c =====================================================================
1583 @c =====================================================================
1585 @node Tutorial for Macro Users, Macro Packages, Invoking groff, Top
1586 @chapter Tutorial for Macro Users
1587 @cindex tutorial for macro users
1588 @cindex macros, tutorial for users
1589 @cindex user's tutorial for macros
1590 @cindex user's macro tutorial
1592 Most users tend to use a macro package to format their papers. This
1593 means that the whole breadth of @code{groff} is not necessary for most
1594 people. This chapter covers the material needed to efficiently use a
1603 @c =====================================================================
1605 @node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users
1607 @cindex basics of macros
1608 @cindex macro basics
1610 This section covers some of the basic concepts necessary to understand
1611 how to use a macro package.@footnote{This section is derived from
1612 @cite{Writing Papers with nroff using -me} by Eric P.@w{ }Allman.}
1613 References are made throughout to more detailed information, if desired.
1615 @code{gtroff} reads an input file prepared by the user and outputs a
1616 formatted document suitable for publication or framing. The input
1617 consists of text, or words to be printed, and embedded commands
1618 (@dfn{requests} and @dfn{escapes}), which tell @code{gtroff} how to
1619 format the output. For more detail on this, see @ref{Embedded
1622 The word @dfn{argument} is used in this chapter to mean a word or number
1623 which appears on the same line as a request, and which modifies the
1624 meaning of that request. For example, the request
1631 spaces one line, but
1638 spaces four lines. The number@w{ }4 is an argument to the @code{sp}
1639 request which says to space four lines instead of one. Arguments are
1640 separated from the request and from each other by spaces (@emph{no}
1641 tabs). More details on this can be found in @ref{Request Arguments}.
1643 The primary function of @code{gtroff} is to collect words from input
1644 lines, fill output lines with those words, justify the right-hand margin
1645 by inserting extra spaces in the line, and output the result. For
1653 Four score and seven
1658 is read, packed onto output lines, and justified to produce:
1661 Now is the time for all good men to come to the aid of their party.
1662 Four score and seven years ago,...
1667 Sometimes a new output line should be started even though the current
1668 line is not yet full; for example, at the end of a paragraph. To do
1669 this it is possible to cause a @dfn{break}, which starts a new output
1670 line. Some requests cause a break automatically, as do blank input
1671 lines and input lines beginning with a space.
1673 Not all input lines are text to be formatted. Some input lines are
1674 requests which describe how to format the text. Requests always have a
1675 period (@samp{.}) or an apostrophe (@samp{'}) as the first character of
1678 The text formatter also does more complex things, such as automatically
1679 numbering pages, skipping over page boundaries, putting footnotes in the
1680 correct place, and so forth.
1682 Here are a few hints for preparing text for input to @code{gtroff}.
1686 First, keep the input lines short. Short input lines are easier to
1687 edit, and @code{gtroff} packs words onto longer lines anyhow.
1690 In keeping with this, it is helpful to begin a new line after every
1691 comma or phrase, since common corrections are to add or delete sentences
1695 End each sentence with two spaces -- or better, start each sentence on a
1696 new line. @code{gtroff} recognizes characters that usually end a
1697 sentence, and inserts sentence space accordingly.
1700 Do not hyphenate words at the end of lines -- @code{gtroff} is smart
1701 enough to hyphenate words as needed, but is not smart enough to take
1702 hyphens out and join a word back together. Also, words such as
1703 ``mother-in-law'' should not be broken over a line, since then a space
1704 can occur where not wanted, such as ``@w{mother- in}-law''.
1708 @cindex double spacing
1710 @code{gtroff} double spaces output text automatically if you use the
1711 request @w{@samp{.ls 2}}. Reactivate single spaced mode by typing
1714 A number of requests allow to change the way the output looks, sometimes
1715 called the @dfn{layout} of the output page. Most of these requests
1716 adjust the placing of @dfn{white space} (blank lines or spaces).
1719 The @samp{.bp} request starts a new page, causing a line break.
1723 @cindex lines, empty
1724 The request @w{@samp{.sp @var{N}}} leaves @var{N}@w{ }lines of blank
1725 space. @var{N}@w{ }can be omitted (meaning skip a single line) or can
1726 be of the form @var{N}i (for @var{N}@w{ }inches) or @var{N}c (for
1727 @var{N}@w{ }centimeters). For example, the input:
1731 My thoughts on the subject
1736 leaves one and a half inches of space, followed by the line ``My
1737 thoughts on the subject'', followed by a single blank line (more
1738 measurement units are available, see @ref{Measurements}).
1741 @cindex centering lines
1742 @cindex lines, centering
1743 Text lines can be centered by using the @code{ce} request. The line
1744 after @code{ce} is centered (horizontally) on the page. To center more
1745 than one line, use @w{@samp{.ce @var{N}}} (where @var{N} is the number
1746 of lines to center), followed by the @var{N}@w{ }lines. To center many
1747 lines without counting them, type:
1756 The @w{@samp{.ce 0}} request tells @code{groff} to center zero more
1757 lines, in other words, stop centering.
1762 All of these requests cause a break; that is, they always start a new
1763 line. To start a new line without performing any other action, use
1767 @c =====================================================================
1769 @node Common Features, , Basics, Tutorial for Macro Users
1770 @section Common Features
1771 @cindex common features
1772 @cindex features, common
1774 @code{gtroff} provides very low-level operations for formatting a
1775 document. There are many common routine operations which are done in
1776 all documents. These common operations are written into @dfn{macros}
1777 and collected into a @dfn{macro package}.
1779 All macro packages provide certain common capabilities which fall into
1780 the following categories.
1782 @c ---------------------------------------------------------------------
1786 * Sections and Chapters::
1787 * Headers and Footers::
1788 * Page Layout Adjustment::
1790 * Footnotes and Annotations::
1791 * Table of Contents::
1794 * Multiple Columns::
1795 * Font and Size Changes::
1796 * Predefined Strings::
1797 * Preprocessor Support::
1798 * Configuration and Customization::
1801 @node Paragraphs, Sections and Chapters, Common Features, Common Features
1802 @subsection Paragraphs
1805 One of the most common and most used capability is starting a paragraph.
1806 There are a number of different types of paragraphs, any of which can be
1807 initiated with macros supplied by the macro package. Normally,
1808 paragraphs start with a blank line and the first line indented, like the
1809 text in this manual. There are also block style paragraphs, which omit
1813 Some men look at constitutions with sanctimonious
1814 reverence, and deem them like the ark of the covenant, too
1815 sacred to be touched.
1819 And there are also indented paragraphs which begin with a tag or label
1820 at the margin and the remaining text indented.
1824 one This is the first paragraph. Notice how the first
1825 line of the resulting paragraph lines up with the
1826 other lines in the paragraph.
1830 This paragraph had a long label. The first
1831 character of text on the first line does not line up
1832 with the text on second and subsequent lines,
1833 although they line up with each other.
1837 A variation of this is a bulleted list.
1841 @c ---------------------------------------------------------------------
1843 @node Sections and Chapters, Headers and Footers, Paragraphs, Common Features
1844 @subsection Sections and Chapters
1846 Most macro packages supply some form of section headers. The simplest
1847 kind is simply the heading on a line by itself in bold type. Others
1848 supply automatically numbered section heading or different heading
1849 styles at different levels. Some, more sophisticated, macro packages
1850 supply macros for starting chapters and appendices.
1852 @c ---------------------------------------------------------------------
1854 @node Headers and Footers, Page Layout Adjustment, Sections and Chapters, Common Features
1855 @subsection Headers and Footers
1857 Every macro package gives some way to manipulate the headers and footers
1858 (or @dfn{titles}) on each page. Some packages allow for different ones
1859 on the even and odd pages (for material printed in a book form).
1861 The titles are called three-part titles, that is, there is a
1862 left-justified part, a centered part, and a right-justified part. An
1863 automatically generated page number may be put in any of these fields
1864 with the @samp{%} character (see @ref{Page Layout}, for more details).
1866 @c ---------------------------------------------------------------------
1868 @node Page Layout Adjustment, Displays, Headers and Footers, Common Features
1869 @subsection Page Layout
1871 Most macro packages let the user specify top and bottom margins and
1872 other details about the appearance of the printed pages.
1874 @c ---------------------------------------------------------------------
1876 @node Displays, Footnotes and Annotations, Page Layout Adjustment, Common Features
1877 @subsection Displays
1880 Displays are sections of text to be set off from the body of the paper.
1881 Major quotes, tables, and figures are types of displays, as are all the
1882 examples used in this document.
1884 @cindex quotes, major
1885 @cindex major quotes
1886 @dfn{Major quotes} are quotes which are several lines long, and hence
1887 are set in from the rest of the text without quote marks around them.
1890 A @dfn{list} is an indented, single spaced, unfilled display. Lists
1891 should be used when the material to be printed should not be filled and
1892 justified like normal text, such as columns of figures or the examples
1896 A @dfn{keep} is a display of lines which are kept on a single page if
1897 possible. An example for a keep might be a diagram. Keeps differ from
1898 lists in that lists may be broken over a page boundary whereas keeps are
1901 @cindex keep, floating
1902 @cindex floating keep
1903 Floating keeps move relative to the text. Hence, they are good for
1904 things which are referred to by name, such as ``See figure@w{ }3''. A
1905 floating keep appears at the bottom of the current page if it fits;
1906 otherwise, it appears at the top of the next page. Meanwhile, the
1907 surrounding text `flows' around the keep, thus leaving no blank areas.
1909 @c ---------------------------------------------------------------------
1911 @node Footnotes and Annotations, Table of Contents, Displays, Common Features
1912 @subsection Footnotes and Annotations
1916 There are a number of requests to save text for later printing.
1918 @dfn{Footnotes} are printed at the bottom of the current page.
1920 @cindex delayed text
1921 @dfn{Delayed text} is very similar to a footnote except that it is
1922 printed when called for explicitly. This allows a list of references to
1923 appear (for example) at the end of each chapter, as is the convention in
1926 Most macro packages which supply this functionality also supply a means
1927 of automatically numbering either type of annotation.
1929 @c ---------------------------------------------------------------------
1931 @node Table of Contents, Indices, Footnotes and Annotations, Common Features
1932 @subsection Table of Contents
1933 @cindex table of contents
1934 @cindex contents, table of
1936 @dfn{Tables of contents} are a type of delayed text having a tag
1937 (usually the page number) attached to each entry after a row of dots.
1938 The table accumulates throughout the paper until printed, usually after
1939 the paper has ended. Many macro packages provide the ability to have
1940 several tables of contents (e.g.@: a standard table of contents, a list
1943 @c ---------------------------------------------------------------------
1945 @node Indices, Paper Formats, Table of Contents, Common Features
1947 @cindex index, in macro package
1949 While some macro packages use the term @dfn{index}, none actually
1950 provide that functionality. The facilities they call indices are
1951 actually more appropriate for tables of contents.
1953 @c ---------------------------------------------------------------------
1955 @node Paper Formats, Multiple Columns, Indices, Common Features
1956 @subsection Paper Formats
1957 @cindex paper formats
1959 Some macro packages provide stock formats for various kinds of
1960 documents. Many of them provide a common format for the title and
1961 opening pages of a technical paper. The @file{mm} macros in particular
1962 provide formats for letters and memoranda.
1964 @c ---------------------------------------------------------------------
1966 @node Multiple Columns, Font and Size Changes, Paper Formats, Common Features
1967 @subsection Multiple Columns
1969 Some macro packages (but not @file{man}) provide the ability to have two
1970 or more columns on a page.
1972 @c ---------------------------------------------------------------------
1974 @node Font and Size Changes, Predefined Strings, Multiple Columns, Common Features
1975 @subsection Font and Size Changes
1977 The built-in font and size functions are not always intuitive, so all
1978 macro packages provide macros to make these operations simpler.
1980 @c ---------------------------------------------------------------------
1982 @node Predefined Strings, Preprocessor Support, Font and Size Changes, Common Features
1983 @subsection Predefined Strings
1985 Most macro packages provide various predefined strings for a variety of
1986 uses; examples are sub- and superscripts, printable dates, quotes and
1987 various special characters.
1989 @c ---------------------------------------------------------------------
1991 @node Preprocessor Support, Configuration and Customization, Predefined Strings, Common Features
1992 @subsection Preprocessor Support
1994 All macro packages provide support for the various preprocessors and may
1995 extend their functionality.
1997 For example, all macro packages mark tables (which are processed with
1998 @code{gtbl}) by placing them between @code{.TS} and @code{.TE} macros.
1999 The @file{ms} macro package has an option, @code{.TS@w{}H}, that prints
2000 a caption at the top of a new page (when the table is too long to fit on
2003 @c ---------------------------------------------------------------------
2005 @node Configuration and Customization, , Preprocessor Support, Common Features
2006 @subsection Configuration and Customization
2008 Some macro packages provide means of customizing many of the details of
2009 how the package behaves. This ranges from setting the default type size
2010 to changing the appearance of section headers.
2014 @c =====================================================================
2015 @c =====================================================================
2017 @node Macro Packages, Programming Tutorial, Tutorial for Macro Users, Top
2018 @chapter Macro Packages
2019 @cindex macro packages
2020 @cindex packages, macros
2022 This chapter documents the main macro packages that come with
2034 @c =====================================================================
2036 @node man, mdoc, Macro Packages, Macro Packages
2039 @cindex manual pages
2042 @pindex man-old.tmac
2044 This is the most popular and probably the most important macro package
2045 of @code{groff}. It is easy to use, and a vast majority of manual pages
2052 * Miscellaneous man macros::
2053 * Predefined man strings::
2054 * Preprocessors in man pages::
2057 @c ---------------------------------------------------------------------
2059 @node Man options, Man usage, man, man
2062 The command line format for using the @file{man} macros with
2066 groff -m man [ -rcR=1 ] [ -rC1 ] [ -rD1 ] [ -rP@var{nnn} ]
2067 [ -rS@var{xx} ] [ -rX@var{nnn} ] [ @var{files}@dots{} ]
2071 It is possible to use @samp{-man} instead of @w{@samp{-m man}}.
2075 This option (the default in nroff mode) creates a single, very long page
2076 instead of multiple pages. Use @code{-rcR=0} to disable it.
2079 If more than one manual page is given on the command line, number the
2080 pages continuously, rather than starting each at@w{ }1.
2083 Double-sided printing. Footers for even and odd pages are formatted
2087 Page numbering starts with @var{nnn} rather than with@w{ }1.
2090 Use @var{xx} (which can be 10, 11, or@w{ }12@dmn{pt}) as the base
2091 document font size instead of the default value of@w{ }10@dmn{pt}.
2094 After page @var{nnn}, number pages as @var{nnn}a, @var{nnn}b,
2095 @var{nnn}c, etc. For example, the option @option{-rX2} produces the
2096 following page numbers: 1, 2, 2a, 2b, 2c, etc.
2099 @c ---------------------------------------------------------------------
2101 @node Man usage, Man font macros, Man options, man
2103 @cindex @code{man} macros
2104 @cindex macros for manual pages
2107 This section describes the available macros for manual pages. For
2108 further customization, put additional macros and requests into the file
2109 @file{man.local} which is loaded immediately after the @file{man}
2112 @Defmac {TH, title section [@Var{extra1}] [@Var{extra2}] [@Var{extra3}]}
2113 Sets the title of the man page to @var{title} and the section to
2114 @var{section}, which must have a value between 1 and@w{ }8. The value
2115 of @var{section} may also have a string appended, e.g.@: @samp{.pm}, to
2116 indicate a specific subsection of the man pages.
2118 Both @var{title} and @var{section} are positioned at the left and right
2119 in the header line (with @var{section} in parentheses immediately
2120 appended to @var{title}. @var{extra1} is positioned in the middle of
2121 the footer line. @var{extra2} is positioned at the left in the footer
2122 line (or at the left on even pages and at the right on odd pages if
2123 double-sided printing is active). @var{extra3} is centered in the
2126 For @acronym{HTML} output, headers and footers are completely suppressed.
2128 Additionally, this macro starts a new page; the new line number is@w{ }1
2129 again (except if the @option{-rC1} option is given on the command line)
2130 -- this feature is intended only for formatting multiple man pages; a
2131 single man page should contain exactly one @code{TH} macro at the
2132 beginning of the file.
2135 @Defmac {SH, [@Var{heading}]}
2136 Sets up an unnumbered section heading sticking out to the left. Prints
2137 out all the text following @code{SH} up to the end of the line (or the
2138 text in the next line if there is no argument to @code{SH}) in bold
2139 face, one size larger than the base document size. Additionally, the
2140 left margin for the following text is reset to its default value.
2143 @Defmac {SS, [@Var{heading}]}
2144 Sets up an unnumbered (sub)section heading. Prints out all the text
2145 following @code{SS} up to the end of the line (or the text in the next
2146 line if there is no argument to @code{SS}) in bold face, at the same
2147 size as the base document size. Additionally, the left margin for the
2148 following text is reset to its default value.
2151 @Defmac {TP, [@Var{nnn}]}
2152 Sets up an indented paragraph with label. The indentation is set to
2153 @var{nnn} if that argument is supplied (the default unit is @samp{n} if
2154 omitted), otherwise it is set to the default indentation value.
2156 The first line of text following this macro is interpreted as a string
2157 to be printed flush-left, as it is appropriate for a label. It is not
2158 interpreted as part of a paragraph, so there is no attempt to fill the
2159 first line with text from the following input lines. Nevertheless, if
2160 the label is not as wide as the indentation, then the paragraph starts
2161 at the same line (but indented), continuing on the following lines. If
2162 the label is wider than the indentation, then the descriptive part of
2163 the paragraph begins on the line following the label, entirely indented.
2164 Note that neither font shape nor font size of the label is set to a
2165 default value; on the other hand, the rest of the text has default font
2172 These macros are mutual aliases. Any of them causes a line break at the
2173 current position, followed by a vertical space downwards by the amount
2174 specified by the @code{PD} macro. The font size and shape are reset to
2175 the default value (10@dmn{pt} Roman). Finally, the current left margin
2179 @Defmac {IP, [@Var{designator}] [@Var{nnn}]}
2180 Sets up an indented paragraph, using @var{designator} as a tag to mark
2181 its beginning. The indentation is set to @var{nnn} if that argument is
2182 supplied (default unit is @samp{n}), otherwise the default indentation
2183 value is used. Font size and face of the paragraph (but not the
2184 designator) are reset to their default values. To start an indented
2185 paragraph with a particular indentation but without a designator, use
2186 @samp{""} (two double quotes) as the first argument of @code{IP}.
2188 For example, to start a paragraph with bullets as the designator and
2189 4@dmn{en} indentation, write
2196 @cindex hanging indentation, in manual pages
2197 @Defmac {HP, [@Var{nnn}]}
2198 Sets up a paragraph with hanging left indentation. The indentation is
2199 set to @var{nnn} if that argument is supplied (default unit is
2200 @samp{n}), otherwise the default indentation value is used. Font size
2201 and face are reset to their default values.
2204 @cindex left margin, how to move, in manual pages
2205 @Defmac {RS, [@Var{nnn}]}
2206 This macro moves the left margin to the right by the value @var{nnn} if
2207 specified (default unit is @samp{n}); otherwise the default indentation
2208 value is used. Calls to the @code{RS} macro can be nested.
2211 @Defmac {RE, [@Var{nnn}]}
2212 This macro moves the left margin back to level @var{nnn}; if no argument
2213 is given, it moves one level back. The first level (i.e., no call to
2214 @code{RS} yet) has number@w{ }1, and each call to @code{RS} increases
2226 To summarize, the following macros cause a line break with the insertion
2227 of vertical space (which amount can be changed with the @code{PD}
2228 macro): @code{SH}, @code{SS}, @code{TP}, @code{LP} (@code{PP},
2229 @code{P}), @code{IP}, and @code{HP}.
2233 The macros @code{RS} and @code{RE} also cause a break but do not insert
2236 @c ---------------------------------------------------------------------
2238 @node Man font macros, Miscellaneous man macros, Man usage, man
2239 @subsection Macros to set fonts
2240 @cindex fonts in manual pages
2241 @cindex @code{man}, how to set fonts
2243 The standard font is Roman; the default text size is 10@w{ }point.
2245 @Defmac {SM, [@Var{text}]}
2246 Sets the text on the same line or the text on the next line in a font
2247 that is one point size smaller than the default font.
2250 @cindex boldface, in manual pages
2251 @Defmac {SB, [@Var{text}]}
2252 Sets the text on the same line or the text on the next line in boldface
2253 font, one point size smaller than the default font.
2257 Sets its arguments alternately in bold face and italic. Thus,
2260 .BI this "word and" that
2264 would set ``this'' and ``that'' in bold face, and ``word and'' in
2269 Sets its arguments alternately in italic and bold face.
2273 Sets its arguments alternately in roman and italic.
2277 Sets its arguments alternately in italic and roman.
2281 Sets its arguments alternately in bold face and roman.
2285 Sets its arguments alternately in roman and bold face.
2288 @Defmac {R, [@Var{text}]}
2289 Sets @var{text} in roman font. If no text is present on the line where
2290 the macro is called, then the text of the next line appears in roman.
2291 This is the default font to which text is returned at the end of
2292 processing of the other macros.
2295 @Defmac {B, [@Var{text}]}
2296 Sets @var{text} in bold face. If no text is present on the line where
2297 the macro is called, then the text of the next line appears in bold
2301 @cindex italic, in manual pages
2302 @Defmac {I, [@Var{text}]}
2303 Sets @var{text} in italic. If no text is present on the line where the
2304 macro is called, then the text of the next line appears in italic.
2307 @c ---------------------------------------------------------------------
2309 @node Miscellaneous man macros, Predefined man strings, Man font macros, man
2310 @subsection Miscellaneous macros
2313 @cindex @file{man}, default indentation
2314 @cindex default indentation, @file{man}
2315 The default indentation is 7.2@dmn{n} for all output devices except for
2316 @code{grohtml} which ignores indentation.
2319 @cindex tab stops, in manual pages
2321 Sets tabs every 0.5@w{ }inches. Since this macro is always called
2322 during a @code{TH} request, it makes sense to call it only if the tab
2323 positions have been changed.
2326 @cindex empty space before a paragraph, in manual pages
2327 @Defmac {PD, [@Var{nnn}]}
2328 Adjusts the empty space before a new paragraph (or section). The
2329 optional argument gives the amount of space (default units are
2330 @samp{v}); without parameter, the value is reset to its default value
2331 (1@w{ }line for tty devices, 0.4@dmn{v}@w{ }otherwise).
2342 This affects the macros @code{SH}, @code{SS}, @code{TP}, @code{LP} (as
2343 well as @code{PP} and @code{P}), @code{IP}, and @code{HP}.
2345 @c ---------------------------------------------------------------------
2347 @node Predefined man strings, Preprocessors in man pages, Miscellaneous man macros, man
2348 @subsection Predefined strings
2350 The following strings are defined:
2353 Switch back to the default font size.
2357 The `registered' sign.
2361 The `trademark' sign.
2368 Left and right quote. This is equal to @code{\(lq} and @code{\(rq},
2372 @c ---------------------------------------------------------------------
2374 @node Preprocessors in man pages, , Predefined man strings, man
2375 @subsection Preprocessors in @file{man} pages
2377 @cindex preprocessor, calling convention
2378 @cindex calling convention of preprocessors
2379 If a preprocessor like @code{gtbl} or @code{geqn} is needed, it has
2380 become common usage to make the first line of the man page look like
2387 @pindex geqn@r{, invocation in manual pages}
2388 @pindex grefer@r{, invocation in manual pages}
2389 @pindex gtbl@r{, invocation in manual pages}
2390 @pindex man@r{, invocation of preprocessors}
2392 Note the single space character after the double quote. @var{word}
2393 consists of letters for the needed preprocessors: @samp{e} for
2394 @code{geqn}, @samp{r} for @code{grefer}, @samp{t} for @code{gtbl}.
2395 Modern implementations of the @code{man} program read this first line
2396 and automatically call the right preprocessor(s).
2399 @c =====================================================================
2401 @node mdoc, ms, man, Macro Packages
2402 @section @file{mdoc}
2405 @c XXX documentation
2408 @c =====================================================================
2410 @node ms, me, mdoc, Macro Packages
2414 @c XXX documentation
2417 @c =====================================================================
2419 @node me, mm, ms, Macro Packages
2423 @c XXX documentation
2426 @c =====================================================================
2428 @node mm, , me, Macro Packages
2432 @c XXX documentation
2436 @c =====================================================================
2437 @c =====================================================================
2439 @node Programming Tutorial, Preprocessors, Macro Packages, Top
2440 @chapter Programming Tutorial
2441 @cindex programming tutorial
2442 @cindex tutorial for programming
2444 This chapter covers @strong{all} of the facilities of @code{gtroff}.
2445 Users of macro packages may skip it if not interested in details.
2450 * Input Conventions::
2454 * Embedded Commands::
2456 * Manipulating Filling and Adjusting::
2457 * Manipulating Hyphenation::
2458 * Manipulating Spacing::
2460 * Character Translations::
2461 * Troff and Nroff Mode::
2468 * Conditionals and Loops::
2471 * Drawing Requests::
2475 * Suppressing output::
2477 * Postprocessor Access::
2480 * Implementation Differences::
2485 @c =====================================================================
2487 @node Text, Input Conventions, Programming Tutorial, Programming Tutorial
2489 @cindex text, @code{gtroff} processing
2491 @code{gtroff} input files contain text with control commands
2492 interspersed throughout. But, even without control codes, @code{gtroff}
2493 still does several things with the input text:
2497 filling and adjusting
2500 adding additional space after sentences
2506 inserting implicit line breaks
2510 * Filling and Adjusting::
2514 * Implicit Line Breaks::
2517 @c ---------------------------------------------------------------------
2519 @node Filling and Adjusting, Hyphenation, Text, Text
2520 @subsection Filling and Adjusting
2524 When @code{gtroff} reads text, it collects words from the input and fits
2525 as many of them together on one output line as it can. This is known as
2528 @cindex leading spaces
2529 @cindex spaces, leading and trailing
2530 @cindex extra spaces
2531 @cindex trailing spaces
2532 Once @code{gtroff} has a @dfn{filled} line, it tries to @dfn{adjust}
2533 it. This means it widens the spacing between words until the text
2534 reaches the right margin (in the default adjustment mode). Extra spaces
2535 between words are preserved, but spaces at the end of lines are ignored.
2536 Spaces at the front of a line cause a @dfn{break} (breaks are
2537 explained in @ref{Implicit Line Breaks})
2539 @xref{Manipulating Filling and Adjusting}.
2541 @c ---------------------------------------------------------------------
2543 @node Hyphenation, Sentences, Filling and Adjusting, Text
2544 @subsection Hyphenation
2547 Since the odds are not great for finding a set of words, for every
2548 output line, which fit nicely on a line without inserting excessive
2549 amounts of space between words, @code{gtroff} hyphenates words so
2550 that it can justify lines without inserting too much space between
2551 words. It uses an internal hyphenation algorithm (a simplified version
2552 of the algorithm used within @TeX{}) to indicate which words can be
2553 hyphenated and how to do so. When a word is hyphenated, the first part
2554 of the word is added to the current filled line being output (with
2555 an attached hyphen), and the other portion is added to the next
2558 @xref{Manipulating Hyphenation}.
2560 @c ---------------------------------------------------------------------
2562 @node Sentences, Tab Stops, Hyphenation, Text
2563 @subsection Sentences
2566 Although it is often debated, some typesetting rules say there should be
2567 different amounts of space after various punctuation marks. For
2568 example, the @cite{Chicago typsetting manual} says that a period at the
2569 end of a sentence should have twice as much space following it as would
2570 a comma or a period as part of an abbreviation.
2572 @c XXX exact citation of Chicago manual
2574 @cindex sentence space
2575 @cindex space between sentences
2576 @cindex french-spacing
2577 @code{gtroff} does this by flagging certain characters (normally
2578 @samp{!}, @samp{?}, and @samp{.}) as @dfn{end of sentence} characters.
2579 When @code{gtroff} encounters one of these characters at the end of a
2580 line, it appends a normal space followed by a @dfn{sentence space} in
2581 the formatted output. (This justifies one of the conventions mentioned
2582 in @ref{Input Conventions}.)
2584 @cindex transparent characters
2585 @cindex character, transparent
2593 In addition, the following characters or glyphs are treated
2594 transparently while handling end of sentence characters: @samp{"},
2595 @samp{'}, @samp{)}, @samp{]}, @samp{*}, @code{dg}, and @code{rq}.
2597 See the @code{cflags} request in @ref{Using Symbols}, for more details.
2600 To prevent the insertion of extra space after an end of sentence
2601 character (at the end of a line), append @code{\&}.
2603 @c ---------------------------------------------------------------------
2605 @node Tab Stops, Implicit Line Breaks, Sentences, Text
2606 @subsection Tab Stops
2608 @cindex stops, tabulator
2609 @cindex tab character
2610 @cindex character, tabulator
2612 @cindex @acronym{EBCDIC} encoding
2613 @code{gtroff} translates @dfn{tabulator characters}, also called
2614 @dfn{tabs} (normally code point @acronym{ASCII} @code{0x09} or
2615 @acronym{EBCDIC} @code{0x05}), in the input into movements to the next
2616 tabulator stop. These tab stops are initially located every half inch
2617 across the page. Using this, simple tables can be made easily.
2618 However, it can often be deceptive as the appearance (and width) of the
2619 text on a terminal and the results from @code{gtroff} can vary greatly.
2621 Also, a possible sticking point is that lines beginning with tab
2622 characters are still filled, again producing unexpected results.
2623 For example, the following input
2625 @multitable {12345678} {12345678} {12345678} {12345678}
2627 @tab 1 @tab 2 @tab 3
2635 @multitable {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} {12345678}
2637 @tab 1 @tab 2 @tab 3 @tab @tab 4 @tab 5
2640 @xref{Tabs and Fields}.
2642 @c ---------------------------------------------------------------------
2644 @node Implicit Line Breaks, , Tab Stops, Text
2645 @subsection Implicit Line Breaks
2646 @cindex implicit line breaks
2647 @cindex implicit breaks of lines
2648 @cindex line, implicit breaks
2649 @cindex break, implicit
2652 An important concept in @code{gtroff} is the @dfn{break}. When a break
2653 occurs, @code{gtroff} outputs the partially filled line
2654 (unjustified), and resumes collecting and filling text on the next output
2660 There are several ways to cause a break in @code{gtroff}. A blank line
2661 not only causes a break, but it also outputs a one line vertical
2662 space (effectively a blank line).
2666 A line that begins with a space causes a break and the space is
2667 output at the beginning of the next line. Note that this space isn't
2668 adjusted, even in fill mode.
2670 The end of file also causes a break -- otherwise the last line of
2671 the document may vanish!
2673 Certain requests also cause breaks, implicitly or explicitly. This is
2674 discussed in @ref{Manipulating Filling and Adjusting}.
2677 @c =====================================================================
2679 @node Input Conventions, Measurements, Text, Programming Tutorial
2680 @section Input Conventions
2681 @cindex input conventions
2682 @cindex conventions for input
2684 Since @code{gtroff} does filling automatically, it is traditional in
2685 @code{groff} not to try and type things in as nicely formatted
2686 paragraphs. These are some conventions commonly used when typing
2691 Break lines after punctuation, particularly at the end of a sentence
2692 and in other logical places. Keep separate phrases on lines by
2693 themselves, as entire phrases are often added or deleted when editing.
2696 Try to keep lines less than 40-60@w{ }characters, to allow space for
2697 inserting more text.
2700 Do not try to do any formatting in a @acronym{WYSIWYG} manner (i.e.,
2701 don't try using spaces to get proper indentation).
2705 @c =====================================================================
2707 @node Measurements, Expressions, Input Conventions, Programming Tutorial
2708 @section Measurements
2709 @cindex measurements
2711 @cindex units of measurement
2713 @cindex machine units
2714 @cindex measurement units
2715 @cindex @code{u} unit
2716 @cindex unit, @code{u}
2717 @code{gtroff} (like many other programs) requires numeric parameters to
2718 specify various measurements. Most numeric parameters@footnote{those
2719 that specify vertical or horizontal motion or a type size} may have a
2720 @dfn{measurement unit} attached. These units are specified as a single
2721 character which immediately follows the number or expression. Each of
2722 these units are understood, by @code{gtroff}, to be a multiple of its
2723 @dfn{basic unit}. So, whenever a different measurement unit is
2724 specified @code{gtroff} converts this into its @dfn{basic units}. This
2725 basic unit, represented by a @samp{u}, is a device dependent measurement
2726 which is quite small, ranging from 1/75@dmn{th} to 1/72000@dmn{th} of an
2727 inch. The values may be given as fractional numbers; however,
2728 fractional basic units are always rounded to integers.
2730 Some of the measurement units are completely independent of any of the
2731 current settings (e.g.@: type size) of @code{gtroff}.
2736 @cindex @code{i} unit
2737 @cindex unit, @code{i}
2738 Inches. An antiquated measurement unit still in use in certain
2739 backwards countries with incredibly low-cost computer equipment. One
2740 inch is equal to@w{ }2.54@dmn{cm}.
2744 @cindex @code{c} unit
2745 @cindex unit, @code{c}
2746 Centimeters. One centimeter is equal to@w{ }0.3937@dmn{in}.
2750 @cindex @code{p} unit
2751 @cindex unit, @code{p}
2752 Points. This is a typesetter's measurement used for measure type size.
2753 It is 72@w{ }points to an inch.
2757 @cindex @code{P} unit
2758 @cindex unit, @code{P}
2759 Pica. Another typesetting measurement. 6@w{ }Picas to an inch (and
2760 12@w{ }points to a pica).
2764 @cindex @code{s} unit
2765 @cindex unit, @code{s}
2766 @cindex @code{z} unit
2767 @cindex unit, @code{z}
2768 @xref{Fractional Type Sizes}, for a discussion of these units.
2771 The other measurements understood by @code{gtroff} depend on
2772 settings currently in effect in @code{gtroff}. These are very useful
2773 for specifying measurements which should look proper with any size of
2779 @cindex @code{m} unit
2780 @cindex unit, @code{m}
2781 Ems. This unit is equal to the current font size in points. So called
2782 because it is @emph{approximately} the width of the letter@w{ }@samp{m}
2783 in the current font.
2787 @cindex @code{n} unit
2788 @cindex unit, @code{n}
2789 Ens. This is half of an em.
2792 @cindex vertical space
2793 @cindex space, vertical
2794 @cindex @code{v} unit
2795 @cindex unit, @code{v}
2796 Vertical space. This is equivalent to the current line spacing.
2797 @xref{Sizes}, for more information about this.
2800 @cindex @code{M} unit
2801 @cindex unit, @code{M}
2809 @c ---------------------------------------------------------------------
2811 @node Default Units, , Measurements, Measurements
2812 @subsection Default Units
2813 @cindex default units
2814 @cindex units, default
2816 Many requests take a default unit. While this can be helpful at times,
2817 it can cause strange errors in some expressions. For example, the line
2818 length request expects em units. Here are several attempts to get a
2819 line length of 3.5@w{ }inches and their results:
2826 7i/2u @result{} 3.5i
2830 Everything is converted to basic units first. In the above example it
2831 is assumed that 1@dmn{i} equals@w{ }240@dmn{u}, and 1@dmn{m} equals@w{
2832 }10@dmn{p} (thus 1@dmn{m} equals@w{ }33@dmn{u}). The value 7@dmn{i}/2
2833 is first handled as 7@dmn{i}/2@dmn{m}, then converted to
2834 1680@dmn{u}/66@dmn{u} which is 25@dmn{u}, and this is approximately
2837 @cindex measurements, specifying safely
2838 Thus, the safest way to specify measurements is to always
2839 attach a scaling indicator. If you want to multiply or divide by a
2840 certain scalar value, use @samp{u} as the unit for that value.
2843 @c =====================================================================
2845 @node Expressions, Identifiers, Measurements, Programming Tutorial
2846 @section Expressions
2849 @code{gtroff} has most arithmetic operators common to other languages:
2851 @c XXX more details; examples
2855 @cindex arithmetic operators
2856 @cindex operators, arithmetic
2862 Arithmetic: @samp{+} (addition), @samp{-} (subtraction), @samp{/}
2863 (division), @samp{*} (multiplication), @samp{%} (modulo).
2865 @code{gtroff} only provides integer arithmetic. The internal type used
2866 for computing results is @samp{int}, which is usually a 32@dmn{bit}
2870 @cindex comparison operators
2871 @cindex operators, comparison
2878 Comparison: @samp{<} (less than), @samp{>} (greater than), @samp{<=}
2879 (less than or equal), @samp{>=} (greater than or equal), @samp{=}
2880 (equal), @samp{==} (the same as @samp{=}).
2883 @cindex logical operators
2884 @cindex operators, logical
2887 Logical: @samp{&} (logical and), @samp{:} (logical or).
2890 @cindex unary operators
2891 @cindex operators, unary
2897 @cindex @code{if}, and the @samp{!} operator
2898 @cindex @code{while}, and the @samp{!} operator
2899 Unary operators: @samp{-} (negating, i.e.@: changing the sign), @samp{+}
2900 (just for completeness; does nothing in expressions), @samp{!} (logical
2901 not; this works only within @code{if} and @code{while} requests). See
2902 below for the use of unary operators in motion requests.
2905 @cindex extremum operators
2906 @cindex operators, extremum
2909 Extrema: @samp{>?} (maximum), @samp{<?} (minimum). For example,
2910 @samp{5>?3} yields@w{ }@samp{5}.
2915 @cindex scaling operator
2916 @cindex operator, scaling
2917 Scaling: @code{(@var{c};@var{e})}. Evaluate @var{e} using @var{c} as
2918 the default scaling indicator. If @var{c} is missing, ignore scaling
2919 indicators in the evaluation of @var{e}.
2923 @cindex order of evaluation in expressions
2924 @cindex expression, order of evaluation
2927 Parentheses may be used as in any other language. However, in
2928 @code{gtroff} they are necessary to ensure order of evaluation.
2929 @code{gtroff} has no operator precedence; expressions are evaluated left
2930 to right. This means that @code{gtroff} evaluates @samp{3+5*4} as if it were
2931 parenthesized like @samp{(3+5)*4}, not as @samp{3+(5*4)}, as might be
2934 @opindex +@r{, and page motion}
2935 @opindex -@r{, and page motion}
2936 @opindex |@r{, and page motion}
2937 @cindex motion operators
2938 @cindex operators, motion
2939 For many requests which cause a motion on the page, the unary operators
2940 work differently. The @samp{+} and @samp{-} operators then indicate a
2941 motion relative to the current position (down or up, respectively), and
2942 the @samp{|} operator indicates an absolute position on the page or
2945 @samp{+} and @samp{-} are also treated differently by the following
2946 requests and escapes: @code{bp}, @code{in}, @code{ll}, @code{lt},
2947 @code{nm}, @code{nr}, @code{pl}, @code{pn}, @code{po}, @code{ps},
2948 @code{rt}, @code{ti}, @code{\R}, and @code{\s}. Here the plus and minus
2949 signs indicate increments and decrements.
2951 @c XXX add more xref
2952 @xref{Setting Registers}.
2954 @cindex space characters in expressions
2955 @cindex expressions and space characters
2956 Due to the way arguments are parsed, spaces are not allowed in
2957 expressions, unless the entire expression is surrounded by parentheses.
2959 @xref{Request Arguments}, and @ref{Conditionals and Loops}.
2962 @c =====================================================================
2964 @node Identifiers, Embedded Commands, Expressions, Programming Tutorial
2965 @section Identifiers
2968 Like any other language, @code{gtroff} has rules for properly formed
2969 @dfn{identifiers}. In @code{gtroff}, an identifier can be made up of
2970 almost any printable character, with the exception of the following
2975 @cindex whitespace characters
2976 @cindex newline character
2977 @cindex character, whitespace
2978 Whitespace characters (spaces, tabs, and newlines).
2981 @cindex character, backspace
2982 @cindex backspace character
2983 @cindex @acronym{EBCDIC} encoding of backspace
2984 Backspace (@acronym{ASCII}@w{ }@code{0x08} or @acronym{EBCDIC}@w{
2985 }@code{0x16}) and character code @code{0x01}.
2988 @cindex invalid input characters
2989 @cindex input characters, invalid
2990 @cindex characters, invalid input
2992 The following input characters are invalid and are ignored if
2993 @code{groff} runs on a machine based on @acronym{ASCII}, causing a
2994 warning message of type @samp{input} (see @ref{Debugging}, for more
2995 details): @code{0x00}, @code{0x0B}, @code{0x0D}-@code{0x1F},
2996 @code{0x80}-@code{0x9F}.
2998 And here are the invalid input characters if @code{groff} runs on an
2999 @acronym{EBCDIC} host: @code{0x00}, @code{0x08}, @code{0x09},
3000 @code{0x0B}, @code{0x0D}-@code{0x14}, @code{0x17}-@code{0x1F},
3001 @code{0x30}-@code{0x3F}.
3003 Currently, some of these reserved codepoints are used internally, thus
3004 making it non-trivial to extend @code{gtroff} to cover Unicode or other
3005 character sets and encodings which use characters of these ranges.
3007 Note that invalid characters are removed before parsing; an
3008 identifier @code{foo}, followed by an invalid character, followed by
3009 @code{bar} is treated as @code{foobar}.
3012 For example, any of the following is valid.
3024 Note that identifiers longer than two characters with a closing bracket
3025 (@samp{]}) in its name can't be accessed with escape sequences which
3026 expect an identifier as a parameter. For example, @samp{\[foo]]}
3027 accesses the glyph @samp{foo}, followed by @samp{]}, whereas
3028 @samp{\C'foo]'} really asks for glyph @samp{foo]}.
3032 @Defesc {\\A, ', ident, '}
3033 Use the @code{\A} escape to test
3034 whether an identifier @var{ident} is valid in @code{gtroff}.
3035 It expands to the character@w{ }1
3036 or@w{ }0 according to whether its argument (usually delimited by quotes)
3037 is or is not acceptable as the name of a string, macro, diversion,
3038 number register, environment, or font. It returns@w{ }0 if no
3039 argument is given. This is useful for looking up user input in some
3040 sort of associative table.
3048 @xref{Escapes}, for details on parameter delimiting characters.
3050 @c XXX add xrefs above
3052 Identifiers in @code{gtroff} can be any length, but, in some contexts,
3053 @code{gtroff} needs to be told where identifiers end and text begins
3054 (and in different ways depending on their length):
3064 Two characters. Must be prefixed with @samp{(} in some situations.
3067 Arbitrary length (@code{gtroff} only). Must be bracketed with @samp{[}
3068 and@w{ }@samp{]} in some situations. Any length identifier can be put
3072 @cindex undefined identifiers
3073 @cindex indentifiers, undefined
3074 Unlike many other programming languages, undefined identifiers are
3075 silently ignored or expanded to nothing.
3076 When @code{gtroff} finds an undefined identifier, it emits a
3081 If the identifier is a string, macro, or diversion,
3082 @code{gtroff} defines it as empty.
3085 If the identifier is a number register, @code{gtroff}
3086 defines it with a value of@w{ }0.
3091 @c XXX info about common identifier pool for strings and macros.
3093 @xref{Interpolating Registers}, and @ref{Strings}.
3096 @c =====================================================================
3098 @node Embedded Commands, Registers, Identifiers, Programming Tutorial
3099 @section Embedded Commands
3100 @cindex embedded commands
3101 @cindex commands, embedded
3103 Most documents need more functionality beyond filling, adjusting and
3104 implicit line breaking. In order to gain further functionality,
3105 @code{gtroff} allows commands to be embedded into the text, in two ways.
3107 The first is a @dfn{request} which takes up an entire line, and does
3108 some large-scale operation (e.g.@: break lines, start new pages).
3110 The other is an @dfn{escape} which can be embedded anywhere in the text,
3111 or even as an argument to a request.
3112 @c XXX (Not always?)
3113 Escapes generally do more minor operations like sub- and superscripts,
3114 print a symbol, etc.
3122 @c ---------------------------------------------------------------------
3124 @node Requests, Macros, Embedded Commands, Embedded Commands
3125 @subsection Requests
3128 @cindex control character
3129 @cindex character, control
3130 @cindex no-break control character
3131 @cindex character, no-break control
3132 @cindex control character, no-break
3135 A request line begins with a control character, which is either a single
3136 quote (@samp{'}, the @dfn{no-break control character}) or a period
3137 (@samp{.}, the normal @dfn{control character}). These can be changed;
3138 see @ref{Character Translations}, for details. After this there may be
3139 optional tabs or spaces followed by an identifier which is the name of
3140 the request. This may be followed by any number of space-separated
3141 arguments (@emph{no} tabs here).
3143 @cindex zero width space character
3144 @cindex character, zero width space
3145 @cindex space character, zero width
3147 @cindex @code{\&}, escaping control characters
3148 To begin a line with a control character without it being interpreted,
3149 precede it with @code{\&}. This represents a zero width space, which
3150 means it does not affect the output.
3152 In most cases the period is used as a control character. Several
3153 requests cause a break implicitly; using the single quote control
3154 character prevents this.
3157 * Request Arguments::
3160 @node Request Arguments, , Requests, Requests
3161 @subsubsection Request Arguments
3162 @cindex request arguments
3163 @cindex arguments to requests
3165 Arguments to requests (and macros) are processed much like the shell:
3166 The line is split into arguments according to spaces. An argument which
3167 is intended to contain spaces can either be enclosed in quotes (single
3168 or double), or have the spaces @dfn{escaped} with backslashes.
3170 Here are a few examples:
3173 .uh The Mouse Problem
3174 .uh "The Mouse Problem"
3175 .uh The\ Mouse\ Problem
3181 The first line is the @code{uh} macro being called with 3 arguments,
3182 @samp{The}, @samp{Mouse}, and @samp{Problem}. The latter two have the
3183 same effect of calling the @code{uh} macro with one argument, @samp{The
3184 Mouse Problem}.@footnote{The last solution, i.e., using escaped spaces,
3185 is ``classical'' in the sense that it can be found in most @code{troff}
3186 documents. Nevertheless, it is not optimal in all situations, since
3187 @w{@samp{\ }} inserts a fixed-width, non-breaking space character which
3188 can't stretch. @code{gtroff} provides a different command @code{\~} to
3189 insert a stretchable, non-breaking space.}
3192 Note, however, that the @code{ds} request works differently.
3193 @xref{Strings}, for more details.
3195 @c ---------------------------------------------------------------------
3197 @node Macros, Escapes, Requests, Embedded Commands
3201 @code{gtroff} has a @dfn{macro} facility for defining a series of lines
3202 which can be invoked by name. They are called in the same manner as
3203 requests -- arguments also may be passed in the same manner.
3205 @xref{Writing Macros}, and @ref{Request Arguments}.
3207 @c ---------------------------------------------------------------------
3209 @node Escapes, , Macros, Embedded Commands
3213 Escapes may occur anywhere in the input to @code{gtroff}. They usually
3214 begin with a backslash and are followed by a single character which
3215 indicates the function to be performed. The escape character can be
3216 changed; see @ref{Character Translations}.
3221 Escape sequences which require an identifier as a parameter accept three
3222 possible syntax forms.
3226 The next single character is the identifier.
3229 If this single character is an opening parenthesis, take the following
3230 two characters as the identifier. Note that there is no closing
3231 parenthesis after the identifier.
3234 If this single character is an opening bracket, take all characters
3235 until a closing bracket as the identifier.
3248 @cindex argument delimiting characters
3249 @cindex characters, argument delimiting
3250 @cindex delimiting characters for arguments
3251 Other escapes may require several arguments and/or some special format.
3252 In such cases the argument is traditionally enclosed in single quotes
3253 (and quotes are always used in this manual for the definitions of escape
3254 sequences). The enclosed text is then processed according to what that
3255 escape expects. Example:
3264 Note that the quote character can be replaced with any other character
3265 which does not occur in the argument (even a newline or a space
3266 character) in the following escapes: @code{\o}, @code{\b}, and
3267 @code{\X}. This makes e.g.
3276 @result{} A caf@'e in Paris
3280 possible, but it is better not to use this feature to avoid confusion.
3310 The following escapes sequences (which are handled similarly to
3311 characters since they don't take a parameter) are also allowed as
3312 delimiters: @code{\%}, @w{@samp{\ }}, @code{\|}, @code{\^}, @code{\@{},
3313 @code{\@}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
3314 @code{\?}, @code{\@@}, @code{\)}, @code{\/}, @code{\,}, @code{\&},
3315 @code{\~}, @code{\0}, @code{\a}, @code{\c}, @code{\d}, @code{\e},
3316 @code{\E}, @code{\p}, @code{\r}, @code{\t}, and @code{\u}. Again, don't
3317 use these if possible.
3323 No newline characters as delimiters are allowed in the following
3324 escapes: @code{\A}, @code{\Z}, @code{\C}, and @code{\w}.
3337 Finally, the escapes @code{\D}, @code{\h}, @code{\H}, @code{\l},
3338 @code{\L}, @code{\N}, @code{\R}, @code{\s}, @code{\S}, @code{\v}, and
3339 @code{\x} can't use the following characters as delimiters:
3345 The digits @code{0}-@code{9}.
3362 The (single-character) operators @samp{+-/*%<>=&:().}.
3365 @cindex space character
3366 @cindex character, space
3367 @cindex tab character
3368 @cindex character, tab
3369 @cindex newline character
3370 @cindex character, newline
3371 The space, tab, and newline characters.
3387 All escape sequences except @code{\%}, @code{\@{}, @code{\@}},
3388 @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, @code{\@@},
3389 @code{\/}, @code{\c}, @code{\e}, and @code{\p}.
3395 To have a backslash (actually, the current escape character) appear in the
3396 output several escapes are defined: @code{\\}, @code{\e} or @code{\E}.
3397 These are very similar, and only differ with respect to being used in
3398 macros or diversions. @xref{Copy-in Mode}, and @ref{Diversions}, for
3401 @c XXX explanation of \E
3403 @xref{Identifiers}, and @ref{Character Translations}.
3409 @node Comments, , Escapes, Escapes
3410 @subsubsection Comments
3413 Probably one of the most@footnote{Unfortunately, this is a lie. But
3414 hopefully future @code{gtroff} hackers will believe it @code{:-)}}
3415 common forms of escapes is the comment.
3418 Start a comment. Everything to the end of the input line is ignored.
3420 This may sound simple, but it can be tricky to keep the comments from
3421 interfering with the appearance of the final output.
3424 If the escape is to the right of some text or a request, that portion of
3425 the line is ignored, but the space leading up to it is noticed
3426 by @code{gtroff}. This only affects the @code{.ds} request.
3427 @c XXX (any others?)
3429 @cindex tabs before comments
3430 @cindex comments, lining up with tabs
3431 One possibly irritating idiosyncracy is that tabs must not be used to
3432 line up comments. Tabs are not treated as white space between the
3433 request and macro arguments.
3435 @cindex undefined request
3436 @cindex request, undefined
3437 A comment on a line by itself is treated as a blank line, because
3438 after eliminating the comment, that is all that remains:
3455 To avoid this, it is common to start the line with @code{.\"} which
3456 causes the line to be treated as an undefined request and thus ignored
3460 Another commenting scheme seen sometimes is three consecutive single
3461 quotes (@code{'''}) at the beginning of a line. This works, but
3462 @code{gtroff} gives a warning about an undefined macro (namely
3463 @code{''}), which is harmless, but irritating.
3467 To avoid all this, @code{gtroff} has a new comment mechanism using
3468 the @code{\#} escape. This escape works the same as @code{\"} except
3469 that the newline is also ignored:
3489 Ignores all input until @code{gtroff} encounters the macro named
3490 @code{.}@var{yy} on a line by itself (or @code{..} if @var{yy}
3491 is not specified). This is useful for commenting out large
3497 This is part of a large block
3498 of text that has been
3499 temporarily(?) commented out.
3501 We can restore it simply by removing
3502 the .ig request and the ".." at the
3505 More text text text...
3512 text text text@dots{} More text text text@dots{}
3516 Note that the commented-out block of text does not
3519 The input is read in copy-mode; auto-incremented registers @emph{are}
3520 affected (@pxref{Auto-increment}).
3524 @c =====================================================================
3526 @node Registers, Manipulating Filling and Adjusting, Embedded Commands, Programming Tutorial
3530 Numeric variables in @code{gtroff} are called @dfn{registers}. There
3531 are a number of built-in registers, supplying anything from the date to
3532 details of formatting parameters.
3534 @xref{Identifiers}, for details on register identifiers.
3537 * Setting Registers::
3538 * Interpolating Registers::
3540 * Assigning Formats::
3541 * Built-in Registers::
3544 @c ---------------------------------------------------------------------
3546 @node Setting Registers, Interpolating Registers, Registers, Registers
3547 @subsection Setting Registers
3548 @cindex setting registers
3549 @cindex registers, setting
3551 Define or set registers using the @code{nr} request or the
3554 @Defreq {nr, ident value}
3555 @Defescx {\\R, ', ident value, '}
3556 Set number register @var{ident} to @var{value}. If @var{ident} doesn't
3557 exist, @code{gtroff} creates it.
3559 The argument to @code{\R} usually has to be enclosed in quotes.
3560 @xref{Escapes}, for details on parameter delimiting characters.
3563 For example, the following two lines are equivalent:
3570 Both @code{nr} and @code{\R} have two additional special forms to
3571 increment or decrement a register.
3573 @Defreq {nr, ident @t{+}@Var{value}}
3574 @Defreqx {nr, ident @t{-}@Var{value}}
3575 @Defescx {\\R, ', ident @t{+}@Var{value}, '}
3576 @Defescx {\\R, ', ident @t{-}@Var{value}, '}
3577 Increment (decrement) register @var{ident} by @var{value}.
3586 @cindex negating register values
3587 To assign the negated value of a register to another register, some care
3588 must be taken to get the desired result:
3602 The surrounding parentheses prevent the interpretation of the minus sign
3603 as a decrementing operator. An alternative is to start the assignment
3619 Remove number register @var{ident}. If @var{ident} doesn't exist, the
3623 @Defreq {rnn, ident1 ident2}
3624 Rename number register @var{ident1} to @var{ident2}. If either
3625 @var{ident1} or @var{ident2} doesn't exist, the request is ignored.
3628 @Defreq {aln, ident1 ident2}
3629 This request creates an alias @var{ident1} for a number register
3630 @var{ident2}. The new name and the old name are exactly equivalent.
3631 If @var{ident1} is undefined, a warning of type @samp{reg} is
3632 generated, and the request is ignored. @xref{Debugging}, for
3633 information about warnings.
3636 @c ---------------------------------------------------------------------
3638 @node Interpolating Registers, Auto-increment, Setting Registers, Registers
3639 @subsection Interpolating Registers
3640 @cindex interpolating registers
3641 @cindex registers, interpolating
3643 Numeric registers can be accessed via the @code{\n} escape.
3645 @Defesc {\\n, , i, }
3646 @Defescx {\\n, @lparen{}, id, }
3647 @Defescx {\\n, @lbrack{}, ident, @rbrack}
3648 @c XXX is the following correct?
3649 Interpolate number register with name @var{ident} (one-character name
3650 @var{i}, two-character name @var{id}). This means that the value of the
3651 register is expanded in-place while @code{gtroff} is parsing the input
3662 @c ---------------------------------------------------------------------
3664 @node Auto-increment, Assigning Formats, Interpolating Registers, Registers
3665 @subsection Auto-increment
3666 @cindex auto-increment
3667 @cindex increment, automatic
3669 Number registers can also be auto-incremented and auto-decremented. The
3670 increment or decrement value can be specified with a third argument to
3671 the @code{nr} request or @code{\R} escape.
3674 @Defreq {nr, ident value incr}
3675 Set number register @var{ident} to @var{value}; the increment for
3676 auto-incrementing is set to @var{incr}. Note that the @code{\R} escape
3677 doesn't support this notation.
3680 To activate auto-incrementing, the escape @code{\n} has a special syntax
3683 @Defesc {\\n, +, i, }
3684 @Defescx {\\n, -, i, }
3685 @Defescx {\\n, @lparen{}+, id, }
3686 @Defescx {\\n, @lparen{}-, id, }
3687 @Defescx {\\n, @lbrack{}+, ident, @rbrack{}}
3688 @Defescx {\\n, @lbrack{}-, ident, @rbrack{}}
3689 Before interpolating, increment or decrement @var{ident} (one-character
3690 name @var{i}, two-character name @var{id}) by the auto-increment value
3691 as specified with the @code{nr} request (or the @code{\R} escape). If
3692 no auto-increment value has been specified, these syntax forms are
3693 identical to @code{\n}.
3702 \n+a, \n+a, \n+a, \n+a, \n+a
3704 \n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx
3706 \n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo]
3714 -5, -10, -15, -20, -25
3718 @cindex increment value without changing the register
3719 To change the increment value without changing the value of a register
3720 (@var{a} in the example), the following can be used:
3726 @c ---------------------------------------------------------------------
3728 @node Assigning Formats, Built-in Registers, Auto-increment, Registers
3729 @subsection Assigning Formats
3730 @cindex assigning formats
3731 @cindex formats, assigning
3733 When a register is used in the text of an input file (as opposed to part
3734 of an expression), it is textually replaced (or interpolated) with a
3735 representation of that number. This output format can be changed to a
3736 variety of formats (numbers, Roman numerals, etc.). This is done using
3737 the @code{af} request.
3739 @Defreq {af, ident format}
3740 Change the output format of a number register. The first argument
3741 @var{ident} is the name of the number register to be changed, and the
3742 second argument @var{format} is the output format. The following output
3743 formats are available:
3747 Decimal arabic numbers. This is the default format: 0, 1, 2, 3,@w{
3751 Decimal numbers with as many digits as specified. So, @samp{00} would
3752 result in printing numbers as 01, 02, 03,@w{ }@enddots{}
3754 In fact, any digit instead of zero will do; @code{gtroff} only counts
3755 how many digits are specified. As a consequence, @code{af}'s default
3756 format @samp{1} could be specified as @samp{0} also (and exactly this is
3757 returned by the @code{\g} escape, see below).
3760 @cindex roman numerals
3761 @cindex numerals, Roman
3762 Upper-case Roman numerals: 0, I, II, III, IV,@w{ }@enddots{}
3765 Lower-case Roman numerals: 0, i, ii, iii, iv,@w{ }@enddots{}
3768 Upper-case letters: 0, A, B, C, @dots{},@w{ }Z, AA, AB,@w{ }@enddots{}
3771 Lower-case letters: 0, a, b, c, @dots{},@w{ }z, aa, ab,@w{ }@enddots{}
3774 Omitting the number register format causes a warning of type
3775 @samp{missing}. @xref{Debugging}, for more details. Specifying a
3776 nonexistent format causes an error.
3778 The following example produces @samp{10, X, j, 010}:
3782 .af a 1 \" the default format
3792 @cindex roman numerals, maximum and minimum
3793 @cindex maximum values of Roman numerals
3794 @cindex minimum values of Roman numerals
3795 The largest number representable for the @samp{i} and @samp{I} formats
3796 is 39999 (or @minus{}39999); @acronym{UNIX} @code{troff} uses @samp{z}
3797 and @samp{w} to represent 10000 and 5000 in Roman numerals, and so does
3798 @code{gtroff}. Currently, the correct glyphs of Roman numeral five
3799 thousand and Roman numeral ten thousand (Unicode code points
3800 @code{U+2182} and @code{U+2181}, respectively) are not available.
3802 If @var{ident} doesn't exist, it is created.
3804 @cindex read-only register, changing format
3805 @cindex changing format, read-only register
3806 Changing the output format of a read-only register causes an error. It
3807 is necessary to first copy the register's value to a writeable register,
3808 then apply the @code{af} request to this other register.
3811 @cindex format of register
3812 @cindex register, format
3813 @Defesc {\\g, , i, }
3814 @Defescx {\\g, @lparen{}, id, }
3815 @Defescx {\\g, @lbrack{}, ident, @rbrack{}}
3816 Return the current format of the specified register @var{ident}
3817 (one-character name @var{i}, two-character name @var{id}). For example,
3818 @samp{\ga} after the previous example would produce the string
3819 @samp{000}. If the register hasn't been defined yet, nothing is
3823 @c ---------------------------------------------------------------------
3825 @node Built-in Registers, , Assigning Formats, Registers
3826 @subsection Built-in Registers
3827 @cindex built-in registers
3828 @cindex registers, built-in
3830 The following lists some built-in registers which are not described
3831 elsewhere in this manual. Any register which begins with a @samp{.} is
3832 read-only. A complete listing of all built-in registers can be found in
3833 @ref{Register Index}.
3837 @cindex horizontal resolution register
3838 @cindex resolution, horizontal, register
3840 Horizontal resolution in basic units.
3843 @cindex vertical resolution register
3844 @cindex resolution, vertical, register
3846 Vertical resolution in basic units.
3849 @cindex day of the week register
3850 @cindex date, day of the week register
3852 Day of the week (1-7).
3855 @cindex day of the month register
3856 @cindex date, day of the month register
3858 Day of the month (1-31).
3861 @cindex month of the year register
3862 @cindex date, month of the year register
3864 Current month (1-12).
3867 @cindex date, year register
3868 @cindex year, current, register
3874 The current year minus@w{ }1900. Unfortunately, the documentation of
3875 @acronym{UNIX} Version@w{ }7's @code{troff} had a year@w{ }2000 bug: It
3876 incorrectly claimed that @code{yr} contains the last two digits of the
3877 year. That claim has never been true of either traditional @code{troff}
3878 or GNU @code{troff}. Old @code{troff} input that looks like this:
3881 '\" The following line stopped working after 1999
3882 This document was formatted in 19\n(yr.
3886 can be corrected as follows:
3889 This document was formatted in \n[year].
3893 or, to be portable to older @code{troff} versions, as follows:
3897 This document was formatted in \n(y4.
3904 @cindex input line number register
3905 @cindex line number, input, register
3906 The current @emph{input} line number. Register @samp{.c} is read-only,
3907 whereas @samp{c.} (a @code{gtroff} extension) is writable also,
3908 affecting both @samp{.c} and @samp{c.}.
3913 @cindex output line number register
3914 @cindex line number, output, register
3915 The current @emph{output} line number after a call to the @code{nm}
3916 request to activate line numbering.
3918 @xref{Miscellaneous}, for more information about line numbering.
3922 @cindex major version number register
3923 @cindex version number, major, register
3924 The major version number. For example, if the version number is@w{
3925 }1.03 then @code{.x} contains@w{ }@samp{1}.
3929 @cindex minor version number register
3930 @cindex version number, minor, register
3931 The minor version number. For example, if the version number is@w{
3932 }1.03 then @code{.y} contains@w{ }@samp{03}.
3936 @cindex revision number register
3937 The revision number of @code{groff}.
3941 @cindex @code{gtroff} identification register
3942 @cindex GNU-specific register
3943 Always@w{ }1. Macros should use this to determine whether they are
3944 running under GNU @code{troff}.
3948 @cindex @acronym{ASCII} approximation output register
3949 If the command line option @option{-a} is used to produce an
3950 @acronym{ASCII} approximation of the output, this is set to@w{ }1, zero
3951 otherwise. @xref{Groff Options}.
3955 This register is set to@w{ }1 (and to@w{ }0 otherwise) if the current
3956 page is actually being printed, i.e., if the @option{-o} option is being
3957 used to only print selected pages. @xref{Groff Options}, for more
3962 If @code{gtroff} is called with the @option{-T} command line option, the
3963 number register @code{.T} is set to@w{ }1, and zero otherwise.
3964 @xref{Groff Options}.
3967 @cindex output device register
3968 Additionally, @code{gtroff} predefines a single read-write string
3969 register @code{.T} which contains the current output device (for
3970 example, @samp{latin1} or @samp{ps}).
3974 @c =====================================================================
3976 @node Manipulating Filling and Adjusting, Manipulating Hyphenation, Registers, Programming Tutorial
3977 @section Manipulating Filling and Adjusting
3978 @cindex manipulating filling and adjusting
3979 @cindex filling and adjusting, manipulating
3980 @cindex adjusting and filling, manipulating
3981 @cindex justifying text
3982 @cindex text, justifying
3997 Various ways of causing @dfn{breaks} were given in @ref{Implicit Line
3998 Breaks}. The @code{br} request likewise causes a break. Several
3999 other requests also cause breaks, but implicitly. These are
4000 @code{bp}, @code{ce}, @code{cf}, @code{fi}, @code{fl}, @code{in},
4001 @code{nf}, @code{rj}, @code{sp}, @code{ti}, and @code{trf}.
4004 Break the current line, i.e., the input collected so far is emitted
4007 If the no-break control character is used, @code{gtroff} suppresses
4018 Initially, @code{gtroff} fills and adjusts text to both margins.
4019 Filling can be disabled via the @code{nf} request and re-enabled with
4020 the @code{fi} request.
4026 Activate fill mode (which is the default). This request implicitly
4027 enables adjusting; it also inserts a break in the text currently being
4028 filled. The read-only number register @code{.u} is set to@w{ }1.
4030 The fill mode status is associated with the current environment
4031 (@pxref{Environments}).
4034 @cindex no-fill mode
4035 @cindex mode, no-fill
4037 Activate no-fill mode. Input lines are output as-is, retaining line
4038 breaks and ignoring the current line length. This command implicitly
4039 disables adjusting; it also causes a break. The number register
4040 @code{.u} is set to@w{ }0.
4042 The fill mode status is associated with the current environment
4043 (@pxref{Environments}).
4046 @Defreq {ad, [@Var{mode}]}
4050 Activation and deactivation of adjusting is done implicitly with
4051 calls to the @code{fi} or @code{nf} requests.
4053 @var{mode} can have one of the following values:
4057 @cindex ragged-right
4058 Adjust text to the left margin. This produces what is traditionally
4059 called ragged-right text.
4063 Adjust text to the right margin, producing ragged-left text.
4066 @cindex centered text
4068 Center filled text. This is different to the @code{ce} request which
4069 only centers text without filling.
4073 Justify to both margins. This is the default used by @code{gtroff}.
4076 With no argument, @code{gtroff} adjusts lines in the same way it did
4077 before adjusting was deactivated (with a call to @code{na}, for
4088 .ad \" back to centering
4092 @cindex current adjustment mode register
4093 The current adjustment mode is available in the read-only number
4094 register @code{.j}; it can be stored and subsequently used to set
4097 The adjustment mode status is associated with the current environment
4098 (@pxref{Environments}).
4102 Disable adjusting. This request won't change the current adjustment
4103 mode: A subsequent call to @code{ad} uses the previous adjustment
4106 The adjustment mode status is associated with the current environment
4107 (@pxref{Environments}).
4111 Adjust the current line and cause a break.
4113 In most cases this produces very ugly results, since @code{gtroff}
4114 doesn't have a sophisticated paragraph building algorithm (as @TeX{}
4115 have, for example); instead, @code{gtroff} fills and adjusts a paragraph
4119 This is an uninteresting sentence.
4120 This is an uninteresting sentence.\p
4121 This is an uninteresting sentence.
4128 This is an uninteresting sentence. This is an
4129 uninteresting sentence.
4130 This is an uninteresting sentence.
4134 @cindex word space size
4135 @cindex size of word space
4136 @cindex space between words
4137 @cindex sentence space size
4138 @cindex size of sentence space
4139 @cindex space between sentences
4140 @Defreq {ss, word_space_size [@Var{sentence_space_size}]}
4143 Change the minimum size of a space between filled words. It takes its
4144 units as one twelfth of the space width parameter for the current font.
4145 Initially both the @var{word_space_size} and @var{sentence_space_size}
4150 If two arguments are given to the @code{ss} request, the second argument
4151 sets the sentence space size. If the second argument is not given,
4152 sentence space size is set to @var{word_space_size}. The sentence space
4153 size is used in two circumstances: If the end of a sentence occurs at
4154 the end of a line in fill mode, then both an inter-word space and a
4155 sentence space are added; if two spaces follow the end of a sentence in
4156 the middle of a line, then the second space is a sentence space. If a
4157 second argument is never given to the @code{ss} request, the behaviour
4158 of @acronym{UNIX} @code{troff} is the same as that exhibited by GNU
4159 @code{troff}. In GNU @code{troff}, as in @acronym{UNIX} @code{troff}, a
4160 sentence should always be followed by either a newline or two spaces.
4162 The read-only number registers @code{.ss} and @code{.sss} hold the
4163 values of the parameters set by the first and second arguments of the
4166 The word space and sentence space values are associated with the current
4167 environment (@pxref{Environments}).
4169 Contrary to traditional Unix @code{troff}, this request is @emph{not}
4170 ignored in nroff mode; the given values are then rounded down to a
4173 The request is ignored if there is no parameter.
4176 @cindex centering lines
4177 @cindex lines, centering
4178 @Defreq {ce, [@Var{nnn}]}
4180 Center text. While the @w{@samp{.ad c}} request also centers text,
4181 it fills the text as well. @code{ce} does not fill the
4182 text it affects. This request causes a break.
4184 The following example demonstrates the differences.
4190 This is a small text fragment which shows the differences
4191 between the `.ce' and the `.ad c' request.
4195 This is a small text fragment which shows the differences
4196 between the `.ce' and the `.ad c' request.
4200 And here the result:
4203 This is a small text fragment which
4204 shows the differences
4205 between the `.ce' and the `.ad c' request.
4207 This is a small text fragment which
4208 shows the differences between the `.ce'
4209 and the `.ad c' request.
4212 With no arguments, @code{ce} centers the next line of text. @var{nnn}
4213 specifies the number of lines to be centered. If the argument is zero
4214 or negative, centering is disabled.
4219 The basic length for centering text is the line length (as set with the
4220 @code{ll} request) minus the indentation (as set with the @code{in}
4221 request). Temporary indentation is ignored.
4223 As can be seen in the previous example, it is a common idiom to turn on
4224 centering for a large number of lines, and to turn off centering after
4225 text to be centered. This is useful for any request which takes a
4226 number of lines as an argument.
4228 The @code{.ce} read-only number register contains the number of lines
4229 remaining to be centered, as set by the @code{ce} request.
4232 @cindex justifying text
4233 @cindex text, justifying
4234 @cindex right-justifying
4235 @Defreq {rj, [@Var{nnn}]}
4237 Justify unfilled text to the right margin. Arguments are identical to
4238 the @code{ce} request. The @code{.rj} read-only number register is the
4239 number of lines to be right-justified as set by the @code{rj} request.
4240 This request causes a break.
4244 @c =====================================================================
4246 @node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjusting, Programming Tutorial
4247 @section Manipulating Hyphenation
4248 @cindex manipulating hyphenation
4249 @cindex hyphenation, manipulating
4251 As discussed in @ref{Hyphenation}, @code{gtroff} hyphenates words.
4252 There are a number of ways to influence hyphenation.
4254 @Defreq {hy, [@Var{mode}]}
4256 Enable hyphenation. The request has an optional numeric argument,
4257 @var{mode}, to restrict hyphenation if necessary:
4261 The default argument if @var{mode} is omitted. Hyphenate without
4262 restrictions. This is also the start-up value of @code{gtroff}.
4265 Do not hyphenate the last word on a page or column.
4268 Do not hyphenate the last two characters of a word.
4271 Do not hyphenate the first two characters of a word.
4274 Values in the previous table are additive. For example, the value@w{
4275 }12 causes @code{gtroff} to neither hyphenate the last two nor the first
4276 two characters of a word.
4278 @cindex hyphenation restrictions register
4279 The current hyphenation restrictions can be found in the read-only
4280 number register @samp{.hy}.
4282 The hyphenation mode is associated with the current environment
4283 (@pxref{Environments}).
4287 Disable hyphenation (i.e., set the hyphenation mode to zero). Note that
4288 the hyphenation mode of the last call to @code{hy} is not remembered.
4290 The hyphenation mode is associated with the current environment
4291 (@pxref{Environments}).
4295 @cindex explicit hyphens
4296 @cindex hyphen, explicit
4297 @cindex consecutive hyphenated lines
4298 @cindex lines, consecutive hyphenated
4299 @cindex hyphenated lines, consecutive
4300 @Defreq {hlm, [@Var{nnn}]}
4303 Set the maximum number of consecutive hyphenated lines to @var{nnn}. If
4304 this number is negative, there is no maximum. The default value is@w{
4305 }@minus{}1 if @var{nnn} is omitted. This value is associated with the
4306 current environment (@pxref{Environments}). Only lines output from a
4307 given environment count towards the maximum associated with that
4308 environment. Hyphens resulting from @code{\%} are counted; explicit
4311 The current setting of @code{hlm} is available in the @code{.hlm}
4312 read-only number register. Also the number of immediately preceding
4313 consecutive hyphenated lines are available in the read-only number
4314 register @samp{.hlc}.
4317 @Defreq {hw, word1 word2 @dots{}}
4318 Define how @var{word1}, @var{word2}, etc.@: are to be hyphenated. The
4319 words must be given with hyphens at the hyphenation points. For
4327 Besides the space character, any character whose hyphenation code value
4328 is zero can be used to separate the arguments of @code{hw} (see the
4329 documentation for the @code{hcode} request below for more information).
4330 In addition, this request can be used more than once.
4332 Hyphenation exceptions specified with the @code{hw} request are
4333 associated with the current hyphenation language; it causes an error
4334 if there is no current hyphenation language.
4336 This request is ignored if there is no parameter.
4338 In old versions of @code{troff} there was a limited amount of space to
4339 store such information; fortunately, with @code{gtroff}, this is no
4340 longer a restriction.
4343 @cindex hyphenation character
4344 @cindex character, hyphenation
4345 @cindex disabling hyphenation
4346 @cindex hyphenation, disabling
4348 To tell @code{gtroff} how to hyphenate words on the fly, use the @code{\%}
4349 escape, also known as the @dfn{hyphenation character}.
4350 Preceding a word with this character prevents it from being
4351 hyphenated; putting it inside a word indicates to @code{gtroff} that the
4352 word may be hyphenated at that point. Note that this mechanism
4353 only affects that one occurrence of the word; to change the hyphenation
4354 of a word for the entire document, use the @code{hw} request.
4357 @Defreq {hc, [@Var{char}]}
4358 Change the hyphenation character to @var{char}. This character
4359 then works the same as the @code{\%} escape, and thus, no longer appears
4360 in the output. Without an argument, @code{hc} resets the
4361 hyphenation character to be @code{\%} (the default) only.
4363 The hyphenation character is associated with the current environment
4364 (@pxref{Environments}).
4367 @cindex hyphenation patterns
4368 @cindex patterns for hyphenation
4369 @Defreq {hpf, pattern_file}
4370 Read in a file of hyphenation patterns. This file is searched for
4371 in the same way as @file{@var{name}.tmac} (or
4372 @file{tmac.@var{name}}) is searched for if the @option{-m@var{name}}
4373 option is specified.
4375 It should have the same format as the argument to the @code{\patterns}
4376 primitive in @TeX{} (without using @TeX{}'s macro expansion); the
4377 letters appearing in this file are interpreted as hyphenation codes. A
4378 @samp{%} character in the patterns file introduces a comment that
4379 continues to the end of the line.
4381 If no @code{hpf} request is specified (either in the document or in a
4382 macro package), @code{gtroff} won't hyphenate at all.
4388 The set of hyphenation patterns is associated with the current language
4389 set by the @code{hla} request. The @code{hpf} request is usually
4390 invoked by the @file{troffrc} or @file{troffrc-end} file; by default,
4391 @file{troffrc} loads hyphenation patterns for American English (in file
4394 Invoking @code{hpf} causes an error if there is no current hyphenation
4398 @cindex hyphenation code
4399 @cindex code, hyphenation
4400 @Defreq {hcode, c1 code1 c2 code2 @dots{}}
4401 Sets the hyphenation code of character @var{c1} to @var{code1}, that of
4402 @var{c2} to @var{code2}, etc. A hyphenation code must be a single input
4403 character (not a special character) other than a digit or a space.
4404 Initially each lower-case letter (@samp{a}-@samp{z}) has its hyphenation
4405 set to itself, and each upper-case letter (@samp{A}-@samp{Z}) has a
4406 hyphenation code which is the lower-case version of itself.
4408 This request is ignored if it has no parameter.
4411 @cindex hyphenation margin
4412 @cindex margin for hyphenation
4414 @Defreq {hym, [@Var{length}]}
4416 Set the (right) hyphenation margin to @var{length}. If the current
4417 adjustment mode is not @samp{b} or@w{ }@samp{n}, the line is not
4418 hyphenated if it is shorter than @var{length}. Without an argument, the
4419 hyphenation margin is reset to its default value, which is@w{ }0. The
4420 default scaling indicator for this request is@w{ }@code{m}. The
4421 hyphenation margin is associated with the current environment
4422 (@pxref{Environments}).
4424 A negative argument resets the hyphenation margin to zero, emitting
4425 a warning of type @samp{range}.
4427 @cindex current hyphenation margin register
4428 The current hyphenation margin is available in the @code{.hym} read-only
4432 @cindex hyphenation space
4434 @Defreq {hys, [@Var{hyphenation_space}]}
4436 Set the hyphenation space to @var{hyphenation_space}. If the current
4437 adjustment mode is @samp{b} or@w{ }@samp{n}, don't hyphenate the line if
4438 it can be justified by adding no more than @var{hyphenation_space} extra
4439 space to each word space. Without argument, the hyphenation space is
4440 set to its default value, which is@w{ }0. The default scaling indicator
4441 for this request is@w{ }@code{m}. The hyphenation space is associated
4442 with the current environment (@pxref{Environments}).
4444 A negative argument resets the hyphenation space to zero, emitting a
4445 warning of type @samp{range}.
4447 @cindex current hyphenation space register
4448 The current hyphenation space is available in the @code{.hys} read-only
4452 @cindex soft hyphen character
4453 @cindex character, soft hyphen
4457 @Defreq {shc, [@Var{char}]}
4458 Set the soft hyphen character to @var{char}. If the argument is
4459 omitted, the soft hyphen character is set to the default character
4460 @code{\(hy} (this is the start-up value of @code{gtroff} also). The
4461 soft hyphen character is the character that is inserted when a
4462 word is hyphenated at a line break. If the soft hyphen character does
4463 not exist in the font of the character immediately preceding a potential
4464 break point, then the line is not broken at that point. Neither
4465 definitions (specified with the @code{char} request) nor translations
4466 (specified with the @code{tr} request) are considered when finding the
4467 soft hyphen character.
4474 @Defreq {hla, language}
4476 Set the current hyphenation language to the string @var{language}.
4477 Hyphenation exceptions specified with the @code{hw} request and
4478 hyphenation patterns specified with the @code{hpf} request are both
4479 associated with the current hyphenation language. The @code{hla}
4480 request is usually invoked by the @file{troffrc} or the
4481 @file{troffrc-end} files; @file{troffrc} sets the default language to
4484 @cindex current hyphenation language register
4485 The current hyphenation language is available as a string in the
4486 read-only number register @samp{.hla}.
4489 .ds curr_language \n[.hla]
4496 @c =====================================================================
4498 @node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, Programming Tutorial
4499 @section Manipulating Spacing
4500 @cindex manipulating spacing
4501 @cindex spacing, manipulating
4503 @Defreq {sp, [@Var{distance}]}
4504 Space downwards @var{distance}. With no argument it advances 1@w{
4505 }line. A negative argument causes @code{gtroff} to move up the page
4506 the specified distance. If the argument is preceded by a @samp{|}
4507 then @code{gtroff} moves that distance from the top of the page. This
4508 request causes a line break. The default scaling indicator is@w{
4512 @cindex double-spacing
4513 @Defreq {ls, [@Var{nnn}]}
4515 Output @w{@var{nnn}@minus{}1} blank lines after each line of text. With
4516 no argument, @code{gtroff} uses the previous value before the last
4520 .ls 2 \" This causes double-spaced output
4521 .ls 3 \" This causes triple-spaced output
4522 .ls \" Again double spaced
4525 The line spacing is associated with the current environment
4526 (@pxref{Environments}).
4528 @cindex current line spacing register
4529 The read-only number register @code{.L} contains the current line
4533 @Defesc {\\x, ', spacing, '}
4535 Sometimes, extra vertical spacing is only needed occasionally, e.g.@: to
4536 allow space for a tall construct (like an equation). The @code{\x}
4537 escape does this. The escape is given a numerical argument, usually
4538 enclosed in quotes (like @samp{\x'3p'}); the default scaling indicator
4539 is@w{ }@code{v}. If this number is positive extra vertical space is
4540 inserted below the current line. A negative number adds space
4541 above. If this escape is used multiple times on the same line, the
4542 maximum of the values is used.
4544 @xref{Escapes}, for details on parameter delimiting characters.
4546 @cindex extra vertical line space register
4547 The @code{.a} read-only number register contains the most recent
4548 (nonnegative) extra vertical line space.
4553 ... example of inline equation ...
4559 @cindex no-space mode
4560 @cindex mode, no-space
4561 @cindex blank lines, disabling
4562 @cindex lines, blank, disabling
4564 Enable @dfn{no-space mode}. In this mode, spacing (either via @code{sp}
4565 or via blank lines) is disabled. The @code{bp} request to advance to
4566 the next page is also disabled, except if it is accompanied by a page
4567 number (see @ref{Page Control}, for more information). This mode
4568 ends when actual text is output or the @code{rs} request is encountered.
4570 This request is useful for macros which want to avoid that subsequent
4571 macros inadvertently insert some vertical space before the text starts
4572 (for example, to set up the first paragraph after a section header). It
4573 is associated with the current diversion level.
4579 Disable no-space mode. This request is associated with the current
4586 @c =====================================================================
4588 @node Tabs and Fields, Character Translations, Manipulating Spacing, Programming Tutorial
4589 @section Tabs and Fields
4590 @cindex tabs and fields
4591 @cindex fields and tabs
4593 @cindex @acronym{EBCDIC} encoding of a tab
4594 A tab character (@acronym{ASCII} char@w{ }9, @acronym{EBCDIC} char@w{
4595 }5) causes a horizontal movement to the next tab stop (much
4596 like it did on a typewriter).
4599 This escape is a non-interpreted tab character. In copy mode
4600 (@pxref{Copy-in Mode}), @code{\t} is the same as a real tab character.
4603 @Defreq {ta, [@Var{n1} @Var{n2} @dots{} @Var{nn} @t{T} @Var{r1} @Var{r2} @dots{} @Var{rn}]}
4605 Change tab stop positions. This request takes a series of tab
4606 specifiers as arguments (optionally divided into two groups with the
4607 letter @samp{T}) which indicate where each tab stop is to be (overriding
4608 any previous settings).
4610 Tab stops can be specified absolutely, i.e., as the distance from the
4611 left margin. For example, the following sets 6@w{ }tab stops every
4615 .ta 1i 2i 3i 4i 5i 6i
4618 Tab stops can also be specified using a leading @samp{+}
4619 which means that the specified tab stop is set relative to
4620 the previous tab stop. For example, the following is equivalent to the
4624 .ta 1i +1i +1i +1i +1i +1i
4627 @code{gtroff} supports an extended syntax to specify repeat values after
4628 the @samp{T} mark (these values are always taken as relative) -- this is
4629 the usual way to specify tabs set at equal intervals. The following is,
4630 yet again, the same as the previous examples. It does even more since
4631 it defines an infinite number of tab stops separated by one inch.
4637 Now we are ready to interpret the full syntax given at the beginning:
4638 Set tabs at positions @var{n1}, @var{n2}, @dots{}, @var{nn} and then set
4639 tabs at @var{nn}+@var{r1}, @var{nn}+@var{r2}, @dots{}, @var{nn}+@var{rn}
4640 and then at @var{nn}+@var{rn}+@var{r1}, @var{nn}+@var{rn}+@var{r2},
4641 @dots{}, @var{nn}+@var{rn}+@var{rn}, and so on.
4643 Example: @samp{4c +6c T 3c 5c 2c} is equivalent to @samp{4c 10c 13c 18c
4644 20c 23c 28c 30c @dots{}}.
4646 The material in each tab column (i.e., the column between two tab stops)
4647 may be justified to the right or left or centered in the column. This
4648 is specified by appending @samp{R}, @samp{L}, or @samp{C} to the tab
4649 specifier. The default justification is @samp{L}. Example:
4659 The default unit of the @code{ta} request is @samp{m}.
4662 A tab stop is converted into a non-breakable horizontal movement which
4663 can be neither stretched nor squeezed. For example,
4672 creates a single line which is a bit longer than 10@w{ }inches (a string
4673 is used to show exactly where the tab characters are). Now consider the
4683 @code{gtroff} first converts the tab stops of the line into unbreakable
4684 horizontal movements, then splits the line after the second @samp{b}
4685 (assuming a sufficiently short line length). Usually, this isn't what
4689 Superfluous tabs (i.e., tab characters which do not correspond to a tab
4690 stop) are ignored except the first one which delimits the characters
4691 belonging to the last tab stop for right-justifying or centering.
4692 Consider the following example
4696 .ds ZZ foo\tbar\tfoobar
4697 .ds ZZZ foo\tbar\tfoo\tbar
4708 which produces the following output:
4717 The first line right-justifies the second `foo' relative to the tab
4718 stop. The second line right-justifies `foobar'. The third line finally
4719 right-justifies only `foo' because of the additional tab character which
4720 marks the end of the string belonging to the last defined tab stop.
4723 Tab stops are associated with the current environment
4724 (@pxref{Environments}).
4727 Calling @code{ta} without an argument removes all tab stops.
4730 @cindex tab stops, in nroff mode
4731 The start-up value of @code{gtroff} is @w{@samp{T 0.5i}}. This value is
4732 used even in nroff mode (contrary to @acronym{UNIX} @code{nroff} which
4733 has tab stops preset every 0.8@dmn{i}).
4736 @cindex current tab settings register
4737 The read-only number register @code{.tabs} contains a string
4738 representation of the current tab settings suitable for use as an
4739 argument to the @code{ta} request.
4742 .ds tab-string \n[.tabs]
4748 @cindex tab repetition character
4749 @cindex character, tab repetition
4750 @Defreq {tc, [@Var{fill-char}]}
4751 Normally @code{gtroff} fills the space to the next tab stop with
4752 whitespace. This can be changed with the @code{tc} request. With no
4753 argument @code{gtroff} reverts to using whitespace, which is the default.
4754 The value of this @dfn{tab repetition} character is associated with the
4755 current environment (@pxref{Environments}).
4763 @c ---------------------------------------------------------------------
4765 @node Leaders, Fields, Tabs and Fields, Tabs and Fields
4769 Sometimes it may may be desirable to use the @code{tc} request to fill a
4770 particular tab stop with a given character (for example dots in a table
4771 of contents), but also normal tab stops on the rest of the line. For
4772 this @code{gtroff} provides an alternate tab mechanism, called
4773 @dfn{leaders} which does just that.
4775 @cindex leader character
4776 A leader character (character code@w{ }1) behaves similarly to a tab
4777 character: It moves to the next tab stop. The only difference is that
4778 for this movement, the fill character defaults to a period character and
4782 This escape is a non-interpreted leader character. In copy mode
4783 (@pxref{Copy-in Mode}), @code{\a} is the same as a real leader
4787 @cindex leader repetition character
4788 @cindex character, leader repetition
4789 @Defreq {lc, [@Var{fill-char}]}
4790 Declares the leader character.
4791 Without an argument, leaders act the same as tabs (i.e.,
4792 using whitespace for filling). @code{gtroff}'s start-up value is @samp{.}.
4793 The value of this @dfn{leader repetition} character is associated with
4794 the current environment (@pxref{Environments}).
4797 @cindex table of contents
4798 @cindex contents, table of
4799 For a table of contents, to name an example, tab stops may be defined so
4800 that the section number is one tab stop, the title is the second with
4801 the remaining space being filled with a line of dots, and then the page
4802 number slightly separated from the dots.
4805 .ds entry 1.1\tFoo\a\t12
4815 1.1 Foo.......................................... 12
4818 @c ---------------------------------------------------------------------
4820 @node Fields, , Leaders, Tabs and Fields
4824 @cindex field delimiting character
4825 @cindex delimiting character for fields
4826 @cindex character, field delimiting
4827 @cindex field padding character
4828 @cindex padding character for fields
4829 @cindex character, field padding
4830 @dfn{Fields} are a more general way of laying out tabular data. A field
4831 is defined as the data between a pair of @dfn{delimiting characters}.
4832 It contains substrings which are separated by @dfn{padding characters}.
4833 The width of a field is the distance on the @emph{input} line from the
4834 position where the field starts to the next tab stop. A padding
4835 character inserts stretchable space similar to @TeX{}'s @code{\hss}
4836 command (thus it can even be negative) to make the sum of all substring
4837 lengths plus the stretchable space equal to the field width. If more
4838 than one padding character is inserted, the available space is evenly
4839 distributed among them.
4841 @Defreq {fc, [@Var{delim-char} [@Var{padding-char}]]}
4842 Define a delimiting and a padding character for fields. If the latter
4843 is missing, the padding character defaults to a space character. If
4844 there is no argument at all, the field mechanism is disabled (which is
4845 the default). Note that contrary to e.g.@: the tab repetition
4846 character, delimiting and padding characters are not associated to the
4847 current environment (@pxref{Environments}).
4860 and here the result:
4869 @c =====================================================================
4871 @node Character Translations, Troff and Nroff Mode, Tabs and Fields, Programming Tutorial
4872 @section Character Translations
4873 @cindex character translations
4874 @cindex translations of characters
4878 @cindex control character
4879 @cindex character, control
4880 @cindex no-break control character
4881 @cindex character, no-break control
4882 @cindex control character, no-break
4883 The control character (@samp{.}) and the no-break control character
4884 (@samp{'}) can be changed with the @code{cc} and @code{c2} requests,
4887 @Defreq {cc, [@Var{c}]}
4888 Set the control character to @var{c}. With no argument the default
4889 control character @samp{.} is restored. The value of the control
4890 character is associated with the current environment
4891 (@pxref{Environments}).
4894 @Defreq {c2, [@Var{c}]}
4895 Set the no-break control character to @var{c}. With no argument the
4896 default control character @samp{'} is restored. The value of the
4897 no-break control character is associated with the current environment
4898 (@pxref{Environments}).
4903 Disable the escape mechanism completely. After executing this request,
4904 the backslash character @samp{\} no longer starts an escape sequence.
4906 This request can be very helpful in writing macros since it is not
4907 necessary then to double the escape character. Here an example:
4910 .\" This is a simplified version of the
4911 .\" .BR request from the man macro package
4915 . while (\n[.$] >= 2) \@{\
4916 . as result \fB\$1\fR\$2
4919 . if \n[.$] .as result \fB\$1
4927 @cindex escape character
4928 @cindex character, escape
4929 @Defreq {ec, [@Var{c}]}
4930 Set the escape character to @var{c}. With no argument the default
4931 escape character @samp{\} is restored. It can be also used to re-enable
4932 the escape mechanism after an @code{eo} request.
4934 Note that changing the escape character globally will likely break macro
4935 packages since @code{gtroff} has no mechanism (like @TeX{}) to `intern'
4936 macros, i.e., to convert a macro definition into an internal form which
4937 is independent of its representation. If a macro is called, it is
4942 This escape sequence prints the current escape character (which is the
4943 backslash character @samp{\} by default).
4946 A @dfn{translation} is a mapping of an input character to an output
4947 character. The default mappings are given in the font definition files
4948 for the specific output device (@pxref{Font Files}); all mappings (both
4949 with @code{tr} and in the font definition files) occur at output time,
4950 i.e., the input character gets assigned the metric information of the
4951 mapped output character.
4953 @Defreq {tr, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
4954 Translate character @var{a} to @var{b}, character @var{c} to @var{d},
4955 etc. If there is an odd number of arguments, the last one is
4956 translated to the space character.
4971 @cindex special character
4972 @cindex character, special
4973 @cindex numbered character
4974 @cindex character, numbered
4975 Special characters (@code{\(@var{xx}}, @code{\[@var{xxx}]},
4976 @code{\C'@var{xxx}'}, @code{\'}, @code{\`}, @code{\-}, @code{\_}),
4977 characters defined with the @code{char} request, and numbered characters
4978 (@code{\N'@var{xxx}'}) can be translated also.
4982 The @code{\e} escape can be translated also.
4987 Characters can be mapped onto the @code{\%} and @code{\~} escapes (but
4988 @code{\%} and @code{\~} can't be mapped onto another character).
4991 @cindex backspace character
4992 @cindex character, backspace
4993 @cindex leader character
4994 @cindex character, leader
4995 @cindex newline character
4996 @cindex character, newline
4997 @cindex tab character
4998 @cindex character, tab
5001 The following characters can't be translated: space (with one exception,
5002 see below), backspace, newline, leader (and @code{\a}), tab (and
5007 Translations are not considered for finding the soft hyphen character
5008 set with the @code{shc} request.
5012 The character pair @samp{@var{c}\&} (this is an arbitrary character@w{
5013 }@var{c} followed by the zero width space character) maps this
5014 character to nothing.
5023 It is even possible to map the space character to nothing:
5032 As shown in the example, the space character can't be the first
5033 character pair as an argument of @code{tr}. Additionally, it is not
5034 possible to map the space character to any other character; requests
5035 like @w{@samp{.tr aa x}} undo @w{@samp{.tr aa \&}} instead.
5037 If justification is active, lines are justified in spite of the
5038 `empty' space character (but there is no minimal distance, i.e.@: the
5039 space character, between words).
5042 After an output character has been constructed (this happens at the
5043 moment immediately before the character is appended to an output
5044 character list, either by direct output, in a macro, diversion, or
5045 string), it is no longer affected by @code{tr}.
5050 Without an argument, the @code{tr} request is ignored.
5055 @cindex @code{\!}, and @code{trnt}
5056 @Defreq {trnt, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}}
5057 @code{trnt} is the same as the @code{tr} request except that the
5058 translations do not apply to text that is transparently throughput into
5059 a diversion with @code{\!}. @xref{Diversions}, for more information.
5072 prints @samp{b}; if @code{trnt} is used instead of @code{tr} it
5077 @c =====================================================================
5079 @node Troff and Nroff Mode, Line Layout, Character Translations, Programming Tutorial
5080 @section Troff and Nroff Mode
5086 Originally, @code{nroff} and @code{troff} were two separate programs,
5087 the former for tty output, the latter for everything else. With GNU
5088 @code{troff}, both programs are merged into one executable.
5090 Usually, a macro package can be used with both @code{nroff} and
5091 @code{troff}. Nevertheless, it is sometimes necessary to make a
5092 distinction between the two programs (modes), and @code{gtroff}
5093 provides two built-in conditions @samp{n} and @samp{t} for the
5094 @code{if}, @code{ie}, and @code{while} requests to decide whether
5095 @code{gtroff} shall behave like @code{nroff} or like @code{troff}.
5100 Make the @samp{t} built-in condition true (and the @samp{n} built-in
5101 condition false) for @code{if}, @code{ie}, and @code{while} conditional
5102 requests. This is the default if @code{gtroff} (@emph{not}
5103 @code{groff}) is started with the @option{-R} switch to avoid loading of
5104 the start-up files @file{troffrc} and @file{troffrc-end}. Without
5105 @option{-R}, @code{gtroff} stays in troff mode if the output device is
5106 not a tty (e.g.@: `ps').
5111 Make the @samp{n} built-in condition true (and the @samp{t} built-in
5112 condition false) for @code{if}, @code{ie}, and @code{while} conditional
5113 requests. This is the default if @code{gtroff} uses a tty output
5114 device; the code for switching to nroff mode is in the file
5115 @file{tty.tmac} which is loaded by the start-up file
5119 @xref{Conditionals and Loops}, for more details on built-in conditions.
5122 @c =====================================================================
5124 @node Line Layout, Page Layout, Troff and Nroff Mode, Programming Tutorial
5125 @section Line Layout
5127 @cindex layout, line
5129 @cindex dimensions, line
5130 @cindex line dimensions
5131 The following drawing shows the dimensions which @code{gtroff} uses for
5132 placing a line of output onto the page. They are labeled with the
5133 request which manipulates each dimension.
5137 |<-----------ll------------>|
5138 +----+----+----------------------+----+
5140 +----+----+----------------------+----+
5142 |<--------paper width---------------->|
5146 These dimensions are:
5151 @cindex margin, left
5153 @cindex offset, page
5154 @dfn{Page offset} -- this is the leftmost position of text on the final
5155 output, defining the @dfn{left margin}.
5159 @cindex line indentation
5160 @dfn{Indentation} -- this is the distance from the left margin where
5165 @cindex length of line
5166 @dfn{Line length} -- this is the distance from the left margin to right
5170 @c XXX improve example
5175 A bunch of really boring text which should
5176 be indented from both margins.
5177 Replace me with a better (and more) example!
5186 @Defreq {po, [@Var{offset}]}
5187 @Defreqx {po, @t{+}@Var{offset}}
5188 @Defreqx {po, @t{-}@Var{offset}}
5190 Set horizontal page offset to @var{offset} (or increment or
5191 decrement the current value by @var{offset}). Note that this request
5192 does not cause a break, so changing the page offset in the middle of
5193 text being filled may not yield the expected result. The initial value
5194 is 1@dmn{i} if in troff mode, and 0 if in nroff mode (@pxref{Troff and
5195 Nroff Mode}); the default scaling indicator is@w{ }@code{m} (and not@w{
5196 }@code{v} as incorrectly documented in the original @acronym{UNIX} troff
5199 The current page offset can be found in the read-only number register
5202 If @code{po} is called without an argument, the page offset is reset to
5203 the previous value before the last call to @code{po}.
5218 @Defreq {in, [@Var{indent}]}
5219 @Defreqx {in, @t{+}@Var{indent}}
5220 @Defreqx {in, @t{-}@Var{indent}}
5222 Set indentation to @var{indent} (or increment or decrement the
5223 current value by @var{indent}). This request causes a break.
5224 Initially, there is no indentation.
5226 If @code{in} is called without an argument, the indentation is reset to
5227 the previous value before the last call to @code{in}. The default
5228 scaling indicator is@w{ }@code{m}.
5230 The indentation is associated with the current environment.
5232 If a negative indentation value is specified (which is not allowed),
5233 @code{gtroff} emits a warning of type @samp{range} and sets the
5234 indentation to zero.
5236 The effect of @code{in} is delayed until a partially collected line (if
5237 it exists) is output. A temporary indent value is reset to zero also.
5239 The current indentation (as set by @code{in}) can be found in the
5240 read-only number register @samp{.i}.
5243 @Defreq {ti, offset}
5244 @Defreqx {ti, @t{+}@Var{offset}}
5245 @Defreqx {ti, @t{-}@Var{offset}}
5247 Temporarily indent the next output line by @var{offset}. If an
5248 increment or decrement value is specified, adjust the temporary
5249 indentation relative to the value set by the @code{in} request.
5251 This request causes a break; its value is associated with the current
5252 environment. The default scaling indicator is@w{ }@code{m}. A call of
5253 @code{ti} without an argument is ignored.
5255 If the total indentation value is negative (which is not allowed),
5256 @code{gtroff} emits a warning of type @samp{range} and sets the
5257 temporary indentation to zero. `Total indentation' is either
5258 @var{offset} if specified as an absolute value, or the temporary plus
5259 normal indentation, if @var{offset} is given as a relative value.
5261 The effect of @code{ti} is delayed until a partially collected line (if
5262 it exists) is output.
5264 The read-only number register @code{.in} is the indentation that applies
5265 to the current output line.
5267 The difference between @code{.i} and @code{.in} is that the latter takes
5268 into account whether a partially collected line still uses the old
5269 indentation value or a temporary indentation value is active.
5272 @Defreq {ll, [@Var{length}]}
5273 @Defreqx {ll, @t{+}@Var{length}}
5274 @Defreqx {ll, @t{-}@Var{length}}
5277 Set the line length to @var{length} (or increment or decrement the
5278 current value by @var{length}). Initially, the line length is set to
5279 6.5@dmn{i}. The effect of @code{ll} is delayed until a partially
5280 collected line (if it exists) is output. The default scaling indicator
5283 If @code{ll} is called without an argument, the line length is reset to
5284 the previous value before the last call to @code{ll}. If a negative
5285 line length is specified (which is not allowed), @code{gtroff} emits a
5286 warning of type @samp{range} and sets the line length to zero.
5288 The line length is associated with the current environment.
5290 @cindex current line length register
5291 The current line length (as set by @code{ll}) can be found in the
5292 read-only number register @samp{.l}. The read-only number register
5293 @code{.ll} is the line length that applies to the current output line.
5295 Similar to @code{.i} and @code{.in}, the difference between @code{.l}
5296 and @code{.ll} is that the latter takes into account whether a partially
5297 collected line still uses the old line length value.
5301 @c =====================================================================
5303 @node Page Layout, Page Control, Line Layout, Programming Tutorial
5304 @section Page Layout
5306 @cindex layout, page
5308 @code{gtroff} provides some very primitive operations for controlling
5312 @cindex length of page
5313 @Defreq {pl, [@Var{length}]}
5314 @Defreqx {pl, @t{+}@Var{length}}
5315 @Defreqx {pl, @t{-}@Var{length}}
5317 Set the @dfn{page length} to @var{length} (or increment or decrement the
5318 current value by @var{length}). This is the length of the physical
5319 output page. The default scaling indicator is@w{ }@code{v}.
5321 @cindex current page length register
5322 The current setting can be found in the read-only number register
5327 @cindex bottom margin
5328 @cindex margin, bottom
5329 Note that this only specifies the size of the page, not the top and
5330 bottom margins. Those are not set by @code{gtroff} directly.
5331 @xref{Traps}, for further information on how to do this.
5333 Negative @code{pl} values are possible also, but not very useful: No
5334 trap is sprung, and each line is output on a single page (thus
5335 suppressing all vertical spacing).
5337 If no argument or an invalid argument is given, @code{pl} sets the page
5338 length to 11@dmn{i}.
5344 @code{gtroff} provides several operations which help in setting up top
5345 and bottom titles (or headers and footers).
5348 @cindex three-part title
5349 @cindex page number character
5350 @Defreq {tl, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}}
5351 The @code{tl} request prints a @dfn{title line}, which consists of three
5352 parts: a left justified portion, a centered portion, and a right
5353 justified portion. The argument separator @samp{'} can be replaced with
5354 any character not occurring in the title line. The @samp{%} character
5355 is replaced with the current page number. This character can be changed
5356 with the @code{pc} request (see below).
5358 Without argument, @code{tl} is ignored.
5364 A title line is not restricted to the top or bottom of a page.
5367 @code{tl} prints the title line immediately, ignoring a partially filled
5368 line (which stays untouched).
5371 It is not an error to omit closing delimiters. For example,
5372 @w{@samp{.tl /foo}} is equivalent to @w{@samp{.tl /foo///}}: It prints a
5373 title line with the left justified word @samp{foo}; the centered and
5374 right justfied parts are empty.
5377 Any modifications to the current environment within @code{tl} (e.g.@:
5378 changing the font or font size) are undone after processing @code{tl}.
5381 @code{tl} accepts the same parameter delimiting characters as the
5382 @code{\A} escape; see @ref{Escapes}.
5387 @cindex length of title line
5388 @cindex title line, length
5389 @cindex current title line length register
5390 @Defreq {lt, [@Var{length}]}
5391 @Defreqx {lt, @t{+}@Var{length}}
5392 @Defreqx {lt, @t{-}@Var{length}}
5394 The title line is printed using its own line length, which is specified
5395 (or incremented or decremented) with the @code{lt} request. Initially,
5396 the title line length is set to 6.5@dmn{i}. If a negative line length
5397 is specified (which is not allowed), @code{gtroff} emits a warning of
5398 type @samp{range} and sets the title line length to zero. The default
5399 scaling indicator is@w{ }@code{m}. If @code{lt} is called without an
5400 argument, the title length is reset to the previous value before the
5401 last call to @code{lt}.
5403 The current setting of this is available in the @code{.lt} read-only
5408 @cindex number, page
5411 The @code{pn} request changes the page number of the @emph{next}
5412 page. The only argument is the page number; the request is ignored
5413 without a parameter.
5415 The read-only number register @code{.pn} contains the number of the next
5416 page: either the value set by a @code{pn} request, or the number of the
5417 current page plus@w{ }1.
5420 @cindex current page number register
5422 A read-write register holding the current page number.
5425 @cindex changing the page number character
5426 @cindex page number character, changing
5428 @Defreq {pc, [@Var{char}]}
5429 The @code{pc} request changes the page number character (used by the
5430 @code{tl} request) to a different character. With no argument, this
5431 mechanism is disabled. Note that this doesn't affect the number
5438 @c =====================================================================
5440 @node Page Control, Fonts, Page Layout, Programming Tutorial
5441 @section Page Control
5442 @cindex page control
5443 @cindex control, page
5447 @Defreq {bp, [@Var{page}]}
5448 To stop processing the current page, and move to the next page, invoke
5449 @code{bp}. This request causes a break. It can also take an argument
5450 of what the next page should be numbered. The only difference between
5451 @code{bp} and @code{pn} is that @code{pn} does not cause a break or
5452 actually eject a page.
5455 .de newpage \" define macro
5457 'sp .5i \" vertical space
5458 .tl 'left top'center top'right top' \" title
5459 'sp .3i \" vertical space
5466 It is often necessary to force a certain amount of space before a new
5467 page occurs. This is most useful to make sure that there is not a
5468 single @dfn{orphan} line left at the bottom of a page. The @code{ne}
5469 request ensures that there is a certain distance, specified by the first
5470 argument, before the next page is triggered (see @ref{Traps}, for
5471 further information). The default unit for @code{ne} is @code{v} and
5472 the default argument is@w{ }1@dmn{v}.
5474 For example, to make sure that no fewer than 2@w{ }lines get orphaned,
5475 do the following before each paragraph:
5487 @code{sv} is similar to the @code{ne} request; it reserves the specified
5488 amount of vertical space. If the desired amount of space exists before
5489 the next trap (bottom page boundary), the space is output
5490 immediately. If there is not enough space, it is stored for later
5491 output via the @code{os} request. The default argument is@w{ }1@dmn{v}
5492 and the default unit is @code{v}.
5496 @c =====================================================================
5498 @node Fonts, Sizes, Page Control, Programming Tutorial
5502 @code{gtroff} can switch fonts at any point in the text.
5505 @Defescx {\\f, ', font, '}
5506 The @code{ft} request and the @code{\f} escape change the
5507 current font to @samp{font}.
5509 Fonts are generally specified as upper-case strings, which are usually
5510 1@w{ }to 4 characters representing an abbreviation or acronym of the font
5513 The basic set of fonts are @samp{R}, @samp{I}, @samp{B}, and @samp{BI}.
5514 These are Times Roman, Italic, Bold, and Bold Italic. There is also at
5515 least one symbol font which contains various special symbols (Greek,
5516 mathematics). Such symbols fonts cannot be used directly, but should be
5518 @c XXX should we list PostScript fonts here too?
5526 * Artificial Fonts::
5527 * Ligatures and Kerning::
5530 @c ---------------------------------------------------------------------
5532 @node Changing Fonts, Font Families, Fonts, Fonts
5533 @subsection Changing Fonts
5534 @cindex changing fonts
5535 @cindex fonts, changing
5538 @cindex previous font
5539 @cindex font, previous
5540 Use the @code{ft} request or the @code{\f} request to change fonts.
5541 With no arguments, @code{.ft} switches to the previous
5542 font (use @code{\fP} to do this with an escape).
5553 Use the @code{\f} escape to change fonts in the middle of
5557 eggs, bacon, \fBspam\fP and sausage.
5561 Both of the above examples produce the same output. Note the usage
5562 of @samp{P} to indicate the previous font -- this cannot be omitted
5565 Sometimes, when typesetting letters of different fonts, more or less space at
5566 such boundaries are needed. There are two escapes to help with this.
5568 @cindex italic correction
5569 @cindex correction, italic
5571 The @code{\/} escape increases the width of the preceding character so
5572 that the spacing between that character and the following character is
5573 correct if the following character is a Roman character. For
5574 example, if an italic@w{ }f is immediately followed by a Roman right
5575 parenthesis, then in many fonts the top right portion of the @code{f}
5576 overlaps the top left of the right parenthesis. Use
5577 this escape sequence whenever an italic character is immediately
5578 followed by a Roman character without any intervening space. This small
5579 amount of space is also called @dfn{italic correction}.
5582 @c producing @i{f}), which is ugly. Inserting \/ produces f) and avoids
5586 @cindex left italic correction
5587 @cindex correction, left italic
5588 @Defesc {\\\,, , , }
5589 The @code{\,} escape modifies the spacing of the following character so
5590 that the spacing between that character and the preceding character is
5591 correct if the preceding character is a Roman character.
5592 Use this escape sequence whenever a Roman character is
5593 immediately followed by an italic character without any intervening
5594 space. In analogy to above, this space could be called @dfn{left italic
5595 correction}, but this term isn't used widely.
5598 @c For example, inserting \, between the parenthesis and the f changes
5613 The @code{ftr} request translates fonts; its syntax is
5616 .ftr @var{F} @var{G}
5620 which translates font@w{ }@var{F} to font@w{ }@var{G}. Whenever a font
5621 named @var{F} is referred to in a @code{\f} escape sequence, or in the
5622 @code{ft}, @code{ul}, @code{bd}, @code{cs}, @code{tkf}, @code{special},
5623 @code{fspecial}, @code{fp}, or @code{code} requests, font@w{ }@var{G}
5624 is used. If @var{G} is missing, or equal to @var{F} then font@w{
5625 }@var{F} is not translated.
5628 @c ---------------------------------------------------------------------
5630 @node Font Families, Font Positions, Changing Fonts, Fonts
5631 @subsection Font Families
5632 @cindex font families
5633 @cindex families, font
5635 Due to the variety of fonts available, @code{gtroff} has added the
5636 concept of font families. Each of these families has four styles
5637 (@samp{R}, @samp{I}, @samp{B} and @samp{BI}).
5639 The fonts are specified as the concatenation of the font family and
5640 style. Specifying a font without the family part causes
5641 @code{gtroff} to use that style of the current family. By default,
5642 @code{gtroff} uses the Times family.
5644 This way, it is possible to use the basic four fonts and to select a
5645 different font family on the command line.
5647 @Defreq {fam, family}
5649 Switch font families with the @code{fam} request. The current font
5650 family is available in the read-only number register @code{.fam}. This
5651 is a string-valued register.
5668 @c ---------------------------------------------------------------------
5670 @node Font Positions, Using Symbols, Font Families, Fonts
5671 @subsection Font Positions
5672 @cindex font positions
5673 @cindex positions, font
5675 For the sake of old phototypesetters and compatability with old versions
5676 of @code{troff}, @code{gtroff} has the concept of font @dfn{positions},
5677 on which various fonts are mounted. The last one or two are reserved
5678 for the symbol font(s).
5680 @Defreq {fp, pos font [@Var{external-name}]}
5683 New fonts can be mounted with the @code{fp} request. These numeric
5684 positions can then be referred to with font changing commands. When
5685 @code{gtroff} starts it is using font number one.
5701 Note that after these font changes have taken place, the original font
5704 @cindex current font position register
5705 The current font in use, as a font position, is available in the
5706 read-only number register @code{.f}. This can be useful to remember the
5707 current font, for later recall.
5711 ... lots 'o text ...
5715 @cindex next free font position register
5716 The number of the next free font position is available in the read-only
5717 number register @code{.fp}. This is useful when mounting a new font,
5721 .fp \n[.fp] NEATOFONT
5724 @pindex DESC@r{, and font mounting}
5725 Fonts not listed in the @file{DESC} file are automatically mounted on
5726 the next available font position when they are referenced. If a font is
5727 to be mounted explicitly with the @code{fp} request on an unused font
5728 position, it should be mounted on the first unused font position, which
5729 can be found in the @code{.fp} register. Although @code{gtroff} does
5730 not enforce this strictly, it does not allow a font to be mounted at a
5731 position whose number is much greater than that of any currently used
5735 The @code{fp} request has an optional third argument. This argument
5736 gives the external name of the font, which is used for finding the font
5737 description file. The second argument gives the internal name of the
5738 font which is used to refer to the font in @code{gtroff} after it has
5739 been mounted. If there is no third argument then the internal name is
5740 used as the external name. This feature makes it possible to use
5741 fonts with long names in compatibility mode.
5744 @c ---------------------------------------------------------------------
5746 @node Using Symbols, Artificial Fonts, Font Positions, Fonts
5747 @subsection Using Symbols
5748 @cindex using symbols
5749 @cindex symbols, using
5753 Symbols can be inserted by using a special escape sequence. This escape
5754 is simply the escape character (usually a backslash) followed by an
5755 identifier. The symbol identifiers have to be two or more characters,
5756 since single characters conflict with all the other escapes. The
5757 identifier can be either preceded by a parenthesis if it is two
5758 characters long, or surrounded by square brackets. So, the symbol for
5759 the mathematical Greek letter `pi' can be produced either by @code{\(*p}
5763 area = \(*p\fIr\fP\u2\d
5766 @Defesc {\\C, ', xxx, '}
5767 The escape @code{\C'@var{xxx}'} typesets the character named
5768 @var{xxx}. Normally it is more convenient to use @code{\[@var{xxx}]}.
5769 But @code{\C} has the advantage that it is compatible with recent
5770 versions of @code{ditroff} and is available in compatibility mode.
5774 @Defesc {\\N, ', n, '}
5775 The escape @code{\N'@var{n}'} typesets the character with code@w{
5776 }@var{n} in the current font. @var{n} can be any integer. Most devices
5777 only have characters with codes between 0 and@w{ }255. If the current
5778 font does not contain a character with that code, special fonts are
5779 @emph{not} searched. The @code{\N} escape sequence can be
5780 conveniently used in conjunction with the @code{char} request:
5783 .char \[phone] \f(ZD\N'37'
5789 @cindex unnamed characters
5790 @cindex characters, unnamed
5791 The code of each character is given in the fourth column in the font
5792 description file after the charset command. It is possible to include
5793 unnamed characters in the font description file by using a name of
5794 @samp{---}; the @code{\N} escape sequence is the only way to use these.
5796 @c XXX should be `glyph', not `character'
5799 @cindex character properties
5800 @cindex properties of characters
5801 Each character has certain properties associated with it. These
5802 properties can be modified with the @code{cflags} request. The first
5803 argument is the the sum of the desired flags and the remaining arguments
5804 are the characters to have those properties.
5808 @cindex end of sentence characters
5809 @cindex characters, end of sentence
5810 the character ends sentences (initially characters @samp{.?!} have this
5814 @cindex hyphenating characters
5815 @cindex characters, hyphenation
5816 lines can be broken before the character (initially no characters have
5822 lines can be broken after the character (initially the characters
5823 @samp{-\(hy\(em} have this property)
5826 @cindex overlapping characters
5827 @cindex characters, overlapping
5831 the character overlaps horizontally (initially the characters
5832 @samp{\(ul\(rn\(ru} have this property)
5836 the character overlaps vertically (initially character @samp{\(br} has
5840 @cindex transparent characters
5841 @cindex character, transparent
5849 an end of sentence character followed by any number of characters with
5850 this property is treated as the end of a sentence if followed by a
5851 newline or two spaces; in other words the character is @dfn{transparent}
5852 for the purposes of end of sentence recognition -- this is the same as
5853 having a zero space factor in @TeX{} (initially characters
5854 @samp{"')]*\(dg\(rq} have this property).
5857 @cindex defining characters
5858 @cindex characters, defining
5859 @cindex creating new characters
5860 @Defreq {char, c string}
5861 New characters can be created with the @code{char} request. It is
5865 .char @var{c} @var{string}
5874 This defines character@w{ }@var{c} to be @var{string}. Every time
5875 character@w{ }@var{c} needs to be printed, @var{string} is
5876 processed in a temporary environment and the result is wrapped up
5877 into a single object. Compatibility mode is turned off and the
5878 escape character is set to @samp{\} while @var{string} is being
5879 processed. Any emboldening, constant spacing or track kerning is
5880 applied to this object rather than to individual characters in
5881 @var{string}. A character defined by this request can be used just like
5882 a normal character provided by the output device. In particular other
5883 characters can be translated to it with the @code{tr} request; it can be
5884 made the leader character by the @code{lc} request; repeated patterns
5885 can be drawn with the character using the @code{\l} and @code{\L} escape
5886 sequences; words containing the character can be hyphenated correctly,
5887 if the @code{hcode} request is used to give the character a hyphenation
5888 code. There is a special anti-recursion feature: use of character
5889 within the character's definition is handled like normal characters
5890 not defined with @code{char}.
5893 @cindex removing character definition
5894 @cindex character, removing definition
5895 @Defreq {rchar, def}
5896 A character definition can be removed with the @code{rchar} request.
5897 Its arguments are the characters to be removed. This undoes the effect
5898 of a @code{char} request.
5901 @xref{Special Characters}.
5903 @c ---------------------------------------------------------------------
5905 @node Artificial Fonts, Ligatures and Kerning, Using Symbols, Fonts
5906 @subsection Artificial Fonts
5907 @cindex artificial fonts
5908 @cindex fonts, artificial
5910 There are a number of requests for artificially creating fonts. These
5911 are largely vestiges of the days when output devices did not
5912 have a wide variety of fonts, and when @code{nroff} and @code{troff}
5913 were separate programs. These are no longer necessary in GNU
5918 The @code{ul} request prints subsequent lines in italics on a device
5919 capable of it, or underlines the text on a character output device. The
5920 single argument is the number of lines to be ``underlined,'' with no
5921 argument, the next line is underlined.
5922 The @code{ul} request does not underline spaces.
5925 @cindex continuous underlining
5926 @cindex underlining, continuous
5928 The @code{cu} request is similar to @code{ul}
5929 but underlines spaces as well.
5934 @cindex underline font
5935 @cindex font for underlining
5937 The @code{uf} request sets the underline font used by @code{ul} and
5941 @cindex imitating bold face
5942 @cindex bold face, imitating
5943 @Defreq {bd, font offset}
5944 The @code{bd} request artificially creates a bold font by printing each
5945 character twice, slightly offset. The first argument specifies the font
5946 to embolden, and the second is the number of basic units, minus one, by
5947 which the two characters is offset. If the second argument is
5948 missing, emboldening is turned off.
5951 @c ---------------------------------------------------------------------
5953 @node Ligatures and Kerning, , Artificial Fonts, Fonts
5954 @subsection Ligatures and Kerning
5955 @cindex ligatures and kerning
5956 @cindex kerning and ligatures
5958 Ligatures are groups of characters that are run together.
5959 For example, look at the letters @code{f} and @code{i}
5961 This produces a cleaner look (albeit subtle) to the printed output.
5963 Most PostScript fonts support the fi and fl ligatures.
5964 The C/A/T typesetter that was the target of AT&T @code{troff}
5965 also supported ff, ffi, and ffl ligatures.
5966 Advanced typesetters or "expert" fonts may include ligatures
5967 for ft and ct, although GNU @code{troff} does not support these yet.
5969 @c XXX more info -> nroff mode
5971 @cindex ligatures enabled register
5972 @Defreq {lg, [@Var{flag}]}
5974 The ligature mechanism can be switched on or off with the @code{lg}
5975 request; if the parameter is non-zero or missing, ligatures are enabled,
5976 otherwise disabled. Default is on. The current ligature mode can be
5977 found in the read-only number register @code{.lg} (set to 1 or@w{ }2 if
5978 ligatures are enabled, 0@w{ }otherwise).
5980 Setting the ligature mode to@w{ }2 enables the two-character
5981 ligatures (fi, fl, and ff) and disables the three-character
5982 ligatures (ffi and ffl).
5985 @dfn{Pairwise kerning} is another subtle typesetting mechanism
5986 that moves characters closer together when space permits.
5988 For example, look at the letters @code{T} and @code{a}
5990 The @code{a} is tucked slightly under the @code{T}.
5994 @cindex kerning enabled register
5995 @Defreq {kern, [@Var{flag}]}
5997 @Defescx {\\&, , , }
5998 Kerning can be activated with the @code{kern} request. If the parameter
5999 is non-zero or missing, enable pairwise kerning, otherwise disable it.
6000 The read-only number register @code{.kern} is set to@w{ }1 if pairwise
6001 kerning is enabled, 0@w{ }otherwise.
6003 @cindex zero width space character
6004 @cindex character, zero width space
6005 @cindex space character, zero width
6006 If the font description file contains pairwise kerning information,
6007 characters from that font are kerned. Kerning between two
6008 characters can be inhibited by placing @code{\&} between them.
6012 @cindex track kerning
6013 @cindex kerning, track
6014 Track kerning expands or reduces the space between characters.
6015 This can be handy, for example,
6016 if you need to squeeze a long word onto a single line
6017 or spread some text to fill a narrow column.
6020 Track kerning must be used with great care since it is usually
6021 considered bad typography if the reader notices the effect.
6023 @Defreq {tkf, f s1 n1 s2 n2}
6024 Enable track kerning for font@w{ }@var{f}. If the current font is@w{
6025 }@var{f} the width of every character is increased by an amount
6026 between @var{n1} and @var{n2}; if the current point size is less than or
6027 equal to @var{s1} the width is increased by @var{n1}; if it is
6028 greater than or equal to @var{s2} the width is increased by
6029 @var{n2}; if the point size is greater than or equal to @var{s1} and
6030 less than or equal to @var{s2} the increase in width is a linear
6031 function of the point size.
6032 @c XXX can n1 or n2 be negative?
6036 @c =====================================================================
6038 @node Sizes, Strings, Fonts, Programming Tutorial
6044 @cindex size of type
6045 @cindex vertical spacing
6046 @cindex spacing, vertical
6047 @code{gtroff} uses two dimensions with each line of text, type size and
6048 vertical spacing. The @dfn{type size} is the height from the text
6049 @dfn{baseline} to the top of the tallest character (descenders may drop
6050 below this baseline). @dfn{Vertical spacing} is the amount of space
6051 @code{gtroff} allows for a line of text; normally, this is about 20%@w{
6052 }larger than the current type size. Ratios smaller than this can result
6053 in hard-to-read text; larger than this, it spreads the text out more
6054 vertically (useful for term papers). By default, @code{gtroff} uses
6055 10@w{ }point type on 12@w{ }point spacing.
6058 The difference between type size and vertical spacing is known, by
6059 typesetters, as @dfn{leading}.
6062 * Changing Type Sizes::
6063 * Fractional Type Sizes::
6066 @c ---------------------------------------------------------------------
6068 @node Changing Type Sizes, Fractional Type Sizes, Sizes, Sizes
6069 @subsection Changing Type Sizes
6070 @cindex changing type sizes
6071 @cindex type sizes, changing
6073 @Defreq {ps, [@Var{size}]}
6074 @Defescx {\\s, , size, }
6076 Use the @code{ps} request or the @code{\s} escape to change the type
6077 size (in points). Specify the @var{size} as either an absolute point
6078 size, or as a relative change from the current size. The size@w{ }0, or
6079 no argument, goes back to the previous size.
6081 The read-only number register @code{.s} returns the point size in points
6082 as a decimal fraction.
6089 wink, wink, \s+2nudge, nudge,\s+8 say no more!
6093 The @code{\s} escape may be called in a variety of ways. Much like
6094 other escapes there must be a way to determine where the argument ends
6095 and the text begins. Any of the following forms are valid:
6099 Set the point size to @var{n}@w{ }points. @var{n}@w{ }must be either 0
6100 or in the range 4 to@w{ }39.
6104 Increase or decrease the point size by @var{n}@w{ }points.
6105 @var{n}@w{ }must be exactly one digit.
6108 Set the point size to @var{nn}@w{ }points. @var{nn} must be exactly two
6115 Increase or decrease the point size by @var{nn}@w{ }points.
6116 @var{nn} must be exactly two digits.
6119 @xref{Fractional Type Sizes}, for yet another syntactical form of using
6120 the @code{\s} escape.
6122 Some devices may only have certain permissible sizes, in which case
6123 @code{gtroff} rounds to the nearest permissible size.
6126 @cindex current type size register
6127 @cindex current vertical spacing register
6130 Changes the vertical spacing. The default unit is points.
6132 The read-only number register @code{.v} contains the current vertical
6140 ... .sz macro example?? ...
6144 @c ---------------------------------------------------------------------
6146 @node Fractional Type Sizes, , Changing Type Sizes, Sizes
6147 @subsection Fractional Type Sizes
6148 @cindex fractional type sizes
6149 @cindex type sizes, fractional
6151 @cindex @code{s} unit
6152 @cindex unit, @code{s}
6153 @cindex @code{z} unit
6154 @cindex unit, @code{z}
6160 A @dfn{scaled point} is equal to 1/@var{sizescale} points, where
6161 @var{sizescale} is specified in the @file{DESC} file (1@w{ }by default.)
6162 There is a new scale indicator @samp{z} which has the effect of
6163 multiplying by @var{sizescale}. Requests and escape sequences in
6164 @code{gtroff} interpret arguments that represent a point size as being
6165 in units of scaled points, but they evaluate each such argument using a
6166 default scale indicator of @samp{z}. Arguments treated in this way are
6167 the argument to the @code{ps} request, the third argument to the
6168 @code{cs} request, the second and fourth arguments to the @code{tkf}
6169 request, the argument to the @code{\H} escape sequence, and those
6170 variants of the @code{\s} escape sequence that take a numeric expression
6171 as their argument (see below).
6173 For example, suppose @var{sizescale} is@w{ }1000; then a scaled point
6174 is equivalent to a millipoint; the request @w{@samp{.ps 10.25}} is
6175 equivalent to @w{@samp{.ps 10.25z}} and thus sets the point size to
6176 10250@w{ }scaled points, which is equal to 10.25@w{ }points.
6178 @code{gtroff} disallows the use of the @samp{z} scale indicator in
6179 instances where it would make no sense, such as a numeric
6180 expression whose default scale indicator was neither @samp{u} nor
6181 @samp{z}. Similarly it would make
6182 no sense to use a scaling indicator other than @samp{z} or @samp{u} in a
6183 numeric expression whose default scale indicator was @samp{z}, and so
6184 @code{gtroff} disallows this as well.
6186 There is also new scale indicator @samp{s} which multiplies by the
6187 number of units in a scaled point. So, for example, @samp{\n[.ps]s} is
6188 equal to @samp{1m}. Be sure not to confuse the @samp{s} and @samp{z}
6193 A read-only number register returning the point size in scaled points.
6196 @cindex last-requested point size register
6199 The last-requested point size in scaled points is contained in the
6200 @code{.psr} read-only number register. The last requested point size in
6201 points as a decimal fraction can be found in @code{.sr}. This is a
6202 string-valued read-only number register.
6205 The @code{\s} escape has the following syntax for working with
6206 fractional type sizes:
6211 Set the point size to @var{n} scaled points; @var{n}@w{ }is a numeric
6212 expression with a default scale indicator of @samp{z}.
6222 Increase or or decrease the point size by @var{n} scaled points;
6223 @var{n} is a numeric expression with a default scale indicator of
6230 @c =====================================================================
6232 @node Strings, Conditionals and Loops, Sizes, Programming Tutorial
6236 @code{gtroff} has string variables, which are entirely for user
6237 convenience (i.e.@: there are no built-in strings).
6239 @Defreq {ds, name string}
6240 @Defescx {\\*, , n, }
6241 @Defescx {\\*, @lparen{}, nm, }
6242 @Defescx {\\*, @lbrack{}, name, @rbrack{}}
6243 Defines and accesses a string variable.
6246 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d
6250 @cindex string interpolation
6251 @cindex string expansion
6252 @cindex interpolation of strings
6253 @cindex expansion of strings
6254 Use the @code{\*} escape to @dfn{interpolate}, or expand in-place,
6255 a previously-defined string variable.
6258 The \*(UX Operating System
6261 If the string named by the @code{\*} does not exist, the escape is
6262 replaced by nothing.
6264 @cindex comments, with @code{ds}
6265 @strong{Caution:} Unlike other requests, the second argument to the
6266 @code{ds} request takes up the entire line including trailing spaces.
6267 This means that comments on a line with such a request can introduce
6268 unwanted space into a string.
6271 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark
6275 Instead the comment should be put on another line or have the comment
6276 escape adjacent with the end of the string.
6279 .ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" UNIX trademark
6282 @cindex trailing quotes
6283 @cindex quotes, trailing
6284 @cindex leading spaces with @code{ds}
6285 @cindex spaces with @code{ds}
6286 To produce leading space the string can be started with a double quote.
6287 No trailing quote is needed; in fact, any trailing quote is included in
6291 .ds sign " Yours in a white wine sauce,
6295 @cindex multi-line strings
6296 @cindex strings, multi-line
6297 @cindex newline character in strings, escaping
6298 @cindex escaping newline characters in strings
6299 Strings are not limited to a single line of text. A string can span
6300 several lines by escaping the newlines with a backslash. The resulting
6301 string is stored @emph{without} the newlines.
6304 .ds foo lots and lots \
6305 of text are on these \
6310 @cindex appending to strings
6311 @cindex strings, appending
6312 @Defreq {as, name string}
6313 The @code{as} request appends a string to another string. It is
6314 similar to the @code{ds} request except that it appends the second
6315 argument onto the string named by the first argument.
6318 .as sign " with shallots, onions and garlic,
6323 @Defreq {substring, xx n1 [@Var{n2}]}
6324 @Defreqx {length, xx string}
6325 Rudimentary string manipulation routines are given with the
6326 @code{substring} and @code{length} requests.
6328 The @code{substring} request replaces the string in register@w{
6329 }@var{xx} with the substring defined by the indices @var{n1} and@w{
6330 }@var{n2}. The first character in the string has index one. If
6331 @var{n2} is omitted, it is taken to be equal to the string's length. If
6332 the index value @var{n1} or @var{n2} is negative or zero, it is counted
6333 from the end of the string, going backwards: The last character has
6334 index@w{ }0, the character before the last character has index@w{
6337 @cindex length of a string
6338 @cindex string, length of
6339 Here the syntax of the @code{length} request:
6341 The @code{length} request
6342 computes the length of @var{string} and returns it in the number
6343 register@w{ }@var{xx} (which is not necessarily defined before).
6346 @cindex rename request
6347 @cindex rename macro
6348 @cindex rename string
6350 Renames the request, macro, or string @var{xx} to @var{yy}.
6353 @cindex remove request
6354 @cindex remove macro
6355 @cindex remove string
6357 Removes the request, macro, or string @var{xx}.
6358 @code{gtroff} treats subsequent invocations as if the
6359 object had never been defined.
6363 @Defreq {als, new old}
6364 Create an alias named @var{new} for the request, string,
6365 macro, or diversion object named @var{old}. The new name and
6366 the old name are exactly equivalent (it is similar to a hard
6367 rather than a soft link). If @var{old} is undefined,
6368 @code{gtroff} generates a warning of type @b{mac} and ignores
6371 The @code{de}, @code{am}, @code{di}, @code{da}, @code{ds},
6372 and @code{as} requests only create a new object if the name
6373 of the macro, diversion or string diversion is currently
6374 undefined or if it is defined to be a request; normally
6375 they modify the value of an existing object.
6379 Remove (chop) the last character from the macro, string,
6380 or diversion named @var{xx}. This is useful for removing
6381 the newline from the end of diversions that are to be
6382 interpolated as strings.
6385 @xref{Identifiers}, and @ref{Comments}.
6388 @c =====================================================================
6390 @node Conditionals and Loops, Writing Macros, Strings, Programming Tutorial
6391 @section Conditionals and Loops
6392 @cindex conditionals and loops
6393 @cindex loops and conditionals
6397 @cindex @code{if}, operators to use with it
6398 @cindex @code{while}, operators to use with it
6399 In @code{if} and @code{while} requests, there are several more operators
6405 True if the current page is even or odd numbered (respectively).
6409 True if the document is being processed in nroff mode.
6413 True if the document is being processed in troff mode.
6415 @item "@var{xxx}"@var{yyy}"
6416 True if the string @var{xxx} is equal to the string @var{yyy}. Other
6417 characters can be used in place of the double quotes.
6418 @c XXX which characters?
6419 @code{gtroff} formats the strings before being compared; for example,
6429 yields ``true''. The resulting motions, character sizes, and fonts
6430 have to match, and not the individual motion, size, and font requests.
6431 Here, @samp{|} and @samp{\fR|\fP} both result in a roman @samp{|}
6432 character with the same point size and at the same location on the
6433 page, so the strings are equal. If @samp{.ft@w{ }I} had been added
6434 before the @samp{.ie}, then the result would be ``false'' because
6435 @samp{|} produces an italic @samp{|} rather than a roman one.
6438 True if there is a number register named @var{xxx}.
6441 True if there is a string, macro, diversion, or request named @var{xxx}.
6445 True if there is a character @var{ch} available; @var{ch} is either an
6446 @acronym{ASCII} character or a special character (@code{\(@var{ch}} or
6447 @code{\[@var{ch}]}); the condition is also true if @var{ch} has
6448 been defined by the @code{char} request.
6458 @c ---------------------------------------------------------------------
6460 @node if-else, while, Conditionals and Loops, Conditionals and Loops
6464 @code{gtroff} has if-then-else constructs like other languages, although
6465 the formatting can be painful.
6467 @Defreq {if, expr anything}
6468 Evaluates the expression @var{expr}, and executes @var{anything} (the
6469 remainder of the line) if @var{expr} evaluates to
6470 non-zero (true). @var{anything} is interpreted as though it was on
6471 a line by itself. @xref{Expressions}, for more info.
6473 Here are some examples:
6476 .if t .ls 2 \" double spacing in troff
6477 .if 0 .ab how'd this happen?
6483 @Defreq {ie, expr anything}
6484 @Defreqx {el, anything}
6485 Use the @code{ie} and @code{el} requests to write an if-then-else.
6486 The first request is the `if' part and the latter is the `else' part.
6489 .ie n .ls 2 \" double spacing in nroff
6490 .el .ls 1 \" single spacing in troff
6494 @c this looks like a bug in makeinfo: you can't have `@{' as an argument
6499 @c @Defesc{\\@@@ {, , , }
6500 @c @Defescx {\\@@@}, , , }
6501 In many cases, an if (or if-else) construct needs to execute
6502 more than one request.
6503 This can be done using the @code{\@{} and @code{\@}}
6504 escapes. The following example shows the possible ways to use these
6505 escapes (note the position of the opening and closing braces).
6522 @c ---------------------------------------------------------------------
6524 @node while, , if-else, Conditionals and Loops
6528 @code{gtroff} provides a looping construct using the @code{while}
6529 request, which is used much like the @code{if} (and related) requests.
6531 @Defreq {while, expr anything}
6532 Evaluates the expression @var{expr}, and repeatedly executes
6533 @var{anything} (the remainder of the line) until @var{expr}
6534 evaluates to 0 or false.
6538 .while (\na<9) \&\n+a,
6543 The preceding example produces:
6546 1, 2, 3, 4, 5, 6, 7, 8, 9, 10
6549 @cindex zero width space character
6550 @cindex character, zero width space
6551 @cindex space character, zero width
6554 Note the usage of the @code{\&} escape to avoid a control character at
6555 the beginning of a line.
6559 @cindex @code{break}, in a @code{while} loop
6560 @cindex @code{continue}, in a @code{while} loop
6562 @dfn{break} out of a while loop. Be sure
6563 not to confuse this with the @code{br} request (causing a line break).
6566 @Defreq {continue, }
6567 Finishes the current iteration of a while
6568 loop, immediately restarting the next iteration.
6574 @c =====================================================================
6576 @node Writing Macros, Page Motions, Conditionals and Loops, Programming Tutorial
6577 @section Writing Macros
6578 @cindex writing macros
6579 @cindex macros, writing
6581 A @dfn{macro} is a collection of text and embedded commands which can be
6582 invoked multiple times. Use macros to define common operations.
6584 @Defreq {de, name [@Var{end}]}
6585 Defines a new macro named @var{name}. @code{gtroff} copies
6586 subsequent lines into an internal buffer until it encounters
6587 the line @code{..} (two dots). The
6588 optional second argument to @code{de} changes this ending token.
6590 Here a small example macro called @samp{P} which causes a break and
6591 inserts some vertical space. It could be used to separate
6601 @c XXX add info about indirect macro calls:
6607 @c test \*[xxx] test
6608 @c => test from xxx test
6610 @c XXX info about common identifier pool for strings and macros.
6613 @cindex appending, to a macro
6615 Works similarly to @code{de} except it appends
6616 onto the macro named @var{xx}. So, to make the previously
6617 defined @samp{P} macro actually do indented instead of block paragraphs,
6618 add the necessary code to the existing macro like
6629 @Defreq {als, new old}
6630 Create an alias named @var{new} for the request, string,
6631 macro, or diversion object named @var{old}. The new name and
6632 the old name are exactly equivalent (it is similar to a hard
6633 rather than a soft link). If @var{old} is undefined,
6634 @code{gtroff} generates a warning of type @b{mac} and ignores
6637 The @code{de}, @code{am}, @code{di}, @code{da}, @code{ds},
6638 and @code{as} requests only create a new object if the name
6639 of the macro, diversion or string diversion is currently
6640 undefined or if it is defined to be a request; normally
6641 they modify the value of an existing object.
6649 @c ---------------------------------------------------------------------
6651 @node Copy-in Mode, Parameters, Writing Macros, Writing Macros
6652 @subsection Copy-in Mode
6653 @cindex copy-in mode
6654 @cindex mode, copy-in
6661 @cindex @code{\n}, when reading text for a macro
6662 @cindex @code{\$}, when reading text for a macro
6663 @cindex @code{\*}, when reading text for a macro
6664 @cindex @code{\\}, when reading text for a macro
6665 @cindex \@key{RET}, when reading text for a macro
6666 When @code{gtroff} reads in the text for a macro or diversion, it copies
6667 the text (including request lines, but excluding escapes) into an
6668 internal buffer. Escapes are converted into an internal form,
6669 except for @code{\n}, @code{\$}, @code{\*}, @code{\\} and
6670 @code{\@key{RET}} which are evaluated and inserted into the text where
6671 the escape was located. This is known as @dfn{copy-in} mode or
6674 What this means is that you can specify when these escapes are to be
6675 evaluated (either at copy-in time or at the time of use) by insulating
6676 the escapes with an extra backslash. Compare this to the @code{\def}
6677 and @code{\edef} commands in @TeX{}.
6679 The following example prints the numbers 20 and@w{ }10:
6691 @c ---------------------------------------------------------------------
6693 @node Parameters, , Copy-in Mode, Writing Macros
6694 @subsection Parameters
6698 The arguments to a macro can be examined using a variety of escapes.
6699 The number of arguments is available in the @code{.$} number register.
6700 Any individual argument can be retrieved with one of the following
6703 @cindex copy-in mode, and macro arguments
6704 @Defesc {\\$, n, , }
6705 @Defescx {\\$, @lparen{}, nn, }
6706 @Defescx {\\$, @lbrack{}, nnn, @rbrack{}}
6707 The escapes @code{\$@var{n}}, @code{\$(@var{nn}} and
6708 @code{\$[@var{nnn}]} retrieve the @var{n}@dmn{th}, @var{nn}@dmn{th} or
6709 @var{nnn}@dmn{th} argument. As usual, the first form only accepts a
6710 single number (larger than zero), the second a two-digit number (larger
6711 or equal to@w{ }10), and the third any positive integer value (larger
6712 than zero). Macros can have an unlimited number of arguments. Note
6713 that due to copy-in mode, use two backslashes on these in actual use to
6714 prevent interpolation until the macro is actually invoked.
6717 @Defreq {shift, [@Var{n}]}
6718 Shifts the arguments 1@w{ }position, or as
6719 many positions as specified by its argument. After executing this
6720 request, argument@w{ }@var{i} becomes argument @var{i}-@var{n};
6721 arguments 1 to@w{ }@var{n} are no longer available. Shifting by
6722 negative amounts is currently undefined.
6725 @Defesc {\\$*, , , }
6726 @Defescx {\\$@@, , , }
6727 In some cases it is convenient to use all of the arguments at once (for
6728 example, to pass the arguments along to another macro). The @code{\$*}
6729 escape concatenates all the arguments separated by spaces. A
6730 similar escape is @code{\$@@}, which concatenates all the
6731 arguments with each surrounded by double quotes, and separated by
6736 @cindex @code{als}, use with @code{\$0}
6737 @Defesc {\\$0, , , }
6738 The name used to invoke the current macro.
6739 The @code{als} request can make a macro have more than one name.
6743 .ie \\n(.$=1 .ds Vl Pre-Release Version
6744 .el .ds Vl Version \\$3, \\$4.
6749 This would be called as
6756 @xref{Request Arguments}.
6759 @c =====================================================================
6761 @node Page Motions, Drawing Requests, Writing Macros, Programming Tutorial
6762 @section Page Motions
6763 @cindex page motions
6764 @cindex motions, page
6766 @cindex @code{sp}, as vertical page motion
6767 @Defreq {sp, [@Var{len}]}
6768 Motions up and down the page can be done with the @code{sp} request.
6769 However, this causes a break so that the actual effect is to move to the
6770 left margin and then to the specified location.
6773 @Defreq {mk, [@Var{reg}]}
6775 The request @code{mk} can be used to mark a location on a page, for
6776 movement to later. This request takes a register name as an argument in
6777 which to store the current page location. With no argument it
6778 stores the location in an internal register. The results of this can be
6779 used later by the @code{rt} or the @code{sp} request. The @code{rt}
6780 request returns @emph{upwards} to the location given in the register
6781 name given as an argument; with no argument it returns to the
6782 location marked with the @code{mk} request.
6787 ... dual column example ...
6792 The following escapes give fine control of movements about the page.
6794 @cindex vertical motion
6795 @cindex motion, vertical
6796 @Defesc {\\v, ', e, '}
6797 The @code{\v'@var{e}'} escape enables arbitrary vertical motion from the
6798 current location on the page. The argument@w{ }@var{e} specifies the
6799 distance to move; positive is downwards and negative upwards. The
6800 default unit for this escape is vertical spaces, @code{v}'s. Beware,
6801 however, that @code{gtroff} continues text processing at the point
6802 where the motion ends, so you should always balance motions
6803 to avoid interference with text processing.
6806 There are some special case escapes for vertical motion.
6810 move upwards@w{ }1@dmn{v}.
6813 move upwards@w{ }.5@dmn{v}.
6816 move down@w{ }.5@dmn{v}.
6819 @cindex inserting horizontal space
6820 @cindex horizontal space
6821 @cindex space, horizontal
6822 @Defesc {\\h, ', e, '}
6823 The @code{\h'@var{e}'} escape provides horizontal motions. The
6824 expression@w{ }@var{e} indicates how far to move: positive is rightwards
6825 and negative leftwards.
6826 @c XXX Is there a default unit for this?
6829 There are a number of special case escapes for horizontal motion:
6833 an unbreakable and unpaddable (i.e.@: not expanded during filling)
6834 space. (Note: This is a backslash followed by a space.)
6837 an unbreakable space that stretches like a normal inter-word space when
6841 a 1/6@dmn{th} em space. Ignored in nroff mode.
6844 a 1/12@dmn{th} em space. Ignored in nroff mode.
6847 a space the size of a digit.
6850 @cindex zero width space character
6851 @cindex character, zero width space
6852 @cindex space character, zero width
6856 Like @code{\&} except that it behaves like a character declared with the
6857 @code{cflags} request to be transparent for the purposes of end of
6858 sentence recognition.
6861 The following string sets the @TeX{} logo:
6864 .ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X
6867 @cindex width escape
6868 @cindex escape, width
6869 @Defesc {\\w, ', text, '}
6870 Used as @code{\w'@var{text}'},
6871 returns the width of the specified @var{text} in basic units.
6872 This allows horizontal movement based on the width of some
6873 arbitrary text (e.g.@: given as an argument to a macro).
6879 ... strlen example ...
6883 Font changes may occur in @var{text} which don't affect current
6886 After use, @code{\w} sets several registers:
6893 The highest and lowest point, respectively, in @var{text}.
6899 Like the @code{st} and @code{sb} registers, but takes account of the
6900 heights and depths of characters.
6904 Defines the kinds of characters occurring in @var{text}:
6908 only short characters, no descenders or tall characters.
6911 at least one descender.
6914 at least one tall character.
6917 at least one each of a descender and a tall character.
6922 The amount of horizontal space (possibly negative) that should be added
6923 to the last character before a subscript.
6927 How far to right of the center of the last character in the @code{\w}
6928 argument, the center of an accent from a Roman font should be placed
6929 over that character.
6933 @Defesc {\\k, ', x, '}
6934 Stores the current horizontal position in register @var{x}.
6935 Use this, for example, to return to the beginning of a string
6936 for highlighting or other decoration.
6940 A read-only number register containing the current horizontal output
6944 @c XXX documentation
6947 @c =====================================================================
6949 @node Drawing Requests, Traps, Page Motions, Programming Tutorial
6950 @section Drawing Requests
6951 @cindex drawing requests
6952 @cindex requests for drawing
6954 @code{gtroff} provides a number of ways to draw lines and other figures
6955 on the page. Used in combination with the page motion commands (see
6956 @ref{Page Motions}, for more info), a wide variety of figures can be
6957 drawn. However, for complex drawings these operations can be quite
6958 cumbersome, and it may be wise to use graphic preprocessors like
6959 @code{gpic} or @code{ggrn}. @xref{gpic}, and @ref{ggrn}, for more
6962 All drawing is done via escapes.
6964 @cindex drawing horizontal lines
6965 @cindex horizontal line, drawing
6966 @cindex line, horizontal, drawing
6967 @Defesc {\\l, ', l c, '}
6968 Draws a line rightwards from the current
6969 location. The full syntax for this escape is:
6976 where @var{l} is the length of the line to be drawn, starting at the
6977 current location; positive numbers draw to the right, and negative
6978 numbers draw towards the left. This can also be specified absolutely
6979 (i.e.@: with a leading @samp{|}) which draws back to the beginning
6982 @cindex underscore character
6983 @cindex character, underscore
6984 @cindex line drawing character
6985 @cindex character for line drawing
6986 The optional second parameter @var{c} is a character to draw the line
6987 with. If this second argument is not specified, @code{gtroff} uses
6988 the underscore character.
6990 @cindex zero width space character
6991 @cindex character, zero width space
6992 @cindex space character, zero width
6994 To separate the two arguments (to prevent @code{gtroff} from
6995 interpreting a drawing character as a scaling indicator) use @code{\&}.
6997 Here a small useful example:
7001 \(br\\$*\(br\l'|0\(rn'\l'|0\(ul'
7007 Note that this works by outputting a box rule (a vertical line), then
7008 the text given as an argument and then another box rule. Then the line
7009 drawing escapes both draw from the current location to the beginning of
7010 the @emph{input} line.
7013 @cindex drawing vertical lines
7014 @cindex vertical line drawing
7015 @cindex line, vertical, drawing
7016 @cindex line drawing character
7017 @cindex character for line drawing
7018 @cindex box rule character
7019 @cindex character, box rule
7020 @Defesc {\\L, ', l c, '}
7021 Draws vertical lines. Its parameters are
7022 similar to the @code{\l} escape. The
7023 movement is downwards for positive values,
7024 and upwards for negative values. The
7025 default character is the box rule character. As with the vertical
7026 motion escapes, text processing blindly continues where the line
7038 @Defesc {\\D, ', command arg @dots{}, '}
7039 The @code{\D} escape provides a variety of drawing functions.
7040 While the previous escapes work on a character device, these
7044 @item \D'l @var{dx} @var{dy}'
7045 Draw a line from the current location to the relative point specified by
7046 (@var{dx},@var{dy}).
7052 ...revised box macro...
7057 @cindex circle drawing
7058 @cindex drawing a circle
7059 Draw a circle with a diameter of @var{d} with the leftmost point at the
7063 Draw a solid circle with the same parameters as an outlined circle.
7065 @item \D'e @var{dx} @var{dy}'
7066 @cindex drawing an ellipse
7067 @cindex ellipse drawing
7068 Draw an ellipse with a horizontal diameter of @var{dx} and a vertical
7069 diameter of @var{dy} with the leftmost point at the current position.
7071 @item \D'E @var{dx} @var{dy}'
7072 Draw a solid ellipse with the same parameters as an outlined ellipse.
7074 @item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}'
7076 @cindex drawing an arc
7077 Draw an arc clockwise from the current location through the two
7078 specified locations (@var{dx1},@var{dy1}) and (@var{dx2},@var{dy2}).
7080 @item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
7081 @cindex drawing a spline
7082 @cindex spline drawing
7083 Draw a spline from the current location to (@var{dx1},@var{dy1}) and
7084 then to (@var{dx2},@var{dy2}), and so on.
7087 @cindex gray shading
7089 @cindex shades for filling objects
7090 Set the shade of gray to be used for filling solid objects to@w{
7091 }@var{n}; @var{n}@w{ }must be an integer between 0 and@w{ }1000, where 0
7092 corresponds solid white and 1000 to solid black, and values in between
7093 correspond to intermediate shades of gray. This applies only to solid
7094 circles, solid ellipses and solid polygons. By default, a level of@w{
7097 @item \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
7098 @cindex drawing a polygon
7099 @cindex polygon drawing
7100 Draw a polygon from the current location to (@var{dx1},@var{dy1}) and
7101 then to (@var{dx2},@var{dy2}) and so on. When the specified data points
7102 are exhausted, a line is drawn back to the starting point.
7108 ... box example (yes, again)...
7112 @item \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} ...'
7113 Draw a solid polygon with the same parameters as an outlined polygon.
7119 ... shaded box example ...
7124 @cindex line thickness
7125 @cindex thickness of lines
7126 Set the current line thickness to @var{n} machine units. A value of
7127 zero selects the smallest available line thickness. A negative value
7128 makes the line thickness proportional to the current point size (this is
7129 the default behaviour of @code{ditroff}).
7133 @cindex pile, character
7134 @cindex character pile
7135 @Defesc {\\b, ', string, '}
7136 @dfn{Piles} a sequence of characters
7137 vertically, and centers it vertically on the current line. Use it
7138 to build large brackets and braces.
7141 \b'\(lt\(bv\(lk\(bv\(lb'
7145 @xref{Drawing Functions}.
7148 @c =====================================================================
7150 @node Traps, Diversions, Drawing Requests, Programming Tutorial
7154 @dfn{Traps} are locations, which, when reached, call a specified
7155 macro. These traps can occur at a given location on the page, at a
7156 given location in the current diversion, after a certain number of input
7157 lines or at the end of input.
7160 * Page Location Traps::
7162 * Input Line Traps::
7163 * End-of-input Traps::
7166 @c ---------------------------------------------------------------------
7168 @node Page Location Traps, Diversion Traps, Traps, Traps
7169 @subsection Page Location Traps
7170 @cindex page location traps
7171 @cindex traps, page location
7173 @dfn{Page location traps} perform an action when @code{gtroff}
7174 reaches a certain vertical location on the page. Page location
7175 traps have a variety of purposes, including:
7179 setting headers and footers
7182 setting body text in multiple columns
7188 @cindex vertical position trap enable register
7191 Enables vertical position traps if @var{flag} is non-zero, or disables
7192 them otherwise. Vertical position traps are traps set by the @code{wh}
7193 or @code{dt} requests. Traps set by the @code{it} request are not
7194 vertical position traps. The parameter that controls whether vertical
7195 position traps are enabled is global. Initially vertical position traps
7196 are enabled. The current setting of this is available in the
7197 @code{.vpt} read-only number register.
7200 @Defreq {wh, dist macro}
7201 Sets a page location trap. Positive values for @var{dist} set
7202 the trap relative to the top of the page; negative values set
7203 the trap relative to the bottom of the page.
7205 @var{macro} is the name of the macro to execute when the
7208 @cindex page headers
7209 @cindex page footers
7212 The following is a simple example of how many macro packages
7213 set headers and footers.
7216 .de hd \" Page header
7221 .de fo \" Page footer
7226 .wh 0 hd \" trap at top of the page
7227 .wh -1i fo \" trap one inch from bottom
7231 @cindex distance to next trap
7232 @cindex trap, distance
7234 A read-only number register holding the distance to the next trap.
7237 @cindex changing trap location
7238 @cindex trap, changing location
7239 @Defreq {ch, dist macro}
7240 Changes the location of a trap.
7241 The first argument is the name of the macro to be invoked at
7242 the trap, and the second argument is the new location for the trap
7243 (note that the parameters are specified the opposite of the @code{.wh} request).
7244 This is useful for building up footnotes in a diversion to allow more
7245 space at the bottom of the page for them.
7251 ... (simplified) footnote example ...
7257 The read-only number register @code{.ne} contains the amount of space
7258 that was needed in the last @code{ne} request that caused a trap to be
7259 sprung. Useful in conjunction with the @code{.trunc} register.
7260 @xref{Page Control}, for more information.
7264 @cindex @code{ne}, and the @code{.trunc} register
7266 A read-only register containing the amount of vertical space truncated
7267 by the most recently sprung vertical position trap, or, if the trap was
7268 sprung by an @code{ne} request, minus the amount of vertical motion
7269 produced by the @code{ne} request. In other words, at the point a trap
7270 is sprung, it represents the difference of what the vertical position
7271 would have been but for the trap, and what the vertical position
7275 @c ---------------------------------------------------------------------
7277 @node Diversion Traps, Input Line Traps, Page Location Traps, Traps
7278 @subsection Diversion Traps
7279 @cindex diversion traps
7280 @cindex traps, diversion
7283 @cindex @code{.t}, and diversions
7284 @Defreq {dt, dist macro}
7285 Sets a trap @emph{within} a diversion.
7286 @var{dist} is the first argument is the location of the trap
7287 (identical to the @code{.wh} request)
7288 and @var{macro} is the name of the macro to be invoked. The
7289 number register @code{.t} still works within diversions.
7290 @xref{Diversions}, for more information.
7293 @c ---------------------------------------------------------------------
7295 @node Input Line Traps, End-of-input Traps, Diversion Traps, Traps
7296 @subsection Input Line Traps
7297 @cindex input line traps
7298 @cindex traps, input line
7300 @Defreq {it, n macro}
7301 Sets an input line trap.
7302 @var{n} is the number of lines of input which may be read before
7303 @dfn{springing} the trap, @var{macro} is the macro to be invoked.
7304 Request lines are not counted as input lines.
7306 For example, one possible use is to have a macro which prints the
7307 next @var{n}@w{ }lines in a bold font.
7320 @c ---------------------------------------------------------------------
7322 @node End-of-input Traps, , Input Line Traps, Traps
7323 @subsection End-of-input Traps
7324 @cindex end-of-input traps
7325 @cindex traps, end-of-input
7328 Sets a trap at the end of input. The @var{macro}
7329 specified is executed after the last line of the
7330 input file has been processed.
7332 For example, if the document had to have a section at the bottom of the
7333 last page for someone to approve it, the @code{em} request could be
7352 @c =====================================================================
7354 @node Diversions, Environments, Traps, Programming Tutorial
7358 In @code{gtroff} it is possible to @dfn{divert} text into a named
7359 storage area. Due to the similarity to defining macros it is sometimes
7360 said to be stored in a macro. This is used for saving text for output
7361 at a later time, which is useful for keeping blocks of text on the same
7362 page, footnotes, tables of contents and indices.
7365 @Defreqx {da, macro}
7366 Begins a diversion. Like the @code{de}
7367 request, it takes an argument of a macro name to divert subsequent text
7368 into. The @code{da} macro appends to an existing diversion.
7370 @code{di} or @code{da} without an argument ends the diversion.
7376 ... end-note example ...
7383 @cindex nested diversions
7384 @cindex diversion, nested
7387 Diversions may be nested. The read-only number register @code{.z}
7388 contains the name of the current diversion (this is a string-valued
7389 register). The read-only number register @code{.d} contains the current
7390 vertical place in the diversion. If not in a diversion it is the same
7391 as the register @code{nl}.
7397 The @dfn{high-water mark} on the current page. It corresponds to the
7398 text baseline of the lowest line on the page. This is a read-only
7404 After completing a diversion, the read-write number registers @code{dn}
7405 and @code{dl} contain the vertical and horizontal size of the diversion.
7409 .\" Center text both horizontally & vertically
7420 .nr @@s (((\\n(.tu-\\n(dnu)/2u)-1v)
7436 @cindex transparent output
7437 @cindex output, transparent
7439 @Defescx {\\?, , @Var{anything}, \\?}
7440 Prevents requests, macros and escapes from being
7441 interpreted when read into a diversion. This takes the given text
7442 and @dfn{transparently} embeds it into the diversion. This is useful for
7443 macros which shouldn't be invoked until the diverted text is actually
7446 @c XXX anything is read in copy mode. (what about \! ??)
7448 The @code{\!} escape transparently embeds text up to
7449 and including the end of the line.
7450 The @code{\?} escape transparently embeds text until the next
7451 occurrence of the @code{\?} escape. For example:
7458 @var{anything} may not contain newlines; use @code{\!} to embed
7459 newlines in a diversion. The escape sequence @code{\?} is also
7460 recognized in copy mode and turned into a single internal code; it is
7461 this code that terminates anything. Thus the following example
7468 \?\\?\\\\?\\\\\\\\nx\\\\?\\?\?
7483 @cindex unformatting diversions
7484 @cindex diversion, unformatting
7485 @Defreq {asciify, div}
7486 @dfn{Unformats} the diversion specified by @var{div}
7487 in such a way that @acronym{ASCII} and space characters that
7488 were formatted and diverted are treated like ordinary input
7489 characters when the diversion is reread. It can be also used for gross
7490 hacks; for example, the following sets register @code{n} to@w{ }1.
7503 @xref{Copy-in Mode}.
7507 @c =====================================================================
7509 @node Environments, Suppressing output, Diversions, Programming Tutorial
7510 @section Environments
7511 @cindex environments
7513 It happens frequently that some text should be printed in a certain
7514 format regardless of what may be in effect at the time, for example, in
7515 a trap invoked macro to print headers and footers. To solve this
7516 @code{gtroff} processes text in @dfn{environments}. An
7517 environment contains most of the parameters that control text
7518 processing. It is possible to switch amongst these environments; by
7519 default @code{gtroff} processes text in environment@w{ }0. The
7520 following is the information kept in an environment.
7524 font parameters (size, family, style, character height and slant, space
7525 and sentence space size)
7528 page parameters (line length, title length, vertical spacing,
7529 line spacing, indentation, line numbering, hyphenation data)
7532 fill and adjust mode
7535 tab stops, tab and leader characters, escape character, no-break and
7536 hyphen indicators, margin character data
7539 partially collected lines
7542 These environments may be given arbitrary names (see @ref{Identifiers},
7543 for more info). Old versions of @code{troff} only had environments
7544 named @samp{0}, @samp{1} and@w{ }@samp{2}.
7546 @cindex switch environments
7547 @cindex current environment number/name register
7550 Switches to another environment. The argument @var{env} is the name of
7551 the environment to switch to. With no argument, @code{gtroff} switches
7552 back to the previous environment. There is no limit on the number of
7553 named environments; they are created the first time that they are
7554 referenced. The @code{.ev} read-only register contains the name or
7555 number of the current environment. This is a string-valued register.
7557 Note that a call to @code{ev} (with argument) pushes the previously
7558 active environment onto a stack. If, say, environments @samp{foo},
7559 @samp{bar}, and @samp{zap} are called (in that order), the first
7560 @code{ev} request without parameter switches back to environment
7561 @samp{bar} (which is popped off the stack), and a second call
7562 switches back to environment @samp{foo}.
7568 ... page break macro, revised ...
7585 \(dg Note the large, friendly letters.
7590 @cindex copy environment
7592 Copies the environment @var{env} into the current environment.
7596 @c =====================================================================
7598 @node Suppressing output, I/O, Environments, Programming Tutorial
7599 @section Suppressing output
7600 @cindex suppressing output
7602 @Defesc {\\O, , num, }
7603 Disables or enables output depending on the value of @var{num}:
7607 Disable any ditroff glyphs from being emitted to the device driver.
7610 Enable output of glyphs.
7617 @code{\O0} and @code{\O1} also reset the four registers @samp{opminx},
7618 @samp{opminy}, @samp{opmaxx}, and @samp{opmaxy} to @minus{}1.
7619 @xref{Register Index}. These four registers mark the top left and
7620 bottom right hand corners of a box which encompasses all written glyphs.
7622 The following two forms of @code{\O} are specific to @code{grohtml}.
7626 Disable any ditroff glyphs from being emitted to the device driver. Also
7627 write out to @code{stderr} the page number and four registers encompassing
7628 the glyphs previously written since the last call to @code{\O}.
7631 Enable output of glyphs (the default). Also write out to @code{stderr}
7632 the page number and four registers encompassing the glyphs previously
7633 written since the last call to @code{\O}.
7638 @c =====================================================================
7640 @node I/O, Postprocessor Access, Suppressing output, Programming Tutorial
7643 @cindex input and output requests
7644 @cindex requests for input and output
7645 @cindex output and input requests
7647 @code{gtroff} has several requests for including files:
7649 @cindex including a file
7650 @cindex file inclusion
7652 Reads in the specified @var{file} and
7653 includes it in place of the @code{so} request. This is quite useful for
7654 large documents, e.g.@: keeping each chapter in a separate file.
7655 @xref{gsoelim}, for more information.
7659 Identical to the @code{so} request except that @code{gtroff}
7660 searches for the specified
7661 @var{file} in the same directories as macro files for the
7662 the @option{-m} command line option. If the file name to be included
7663 has the form @file{@var{name}.tmac} and it isn't found, @code{mso} tries
7664 to include @file{tmac.@var{name}} and vice versa.
7667 @cindex transparent output
7668 @cindex output, transparent
7670 @Defreqx {trf, file}
7671 Transparently outputs the contents of @var{file}. Each line is output
7672 as it were preceded by @code{\!}; however, the lines are not subject to
7673 copy mode interpretation. If the file does not end with a newline, then
7674 a newline is added. For example, to define a macro@w{ }@code{x}
7675 containing the contents of file@w{ }@file{f}, use
7683 The request @w{@code{.cf @var{filename}}}, when used in a diversion,
7684 embeds an object in the diversion which, when reread, causes the
7685 contents of @var{filename} to be transparently copied through to the
7688 In @acronym{UNIX} @code{troff}, the contents of @var{filename}
7689 is immediately copied through to the output regardless of whether there
7690 is a current diversion; this behaviour is so anomalous that it must be
7691 considered a bug. This request causes a line break.
7694 With @code{trf}, unlike @code{cf}, the file cannot contain characters
7695 such as NUL that are not valid @code{gtroff} input characters
7696 (@pxref{Identifiers}). This request causes a line break.
7700 Forces @code{gtroff} to continue processing of
7701 the file specified as an argument.
7705 The @code{rd} request reads from standard input, and includes what is
7706 read as though it were part of the input file. Text is read until a
7707 blank line is encountered.
7710 @cindex form letters
7711 @cindex letters, form
7712 Using the @code{nx} and @code{rd} requests,
7713 it is easy to set up form letters. The form
7714 letter template is constructed like this:
7732 When this is run, the following file should be redirected in. Note that
7733 requests included in this file are executed as though they were part of
7734 the form letter. The last block of input is the @code{ex} requests
7735 which tells groff to stop processing. If this was not there, groff
7736 would not know when to stop.
7740 708 NW 19th Av., #202
7755 Pipes the output of @code{gtroff} to the shell command(s)
7756 specified by @var{pipe}. This request must occur before
7757 @code{gtroff} has a chance to print anything.
7762 In @dfn{unsafe} mode, executes the shell command(s) specified by
7763 @var{cmds}. The output is not saved anyplace, so it is up to the user
7766 @c XXX add info about safer and unsafe mode
7768 For example, the following example introduces the current time
7771 @cindex time, current
7772 @cindex current time
7775 .sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\
7776 (localtime(time))[2,1,0]' > /tmp/x\n[$$]
7783 Note that this works by having the @code{perl} script (run by @code{sy})
7784 print out the @code{nr} requests which set the number registers
7785 @samp{H}, @samp{M} and @samp{S}, and then reads those commands in with
7786 the @code{so} request.
7788 @cindex @code{system()} return value register
7789 The @code{systat} read-write number register contains the return value
7790 of the @code{system()} function executed by the last @code{sy} request.
7793 @Defreq {open, stream file}
7794 @Defreqx {opena, stream file}
7795 Opens the specified @var{file} for writing and
7796 associates the specified @var{stream} with it.
7798 The @code{opena} is like @code{open}, but if the file exists, append to
7799 it instead of truncating it.
7802 @cindex copy-in mode, and @code{write} requests
7803 @cindex mode, copy-in, and @code{write} requests
7804 @Defreq {write, stream data}
7805 Writes to the file associated with the specified @var{stream}.
7806 The stream must previously have
7807 been the subject of an open request. The remainder of the line is
7808 interpreted as the @code{ds} request reads its second argument: A
7809 leading @samp{"} is stripped, and it is read in copy-in mode.
7812 @Defreq {close, stream}
7813 Closes the specified @var{stream};
7814 the stream is no longer an acceptable argument to the
7815 @code{write} request.
7821 ... example of open write &c...
7826 @Defesc {\\V, ', xxx, '}
7827 Interpolates the contents of the specified
7828 environment variable, as returned by the function @code{getenv}.
7829 Specify the argument to @code{\V} as an identifier, i.e.@:
7830 @samp{\V@var{x}}, @samp{\V(@var{xx}} or @samp{\V[@var{xxx}]}. @code{\V}
7831 is interpreted in copy-in mode.
7835 @c =====================================================================
7837 @node Postprocessor Access, Miscellaneous, I/O, Programming Tutorial
7838 @section Postprocessor Access
7839 @cindex postprocessor access
7840 @cindex access of postprocessor
7842 There are two escapes which give information directly
7843 to the postprocessor. This is particularly useful for embedding
7844 @sc{PostScript} into the final document.
7846 @Defesc {\\X, ', xxx, '}
7847 Embeds its argument into the @code{gtroff}
7848 output preceded with @w{@samp{x X}}.
7851 @Defesc {\\Y, ', xxx, '}
7852 The @code{\Y} escape is called with an identifier (i.e.@:
7853 @code{\Y@var{x}}, @code{\Y(@var{xx}} or @code{\Y[@var{xxx}]}). This is
7854 approximately equivalent to @samp{\X'\*[@var{xxx}]'}. However, the
7855 contents of the string or macro @var{xxx} are not interpreted; also it
7856 is permitted for @var{xxx} to have been defined as a macro and thus
7857 contain newlines (it is not permitted for the argument to @code{\X} to
7858 contain newlines). The inclusion of newlines requires an extension to
7859 the @acronym{UNIX} @code{troff} output format, and confuses drivers
7860 that do not know about this extension.
7863 @xref{Output Devices}.
7866 @c =====================================================================
7868 @node Miscellaneous, Debugging, Postprocessor Access, Programming Tutorial
7869 @section Miscellaneous
7870 @cindex miscellaneous
7872 This section documents parts of @code{gtroff} which cannot (yet) be
7873 categorized elsewhere in this manual.
7875 @cindex line numbers
7876 @cindex numbers, line
7877 @Defreq {nm, start inc space indent}
7878 Prints line numbers in the left margin.
7879 @var{start} is the line number of the @emph{next}
7880 output line; this defaults to@w{ }1. @var{inc} indicates on
7881 which lines numbers are printed, i.e.@: 5 means put line numbers on
7882 every 5@w{ }lines; this defaults to@w{ }1. @var{space} is the
7883 space to be left between the number and the text; this defaults to@w{
7884 }1. The fourth argument is the indentation of the line numbers.
7885 Without arguments, line numbers are turned off.
7888 @c XXX xref ln register
7890 @Defreq {nn, [@Var{skip}]}
7891 Temporarily turns off line numbering. The
7892 argument is the number of lines not to be numbered; this defaults
7895 @c XXX (does this disable incrementing or display?)
7901 ... line numbering example ...
7906 @cindex margin characters
7907 @cindex characters for margins
7908 @Defreq {mc, char dist}
7909 Prints margin characters to the right of the text.
7910 The first argument is the character to be
7911 printed, and the second argument is the distance away from the main body
7912 text. With no arguments the margin characters are turned off. If this
7913 occurs before a break, no margin character is printed.
7917 This is quite useful for indicating text that has changed, and, in fact,
7918 there are programs available for doing this (they are called
7919 @code{nrchbar} and @code{changebar} and can be found in any
7920 @samp{comp.sources.unix} archive.
7926 ... margin char example ...
7932 @cindex multi-file documents
7933 @cindex documents, multi-file
7934 @Defreq {lf, line filename}
7936 documents which are split into many files, then put together
7937 with @code{soelim} and other preprocessors. The second argument is the
7938 name of the file and the first argument is the input line number in
7939 that file. This way @code{gtroff} can produce error messages which are
7940 intelligible to the user.
7946 ... example of soelim'ed doc ...
7952 @c =====================================================================
7954 @node Debugging, Implementation Differences, Miscellaneous, Programming Tutorial
7958 @code{gtroff} is not easy to debug, but there are some useful features
7959 and strategies for debugging.
7961 @Defreq {tm, string}
7962 Sends the @var{string} to the standard error stream;
7963 this is very useful for printing debugging output among other things.
7967 @Defreq {ab, [@Var{string}]}
7968 Similar to the @code{tm} request, except that
7969 it causes @code{gtroff} to stop processing. With no argument it
7970 prints @samp{User Abort}.
7973 @cindex @code{ex}, use in debugging
7976 The @code{ex} request also causes @code{gtroff} to stop processing
7977 if encountered at the topmost level; see also @ref{I/O}.
7980 When doing something involved it is useful to leave the debugging
7981 statements in the code and have them turned on by a command line flag.
7984 .if \n(DB .tm debugging output
7988 To activate these statements say
7994 @c XXX .tm1, .tmc requests
7996 If it is known in advance that there will be many errors and no useful
7997 output, @code{gtroff} can be forced to suppress formatted output with
7998 the @option{-z} flag.
8000 @cindex dumping symbol table
8001 @cindex symbol table, dumping
8003 The @code{pm} request prints out the entire symbol table on @code{stderr}.
8006 @cindex dumping number registers
8007 @cindex number registers, dumping
8009 Prints the names and contents of all
8010 currently defined number registers on @code{stderr}.
8013 @cindex dumping traps
8014 @cindex traps, dumping
8016 Prints the names and positions of all traps
8017 (not including input line traps and diversion traps) on @code{stderr}.
8018 Empty slots in the page trap list are printed as well, because they can
8019 affect the priority of subsequently planted traps.
8022 @cindex flush output
8023 @cindex output, flush
8024 @cindex interactive use of @code{gtroff}
8025 @cindex @code{gtroff}, interactive use
8027 Instructs @code{gtroff} to flush its output
8028 immediately. The intent is for interactive use.
8029 @code{gtroff}; there is little other use for it. This
8030 request causes a line break.
8033 @cindex backtrace of input stack
8034 @cindex input stack, backtrace
8035 @Defreq {backtrace, }
8036 The @code{backtrace} request prints a backtrace of the input stack
8037 to the standard error stream.
8041 @code{gtroff} has command line options for printing out more warnings
8042 (@option{-w}) and for printing backtraces (@option{-b}) when a warning
8043 or an error occurs. The most verbose level of warnings is @option{-ww}.
8045 @cindex level of warnings
8046 @cindex warnings, level
8047 @Defreq {warn, [@Var{flags}]}
8049 Controls the level of warnings checked for. The @var{flags} are the sum
8050 of the numbers associated with each warning that is to be enabled; all
8051 other warnings are disabled. The number associated with each warning is
8052 listed below. For example, @w{@code{.warn 0}} disables all warnings,
8053 and @w{@code{.warn 1}} disables all warnings except that about missing
8054 characters. If an argument is not given, all warnings are enabled.
8056 The read-only number register @code{.warn} contains the current warning
8060 @c ---------------------------------------------------------------------
8066 @node Warnings, , Debugging, Debugging
8067 @subsection Warnings
8070 The warnings that can be given to @code{gtroff} are divided into the
8071 following categories. The name associated with each warning is used by
8072 the @option{-w} and @option{-W} options; the number is used by the
8073 @code{warn} request and by the @code{.warn} register.
8078 Non-existent characters. This is enabled by default.
8082 Invalid numeric expressions. This is enabled by default.
8089 In fill mode, lines which could not be broken so that their length was
8090 less than the line length. This is enabled by default.
8094 Missing or mismatched closing delimiters.
8100 Use of the @code{el} request with no matching @code{ie} request.
8105 Meaningless scaling indicators.
8109 Out of range arguments.
8113 Dubious syntax in numeric expressions.
8119 @cindex @code{di}, debugging
8120 @cindex @code{da}, debugging
8121 Use of @code{di} or @code{da} without an argument when there is no
8127 @c XXX more index entries
8128 Use of undefined strings, macros and diversions. When an undefined
8129 string, macro or diversion is used, that string is automatically defined
8130 as empty. So, in most cases, at most one warning is given for each
8136 @c XXX more index entries
8137 Use of undefined number registers. When an undefined number register is
8138 used, that register is automatically defined to have a value of@w{ }0.
8139 A definition is automatically made with a value of@w{ }0. So, in most
8140 cases, at most one warning is given for use of a particular name.
8144 Use of a tab character where a number was expected.
8149 @cindex @code{\@}}, debugging
8150 Use of @code{\@}} where a number was expected.
8154 Requests that are missing non-optional arguments.
8158 Illegal input characters.
8162 Unrecognized escape sequences. When an unrecognized escape sequence is
8163 encountered, the escape character is ignored.
8167 @cindex compatibility mode
8168 Missing space between a request or macro and its argument. This warning
8169 is given when an undefined name longer than two characters is
8170 encountered, and the first two characters of the name make a defined
8171 name. The request or macro is not invoked. When this warning is
8172 given, no macro is automatically defined. This is enabled by default.
8173 This warning never occurs in compatibility mode.
8177 Non-existent fonts. This is enabled by default.
8180 All warnings except @samp{di}, @samp{mac} and @samp{reg}. It is
8181 intended that this covers all warnings that are useful with traditional
8189 @c =====================================================================
8191 @node Implementation Differences, Summary, Debugging, Programming Tutorial
8192 @section Implementation Differences
8193 @cindex implementation differences
8194 @cindex differences in implementation
8195 @cindex incompatibilities with Unix @code{troff}
8196 @cindex compatibility mode
8197 @cindex mode, compatibility
8199 GNU @code{troff} has a number of features which cause incompatibilities
8200 with documents written with old versions of @code{troff}.
8204 Long names cause some incompatibilities. @acronym{UNIX} @code{troff}
8213 @cindex @code{\*}, incompatibilities with Unix @code{troff}
8214 @cindex @code{\n}, incompatibilities with Unix @code{troff}
8218 as defining a string @samp{ab} with contents @samp{cd}. Normally, GNU
8219 @code{troff} interprets this as a call of a macro named
8220 @code{dsabcd}. Also @acronym{UNIX} @code{troff} interprets
8221 @code{\*[} or @code{\n[} as references to a string or number register
8222 called @samp{[}. In GNU @code{troff}, however, this is normally
8223 interpreted as the start of a long name. In compatibility mode GNU
8224 @code{troff} interprets long names in the traditional way
8225 (which means that they are not recognized as names).
8226 Compatibility mode can be turned on with the @option{-C} command line
8227 option, and turned on or off with the @code{cp} request. The number
8228 register @code{.C} is@w{ }1 if compatibility mode is on, 0@w{
8245 GNU @code{troff} does not allow the use of the escape sequences
8246 @code{\|}, @code{\^}, @code{\&}, @code{\@{}, @code{\@}},
8247 @code{\@key{SP}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!},
8248 @code{\%}, and @code{\c} in names of strings, macros, diversions, number
8249 registers, fonts or environments; @acronym{UNIX} @code{troff} does. The
8250 @code{\A} escape sequence (@pxref{Identifiers}) may be helpful in
8251 avoiding use of these escape sequences in names.
8253 @cindex fractional point sizes
8254 @cindex point sizes, fractional
8256 @cindex @code{ps}, incompatibilities with Unix @code{troff}
8257 Fractional point sizes cause one noteworthy incompatibility. In
8258 @acronym{UNIX} @code{troff} the @code{ps} request ignores scale
8266 sets the point size to 10@w{ }points, whereas in GNU @code{troff} it
8267 sets the point size to 10@w{ }scaled points. @xref{Fractional Type
8268 Sizes}, for more information.
8275 @cindex @code{bd}, incompatibilities with Unix @code{troff}
8276 @cindex @code{cs}, incompatibilities with Unix @code{troff}
8277 @cindex @code{tkf}, incompatibilities with Unix @code{troff}
8278 @cindex @code{tr}, incompatibilities with Unix @code{troff}
8279 @cindex @code{fp}, incompatibilities with Unix @code{troff}
8280 @cindex input and output characters, compatibility with Unix
8281 @cindex output characters, compatibility with Unix
8282 @cindex characters, input and output, compatibility with Unix
8283 In GNU @code{troff} there is a fundamental difference between
8284 unformatted, input characters, and formatted, output characters.
8285 Everything that affects how an output character is output is stored
8286 with the character; once an output character has been constructed it is
8287 unaffected by any subsequent requests that are executed, including
8288 @code{bd}, @code{cs}, @code{tkf}, @code{tr}, or @code{fp} requests.
8289 Normally output characters are constructed from input characters at the
8290 moment immediately before the character is added to the current output
8291 line. Macros, diversions and strings are all, in fact, the same type of
8292 object; they contain lists of input characters and output characters in
8293 any combination. An output character does not behave like an input
8294 character for the purposes of macro processing; it does not inherit any
8295 of the special properties that the input character from which it was
8296 constructed might have had. For example,
8309 @cindex @code{\e}, incompatibilities with Unix @code{troff}
8310 @cindex @code{\!}, incompatibilities with Unix @code{troff}
8311 @cindex @code{\?}, incompatibilities with Unix @code{troff}
8312 @cindex transparent output, incompatibilities with Unix @code{troff}
8313 @cindex output, transparent, incompatibilities with Unix @code{troff}
8315 prints @samp{\\} in GNU @code{troff}; each pair of input backslashes
8316 is turned into one output backslash and the resulting output backslashes
8317 are not interpreted as escape characters when they are reread.
8318 @acronym{UNIX} @code{troff} would interpret them as escape characters
8319 when they were reread and would end up printing one @samp{\}. The
8320 correct way to obtain a printable backslash is to use the @code{\e}
8321 escape sequence: This always prints a single instance of the current
8322 escape character, regardless of whether or not it is used in a
8323 diversion; it also works in both GNU @code{troff} and @acronym{UNIX}
8324 @code{troff}. To store, for some reason, an escape sequence in a
8325 diversion that will be interpreted when the diversion is reread, either
8326 use the traditional @code{\!} transparent output facility, or, if this
8327 is unsuitable, the new @code{\?} escape sequence.
8329 @c XXX .tl compatibility mode -> input stack level
8330 @c XXX .if compatibility mode -> input stack level
8332 @xref{Diversions}, for more information.
8335 @c =====================================================================
8337 @node Summary, , Implementation Differences, Programming Tutorial
8341 @c XXX documentation
8345 @c =====================================================================
8346 @c =====================================================================
8348 @node Preprocessors, Output Devices, Programming Tutorial, Top
8349 @chapter Preprocessors
8350 @cindex preprocessors
8352 This chapter describes all preprocessors that come with @code{groff} or
8353 which are freely available.
8366 @c =====================================================================
8368 @node geqn, gtbl, Preprocessors, Preprocessors
8369 @section @code{geqn}
8379 @c ---------------------------------------------------------------------
8381 @node Invoking geqn, , geqn, geqn
8382 @subsection Invoking @code{geqn}
8383 @cindex invoking @code{geqn}
8384 @cindex @code{geqn}, invoking
8389 @c =====================================================================
8391 @node gtbl, gpic, geqn, Preprocessors
8392 @section @code{gtbl}
8402 @c ---------------------------------------------------------------------
8404 @node Invoking gtbl, , gtbl, gtbl
8405 @subsection Invoking @code{gtbl}
8406 @cindex invoking @code{gtbl}
8407 @cindex @code{gtbl}, invoking
8412 @c =====================================================================
8414 @node gpic, ggrn, gtbl, Preprocessors
8415 @section @code{gpic}
8425 @c ---------------------------------------------------------------------
8427 @node Invoking gpic, , gpic, gpic
8428 @subsection Invoking @code{gpic}
8429 @cindex invoking @code{gpic}
8430 @cindex @code{gpic}, invoking
8435 @c =====================================================================
8437 @node ggrn, grap, gpic, Preprocessors
8438 @section @code{ggrn}
8448 @c ---------------------------------------------------------------------
8450 @node Invoking ggrn, , ggrn, ggrn
8451 @subsection Invoking @code{ggrn}
8452 @cindex invoking @code{ggrn}
8453 @cindex @code{ggrn}, invoking
8458 @c =====================================================================
8460 @node grap, grefer, ggrn, Preprocessors
8461 @section @code{grap}
8464 A free implementation of @code{grap}, written by Ted Faber,
8465 is available as an extra package from the following address:
8468 @url{http://www.lunabase.org/~faber/Vault/software/grap/}
8472 @c =====================================================================
8474 @node grefer, gsoelim, grap, Preprocessors
8475 @section @code{grefer}
8476 @cindex @code{refer}
8477 @cindex @code{grefer}
8485 @c ---------------------------------------------------------------------
8487 @node Invoking grefer, , grefer, grefer
8488 @subsection Invoking @code{grefer}
8489 @cindex invoking @code{grefer}
8490 @cindex @code{grefer}, invoking
8495 @c =====================================================================
8497 @node gsoelim, , grefer, Preprocessors
8498 @section @code{gsoelim}
8499 @cindex @code{soelim}
8500 @cindex @code{gsoelim}
8505 * Invoking gsoelim::
8508 @c ---------------------------------------------------------------------
8510 @node Invoking gsoelim, , gsoelim, gsoelim
8511 @subsection Invoking @code{gsoelim}
8512 @cindex invoking @code{gsoelim}
8513 @cindex @code{gsoelim}, invoking
8519 @c =====================================================================
8520 @c =====================================================================
8522 @node Output Devices, File formats, Preprocessors, Top
8523 @chapter Output Devices
8524 @cindex output devices
8525 @cindex devices for output
8530 * Special Characters::
8541 @c =====================================================================
8543 @node Special Characters, grotty, Output Devices, Output Devices
8544 @section Special Characters
8545 @cindex special characters
8546 @cindex characters, special
8553 @c =====================================================================
8555 @node grotty, grops, Special Characters, Output Devices
8556 @section @code{grotty}
8557 @cindex @code{grotty}
8565 @c ---------------------------------------------------------------------
8567 @node Invoking grotty, , grotty, grotty
8568 @subsection Invoking @code{grotty}
8569 @cindex invoking @code{grotty}
8570 @cindex @code{grotty}, invoking
8575 @c =====================================================================
8577 @node grops, grodvi, grotty, Output Devices
8578 @section @code{grops}
8579 @cindex @code{grops}
8585 * Embedding PostScript::
8588 @c ---------------------------------------------------------------------
8590 @node Invoking grops, Embedding PostScript, grops, grops
8591 @subsection Invoking @code{grops}
8592 @cindex invoking @code{grops}
8593 @cindex @code{grops}, invoking
8597 @c ---------------------------------------------------------------------
8599 @node Embedding PostScript, , Invoking grops, grops
8600 @subsection Embedding @sc{PostScript}
8601 @cindex embedding postscript
8602 @cindex postscript, embedding
8607 @c =====================================================================
8609 @node grodvi, grolj4, grops, Output Devices
8610 @section @code{grodvi}
8611 @cindex @code{grodvi}
8619 @c ---------------------------------------------------------------------
8621 @node Invoking grodvi, , grodvi, grodvi
8622 @subsection Invoking @code{grodvi}
8623 @cindex invoking @code{grodvi}
8624 @cindex @code{grodvi}, invoking
8629 @c =====================================================================
8631 @node grolj4, grolbp, grodvi, Output Devices
8632 @section @code{grolj4}
8633 @cindex @code{grolj4}
8641 @c ---------------------------------------------------------------------
8643 @node Invoking grolj4, , grolj4, grolj4
8644 @subsection Invoking @code{grolj4}
8645 @cindex invoking @code{grolj4}
8646 @cindex @code{grolj4}, invoking
8651 @c =====================================================================
8653 @node grolbp, grohtml, grolj4, Output Devices
8654 @section @code{grolbp}
8655 @cindex @code{grolbp}
8663 @c ---------------------------------------------------------------------
8665 @node Invoking grolbp, , grolbp, grolbp
8666 @subsection Invoking @code{grolbp}
8667 @cindex invoking @code{grolbp}
8668 @cindex @code{grolbp}, invoking
8673 @c =====================================================================
8675 @node grohtml, gxditview, grolbp, Output Devices
8676 @section @code{grohtml}
8677 @cindex @code{grohtml}
8682 * Invoking grohtml::
8685 @c ---------------------------------------------------------------------
8687 @node Invoking grohtml, , grohtml, grohtml
8688 @subsection Invoking @code{grohtml}
8689 @cindex invoking @code{grohtml}
8690 @cindex @code{grohtml}, invoking
8695 @c =====================================================================
8697 @node gxditview, , grohtml, Output Devices
8698 @section @code{gxditview}
8699 @cindex @code{gxditview}
8704 * Invoking gxditview::
8707 @c ---------------------------------------------------------------------
8709 @node Invoking gxditview, , gxditview, gxditview
8710 @subsection Invoking @code{gxditview}
8711 @cindex invoking @code{gxditview}
8712 @cindex @code{gxditview}, invoking
8719 @c =====================================================================
8720 @c =====================================================================
8722 @node File formats, Installation, Output Devices, Top
8723 @chapter File formats
8724 @cindex file formats
8725 @cindex formats, file
8735 @c =====================================================================
8737 @node gtroff Output, Font Files, File formats, File formats
8738 @section @code{gtroff} Output
8739 @cindex @code{gtroff} output
8740 @cindex output, @code{gtroff}
8742 This section describes the format output of GNU @code{troff}. The
8743 output format used by GNU @code{troff} is very similar -- but
8744 not identical -- to that used by
8745 @acronym{UNIX} device-independent @code{troff} (@code{ditroff}).
8750 * Drawing Functions::
8751 * Line Continuation::
8754 @c ---------------------------------------------------------------------
8756 @node Output Format, Device Control, gtroff Output, gtroff Output
8757 @subsection Output Format
8758 @cindex output format
8759 @cindex format of output
8762 @cindex input, 8-bit
8763 The output format is text based, as opposed to a binary format (like
8764 @TeX{} DVI). The output format is @w{8-bit} clean, thus single
8765 characters can have the eighth bit set, as can the names of fonts and
8768 The output format consists of single command characters with attached
8769 parameters which are separated from subsequent text by whitespace or a
8772 The names of characters and fonts can be of arbitrary length; drivers
8773 should not assume that they are only two characters long (as
8774 @code{ditroff} does).
8776 When a character is to be printed, that character is always in the
8777 current font. Unlike @code{ditroff}, it is not necessary for drivers to
8778 search special fonts to find a character.
8799 @item @var{nn}@var{c}
8803 @var{xxx} is any sequence of characters terminated by a space or a
8804 newline; the first character should be printed at the current position,
8805 the the current horizontal position should be increased by the width of
8806 the first character, and so on for each character. The width of the
8807 character is that given in the font file, appropriately scaled for the
8808 current point size, and rounded so that it is a multiple of the
8809 horizontal resolution. Special characters cannot be printed using this
8813 @pindex DESC@r{, and @code{tcommand}}
8814 This command is only allowed if the @samp{tcommand} line is present in
8815 the @file{DESC} file.
8817 @item u@var{n} @var{xxx}
8818 This is same as the @samp{t} command except that after printing each
8819 character, the current horizontal position is increased by the sum of
8820 the width of that character and@w{ }@var{n}.
8822 This command is only allowed if the @samp{tcommand} line is present in
8823 the @file{DESC} file.
8825 @item n@var{a}@var{b}
8833 @pindex DESC@r{, and @code{sizescale}}
8834 The argument to the @samp{s} command is in scaled points (units of
8835 points/@var{n}, where @var{n} is the argument to the @samp{sizescale}
8836 command in the @file{DESC} file).
8843 @item D@var{c} @var{x}@dots{}\n
8847 @c ---------------------------------------------------------------------
8849 @node Device Control, Drawing Functions, Output Format, gtroff Output
8850 @subsection Device Control
8851 @cindex device control
8852 @cindex control of devices
8854 The @samp{x} command is normally followed by a letter or word indicating
8855 the function to perform, followed by white space separated arguments.
8857 The first argument can be abbreviated to the first letter.
8866 @item x res @var{n} @var{h} @var{v}
8871 The argument to the @w{@samp{x Height}} command is also in scaled
8875 The first three output commands are guaranteed to be:
8884 For example, the input
8887 crunchy \fH\s+2frog\s0\fP!?
8897 ... sample output here ...
8901 @c ---------------------------------------------------------------------
8903 @node Drawing Functions, Line Continuation, Device Control, gtroff Output
8904 @subsection Drawing Functions
8905 @cindex drawing functions
8906 @cindex functions for drawing
8909 The @samp{D} drawing command has been extended. These extensions are
8910 used by GNU @code{pic} only if the @option{-x} option is given.
8912 @xref{Drawing Requests}.
8917 Set the shade of gray to be used for filling solid objects to@w{
8918 }@var{n}; @var{n}@w{ }must be an integer between 0 and@w{ }1000, where 0
8919 corresponds solid white and 1000 to solid black, and values in between
8920 correspond to intermediate shades of gray. This applies only to solid
8921 circles, solid ellipses and solid polygons. By default, a level of@w{
8922 }1000 is used. Whatever color a solid object has, it should
8923 completely obscure everything beneath it. A value greater than@w{ }1000
8924 or less than@w{ }0 can also be used: this means fill with the shade of
8925 gray that is currently being used for lines and text. Normally this
8926 is black, but some drivers may provide a way of changing this.
8929 Draw a solid circle with a diameter of@w{ }@var{d} with the leftmost
8930 point at the current position.
8932 @item DE @var{dx} @var{dy}
8933 Draw a solid ellipse with a horizontal diameter of@w{ }@var{dx} and a
8934 vertical diameter of@w{ }@var{dy} with the leftmost point at the current
8937 @item Dp @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{} @var{dxn} @var{dyn}
8938 Draw a polygon with automatic closure. The first vertex is at the
8939 current position, the second vertex at an offset (@var{dx1},@var{dy1})
8940 from the current position, the second vertex at an offset
8941 (@var{dx2},@var{dy2}) from the first vertex, and so on up to the
8942 @var{n}@dmn{th} vertex. At the moment, GNU @code{pic} only uses this
8943 command to generate triangles and rectangles.
8945 @item DP @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{} @var{dxn} @var{dyn}
8946 Like @code{Dp} but draw a solid rather than outlined polygon.
8949 @cindex line thickness
8950 @cindex thickness of lines
8951 Set the current line thickness to @var{n}@w{ }machine units.
8952 Traditionally, @acronym{UNIX} @code{troff} drivers use a line thickness
8953 proportional to the current point size; drivers should continue to do
8954 this if no @code{Dt} command has been given, or if a @code{Dt} command
8955 has been given with a negative value of@w{ }@var{n}. A zero value of@w{
8956 }@var{n} selects the smallest available line thickness.
8960 A difficulty arises in how the current position should be changed after
8961 the execution of these commands. This is not of great importance since
8962 the code generated by GNU @code{pic} does not depend on this. Given a
8963 drawing command of the form
8966 \D'@var{c} @var{x1} @var{y1} @var{x2} @var{y2} @dots{} @var{xn} @var{yn}'
8973 where @var{c} is not one of @samp{c}, @samp{e}, @samp{l}, @samp{a} or
8974 @samp{~}, @acronym{UNIX} @code{troff} treats each x@w{ }value
8975 as a horizontal quantity, and each y@w{ }value as a vertical
8976 quantity; it assumes that the width of the drawn object is the sum of
8977 all x@w{ }values, and that the height is the sum of all y@w{ }values.
8978 (The assumption about the height can be seen by examining the @code{st}
8979 and @code{sb} registers after using such a @code{D}@w{ }command in a
8980 @code{\w} escape sequence.) This rule also holds for all the original
8981 drawing commands with the exception of @code{De}. For the sake of
8982 compatibility GNU @code{troff} also follows this rule, even though it
8983 produces an ugly result in the case of the @code{Df}, @code{Dt}, and, to
8984 a lesser extent, @code{DE}@w{ }commands. Thus after executing a
8985 @code{D}@w{ }command of the form
8988 D@var{c} @var{x1} @var{y1} @var{x2} @var{y2} @dots{} @var{xn} @var{yn}
8992 the current position should be increased horizontally by the sum of all
8993 x@w{ }values and vertically by the sum of all y@w{ }values.
8995 @c ---------------------------------------------------------------------
8997 @node Line Continuation, , Drawing Functions, gtroff Output
8998 @subsection Line Continuation
8999 @cindex line continuation in output commands
9000 @cindex output commands, line continuation
9002 There is a continuation convention which permits the argument to the
9003 @w{@samp{x X}} command to contain newlines: When outputting the argument
9004 to the @w{@samp{x X}} command, GNU @code{troff} follows each newline
9005 in the argument with a @samp{+} character (as usual, it terminates
9006 the entire argument with a newline); thus if the line after the line
9007 containing the @w{@samp{x X}} command starts with @samp{+}, then the
9008 newline ending the line containing the @w{@samp{x X}} command should be
9009 treated as part of the argument to the @w{@samp{x X}} command, the
9010 @samp{+} should be ignored, and the part of the line following the
9011 @samp{+} should be treated like the part of the line following the
9012 @w{@samp{x X}} command.
9015 @c =====================================================================
9017 @node Font Files, , gtroff Output, File formats
9022 The @code{gtroff} font format is roughly a superset of the
9023 @code{ditroff} font format. Unlike the @code{ditroff} font format,
9024 there is no associated binary format; all files are text files. The
9025 font files for device @var{name} are stored in a directory
9026 @file{dev@var{name}}. There are two types of file: a device description
9027 file called @file{DESC} and for each font@w{ }@var{f} a font file
9028 called@w{ }@file{@var{f}}.
9031 * DESC file format::
9032 * Font file format::
9035 @c ---------------------------------------------------------------------
9037 @node DESC file format, Font file format, Font Files, Font Files
9038 @subsection @file{DESC} file format
9039 @cindex @file{DESC} file format
9040 @cindex font description file format
9041 @cindex format of font description file
9042 @pindex DESC@r{ file format}
9044 The @file{DESC} file can contain the following types of line:
9049 There are @var{n} machine units per inch.
9053 The horizontal resolution is @var{n} machine units.
9057 The vertical resolution is @var{n} machine units.
9059 @item sizescale @var{n}
9061 The scale factor for point sizes. By default this has a value of@w{ }1.
9062 One scaled point is equal to one point/@var{n}. The arguments to the
9063 @code{unitwidth} and @code{sizes} commands are given in scaled points.
9064 @xref{Fractional Type Sizes}, for more information.
9066 @item unitwidth @var{n}
9068 Quantities in the font files are given in machine units for fonts whose
9069 point size is @var{n}@w{ }scaled points.
9073 This means that the postprocessor can handle the @samp{t} and @samp{u}
9076 @item sizes @var{s1} @var{s2} @dots{} @var{sn} 0
9078 This means that the device has fonts at @var{s1}, @var{s2}, @dots{}
9079 @var{sn} scaled points. The list of sizes must be terminated by a@w{
9080 }0. Each @var{si} can also be a range of sizes @var{m}-@var{n}. The
9081 list can extend over more than one line.
9083 @item styles @var{S1} @var{S2} @dots{} @var{Sm}
9085 The first @var{m}@w{ }font positions are associated with styles
9086 @var{S1} @dots{} @var{Sm}.
9088 @item fonts @var{n} @var{F1} @var{F2} @var{F3} @dots{} @var{Fn}
9090 Fonts @var{F1} @dots{} @var{Fn} are mounted in the font positions
9091 @var{m}+1, @dots{}, @var{m}+@var{n} where @var{m} is the number of
9092 styles. This command may extend over more than one line. A font name
9093 of@var{ }0 means no font is mounted on the corresponding font position.
9095 @item family @var{fam}
9097 The default font family is @var{fam}.
9101 This line and everything following in the file are ignored. It is
9102 allowed for the sake of backwards compatibility.
9105 The @code{res}, @code{unitwidth}, @code{fonts} and @code{sizes} lines
9106 are mandatory. Other commands are ignored by @code{gtroff} but may be
9107 used by postprocessors to store arbitrary information about the device
9108 in the @file{DESC} file.
9110 @c XXX add other commands resp. xrefs to output devices
9111 @c XXX add obsolete commands
9113 @c ---------------------------------------------------------------------
9115 @node Font file format, , DESC file format, Font Files
9116 @subsection Font file format
9117 @cindex font file format
9118 @cindex format of font files
9120 A font file has two sections. The first section is a sequence of lines
9121 each containing a sequence of blank delimited words; the first word in
9122 the line is a key, and subsequent words give a value for that key.
9127 The name of the font is@w{ }@var{f}.
9129 @item spacewidth @var{n}
9131 The normal width of a space is@w{ }@var{n}.
9135 The characters of the font have a slant of @var{n}@w{ }degrees.
9136 (Positive means forward.)
9138 @item ligatures @var{lig1} @var{lig2} @dots{} @var{lign} [0]
9140 Characters @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures;
9141 possible ligatures are @samp{ff}, @samp{fi}, @samp{fl}, @samp{ffi} and
9142 @samp{ffl}. For backwards compatibility, the list of ligatures may be
9143 terminated with a@w{ }0. The list of ligatures may not extend over more
9148 The font is special; this means that when a character is requested that
9149 is not present in the current font, it is searched for in any
9150 special fonts that are mounted.
9153 Other commands are ignored by @code{gtroff} but may be used by
9154 postprocessors to store arbitrary information about the font in the font
9157 @cindex comments in font files
9158 @cindex font files, comments
9160 The first section can contain comments which start with the @samp{#}
9161 character and extend to the end of a line.
9163 The second section contains one or two subsections. It must contain a
9164 @code{charset} subsection and it may also contain a @code{kernpairs}
9165 subsection. These subsections can appear in any order. Each
9166 subsection starts with a word on a line by itself.
9169 The word @code{charset} starts the character set subsection. The
9170 @code{charset} line is followed by a sequence of lines. Each line gives
9171 information for one character. A line comprises a number of fields
9172 separated by blanks or tabs. The format is
9174 @c XXX fix it for new HTML additions
9177 @var{name} @var{metrics} @var{type} @var{code} @var{comment}
9181 @cindex input, 8-bit
9185 @var{name} identifies the character: If @var{name} is a single
9186 character@w{ }@var{c} then it corresponds to the @code{gtroff} input
9187 character @var{c}; if it is of the form @samp{\@var{c}} where @var{c} is
9188 a single character, then it corresponds to the @code{gtroff} input
9189 character@w{ }\@var{c}; otherwise it corresponds to the groff input
9190 character @samp{\[@var{name}]}. (If it is exactly two characters
9191 @var{xx} it can be entered as @samp{\(@var{xx}}.) @code{gtroff}
9192 supports 8-bit characters; however some utilities have difficulties with
9193 eight-bit characters. For this reason, there is a convention that the
9194 name @samp{char@var{n}} is equivalent to the single character whose code
9195 is@w{ }@var{n}. For example, @samp{char163} would be equivalent to the
9196 character with code@w{ }163 which is the pounds sterling sign in @w{ISO
9197 Latin-1} character set. The name @samp{---} is special and indicates
9198 that the character is unnamed; such characters can only be used by means
9199 of the @code{\N} escape sequence in @code{gtroff}.
9201 @c XXX input encodings vs. output encodings
9203 The @var{type} field gives the character type:
9207 the character has an descender, for example, `p';
9210 the character has an ascender, for example, `b';
9213 the character has both an ascender and a descender, for example, `('.
9216 The @var{code} field gives the code which the postprocessor uses to
9217 print the character. The character can also be input to @code{gtroff}
9218 using this code by means of the @code{\N} escape sequence. The code can
9219 be any integer. If it starts with @samp{0} it is interpreted as
9220 octal; if it starts with @samp{0x} or @samp{0X} it is interpreted as
9223 Anything on the line after the @var{code} field is ignored.
9225 The @var{metrics} field has the form:
9228 @var{width}[,@var{height}[,@var{depth}[,@var{italic_correction}
9229 [,@var{left_italic_correction}[,@var{subscript_correction}]]]]]
9233 There must not be any spaces between these subfields (it has been split
9234 here into two lines for better legibility only). Missing subfields are
9235 assumed to be@w{ }0. The subfields are all decimal integers. Since
9236 there is no associated binary format, these values are not required to
9237 fit into a variable of type @samp{char} as they are in @code{ditroff}.
9238 The @var{width} subfield gives the width of the character. The
9239 @var{height} subfield gives the height of the character (upwards is
9240 positive); if a character does not extend above the baseline, it should
9241 be given a zero height, rather than a negative height. The @var{depth}
9242 subfield gives the depth of the character, that is, the distance below
9243 the lowest point below the baseline to which the character extends
9244 (downwards is positive); if a character does not extend below above the
9245 baseline, it should be given a zero depth, rather than a negative depth.
9246 The @var{italic_correction} subfield gives the amount of space that
9247 should be added after the character when it is immediately to be
9248 followed by a character from a Roman font. The
9249 @var{left_italic_correction} subfield gives the amount of space that
9250 should be added before the character when it is immediately to be
9251 preceded by a character from a Roman font. The
9252 @var{subscript_correction} gives the amount of space that should be
9253 added after a character before adding a subscript. This should be less
9254 than the italic correction.
9256 A line in the @code{charset} section can also have the format
9263 This indicates that @var{name} is just another name for the character
9264 mentioned in the preceding line.
9267 The word @code{kernpairs} starts the kernpairs section. This contains a
9268 sequence of lines of the form:
9271 @var{c1} @var{c2} @var{n}
9275 This means that when character @var{c1} appears next to character
9276 @var{c2} the space between them should be increased by@w{ }@var{n}.
9277 Most entries in the kernpairs section have a negative value for@w{
9282 @c =====================================================================
9283 @c =====================================================================
9285 @node Installation, Request Index, File formats, Top
9286 @chapter Installation
9287 @cindex installation
9293 @c =====================================================================
9294 @c =====================================================================
9296 @node Request Index, Escape Index, Installation, Top
9297 @chapter Request Index
9299 Requests appear without the leading control character (normally either
9300 @samp{.} or @samp{'}).
9306 @c =====================================================================
9307 @c =====================================================================
9309 @node Escape Index, Operator Index, Request Index, Top
9310 @chapter Escape Index
9316 @c =====================================================================
9317 @c =====================================================================
9319 @node Operator Index, Register Index, Escape Index, Top
9320 @chapter Operator Index
9326 @c =====================================================================
9327 @c =====================================================================
9329 @node Register Index, Macro Index, Operator Index, Top
9330 @chapter Register Index
9336 @c =====================================================================
9337 @c =====================================================================
9339 @node Macro Index, String Index, Register Index, Top
9340 @chapter Macro Index
9346 @c =====================================================================
9347 @c =====================================================================
9349 @node String Index, Glyph Name Index, Macro Index, Top
9350 @chapter String Index
9356 @c =====================================================================
9357 @c =====================================================================
9359 @node Glyph Name Index, Font File Keyword Index, String Index, Top
9360 @chapter Glyph Name Index
9362 A glyph name @code{xx} consisting of exactly two characters can be
9363 accessed as @samp{\(xx}. Glyph names @code{xxx} of any length can be
9364 accessed as @samp{\[xxx]}.
9370 @c =====================================================================
9371 @c =====================================================================
9373 @node Font File Keyword Index, Program and File Index, Glyph Name Index, Top
9374 @chapter Font File Keyword Index
9380 @c =====================================================================
9381 @c =====================================================================
9383 @node Program and File Index, Concept Index, Font File Keyword Index, Top
9384 @chapter Program and File Index
9390 @c =====================================================================
9391 @c =====================================================================
9393 @node Concept Index, , Program and File Index, Top
9394 @chapter Concept Index