ch17.htm

linux-unix130.linux.and.unix.ebooks130 linux and unix ebookslinuxLearning Linux - Collection of 12 E

<META NAME="ROBOTS" CONTENT="NOINDEX, NOFOLLOW">
<SCRIPT>
<!--
function displayWindow(url, width, height) {
        var Win = window.open(url,"displayWindow",'width=' + width +
',height=' + height + ',resizable=1,scrollbars=yes');
}
//-->
</SCRIPT>
</HEAD>

 -->



 





 








<H1>groff</H1></center>



<UL>

	<LI><A HREF="#Heading1">- 17 -</A>

	<UL>

		<LI><A HREF="#Heading2">groff</A>

		<UL>

			<LI><A HREF="#Heading3">Embedding Commands</A>

			<LI><A HREF="#Heading4">Controlling Character Appearance</A>

			<UL>

				<LI><A HREF="#Heading5">Sizes and Line Spacing</A>

			</UL>

			<LI><A HREF="#Heading6">NOTE</A>

			<UL>

				<LI><A HREF="#Heading7">Fonts</A>

				<LI><A HREF="#Heading8">Indenting and Line Length</A>

				<LI><A HREF="#Heading9">Other Character Controls</A>

			</UL>

			<LI><A HREF="#Heading10">Macros</A>

			<LI><A HREF="#Heading11">WARNING</A>

			<LI><A HREF="#Heading12">Using mm</A>

			<UL>

				<LI><A HREF="#Heading13">Paragraphs and Headers</A>

				<LI><A HREF="#Heading14">Lists</A>

				<LI><A HREF="#Heading15">Font Changes</A>

				<LI><A HREF="#Heading16">Footnotes</A>

			</UL>

			<LI><A HREF="#Heading17">Summary</A>

		</UL>

	</UL>

</UL>



<P>

<HR SIZE="4">



<H2 ALIGN="CENTER"><A NAME="Heading1<FONT COLOR="#000077">- 17 -</FONT></H2>

<H2 ALIGN="CENTER"><A NAME="Heading2<FONT COLOR="#000077">groff</FONT></H2>

<P><I>by Jim Parker</I></P>



<P>IN THIS CHAPTER</P>



<UL>

	<LI>Embedding Commands 

	<P>

	<LI>Controlling Character Appearance 

	<P>

	<LI>Macros 

	<P>

	<LI>Using mm  

</UL>



<P><BR>

This chapter looks at the <TT>groff</TT> text-formatting utility. Specifically, you

will learn about the following topics:



<UL>

	<LI>What <TT>groff</TT> is

	<P>

	<LI>How to do basic text formatting

	<P>

	<LI>How to create macros

	<P>

	<LI>What the <TT>mm</TT> macro package is

</UL>



<P>The <TT>groff</TT> program is the GNU version of <TT>nroff</TT> and <TT>troff</TT>,

text-formatting languages that have been used in UNIX for many years. The <TT>groff</TT>

system includes versions of <TT>troff</TT>, <TT>nroff</TT>, <TT>eqn</TT>, <TT>tbl</TT>,

and other UNIX text-formatting utilities. The <TT>groff</TT> language is used primarily

to compile man pages written and stored in <TT>groff</TT>/<TT>nroff</TT> format into

a form that can be printed or displayed on-screen.</P>

<P>The <TT>nroff</TT> language was designed to provide text formatting in lineprinters,

whereas <TT>troff</TT> was developed for phototypesetters. The commands in the two

languages are identical, although some commands that cannot be processed by a lineprinter

are ignored by <TT>nroff</TT>. In most cases, you don't use <TT>nroff</TT> or <TT>troff</TT>

directly, but use a macro package to access them.</P>

<P>For the most part, <TT>nroff</TT> and <TT>troff</TT> have fallen into disuse with

the development of powerful word processors and desktop-publishing packages. Their

primary remaining use is for formatting man pages, which continue to be used widely.</P>

<P>Both <TT>nroff</TT> and <TT>troff</TT> have many commands that you will never

require. Therefore, in this chapter we will look at the basic command set necessary

for you to use the <TT>groff</TT> version of the two languages, and how they can

be used for man page-specific applications. If you really want to use <TT>groff</TT>

for advanced text formatting, you should pick up a dedicated book on the subject.

<H3 ALIGN="CENTER"><A NAME="Heading3<FONT COLOR="#000077">Embedding Commands</FONT></H3>

<P>One aspect of <TT>groff</TT> that may take a little getting used to is that the

way you type lines in the file isn't necessarily the way they will be displayed in

the finished output. The <TT>groff</TT> system runs text lines together as much as

possible. For example, the source file<FONT COLOR="#0066FF"></FONT>

<PRE><FONT COLOR="#0066FF">This is fine stuff.

It is really interesting and

could keep me busy for hours.

</FONT></PRE>

<P>covers three lines in the source, but when formatted, it's run together by <TT>groff</TT>

to look like this:<FONT COLOR="#0066FF"></FONT>

<PRE><FONT COLOR="#0066FF">This is fine stuff. It is really interesting and could keep me busy for hours.

</FONT></PRE>

<P>with line breaks wherever necessary because of the page layout. This has an advantage

in that you don't have to worry about making everything look properly formatted within

the source. However, the disadvantage is that you might not have any idea what the

output will look like until you see it!</P>

<P>A look at a <TT>groff</TT> source file shows that it is all ASCII characters that

contain the usual text of the displayed output and a set of commands starting with

a period, like this:<FONT COLOR="#0066FF"></FONT>

<PRE><FONT COLOR="#0066FF">This is a bunch of text that will be displayed.

Here is even more text.

.ps 14

The line above is a groff command, identified by the

period in the first column of the line.

</FONT></PRE>

<P>Most <TT>groff</TT> commands are on a line by themselves, although a few can be

embedded anywhere on a line. These commands are usually prefaced by a backslash,

much as the shell uses the backslash as an escape character. An example of a line

with embedded commands is<FONT COLOR="#0066FF"></FONT>

<PRE><FONT COLOR="#0066FF">This \fBline\fR has two embedded \fIgroff\fR commands.

</FONT></PRE>

<P>Although there will be times when you want to use embedded commands, the majority

are the commands on a single line, starting with a period.

<H3 ALIGN="CENTER"><A NAME="Heading4<FONT COLOR="#000077">Controlling Character

Appearance</FONT></H3>

<P>The <TT>groff</TT> language has a few commands for controlling the way characters

look when printed or displayed. These include changing the size and line spacing

of characters, as well as controlling fonts.

<H4 ALIGN="CENTER"><A NAME="Heading5<FONT COLOR="#000077">Sizes and Line Spacing</FONT></H4>

<P>Character size and line spacing are not usually useful when displaying text on-screen,

unless you are using a bitmapped terminal. They are used for printed documents, though.

You can change the size of text with the <TT>.ps</TT> (point size) command:<FONT

COLOR="#0066FF"></FONT>

<PRE><FONT COLOR="#0066FF">This is the default 10-point size.

.ps 14

This is now in 14-point size.

.ps 20

This is a point size of 20.

.ps 6

And this is a really small point size of six.

</FONT></PRE>



<DL>

	<DT><FONT COLOR="#0066FF"></FONT></DT>

</DL>





<DL>

	<DD>

<HR>

<A NAME="Heading6<FONT COLOR="#000077"><B>NOTE:</B> </FONT>A point is 1/72

	of an inch, so a 36-point character size is half an inch high. The 12-point size

	used most commonly is 1/6-inch high. Different versions of <TT>groff</TT> support

	different point sizes, but most versions support 6, 7, 8, 9, 10, 11, 12, 14, 16,

	20, 24, 28, and 36 points. If you set a value that is not supported, it is rounded

	up to the next highest value (to a maximum of 36). The default point size is 10.

	If you use the <TT>.ps</TT> command without a value, <TT>groff</TT> reverts to the

	previous value.

<HR>



</DL>



<P>Within a sentence, the point size can be changed with the line-embedded command

<TT>\s</TT> followed by the point size. For example:<FONT COLOR="#0066FF"></FONT>

<PRE><FONT COLOR="#0066FF">This is in 10-point, while \s20this is in 20,\s10 and back to 10 again.

</FONT></PRE>

<P>The <TT>\s</TT> command should be followed by a legal point size. The special

command <TT>\s0</TT> causes <TT>groff</TT> to revert to its previous value. Relative

changes are also supported, so you could embed commands such as \<TT>s+2</TT> and

<TT>\s-2</TT>, although only a single digit can be specified (so you can't change

by more than nine points).</P>

<P>Line spacing is the vertical spacing between lines. Vertical spacing is not tied

to point size, so it should be adjusted manually. As a general rule, use a vertical

spacing about 20 percent larger than the point size. The default vertical spacing

is 11.</P>

<P>Line spacing is controlled by the <TT>.vs</TT> (vertical space) command. In the

next example, we change the point size and the vertical spacing to permit the characters

to be printed clearly without overlap:<FONT COLOR="#0066FF"></FONT>

<PRE><FONT COLOR="#0066FF">This is in normal 10-point, 11 vertical space size.

.ps 12

.vs 14

This is in 12-point with 14 vertical spacing.

</FONT></PRE>

<P>If you use the <TT>.vs</TT> command without a value, <TT>groff</TT> reverts to

the previous value.</P>

<P>If you want to force spacing for some reason, such as to separate sections of

text, you can use the <TT>.sp</TT> (space) command. Used with no argument, <TT>.sp</TT>

gives one blank line. It can also take arguments of <TT>i</TT> for inches and <TT>p</TT>

for points:<FONT COLOR="#0066FF"></FONT>

<PRE><FONT COLOR="#0066FF">This is default 10-point 11 vertical spaced text.

.sp

We have a blank line above this because of the command.

.sp 3.5i

This is three and a half inches below the previous line.

</FONT></PRE>

<P>You can use fractions in most <TT>groff</TT> commands, as this example shows.

<H4 ALIGN="CENTER"><A NAME="Heading7<FONT COLOR="#000077">Fonts</FONT></H4>

<P>Changing fonts requires the command <TT>.ft</TT> (font type). In the early days

of <TT>troff</TT>, only four fonts were supported: Roman, Roman bold, Roman italics,

and a set of special characters. Other fonts had to be specially loaded in the phototypesetter.

For this reason, <TT>groff</TT> defaults to Roman.</P>

<P>To switch to Roman bold, you use the command <TT>.ft B</TT>, while <TT>.ft I</TT>