[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11. Text Editing

Text editing is one of the most fundamental activities of computing on Linux-based systems, or most any computer for that matter. We edit text when writing a document, sending email, making a Web page, posting an article for Usenet, programming--and the list goes on. Most people spend a good deal of their computing time editing text with a text editor application.

There are a lot of text editors to choose from on Linux systems, as the first recipe in this chapter shows, but the majority of editors fit in one of two families of editor: Emacs and Vi. Most users prefer one or the other; rarely is one adept at both. I give more coverage to Emacs, and not only because it's my preferred editor--its keystroke commands are used by default in many other tools and applications, including the bash shell (see section The Shell).

11.1 Choosing the Perfect Text Editor  Overview of text editors.
11.2 Emacs  Introducing the Emacs editor.
11.3 Running a Vi Tutorial  Learning to use the Vi editor.
11.4 Selecting Text  Selecting text.
11.5 Editing Streams of Text  Editing a stream of text in batch.
11.6 Concatenating Text  Concatenating text.
11.7 Including Text Files  Including text files into new files.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.1 Choosing the Perfect Text Editor

The following table describes some of the more interesting text editors available, and includes information about their special traits and characteristics.

TEXT EDITOR DESCRIPTION
ae Anthony's Editor, ae, is a simple, easy-to-use text editor. It has modes to emulate the behavior of other text editors. {@sf{Debian}}: `ae' {@sf{WWW}}: http://dmoz.org/Computers/Software/Editors/Vi/
cooledit Cooledit is a popular, fast text editor for use in X; its features include anti-aliased fonts, Unicode support, and extensibility via the Python programming language. {@sf{Debian}}: `cooledit' {@sf{WWW}}: http://cooledit.sourceforge.net/
dedit DEdit is a simple editor for use in X with GNOME installed. It can read compressed files and display Japanese characters. {@sf{Debian}}: `dedit'
ee Intended to be an editor that novices can begin using immediately, the Easy Editor features pop-up menus. {@sf{Debian}}: `ee' {@sf{WWW}}: http://mahon.cwx.net/
elvis Elvis is a modern implementation of Vi that comes with many new features and extensions. {@sf{Debian}}: `elvis' {@sf{WWW}}: http://elvis.vi-editor.org
emacs Emacs is one of the two most-popular text editors. I've devoted an entire section to it in this book: Emacs. @sf{Debian}: `emacsen-common' @sf{Debian}: `emacs20' @sf{WWW}: `http://www.emacs.org/'
jed John E. Davis's jed offers many of the conveniences of Emacs and is geared specifically toward programmers. Features unique to it include drop-down menus that work in the console; jed loads quickly, and makes editing files at a shell prompt easy and fast. {@sf{Debian}}: `jed' {@sf{WWW}}: http://space.mit.edu/~davis/jed.html
joe Joe's Own Editor, joe, is a full-screen editor with a look and feel reminiscent of old DOS text editors like EDIT. {@sf{Debian}}: `joe' {@sf{WWW}}: ftp://ftp.std.com/src/editors/
nano Nano is a free software editor inspired by Pico, the editor that is included with the University of Washington's proprietary Pine email program. It's also faster than Pico, and comes with more features. {@sf{Debian}}: `nano' {@sf{WWW}}: http://www.nano-editor.org/
ted Ted is a WYSIWYG text editor for use in X which reads and writes `.rtf' files in Microsoft's "Rich Text Format." {@sf{Debian}}: `ted' {@sf{WWW}}: http://www.nllgg.nl/Ted/
the The Hessling Editor is a configurable editor that uses the Rexx macro language. It was inspired by the XEDIT editor for VM/CMS and the Kedit editor for DOS. {@sf{Debian}}: `the' {@sf{Debian}}: `the-doc' {@sf{WWW}}: http://www.lightlink.com/hessling/THE/
vi Vi (pronounced "vye," or sometimes "vee-eye") is a visual, or full-screen, editor. Touch typists often find its keystroke commands enable very fast editing. Together with Emacs, Vi shares the spotlight for most popular editor on Linux and Unix-based systems in general. Both were initially written in the same period, and both have their staunch adherents. To run a hands-on tutorial, see Running a Vi Tutorial. {@sf{Debian}}: `nvi' {@sf{WWW}}: ftp://mongoose.bostic.com/pub/nvi.tar.gz
vim Like the Elvis editor, Vim ("Vi improved") is a modern implementation of Vi whose new features include syntax coloring, scrollbars and menus, mouse support, and built-in help. {@sf{Debian}}: `vim' {@sf{WWW}}: http://www.vim.org/
wily Wily, an interesting mouse-centric editor, is inspired by the Acme editor from AT&T's Plan 9 experimental operating system. Wily commands consist of various combinations of the three mouse buttons, called chords, which can be tricky to master. {@sf{Debian}}: `wily' {@sf{WWW}}: http://www.cs.su.oz.au/~gary/wily/
xedit Xedit is a simple text editor that comes with, and works in, X. It lets you insert, delete, copy and paste text as well as open and save files--the very basics. {@sf{Debian}}: `xcontrib'
xemacs XEmacs is a version of Emacs with advanced capabilities for use in X, including the ability to display images. {@sf{Debian}}: `emacsen-common' {@sf{Debian}}: `xemacs' {@sf{WWW}}: http://www.xemacs.org/


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.2 Emacs

@sf{Debian}: `emacsen-common'
@sf{WWW}: `http://www.emacs.org/'

To call Emacs a text editor does not do it justice--it's a large application capable of performing many functions, including reading email and Usenet news, browsing the World Wide Web, and even perfunctory psychoanalysis.

There is more than one version of Emacs. GNU Emacs is the Emacs released under the auspices of Richard Stallman, who wrote the original Emacs predecessor in the 1970s. XEmacs (formerly Lucid Emacs) offers essentially the same features GNU Emacs does, but also contains its own features for use with the X Window System (it also behaves differently from GNU Emacs in some minor ways).

GNU Emacs and XEmacs are by far the most popular emacsen (as they are referred to in number); other flavors include jed (described in the previous section) and Chet's Emacs, ce, developed by a programmer at Case Western Reserve University.

Following is a brief introduction to using Emacs, interspersed with the necessary Emacs jargon; following that are recipes that describe how to use some of Emacs's advanced editing features.

11.2.1 Getting Acquainted with Emacs  How to learn Emacs.
11.2.2 Basic Emacs Editing Keys  The basic Emacs editing keys.
11.2.3 Making Abbreviations in Emacs  Making abbreviations to save time.
11.2.4 Recording and Running Macros in Emacs  Making macros to save time.
11.2.5 Inserting Special Characters in Emacs  Inserting special characters in Emacs.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.2.1 Getting Acquainted with Emacs

Start Emacs in the usual way, either by choosing it from the menu supplied by your window manager in X, or by typing its name (in lowercase letters) at a shell prompt.

Upon startup in X, a typical GNU Emacs window looks like this (the window frame will differ depending on your window manager):

text-editing-emacs-01

The welcome message appears when Emacs first starts, and it tells you, among other things, how to run a tutorial (which we'll look at in just a minute).

The top bar is called the menu bar, and you can pull down its menus with the mouse by left-clicking a menu and then dragging it down. When you run Emacs in a console, you can't use the mouse to pull down the menus, but you can access and choose the same menu items in a text menu by typing F10.(17)

A file or other text open in Emacs is held in its own area called a buffer. By default, the current buffer appears in the large area underneath the menu bar. To write text in the buffer, just type it. The place in the buffer where the cursor is at is called point, and is referenced by many Emacs commands.

The horizontal bar near the bottom of the Emacs window and directly underneath the current buffer is called the mode line; it gives information about the current buffer, including its name, what percentage of the buffer fits on the screen, what line point is on, and whether or not the buffer is saved to a file.

The mode line also lists the modes active in the buffer. Emacs modes are general states that control the way Emacs behaves--for example, when Overwrite mode is set, text you type overwrites the text at point; in Insert mode (the default), text you type is inserted at point. Usually, either Fundamental mode (the default) or Text mode will be listed.

You can make the menu bar appear or disappear by toggling Menu bar mode. Typing F10 to activate the menu pull-downs works whether Menu bar mode is on or off; if it's off, the menu choices will appear in a new buffer window.

(If the menu bar is already turned off, this command will turn it on.)

The echo area is where Emacs writes brief status messages, such as error messages; it is the last line in the Emacs window. When you type a command that requires input, that input is requested in this area (and when that happens, the place you type your input, in the echo area, is then called the minibuffer).

Emacs commands usually begin with a Control or Meta (Escape) key sequence; many commands begin with the C-x sequence, which you type by pressing and holding the CTRL key and then pressing the X key (see section Typographical Conventions).

Because Emacs is different in culture from the editors and approach of the Microsoft Windows and Apple MacOS world, it has gotten a rather unfounded reputation in those corners that it is odd and difficult to use. This is not so. The keyboard commands to run its various functions are designed for ease of use and easy recall.

For example, the find-file function prompts for the name of a file and opens a copy of the file in a new buffer; its keyboard accelerator is C-x C-f (you can keep CTRL depressed while you press and release the X and F keys).

You can run any Emacs function by typing M-x followed by the function name and pressing RET.

This command runs the find-file function, which prompts for the name of a file and opens a copy of the file in a new buffer.

Type C-g in Emacs to quit a function or command; if you make a mistake when typing a command, this is useful to cancel and abort the keyboard input.

Now that we have run through the essential Emacs terminology, I'll show you how to exit the program--just type C-x C-c.

Emacs can have more than one buffer open at once. To switch between buffers, type C-x C-b. Then, give the name of the buffer to switch to, followed by RET; alternatively, type RET without a buffer name to switch to the last buffer you had visited. (Viewing a buffer in Emacs is called visiting the buffer.)

A special buffer called `*scratch*' is for notes and things you don't want to save; it always exists in Emacs.

Any file names you give as an argument to emacs will open in separate buffers:

 
$ emacs todo rolo /usr/local/src/nirvarna/README RET

(You can also make new buffers and open files in buffers later, of course.)

Emacs comes with an interactive, self-paced tutorial that teaches you how to use the basics. In my experience, setting aside 25 minutes to go through the tutorial is one of the best things you can do in your computing career--even if you decide that you don't like Emacs very much, a great many other applications use Emacs-like keyboard commands and heuristics, so familiarizing yourself with them will always pay off.

To start the tutorial at any time when you are in Emacs, type C-h t.

Incidentally, C-h is the Emacs help key; all help-related commands begin with this key. For example, to read the Emacs FAQ, type C-h F, and to run the Info documentation browser (which contains The GNU Emacs Manual), type C-h i.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.2.2 Basic Emacs Editing Keys

The following table lists basic editing keys and describes their function. Where two common keystrokes are available for a function, both are given.

KEYS DESCRIPTION
@uparrow or C-p Move point up to the previous line. [GNU INFO BUG: any <> in the preceding line should be the one of the cursor arrow keys.]
@downarrow or C-n Move point down to the next line. [GNU INFO BUG: any <> in the preceding line should be the one of the cursor arrow keys.]
@leftarrow or C-b Move point back through the buffer one character to the left. [GNU INFO BUG: any <> in the preceding line should be the one of the cursor arrow keys.]
@rightarrow or C-f Move point forward through the buffer one character to the right. [GNU INFO BUG: any <> in the preceding line should be the one of the cursor arrow keys.]
PgUp or C-v Move point forward through the buffer one screenful.
PgDn or M-v Move point backward through the buffer one screenful.
BKSP or C-h Delete character to the left of point.
DEL or C-d Delete character to the right of point.
INS Toggles between Insert mode and Overwrite mode.
Shift-INS or C-y Yank text in the kill ring at point (see section Pasting Text).
C-SPC Set mark (see section Cutting Text).
C-_ Undo the last action (control-underscore).
C-a Move point to the beginning of the current line.
C-e Move point to the end of the current line.
C-g Cancel the current command.
C-h F Open a copy of the Emacs FAQ in a new buffer.
C-h a function RET List all Emacs commands related to function.
C-h i Start Info.
C-h k key Describe key.
C-h t Start the Emacs tutorial.
C-k Kill text from point to end of line.
C-l Re-center the text in the Emacs window, placing the line where point is in the middle of the screen.
C-t Transpose the character at point with the character to the left of point.
C-u number Repeat the next command or keystroke you type number times.
C-w Kill text from mark to point.
C-x C-c Save all buffers open in Emacs, and then exit the program.
C-x C-f file RET Open file in a new buffer for editing. To create a new file that does not yet exist, just specify the file name you want to give it. To browse through your files, type TAB instead of a file name.
C-left-click Display a menu of all open buffers, sorted by major mode (works in X only).
SHIFT-left-click Display a font selection menu (works in X only).


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.2.3 Making Abbreviations in Emacs

An abbrev is a word that is an abbreviation of a (usually) longer word or phrase. Abbrevs exist as a convenience to you--you can define abbrevs to expand to a long phrase that is inconvenient to type, or you can define a misspelling that you tend to make to expand to its correct spelling. Abbrevs only expand when you have Abbrev mode enabled.

To define an abbrev, type the abbrev you want to use and then type C-x aig. Emacs will prompt in the minibuffer for the text you want the abbrev to expand to; type that text and then type RET.

Now, whenever you type `rbf' followed by a whitespace or punctuation character in the current buffer, that text will expand to the text `R. Buckminster Fuller'.

To save the abbrevs you have defined so that you can use them later, use the write-abbrev-file function. This saves all of the abbrevs currently defined to a file that you can read in a future Emacs session. (You can also open the file in a buffer and edit the abbrevs if you like.)

Then, in a future Emacs session, you can use the read-abbrev-file function to define those abbrevs for that session.

NOTE: Emacs mode commands are toggles. So to turn off Abbrev mode in a buffer, just type M-x abbrev-mode RET again. If you turn Abbrev mode on in that buffer later on during the Emacs session, the abbrevs will be remembered and will expand again.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.2.4 Recording and Running Macros in Emacs

A macro is like a recording of a sequence of keystrokes--when you run a macro, Emacs executes that key sequence as if you had typed them.

To begin recording a macro, type C-x (. Then, everything you type is recorded as the macro until you stop recording by typing C-x ). After you have recorded a macro, you can play it back at any time during the Emacs session by typing C-x e. You can precede it with the universal-argument command, C-u, to specify a number of times to play it back.

Macros are primary to how Emacs works--in fact, the name Emacs is derived from `Editing MACroS', because the first version of Emacs in 1976 was actually a collection of such macros written for another text editor.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.2.5 Inserting Special Characters in Emacs

There are some characters that you cannot normally type into an Emacs buffer. For example, in a text file, you can specify a page break by inserting the formfeed character, ASCII C-l or octal code 014; when you print a file with formfeeds, the current page is ejected at this character and printing is resumed on a new page.

However, C-l has meaning as an Emacs command. To insert a character like this, use the quoted-insert function, C-q. It takes either a literal keystroke to insert, or the octal code of the character to insert. It inserts that character at point.

The preceding examples both do the same thing: they insert a formfeed character at point.

An interesting use of C-q is to underline text. To do this, insert a literal C-h character followed by an underscore (`_') after each character you want to underline.

You can then use ul to output the text to the screen (see section Underlining Text).

Another kind of special character insert you might want to make is for accented characters and other characters used in various languages.

To insert an accented character, use ISO Accents mode. When this mode is active, you can type a special accent character followed by the character to be accented, and the proper accented character will be inserted at point.

The following table shows the special accent characters and the key combinations to use.

[GNU INFO BUG: Info does not currently display accent characters correctly.]

PREFIX... PLUS THIS LETTER YIELDS THIS RESULT
" a ä
" e ë
" i ï
" o ö
" u ü
" s ß
' a á
' e é
' i í
' o ó
' u ú
` a à
` e è
` i ì
` o ò
` u ù
~ a ã
~ c ç
~ d &dtilde;
~ n ñ
~ t &ttilde;
~ u ũ
~ < <<
~ > >>
~ ! ¡
~ ? ¿
^ a â
^ e ê
^ i î
^ o ô
^ u û
/ a å
/ e æ
/ o ø

When a buffer contains accented characters, it can no longer be saved as plain ASCII text, but must instead be saved as text in the ISO-8859-1 character set (see section Viewing a Character Chart). When you save a buffer, Emacs will notify you that it must do this.

In the event that you want to type the literal key combinations that make up an accented character in a buffer where you have ISO Accents mode on, type the prefix character twice.

NOTE: GNU Emacs has recently added a number of internationalization functions. A complete discussion of their use is out of the scope of this book; for more information on this topic, see section `International Character Set Support' in The GNU Emacs Manual.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.3 Running a Vi Tutorial

@sf{Debian}: `nvi'
@sf{WWW}: ftp://mongoose.bostic.com/pub/nvi.tar.gz
@sf{WWW}: http://www.cs.cmu.edu/~vaschelp/Editors/Vi/

The Vi editor comes with a hands-on, self-paced tutorial, which you can use in vi to learn how to use it. It's stored as a compressed file in the `/usr/doc/nvi' directory; copy this file to your home directory, uncompress it, and open it with vi to start the tutorial.

NOTE: An advanced tutorial is also available in `/usr/doc/nvi'.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.4 Selecting Text

In X, you can cut and paste text between other windows, including xterm and Emacs windows. The most recently selected text is called the X selection.

In the console, you can cut and paste text in the same virtual console or into a different virtual console. To do this, you need the gpm package installed and set up for your mouse (it's a default, recommended package).

The operations described in this section work the same both in X and in virtual consoles. You cannot presently cut and paste text between X and a virtual console.

Three buttons on the mouse are used for cutting and pasting. If you have a two-button mouse, your administrator can set it to emulate three buttons--to specify the middle button, press the left and right buttons simultaneously.

Click the left mouse button and drag the mouse over text to select it. You can also double-click the left mouse button on a word to select that word, and triple-click the left mouse button on a line to select that line. Furthermore, you can click the left mouse button at one end of a portion of text you want to select, and then click the right mouse button at the other end to select all of the text between the points.

NOTE: In an xterm window, when you're running a tool or application locally in a shell (such as the lynx Web browser), the left mouse button alone won't work. When this happens, press and hold the SHIFT key while using the mouse to select text.

11.4.1 Cutting Text  Cutting out a selection of text.
11.4.2 Pasting Text  Pasting in a selection of text.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.4.1 Cutting Text

You don't have to select text to cut it. At a shell prompt or in Emacs, type C-k to cut the text from the cursor to the end of the line.

In Emacs parlance, cutting text is known as killing text. Emacs has additional commands for killing text:


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.4.2 Pasting Text

@sf{Debian}: `xpaste'

To paste the text that was last selected with the mouse, click the middle mouse button at the place you want to paste to. You can also use the keyboard by moving the cursor to where you want to paste and then typing Shift-INS. These commands work both in X and in the console.

In X, to display the contents of the X selection in its own window, run the xpaste X client; its only purpose in life is to display this text in its window.

In Emacs, pasting text is called yanking the text. Emacs offers the additional key, C-y ("yank"), to yank the text that was last selected or killed. This key also works in the bash shell, where it pastes the last text that was killed with C-k in that shell session, if any.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.5 Editing Streams of Text

Some of the recipes in this book that work on text use sed, the "stream editor." It is not a text editor in the usual sense--you don't open a file in sed and interactively edit it; instead, it performs editing operations on a stream of text sent to its standard input, and it writes the results to the standard output. This is more like a filter than an editor, and sed is a useful tool for formatting and searching through text.

"The seder's grab-bag" is a useful collection of sed information including a FAQ and many example scripts.

The sed "one-liners" are useful commands for editing and processing text.

See Info file `sed.info', node `Top', for more information on sed usage.

Other tools that are good for stream editing include the AWK and Perl programming languages; to learn more about using these powerful languages, I recommend the following books:


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.6 Concatenating Text

The cat tool gets its name because it concatenates all of the text given to it, outputting the result to the standard output. It is useful for concatenating files of text together.

For example, suppose you have two files, `early' and `later'. The file `early' contains this text:

 
This Side of Paradise
The Beautiful and Damned

And the file `later' contains this text:

 
The Great Gatsby
Tender Is the Night
The Last Tycoon

This command redirects the standard output to a new file, `novels', which would then contain the following text:

 
This Side of Paradise
The Beautiful and Damned
The Great Gatsby
Tender Is the Night
The Last Tycoon

The files `early' and `later' are not altered.

Had you typed cat later early > novels instead, the files would be concatenated in that reversed order instead, beginning with `later'; so the file `novels' would contain the following:

 
The Great Gatsby
Tender Is the Night
The Last Tycoon
This Side of Paradise
The Beautiful and Damned

The following sections give other recipes for concatenating text.

NOTE: You can also use cat to concatenate files that are not text, but its most popular usage is with text files. Another way to concatenate files of text in an automated way is to use file inclusion---see Including Text Files.

A similar tool, zcat, reads the contents of compressed files.

11.6.1 Writing Text to Files  Writing text to a file.
11.6.2 Appending Text to a File  Appending text to the end of a file.
11.6.3 Inserting Text at the Beginning of a File  Inserting text to the beginning of a file.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.6.1 Writing Text to Files

Sometimes, it's too much trouble to call up a text editor for a particular job--you just want to write a text file with two lines in it, say, or you just want to append a text file with one line. There are ways of doing these kind of micro-editing jobs without a text editor.

To write a text file without using a text editor, redirect the standard output of cat to the file to write. You can then type your text, typing C-d on a line of its own to end the file. This is useful when you want to quickly create a small text file, but that is about it; usually, you open or create a text file in a text editor, as described in the previous sections in this chapter.

In this example, the text file `novels' was created and contains four lines of text (the last line with the C-d is never part of the file).

Typing text like this without an editor will sometimes do in a pinch but, if you make a mistake, there is not much recourse besides starting over--you can type C-u to erase the current line, and C-c to abort the whole thing and not write the text to a file at all, but that's about it.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.6.2 Appending Text to a File

To add text to a text file without opening the file in a text editor, use cat with the append operator, `>>'. (Using `>' instead would overwrite the file.)

In this example, no files were specified to cat for input, so cat used the standard input; then, one line of text was typed, and this text was appended to file `novels', the file used in the example of the previous recipe. So now this file would contain the following:

 
This Side of Paradise
The Beautiful and Damned
The Great Gatsby
Tender Is the Night
The Last Tycoon


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.6.3 Inserting Text at the Beginning of a File

@sf{WWW}: http://dsl.org/comp/tinyutils/

Inserting text at the beginning of a text file without calling up a text editor is a bit trickier than appending text to a file's end--but it is possible.

To insert one or more lines of text at the beginning of a file, use ins. Give the name of the file in which to insert text as an argument; ins will read lines of text from the standard input and insert them at the beginning of the file. (It works by opening the file in ed, a simple line editor.)

Give the EOF--that is, type C-d on a line by itself--to signify the end of the lines of text to insert.

This command inserts two lines of text at the beginning of novels, the file used in the previous examples in this section. This file would now contain the following:

 
The Novels of F. Scott Fitzgerald
---------------------------------
This Side of Paradise
The Beautiful and Damned
The Great Gatsby
Tender Is the Night
The Last Tycoon


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

11.7 Including Text Files

@sf{Debian}: `m4'

File inclusion is where the contents of a file can be included at a particular place within some other file, just by specifying the file's name at that place in the other file.

This is useful if you want or need to frequently rearrange divisions or sections of a document, if you need to keep a document in more than one arrangement, or if you have some sections of text that you frequently insert in more than one document. For these situations, you can keep each section in a separate file and build an include file that contains the file names for the various sections in the order you want to generate that file.

To include a file in a text file, specify the file to be included on a line of its own, like this:

 
include(file)

When you process this file for inclusion, the line with the `include' statement is replaced with the contents of the file file (whose path is relative to the current directory of the include file).

Use the m4 tool, the GNU macro processor, to process an include file. It takes as an argument the name of the include file, and it outputs the inclusion to the standard output. You can use redirection to redirect the output to a file.

For example, suppose the file `soups' contains this text:

 
Clam Chowder
Lobster Bisque
Vegetable

And suppose the file `sandwiches' contains this text:

 
BLT
Ham on Rye
Roast Beef

And finally, suppose the file `menu' contains this text:

 
Diner Menu For Today


Soups
-----

include(soups)


Sandwiches
----------

include(sandwiches)

This command writes a new file, `monday.txt', which looks like this:

 
Diner Menu For Today


Soups
-----

Clam Chowder
Lobster Bisque
Vegetable



Sandwiches
----------

BLT
Ham on Rye
Roast Beef

NOTE: You can write more than one include file that will use your files--and the files themselves can have include files of their own.

This is a fairly simple use of m4; it can do much more, including run commands, manipulate text, and run custom macros. See Info file `m4.info', node `Top' for more information on this tool.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated using texi2html