Creating Your Own Troff
         Macros
         Seninha
_________________________________
1. What is troff




Creating Your Own Troff Macros/1. What is troff   2
Troff vs Nroff.
• troff(1) - format documents for typesetting
• nroff(1) - format documents for terminal
• Implementations.
    • groff.
    • neatroff.
    • plan9 troff.
    • heirloom doctools.




Creating Your Own Troff Macros/1. What is troff   3
Example of troff document.
.TL
Title of the document
.SH
First section.
.PP
This is a paragraph!
The following figure is a quotation.
.FS
.PP
I d just like to interject for a moment.
What you re referring to as Linux,
is in fact, GNU/Linux,
or as I ve recently taken to calling it,
GNU plus Linux.
.FE
Creating Your Own Troff Macros/1. What is troff   4
Do not use low-level troff commands.
• Requests: low-level commands by troff.
• Macros: high-level commands by packages.
• Requests deal with fine formating (indentation, spac-
  ing, point size, etc).
• Macros deal with text elements (title, paragraphs, fig-
  ures, etc).




Creating Your Own Troff Macros/1. What is troff        5
How to use troff?
• pre-processors
• troff
• post-processors
<file.roff pre | troff | post >file.ps




Creating Your Own Troff Macros/1. What is troff   6
_________________________________
2. Troff requests




Creating Your Own Troff Macros/2. Troff requests   7
Writing a paragraph in plain troff.
.br         \" break line
.ft R       \" set font to roman
.ps 12      \" set point size to 12pt
.vs 14pt \" set vertical space to 14pt
.sp 12pt \" space down 12pt
.ne 3       \" get rid of orphans
.in 0       \" set paragraph indentation
.ti 5n      \" set first line indentation
I am a paragraph!




Creating Your Own Troff Macros/2. Troff requests   8
Number registers.
.br
.ft R
.ps \n(PS
.vs \n(VS
.sp \n(PDu
.ne 1+\n(.Vu
.in 0
.ti \n(PIu
I am a paragraph!

.\"   I am a comment!
.\"   \nA
.\"   \n(AB
.\"   \n[ABCD]

Creating Your Own Troff Macros/2. Troff requests   9
Units of measure.
• c - Centimeters.
• i - Inches.
• m - Ems (font-dependent).
• n - Ens (font-dependent).
• p - Points.
• u - Device units.
• v - Vertical space.
.\" PI - Paragraph Indentation
.nr PI 5n




Creating Your Own Troff Macros/2. Troff requests   10
How can we improve our paragraphs?
.br
.ft R
.ps \n(PS
.vs \n(VS
.sp \n(PDu
.ne 1+\n(.Vu
.in 0
.ti \n(PIu
I am a paragraph!
.br
.ft R
...\" repeat all those requests
I am another paragraph!



Creating Your Own Troff Macros/2. Troff requests   11
A macro for paragraphs.
.PP
I am a paragraph!
.PP
I am another paragraph!




Creating Your Own Troff Macros/2. Troff requests   12
_________________________________
3. Macros




Creating Your Own Troff Macros/3. Macros   13
Defining a macro. There s an error here (people who
use m4(1) or any macro processor can identify).
.de PP
.br
.ft R
.ps \n(PS
.vs \n(VS
.sp \n(PDu
.ne 1+\n(.Vu
.in 0
.ti \n(PIu
..




Creating Your Own Troff Macros/3. Macros         14
Changing a number register the macro uses.
.de PP
.br
.ft R
.ps \n(PS
.vs \n(VS
.sp \n(PDu
.ne 1+\n(.Vu
.in 0
.ti \n(PIu
..
.PP
Paragraph indented 5 ens (default).
.nr PI 3i
.PP
Paragraph indented 3 inches?
Creating Your Own Troff Macros/3. Macros     15
Escaping number registers.
.de PP
.br
.ft R
.ps \\n(PS
.vs \\n(VS
.sp \\n(PDu
.ne 1+\\n(.Vu
.in 0
.ti \\n(PIu
..
.PP
Paragraph indented 5 ens (default).
.nr PI 3i
.PP
Paragraph indented 3 inches!
Creating Your Own Troff Macros/3. Macros   16
Macros with arguments.
.de PP
.br
.ft R
.ps \\n(PS
.vs \\n(VS
.sp \\n(PDu
.ne 1+\\n(.Vu
.in 0
.ie \\$1 .ti \\$1u
.el        .ti \\n(PIu
..
.PP
Paragraph indented 5 ens (default).
.PP 3i
Paragraph indented 3 inches!
Creating Your Own Troff Macros/3. Macros   17
_________________________________
4. Macro packages




Creating Your Own Troff Macros/4. Macro packages   18
Macro packages.
• Each macro package has a different set of macros.
• And a different set of number registers.




Creating Your Own Troff Macros/4. Macro packages      19
center, allbox;
ccc
lll
lll
lll
lll
lll
lll
lll
lll
l l l.
T{
Macro
T}T{
In -ms
T}T{
Creating Your Own Troff Macros/4. Macro packages   20
In -mm
T}
_
T{
Paragraph
T}T{
.PP/.LP/.IP
T}T{
.P
T}
T{
Heading
T}T{
.SH/.NH
T}T{
.HU/.H
Creating Your Own Troff Macros/4. Macro packages   21
T}
T{
Title
T}T{
.TL
T}T{
.TL
T}
T{
Abstract
T}T{
.AB, .AE
T}T{
.AS, .AE
T}
T{
Creating Your Own Troff Macros/4. Macro packages   22
Author
T}T{
.AU, .AI
T}T{
.AU
T}
T{
Bold text
T}T{
.B
T}T{
.B/.BI/.IB
T}
T{
Italic text
T}T{
Creating Your Own Troff Macros/4. Macro packages   23
.I
T}T{
.I/.IB/.BI
T}
T{
Text size
T}T{
.LG/.SM
T}T{
.S/.SM
T}
T{
Lists
T}T{
(does not have)
T}T{
Creating Your Own Troff Macros/4. Macro packages   24
.BL/.ML/.DL/...
T}




Creating Your Own Troff Macros/4. Macro packages   25
Why write our own macro package?
• Fine control of the output.
• Expand an existing macro.
• Understand how troff works.




Creating Your Own Troff Macros/4. Macro packages   26
_________________________________
5. Contents of a macro package




Creating Your Own Troff Macros/5. Contents of a macro package   27
What does a macro package have?
• Macros for text elements (paragraphs, headings, title,
  etc).
• Page traps for margins.
• Diversions for figures.
• Initialization.




Creating Your Own Troff Macros/5. Contents of a macro package   28
Macro for paragraphs.
.de PP
.br
.ft R
.ps \\n(PS
.vs \\n(VS
.sp \\n(PDu
.ne 1+\\n(.Vu
.in 0
.ti \\n(PIu
..




Creating Your Own Troff Macros/5. Contents of a macro package   29
Macro for section headings.
.de SH
.br
.ft B
.ps \\n(PS+2
.vs \\n(VS+2
.sp 1
.ne 5
.in 0
.nr SH +1
\\n(SH.
..




Creating Your Own Troff Macros/5. Contents of a macro package   30
Macro for title.
.de TL
.br
.ce
.ft B
.ps \\n(PS+4
.vs \\n(VS+4
.sp 4
.in 0
..




Creating Your Own Troff Macros/5. Contents of a macro package   31
Page traps for top and bottom margins.
.de TM \" top margin
 sp 1i \" space 1 inch from the top
..
.de BM \" bottom margin
 bp       \" break page
..
.wh 0     TM
.wh -1i BM




Creating Your Own Troff Macros/5. Contents of a macro package   32
Page trap for headers and footers.
.de FO \" footer
.ft R
.ps \\n(PS-2
.tl ""%""
.ps \\n(PS
..
.wh -0.5i FO




Creating Your Own Troff Macros/5. Contents of a macro package   33
Figures (table, image, code snippet, etc).
• A figure should not be broken between pages.
• If a figure is longer than the remaining of the page,
  write the figure in the next page.
• But how to get the length of a figure BEFORE writing
  it?
• Diversion!




Creating Your Own Troff Macros/5. Contents of a macro package   34
Figures.
.de FS \" figure start
.br
.sp \\n(PDu
.di FI
..
.de FE \" figure end
.br
.di
.ne \\n(dnu
.FI
..




Creating Your Own Troff Macros/5. Contents of a macro package   35
Code listing.
.de CS \" code start
.br
.nf
.sp \\n(PDu
.di CI
.ft CW
..
.de CE \" code end
.br
.di
.ne \\n(dnu
.CI
.fi
..

Creating Your Own Troff Macros/5. Contents of a macro package   36
Font changing macros.
.de I \" italic font
.ft I
\\$1
.ft
..
.de B \" bold font
.ft B
\\$1
.ft
..




Creating Your Own Troff Macros/5. Contents of a macro package   37
Initialization.
.nr PD 1v
.nr PS 12
.nr VS 14
.nr PI 5n
.fi             \"    enable fill mode
.ll 16c         \"    A4 line lenght for text
.lt 16c         \"    A4 line lenght for .tl
.pl 29.7c \"          A4 page length




Creating Your Own Troff Macros/5. Contents of a macro package   38
_________________________________
6. Conclusion




Creating Your Own Troff Macros/6. Conclusion   39
Macros vs requests.
• Use the -ms macro package first.
• Expand the -ms macro to your needs.
• Write your own macro package.




Creating Your Own Troff Macros/6. Conclusion   40
Example of document.
.PP
Welcome to this document.
Good reading
.SH
First section.
.PP
Here s a quotation.
.FS
.PP
I d just like to interject for a moment.
What you re referring to as Linux,
is in fact, GNU/Linux,
or as I ve recently taken to calling it,
GNU plus Linux.
.FE
Creating Your Own Troff Macros/6. Conclusion   41
The end.
• Questions?




Creating Your Own Troff Macros/6. Conclusion   42