Elements of E-Text Style

Version 1.0

9 August 1993

 

This file should be named ESTYLE10.TXT or estyle10.txt.

 

 

Copyright (c) 1993 by John E. Goodwin. All Rights Reserved.

 

You may make and distribute verbatim copies of this work for non-

commercial purposes using any means, provided this copyright notice is

included in all such copies.

 

Contact: John E. Goodwin

P.O. Box 6022

St. Charles, IL 60174

jegoodwin@delphi.com

 

[John Goodwin is available to consult, write, and teach courses on E-

text issues and Internetworking]

 

 

Abstract: This manual discusses how to use electronic text (E-text) as

a communications medium distinct from the print media. The manual is

written in a non-technical style, such as a humanist-of-little-brain

might enjoy reading.

 

o You can learn how to write effective E-text for personal, business,

and scholarly communication.

 

o It includes sections on preparing forms and texts for electronic

response and on writing effective and business-like E-mail letters.

 

o There is a brief section on Standard Generalized Markup Language, a

coding standard of interest to humanists.

 

 

Just to prove how non-technical it all is, here is an exceptional lapse

into technical jargon, in case you know what the Internet and FTP

archives are:

 

This work is a companion volume to _E-Mail 101_, available free as

ftp://mrcnext.cso.uiuc.edu:/etext/etext93/email025.txt.

 

 

<title> Elements of E-Text Style

 

=Preface= An Apology for E-Text

 

=Part I= Writing for an E-Text Audience

 

=Part II= Specific Differences of Style and Mechanics

 

=Part III= A Very Brief Style Manual

 

=Appendix A= Technical Details: Relationship to SGML and TEI

 

=Table I= Full Table of Contents (go to very end of this file)

 

 

<Preface>

 

This work grew out of my earlier course notes published under the

title _EMAIL 101_. It was originally projected to be a three chapter

section concerning the special needs of writers who wished their works

to be transportable by the electronic networks. The chapters were not

included in the original release as they existed only in outline form.

 

Over the course of Summer 1993 I gradually came to realize that E-text

was a communication medium in its own right, with its own needs and

conventions, its own strengths and weaknesses, and not merely the

bastard child of the print medium. Consequently, many questions of

style, long ago settled for print media and fixed into rules in style

manuals, needed to be re-examined in light of the new medium.

 

Since, it seemed to me, that no one had set out to treat the stylistic

considerations of writing E-text, at least at any length, I decided to

expand my three chapters into the present work. I set out to write down

systematically some observations I had made concerning the differences

between E-text and "ordinary" writing. I treat E-text as a legitimate

medium of expression, one that must be addressed on its own terms and

without unnecessary reference to how the words might look on paper or

how the work might be useful if printed out.

 

For reasons that I will discuss at length in the first part, only a

small fraction of E-text will ever see the light of print. While paper

may offer a better resolution image and a more perspicuous whole, E-text

excels at ease of production and portability. It can be copied simply,

transported great distances in seconds by electronic networks, and

stored on magnetic media--floppy disks, hard drives, and CD-ROMs-- that

are less bulky and cheaper than paper.

 

The extraordinary growth of E-mail in the past few years, from a medium

used by a few scientists and government officials to one accessible to

millions, often in a humanistic or business setting, demands that we

give the writing of E-text the attention it deserves. If you wish to

communicate effectively, you will have to master this new medium. It is

a necessary part of education--if only we knew what to teach!

 

Good writing is, in many respects, the same for any medium. And the

first thing any writer learns is that their** writing must fit both the

audience and the medium being used. We cannot pretend any longer that

we are writing for print or that our audience will be looking at

anything other than a computer screen.

 

** I deliberately use "their" as an ambiguous pronoun throughout.

 

Just as the print media differ among themselves depending on the

intended audience, expected lifetime of the text, and peculiarities of

the medium, so E-text differs from print.

 

This work is organized as follows:

 

In the first part we delineate the major differences between the print

media and E-text.

 

In the second part, we discuss specific issues such as techniques

for designing a visually appealing layout, or representing characters.

 

The third and final part is a brief style manual for writing E-text.

It is not offered as a set of prescriptions, but as an example of how

the principles in the second part can be realized in practice.

 

+ + +

 

In this introductory section, I would like to make a brief apology for

E-text. It is not usual, in discussing the print media, to begin a

manual on style with a defense of the worth of the medium; however, E-

text is so new that many persons will say "Why bother with it?". They

deserve an answer.

 

The most insidious objection to E-text is the claim that it is just

printed text before it has been printed out. In effect, this denies

either that

 

(1) There is any difference between the needs of E-text and the needs

of print; or

 

(2) That all text is printed out before being read.

 

The second premise is demonstrably false--most E-mail correspondence and

anything longer than about 25 pages obtained over a computer network

suffice as examples.

 

The first premise requires a more extended answer, since it is the

source of a great deal of confusion. In fact, the entire first part of

this work is devoted to refuting it. In this brief apology I will

answer two simpler objections: that E-text is so esoteric that it is of

no interest to ordinary persons; or that it is so commonplace as to be

beneath our consideration. I call these two objections the "Ham Radio"

and "Telephone" objections, respectively.

 

 

Not every communications medium is of interest to a large number of

persons. Take, for example, Amateur Radio. Using short-wave radio to

communicate requires a fair technical knowledge and special equipment.

Because of these two investments, neither the medium nor the skills

required to master it are common. This situation is very similar to

that of computers in the late '70's. Computers were not commonplace,

being owned mostly by hobbyists. Communication and distribution of

information was primitive, often by floppy disk passed hand to hand.

And the special programs required to create and read E-text--word

processors--were uncommon and required special skills.

 

On the other hand, some will object that E-text is now so commonplace

that it needs no consideration. You don't read style manuals about how

to talk on the Telephone do you? Although some scholars may discuss how

telephone conversation differs from the ordinary face-to-face variety,

most of us use telephones un-self-consciously. E-text is like typing a

letter. Who cares?

 

Although the *mechanics* of talking on a telephone are trivial, the

social implications are not. One can point out, for example, that to

most people, their parents have become persons that they talk to on the

telephone and not persons that they work with every day and see face-to-

face. The social implications of this are enormous; the technology

trivial.

 

Similarly with E-text: while the mechanics are easily mastered and

perhaps of little interest, E-text together with global computer

networks make possible a form of community that didn't exist prior to

the medium. The sort of community that will form around E-text is

different from the kind of communities that are centered on the

telephone. Rather than family or casual friends, it is likely to be a

community that cares about a single issue or agenda.

 

These communities can range from complex communities like companies or

groups of scholars, to persons sharing a single, simple interest.

Already, in our society, we find that technology has allowed us to adopt

a pattern of individualism never seen in the world before. Most face-

to-face communication is with your immediate family, your co-workers,

and perhaps a few friends. These friends are not as likely to live next

to you as in a small town, and you see them less often.

 

E-text both carries this atomization to its extreme and simultaneous

offers a way out from its worst effects. It is possible, using the

medium, to form important relationships with persons you have never seen

or talked to--this is individual atomism in the extreme. At the same

time, E-text provides a communications medium that can go beyond. It

solves the problem, inherent in much of our society, of shallow

relationships with other humans.

 

These new, deep relationships can be business or scholarly, , or just

old-fashioned friendship. Thus communicating well carries social

implications that go far deeper than talking well on the telephone. How

you write E-text may affect how you *appear* to potential friends,

clients, and one day perhaps even family.**

 

** It is only a matter of time before parents of college children

realize they can have a much closer relationship with their children for

the 10 dollars a month it costs to open an E-mail account.

 

Despite the unnaturalness compared to talking, in many ways E-text is

superior to the telephone as a way to "keep in touch". The telephone

requires that both persons be available simultaneously. Most

conversations are short and business-like, with marathon sessions being

reserved for close family and a few friends.

 

But it is not for writing the occasional personal note that one needs a

style manual. Unlike the telephone, E-mail has more serious uses--the

same uses that print media have. It is used for business, persuasion,

publication, and scholarship. E-mail may become as commonplace as

telephone, but it will not be approached with the same casualness.

 

 

Over the course of the past year or so I have seen collaborations of

individuals in many fields spring up. These collaborations at first

were of course among computer scientists. Then, in the last couple of

years the Scientists have caught on. There are signs that all academic

disciplines will soon have such collaborations. The cost in equipment

is low and the advantages great. Software for business "working groups"

is already in the marketplace.

 

Collaboration by E-mail--and a consequent reliance on E-text--may become

the dominant social model for certain kinds of collaboration: E.g.,

within a company or scholarly community--wherever the persons cannot

meet face to face.

 

There are many who say that E-text as we now know it--the typewriter-

like production of character-oriented terminals--will soon give way to a

new medium, mulitmedia. In this view, newer computers will spawn newer

media and the old ones will be forgotten. In five years, ten at the

most, E-text will be a thing of the past. Surely, the argument goes, we

should not invest time in perfecting a medium that is little better than

a fad.

 

Multimedia indeed shows great promise. I have no doubt that soon it

will be possible to mail graphic images, audio, and video clips along

with text. Printers will print not only color but black and white. And

visual formatting information like font, point size, and so on will be

sent alongside the basic text. Not only that, but these capabilities

will become part of every household, every phone system, cable system,

and cellular communications network. Personal computers will replace

telphones as the "communications center" of the household.

 

The vision of multimedia is one of old media--color magazines,

television, telephone, radio--being reborn in the new guise of

electronics. But what do you think will be a large component of each

and every mulitmedia message? Could it be that most of it will be E-

text? I think multimedia will turn out to be a lot like a letter to

home. We may send an occasional picture, or even an audio cassette, but

most of the communication will be in our writing.

 

Ultimately, writing is easier than taking photographs or editing video

clips--though not as easy as talking. It takes less time, less capital,

and less effort. Multimedia may be good for advertising, for writing

textbooks, and for fun; but for just plain communicating? If it

requires more thought or needs to reach more persons than a short

telephone call, it will be E-text. Multimedia will fill the niche of

four color magazines, coffee table art books, the biology textbooks, and

advertising.

 

Look around you, at your bookshelves, and notice how many have no

pictures. Think how many typed letters your office sends out compared

to the number of four-color brochures it creates. Most information is

disseminated by the cheapest possible means. Right now, electronic text

is that cheapest means. As more and more persons learn how to get it,

it will become the dominant medium. E-text is the black and white print

of the electronic age.

 

The uses of E-text are as diverse as the uses of print. The chief

innovation of the new medium is the fact that it places the capability

to publish in the hands of *anyone*. The capital required to spread

information or ideas has been reduced to a level any person, or at least

any community of persons, can afford.

 

The E-text revolution is that individuals are no longer dependent on

institutions or even businesses to create, share, and gather

information.** Every interest and splinter group, every church or

synagogue, every would-be author, student, or scholar can collaborate

with others, write, and share texts.

 

** They are still dependent on hardware, software, and

telecommunications.

 

As E-text becomes more and more acceptable, it will become the medium of

expression used by the masses. If you wish to reach them, you will have

to learn to write it effectively. Education--real education--has always

been a rather solitary effort. The right conditions seem to involve

access to a good library, a chance to talk with collaborators, write new

material, and have it discussed by the community of interested persons.

E-text can bring these necessary conditions for education out of the

university to the simplest home.

 

 

E-text is at the stage the European vernaculars were at the time of

the Renaissance. There were many doubters who pointed to the

established Latin tongue as the medium of communication. But, in time,

reality forced even the scholars to yield. A revolution was

accomplished in which masses of ordinary people could own books and even

on occasion produce them. The implications for society and learning

were staggering.

 

Like that earlier time, when print was new, there is now much innovation

and experimentation, and the wise practitioner will sift carefully the

techniques and suggestions offered both here and by others. In time we

shall have our Dantes, our Bacons, and our Shakespeares; the persons who

will show us how to make this new medium not only a utilitarian one but

a sublime one. For now, let us take those first hesitant steps down

that path.

 

 

 

<Part I> Writing for an E-Text Audience: Basic Problems

 

Writing for an E-text audience is very much like writing for a print

audience, but there are subtle differences. Nowadays, both works

destined for print and works aimed at the global networks are likely to

be created on a personal computer. The advantage of being able to make

incremental changes to a manuscript, and to create near print-quality

works with a laser printer--not to mention the advantages of spell-

checkers, automatic footnotes and the like--means that both kinds of

author will be using a computer. But one will be aiming for an

effective and attractive *printed* manuscript and the other will be

aiming to accomplish the same end on a computer screen.

 

The difference between E-text and print comes down to two factors:

 

(1) it is not currently possible to create a file that simultaneously

looks good in print and on the screen, yet is universally accepted by

all computer programs; and

 

(2) the least common denominator computer screen has a lower

resolution, a smaller viewing window, and a more limited repertoire of

visual effects than even a typewriter.

 

This Chapter will address three questions:

 

o Why write for an E-text audience at all?

 

o Is it possible to write for both audiences at the same time?

 

o How does writing for an E-text audience differ from writing for a

Print Audience?

 

In Part II we will explore the extent to which you can have it both

ways--strategies for getting as close as possible to the Holy Grail of

Electronic Communications, a file everyone can read that looks just as

good on the screen and in print.

 

Part III presents the mechanics of creating E-text in the form of a very

brief style manual. The issues of the previous two chapters are

summarized in a series of suggestions for creating your own effective

style.

 

The last Chapter of this part of the course discusses copyright issues

that effect the distribution of E-text. These issues, important as they

are for print media, become paramount concerns when copying your text is

as easy as pressing a button.

 

=Section 1.1= Why Write for an E-text Audience?

 

=Section 1.2= Is it Possible to Write E-Text and Print at the Same

Time?

 

=Section 1.3= Differences between E-Text and Print Media

 

=Section 1.4= Version Control

 

 

<Section 1.1> Why Write for an E-text Audience?

 

The basic position here is that computers are basically machines for

creating printed text. This position, contrary to the one taken here,

has a number of advantages:

 

(1) The resolution (appearance) of the final product is superior to

anything that can be created on the screen;

 

(2) Print media are easier to handle and browse;

 

(3) Paper is universally accepted and readable--no special hardware or

programs are required;

 

(4) The product is compatible with all the information-handling

systems that have been developed for paper (files, libraries,

catalogues, ... ); and

 

(5) The author's copyright is easier to maintain because the final

text is harder to copy.

 

These are overwhelming advantages. I call the resulting situation--

paper is the medium of storage and standard of communication while

computers and printers are just tools for creating paper--the "cellulose

interchange standard". It is well established; it works; and it is hard

to beat. It is the norm even in the computing world. The paper bias,

e.g. of word processors, is obvious.

 

Against this view is a reality of modern life: it is becoming very much

cheaper to store information in electronic form and comparatively more

expensive to store it as paper. Let's consider some facts:

 

o A 300 page book takes up a Megabyte of memory--around one 50 cent

floppy.

 

o CD-ROM storage lowers the cost to a few pennies for a book. A

single CD-ROM can store several hundred books.

 

o An 8 mm video tape can store several *thousand* books. This means

that the information in the Harvard University library system, one of

the world's largest (6 million volumes) would take up few thousand

cassette tapes presently costing less than $100,000.

 

Given that, in addition, you can

 

revise electronic text easily,

 

make copies faster,

 

send it further in less time and at less expense,

 

store it more cheaply,

 

print it out,

 

send it as a fax,

 

and convert it to other formats,

 

it will soon be a commonplace that *even for documents that are designed

to be printed out and looked at on paper* the principal means of storing

and exchanging information will be in electronic format.

 

So let's get this straight: we are not discussing whether it is better

to store and exchange information on paper or electronically. The bulk

of information will soon be stored on magnetic media and exchanged

electronically. What we are discussing is whether it makes more sense

to prepare *electronic* documents that look good printed out or ones

that look good on a screen.

 

Paper will become (in fact already is) a luxury reserved for the cream

of the information crop--just as four color printing is reserved for Art

books, glossy magazines, and advertising, while most other printed

information is black and white. You will want the 1% of your

information you use most often in print form. You won't be *able* to

get or afford print versions of most information, any more than you can

afford to buy everything in hard cover or print every brochure in four

colors.

 

And is this so bad? Why not have a good print library *and* good

electronic text. My public library, a very good one, has around 100,000

volumes and cost several millions to build. If I want something they

don't have, I have to wait a week for interlibrary loan, or a xerox

copy, or a fax. In most cases I would be happier with an electronic

version I can look at *today*.

 

The point is that paper doesn't compete with E-text, E-text is probably

information you *would not have* in any other form. It's books you

wouldn't have because you can't afford 1000 books right now (but you can

afford a couple of CD ROMs); it's text you can view (and download) at

your public library that the library couldn't afford in paper; and it's

free stuff that can't be distributed for free any other way, because

paper just costs too much.

 

Do you have to write E-text? You do if you want your audience to

include the 25 million people with E-mail access (projected to be 75

million in three years). You do if you want your message to travel as

far as possible--even if it is intended to be printed at the other end.

 

So you will write electronic text that will never be printed because you

*have to*. That means you need to learn to write effective E-text,

because there really is no alternative. Fortunately, if you can write

well in the print medium, you can write well in E-text. We'll give you

a few tips in a moment, but first we need to dispel the notion that it

is possible to write for both media at the same time.

 

 

<Section 1.2> Is it Possible to Write for E-text and Print at the Same

Time?

 

Here we come to the claim I made above, that it is impossible to satisfy

all three of these criteria with a single file:

 

(1) the file can be read by any computer

 

(2) the file creates good looking print

 

(3) the file looks good on the screen

 

You can pick two out of three, but you can't get all three. This is

unfortunate, but it is also true.

 

The only kind of file that is *universally* accepted is the plain text

file, also called the common =ASCII= file. Actually, even this is an

overstatement. ASCII, the American Standard Code for Information

Interchange, is a very specific code for representing text. A

*fraction* of that code can be translated without difficulty to

virtually all computers, including the fifty-two letters of the English

language (both upper and lower case), the ten digits, and a handful of

punctuation marks.** But the rest of ASCII--some punctuation marks and

special "control" characters used by computers (including the common

tab!)--are off-limits if you want your message to have a truly global

reach.

 

** It is important to remember that some files that need the full

ASCII repertoire, e.g. the source code of computer programs, may not

travel well.

 

Anyway, if you want a file that looks good in print (criterion 2) and is

also a plain text file (criterion 1), you *have* to give up criterion 3

--the file will not look good on the screen. This is because creating

"laser quality" output with a "book quality" appearance requires printed

commands, called =markup=, to be interspersed with text. This can be

minimized, but the cost is a text without even the visual effects that

are possible with a typewriter--underlining, superscripts and

subscripts, and diacritic marks to name a few. If you want these

effects and others typical of book-quality printing--multiple fonts,

automatic footnotes, and so on--then the markup burden makes the file

unpleasant to read, i.e. not effective as E-text.

 

Finally, the question of how to get as close as possible to satisfying

all three criteria and a discussion of formats and markup is left to

next chapter. There has been some success at creating files that look

good on the screen and in print--using so called WYSIWYG ("what you see

is what you get") word processors or using SGML ("Standard Generalized

Markup Language")--but these are not in universal use. I.e., you have

to give up criterion 1 to get numbers 2 and 3.

 

So right now the plain truth is you can have any two out of three but

not all three. Sorry.

 

 

<Section 1.3> Differences Between E-text and Print Media

 

Creating a manuscript on a computer is quite a different process from

the old fashioned method of revising a manuscript by (literally) cutting

an pasting typescript, of maintaining bibliographies, and of checking

spelling against a dictionary. Most of the peculiarities of using a

computer are true whether or not the output is meant to be the printed

page. Nevertheless, it helps to enumerate a few, since these

considerations apply in spades to producing E-text:

 

 

o Computer aided Research and Organization Methods

 

Note taking, creating bibliographies and databases, and gathering

information now involves all the techniques discussed in my course

notes, _EMAIL 101_.**

 

** Available free from:

 

//mrcnext.cso.uiuc.edu:/etext/etext93/email025.txt.

 

o Rigidity of Format and Outlining

 

Word Processing programs enforce a formatting and outlining discipline

to a degree that would be unusual in the old style. Outlining

encourages a strict hierarchical style and the automated formatting

features make for a more rigorous observance of whatever conventions are

built into the program used.

 

Rigorous formatting is a virtual requirement for E-text, since it is

otherwise impossible for programs to tell where a chapter starts, say,

or what portions of the text are italicized.

 

Spellchecking programs are another example of (welcome?) rigidity of

style imposed by the new methods. Rigorous spelling is what enables the

SEARCH command to find all references to a given subject.

 

o Incomplete drafts are more likely to be circulated

 

The ease of making changes leads to a more collaborative style of

working in which draft after draft (not uncommonly 10 or 20) is

circulated to a large group for comments. Often documents are *never*

final, but are instead continuously revised. It is useful to compare

this process to the way computer programs are written:

 

First a trial version, or "alpha" version is circulated to a few

select individuals.

 

Next a beta version, mostly complete and supposedly correct, is given

wide circulation as a trial balloon.

 

Finally there is a succession of ever more refined upgrades ranging

from minor changes to major "releases".

 

It is a good guess that most working documents will be produced in a

similar way. In a way, this is similar to the print industries

"editions" and "printings", except, like the manuscripts themselves,

there is more consciousness of the structure of the process when

computers are involved. Also, the cost of producing minor revisions is

less, so there is less fanfare for a new edition--and more trouble with

version control!

 

o Collaborative efforts are easier.

 

When the drafts we have been discussing are circulated by E-mail, the

working style discussed above becomes even more natural.

 

o Backup copies are necessary

 

Although one might take the precaution of xeroxing an important

manuscript, failing to make backups of works stored in magnetic media is

sheer folly for anything that takes longer than 15 minutes to write.

There is a whole new discipline of saving work frequently to disk,

copying it to backup floppies or tape, and so on.

 

 

<Section 1.4> Version Control

 

The problem of multiple versions is a big one any time the revision

process is easy or frequent. Most computer systems keep track of the

date a file was last modified--so you can tell which of seven files.**

But even time stamps won't help if some files are exact copies of

others--as they should be if you are doing proper backups. It helps to

use version numbers like "3.1.5a" to distinguish the multiple copies.

 

** (three on various floppies, one in a directory "/project/old" and

two in directory "/project/new", is the most current)

 

As with any tree structure,** it is often good to use =dotted decimal=

notation: Version 5.18.2 means release 2 of minor revision 18 of major

revision 5. Version 0.1 is probably a rough draft.

 

** This concept is discussed in part III of my course, _EMAIL 101_.

 

You have to be careful: this notation can either represent successive

versions or divergent versions. For example, 1.4.3 can mean the third

minor change to version 1.4, which was the fourth major change to

version 4. This is the most common scheme. It provides an odometer-

like method of numbering the versions. It differs from an odometer in

that you are not forced to increment the next place when you get to the

tenth revision. As long as the revision path is a straight line, with

each version being derived from the version before it, this scheme will

work.

 

It gets into trouble if there are any branches in the revision path.

Suppose two versions, [a] and [b], are both derived from 1.2. Does

1.2.1 refer to [a] and 1.2.2 to [b]? This is a natural way to describe

*branching* versions, i.e. with a tree notation, but you can't use both

schemes simultaneously.

 

It's a good bet that Version Control software--programs that keep track

of multiple versions, store them as "deltas", or difference files, to

save space, and allow you to recover *any* past version or display

differences between versions--will become more common and integrated in

word processing software.

 

 

 

<Part II> Specific Differences of Style and Mechanics

 

This part enumerates some of the differences between E-text and print

media and discusses them in a general way. Actual recommended practice

is deferred until Part III, which takes the form of a conventional style

manual.

 

In the long run, the reader will find the material in this part more

valuable than the style manual. The manual, after all, is only one

possible concrete realization of the principles discussed here. It is

better to give thought to these principles in the context of your own

writing than to slavishly follow the manual.

 

=Section 2.1= Differences Traceable to Physical Media

 

=Section 2.2= Differences in Style

 

=Section 2.3= Differences in Process

 

=Section 2.4= Differences in Repertoire

 

=Section 2.5= Differences in Layout

 

=Section 2.6= Searching and Hypertext

 

=Section 2.7= Copyright Issues

 

=Section 2.8= The Parts of a Book

 

=Section 2.9= The General Theory of Markup (SGML)

 

=Section 2.10= Summary: Basic Tricks of the Trade

 

 

<Section 2.1> Differences Traceable to Physical Media

 

The basic differences between E-text and print can be traced to the

physical differences of the media, and to the fact that the needs of the

human reader and computer must coexist.**

 

(1) The human's need for visual relief within a 24 line frame.

 

(2) The computer's need for a rigid hierarchy and consistent

spelling.

 

(3) The limitations of the =character set= available

 

(4) The limited possibilities of different renderings of the

characters, e.g. by font and placement on the page; and

 

(5) a consequent dependence on =delimiters= and structure for

rendering.

 

Taken together, these factors account, in the first instance, for most

of the differences that their are.between E-text and print. In this

Part we will primarily be working out the implications for representing

text and developing techniques for dealing with the limitations.

 

** I thank Michael Hart for pointing out this second requirement to

me.

 

The small viewing window of E-text--commonly 24 lines and often less--

has a number of consequences. Combined with the fact that moving around

within a document requires one of:

 

scrolling (moving a scroll bar with a mouse);

 

paging (hitting a single key, such as "return", repeatedly); or

 

searching (using special commands to find sequences of characters);

 

we can see why E-text is hard to navigate, or, as I say, E-text is less

perspicuous than print. I think this limitation of the medium is a

greater bar to its widespread acceptance than visual resolution.

 

This limited window and lack of perspicuity has a number of immediate

consequences for writing style:

 

(1) paragraphs must be short enough to present at least one break in

any given 24 line window.

 

For practical purposes paragraphs much over 10 lines are anathema. This

means that the flow of thought must be broken up on a finer scale than

is common in print--though not, perhaps, as radically as in newspapers.

 

(2) E-text is much more linear than print.

 

Signposts, such as enumeration and other cues, organization, and

arrangement in sequence are much more critical. The trick is to

structure your argument so that the mainline reader can read it in

sequence. Side-trips have a much higher penalty for the reader than in

print.

 

This statement, that E-text is more linear than print, seems to go

against the promise of "hypertext", i.e. documents in which you can skip

around to your heart's content. In fact, it is precisely because E-text

is so linear that hypertext is important. It makes navigating E-text

manageable.

 

The high penalty for skipping around (or passing through long sections)

has a number of other implications:

 

(1) tables of contents should be distributed throughout the text, as a

sort of preview of the following section.

 

In effect, these tables become "hypertext menus", allowing the reader to

locate the appropriate section with a SEARCH command. This gives as

much aid as possible to the reader. However, if the text is long and

there are many logical levels, then the full table of contents should be

provided at the *end* of the document (Not the beginning! We don't want

the reader to have to scroll past a very long table to begin reading.).

The Table of Contents is discussed at length in =Section =.

 

(2) footnotes should be located immediately after the paragraph to

which they refer.

 

An E-text is logically a scroll. There is no such thing as a "page",

except as a arbitrary marker added to synchronize the E-text version

with a print version. Because of the small viewing window, the only

place you can put a footnote is after the paragraph. In effect, it

becomes a "small print" section with added detail.

 

(3) bulleted lists should be relatively short and should not turn into

full-fledged tables.

 

Instead, they should be broken up into sub-lists if possible, with no

more than ten items in one run. Tables and long lists should be placed

in appendices or separate files unless they are exceptionally compact or

unless viewing them is necessary to the flow of ideas.

 

 

<Section 2.2> Differences in Style

 

The most marked characteristic of E-text style is brevity. We have

already commented on brevity of paragraphs. The same can be said for

the overall work. 200k, or about 70 printed pages, is already quite

long. A larger work should probably be broken up into 100-150k

segments.

 

Two other stylistic characteristics are =hierarchy= and =rigidity=.

Given that computers, in popular culture, are often associated with

mindless authority or fascism, these are not promising characteristics

for the would-be writer of E-text. The words "hierarchy" and "rigidity"

are just convenient labels, however. We could use more complimentary

terms, such as "logical organization" and "consistency of style".

 

In any event, the hierarchy and rigidity apply to the formatting and not

the ideas expressed. Qualities such as brevity, an organizational

structure that helps the reader, and consistency in spelling, grammar,

punctuation, and layout, are generally accounted hallmarks of good

style. In fact, their is a trend in print media towards these

qualities, as well as towards shorter paragraphs, perhaps occasioned by

the widespread use of computers for preparing printed text.

 

It might be said that the style advocated is essentially that of

journalism and the classic pyramid scheme for writing newspaper

articles. This is true to a point. E-text, however, is much more

linear than a newspaper article. Above the article level the typical

newspaper is a jumble of many articles bundled together in a very large

package. The E-text equivalent of a newspaper will almost certainly be

a large number of separate files, indexed and arranged in a directory

hierarchy.** Long files purporting to be E-journals are very tedious to

read, precisely because they violate the brevity maxim.

 

**In fact this is the case with Usenet Newsgroups.

 

 

Another stylistic difference is repetition. Saying the same thing

in different contexts, even verbatim, is more acceptable in E-text than

in print. Since it is harder to navigate E-text, repitition** saves the

readers time looking up references. Material that is repeated in

several places is a good candidate for a footnote or "small print"

section.

 

** Repetition is a technique widely used in computer programming to

save the time needed to follow up a reference. In this context it is

called "in-line coding".

 

On top of the major stylistic differences, there are numerous minor

points of grammar and markup (punctuation) that are covered in Part III.

These are almost at the quirk level, and have little effect on style

=per se=, so we don't consider them here.

 

 

<Section 2.3> Differences in Process

 

Electronic text and printed text created on computers are prepared in a

different fashion from print. E-text typically passes through more

stages and is in a rougher form than print. This does not prove that

print is a superior medium because the product is more polished; rather,

the capital investment required to produce *any* edition is so high that

intermediate drafts are too expensive to circulate. E-text creation is

more collaborative and not punctuated by such monumental milestones as

"first draft to printer" or "second edition". The stages tend to be so

incremental as to blend into each other.

 

Thus, "publishing" an incomplete or rough draft is appropriate for E-

text. The medium seems to invite statements that "this section is under

construction". I call this the =cathedral model= of text production. A

premium is placed on the execution of one's art, collaboration among

successive "generations", and grand design, but the product itself is

never really finished. The stages of the E-text production process are

discussed at greater length in =Section 2.3=.

 

The pervasive sense of hierarchy in E-text affects the writing process.

You might think that the rigid hierarchy leads to a top-down process in

which each section is outlined in excruciating detail and the writing

fills in the gaps. In fact, the actual process is a combination of this

and a bottom-up one in which sections are created piecemeal and tacked

together as ideas emerge. The ideal working style, like that of

building a cathedral, works from both ends. There is both a grand

design (far more ambitious than what the author can produce at the

moment) and whole sections that are created of a piece. Unlike

cathedrals, the parts can be re-organized with ease after construction.

 

 

There is another respect in which the E-text production process

differs from its print analogue. In E-text, self-publishing is the

norm. The low capital investment, both in equipment and training

required to create the text, all points to self-publishing as the most

economical distribution method. The traditional segmentation into

author, publisher, printer, distributor, follows the logic of the print

production process. E-text needs only an author and a distributor--the

distributor being a friendly archive site or bulletin board.

 

Print media can use this same simplified distribution scheme *if* it is

in electronic format. It is important to differentiate between

distributing E-text and distributing files that are intended to be

printed. The later are likely to have special markup, commands, or

formatting codes. Often they are binary (i.e. not text) files.

 

 

Since E-text is easily copied, far more so than text locked up in

proprietary formats, it presents a problem for compensating the author.

There are four suggested compensation schemes:

 

(freeware model) no compensation--the text is either in the public

domain or copyrighted but with a license for free distribution

 

The advantage of this model is that the work gains the widest possible

distribution. Without fee, license, or undue copyright restriction, the

work travels wherever it is wanted.

 

(shareware model) distribution is unrestricted but there is a

licensing fee for use.

 

This is an elegant solution to the compensation problem. Its reliance

on the honor system has drawbacks, however.

 

(proprietary model) distribution is restricted by licensing and

copyright.

 

This is the common method for distributing commercial software. In

effect it assimilates E-text to print media by artificially taking away

the natural ease of copying E-text.

 

(patron model) the work is commissioned and paid for by a patron--a

university, government, or other buyer. Since the work is paid for by

the patron, distribution can be free or by any of the other methods.

 

In fact, the patron model is the common, since royalties. Thus cries

that free distribution of E-text will destroy intellectual property are

have little merit. In fact, except in the commercial world,

intellectual property has little market value and is almost always a

public, not a private, good.

 

 

<Section 2.4> Differences in Repertoire

 

In addition to physical, stylistic, and process differences, E-text has

a different repertoire of visual techniques--and consequently different

problems. The major problem is the limited number of characters.

Unlike even the typewriter, E-text is limited to letters, numbers, and a

few punctuation characters *in a single font*. Print-oriented word

processors eliminate these restrictions, of course, but they remain for

E-text.

 

In addition, the visual effects are more limited even than the

typewriter's. Super- and subscripting are not possible, and certain

layouts involving lots of vertical space are ill-advised.** Finally,

graphic images are presently hard to include with text--at best they are

separate files distributed with the text and viewed with difficulty--and

such visual effects as parallel columns, and tabular layout do not work

well. They are not very robust in the E-text environment.

 

** more on this below, in =Section 2.5=.

 

The solutions to the character repertoire problem is to extend the

character set by a number of techniques:

 

o escape characters,

 

o delimiters, and

 

o tags.

 

An =escape character= is a rarely used character, such as the ampersand

or percent sign, that indicates the next character or characters is not

to be interpreted literally but as a symbol for some other character.

In effect, it acts as a sort of shift key to shift the character set.

Thus, "&e" might represent a Greek epsilon instead of an English [e].

 

=Delimiters= are pairs of characters used to mark off text. The equals

signs I have been using in place of italics are delimiters. So are the

asterisks I use if I *really* want to emphasize something. Delimiters

are so-called because they serve to "delimit" the text they enclose.

This strategy, widely used in E-text, replaces *rendering* by

*delimiting*.

 

A final technique is =tagging=. Tagging is discussed at length in

=Section 2.9= on markup. It extends the repertoire of delimiters by

combining delimiters and escape characters in a construct called a

<tag>. The tag is a logical unit that indicates an entity or logical

unit ("element") in the text.

 

The character repertoire problem becomes most acute when different fonts

or formulae are needed. Fonts are effectively handled by the techniques

discussed above, but formulas are a very sticky problem. Probably the

only solution is to realize that the notation we use for formulas grew

up in the handwritten environment. It has been brilliantly adapted to

print, but it's adaptation to E-text is new and awkward. All we can do

is let notation for formulas occurring in E-text evolve *without

reference to their print analogues*. The solution is not to

 

(a) give up and wait for multimedia; or

 

(b) to use print-oriented markup as an interim solution.

 

Programming languages have of necessity experimented with representing

mathematical formula. As E-text communication becomes more common,

conventions *will* evolve that are elegant and empower, rather than

hinder, communication. Some suggestions (and they are only that) for

mathematical notation are contained in Part III.

 

 

<Section 2.5> Differences in Layout

 

Layout of text on the page is one of the major differences between E-

text and print media. Naturally, this consideration is dominated by the

small viewing window of E-text. In E-text, the paragraph, not the page,

is the fundamental frame of reference for the reader.

 

o footnotes, as mentioned above, should be placed at the foot of

their *paragraphs*;

 

o manifestations of hierarchy at the chapter level or above do not

need the differentiated rendering (special indentation, typefaces,

capitalization, and the like) that they have in print media.

 

Instead high-level headings are optimized for searching, using a

consistent numbering scheme such as dotted decimal (e.g. 3.5.2)--or else

replaced by breaking the document into separate files.

 

 

Vertical and horizontal space is less important visually, because

the reader is conceptually "closer" to the text and unable to appreciate

such effects as indentation and vertical spacing. In particular:

 

o paragraphs should not be indented except to mark structural

features such as:

 

list items;

 

sub-paragraphs;

 

"small print"; and

 

minor section breaks.

 

Minor section breaks should have a larger indent than list items, to

distinguish the two.

 

o vertical spaces beyond five blank lines or so are an annoyance.

 

o lines printed with deep indentation in print media, e.g. letter

signatures, date and place of writing, and run-on lines in poetry,

should use some other device to set them off.

 

o unlike print, the visual effect of a block of text carries less

weight in E-text. Consequently you should not go to great

efforts to block text by hand like this paragraph--your

efforts will be wasted in a proportional font anyway.

 

Just as pushed margins are to be avoided in E-text, so attempting to

line up blocks of text in list items should be avoided. While this

visual effect works well in print, it is actually harder to read in E-

text.

 

On the whole, vertical and horizontal spacing merges with formal markup

in E-text, so that it becomes just one more way of delimiting text. Its

role in creating visually pleasing forms is very muted in E-text. Since

the reader is so close to the "painting", the effect, which depends on a

certain distance, is lost. E-text is not a medium that lends itself to

impressionism.

 

Combining "white space" role with the delimiting role is very much an

art. Functionality and minimalism are the main virtues of this art.

Mostly, it is a matter of being sensitive to the different needs of E-

text and print, and avoiding elaborate markup that mimics print

techniques that have little meaning for E-text.

 

 

Tables, multiple columns, and the like do not adapt well to E-text.

Although you might think that E-text is the medium =par excellence= for

tabular material, tables--perspicuous as they are in print--are very

difficult to navigate in E-text. They tend to be long *and* wide. This

is especially true of double-spaced tables common in typewritten text.

Also, E-text tables are difficult to transport and maintain, since

whitespace is the most unstable part of E-text. Various programs may

trim, condense, and reinterpret spaces, tabs, and returns.

 

A far better solution to viewing tables is to treat them as

spreadsheets. Spreadsheet programs, unlike word processors, are

optimized for viewing tables. I would rather have an table in Comma

Separated Value format that I can cut and paste into a spreadsheet

program than one formatted with spaces.**

 

** Admittedly, some, but not all, spreadsheet programs can handle

space formatting.

 

If you are tempted to include a long table in E-text, try to observe the

following:

 

o Put tabular material in appendices or in a separate file so the

reader is not forced to traverse it.

 

Last ditch: tell the reader how to jump over it, if it absolutely must

interrupt the flow of text.

 

o Redesign the data structure of the table so that it is as narrow as

possible, e.g. by breaking it into several logical units--sub-tables--

that can be related by an =index= or =key= column.

 

o Tabular material should have field delimiters other than spaces.

Commas are something of a standard, as are tabs, if portability is not

an issue.

 

Very often, a table that looks good in print has to be redesigned

altogether for E-text. You should constantly ask yourself *why* the

table is effective.

 

Does it have to be a table at all or is it really a list in disguise;

 

Does the tabular arrangement make the right comparison;

 

What is the main relationship a user will look for in the table?

 

One example of an organizing principle useful in print but less so in E-

text is alphabetical ordering. An alphabetical list is very effective

in print because it aids searching. It is also effective in E-text that

has to be *modified by hand*. But it is not effective in E-text that is

meant to be searched, because it gives up the chance for an alternate

organization of the material.

 

Besides tables, layout effects such as =parallel columns= should be

avoided altogether in E-text. The likeliest result is that the text

will be corrupted and rendered unreadable by a program somewhere along

the line.

 

E-text has very different visual needs from print. These are strongly

reflected in layout design. Writing visually appealing E-text requires

a conscious effort to meet the needs of the E-text medium on its own

terms. Whitespace, markup, and structure are all handled differently in

this new medium.

 

 

<Section 2.6> Searching and Hypertext

 

We have already discussed the SEARCH capability of E-text on a number of

occasions. In the present section we tie some of these strands

together, the most important of which is that

 

The author must be constantly aware of the need of the reader to

navigate their text by searching.

 

This imperative leads to a pervasive tendency in E-text: all manner of

references, cross-references, and indexing are replaced by a single

concept, the =pointer=. The pointer is a sequence of characters that

allows the reader to find the reference. This reference may be in the

present file, somewhere else in the same computer system, or in print.

In print, pointers take the following forms:

 

o cross-references (e.g., See page 37. See also "Dinosaurs").

 

o glossary and index references

 

o bibliographic citations

 

o mailing and telephony addresses

 

o subject classifications and shelf locations

 

To these the electronic medium (including E-text) adds:

 

o network and other information retrieval references

 

o hypertext links and menus

 

In E-text, the mechanism of pointing is the same for all these

categories, and =consequently the syntax should be the same also=.

Merely mimicking print forms of expression, with its elaborate

formatting rules for footnotes and bibliographies, obscures the

underlying unity of the "pointer" notion. In print, the visual

differentiation cues the reader in to the process required to resolve

(look up) the reference.

 

In E-text, great efforts should be expended to make the lookup process

the same for all manner of references. The main practical distinction

is between internal references and external ones. Part III discusses

this topic in greater depth.

 

 

<Section 2.7> Copyright issues

 

The most prominent characteristic of E-text, the ease with which it is

copied, leads to endless copyright headaches. Even the simplest E-text

is likely to sport a copyright, even if the author wishes to distribute

it for free, since otherwise who will know that it's for free?

 

Here we just present a few basic copyright concepts:

 

o Everything you "fix in a medium" (e.g., type into E-text) is

copyrighted, whether or not you have a notice, which merely announces

the fact that you have a copyright; or whether you have a registration,

which is legal evidence of your rights.

 

o *WHO* has the copyright is complicated. Usually the author; but it

could be their employer.

 

o Copyrights include the right to (1) copy, (2) distribute, (3)

display publicly, and (4) create derivative works. For other rights,

such as the right to sell these rights to other people and so on,

consult a legal manual.

 

o Copyrights, claimed or otherwise, remain in effect for a *long*

time. The "public domain" ends around 1917, with rare exceptions. If

you *place* your work in the public domain, that's another matter.

 

o A compromise between retaining all your copyrights and is a

"freelore copyright"++ like this manual's. You retain a copyright but

let others copy and distribute your work for free.

 

This is the preferred approach unless you think your work has commercial

value--or if you want to restrict distribution. It lets the work

circulate widely and, most importantly, gives permission to do so

without losing the work to the public domain.

 

You cannot use this method if you want others to be able to produce

"derivative works", however. For that, the Public Domain is your only

choice.**

 

** You could try to write an elaborate general public license, but

with few exceptions it is not worth it. Software source code and

educational curricula are likely exceptions to this rule.

 

++ The term "freelore copyright" is not a legal term. In programming

circles you will sometimes hear it called a GNU-like copyright, after

the GNU project, the first programming project to make extensive use of

a non-restrictive copyright for copyrighting software.

 

 

<Section 2.8> The Parts of a Book

 

In this section we take a brief tour of the typical book and make a few

observations along the way.

 

The front matter of an E-text differs somewhat from its print cousin,

the main virtue being brevity. No reader wants to scroll through page

after page of apparatus to get to text. In a book, it makes a great

deal of sense to put tables and reference material at both ends of the

book, these being the places one can find most easily. They are also

easy to reach in E-text, but most likely the reader wants to begin

reading quickly, so the front of the work, at least, is forbidden

territory.

 

An E-text should have the following frontmatter:

 

o cataloguing information (the title, author's name, preferred name

for the text file, subject classification, and how to get an electronic

copy, since the reader may, after all, be looking at a printout);

 

o an advertisement, abstract, or teaser to entice the reader;

 

o copyright information or terms of use (if too lengthy these should

be placed at the end with a pointer too them after the copyright

statement itself);

 

and THAT'S ALL. Do not ask your reader to scroll through more than

this. Tables of Contents and the like belong in appendices at the end

or in another file.

 

Whether or not you have an official Table of Contents or other indexing

material in an appendix, you should, at the beginning of each major

division, have a list of the contents of that section. You can think of

these as "menus". A merged version of all these local menus is needed

so the reader does not have to search through the entire document to get

an overview; neither should the reader have to scroll back and forth to

the beginning or end for help navigating. E-texts thus always have

*two* tables of contents.

 

The body of E-text is much like that of a print work, except for

comments pertaining to length, the pervasive sense of hierarchy (no more

than three local levels!), and the placement of footnotes after their

paragraphs.

 

The endmatter is likely to contain tables and bibliographies and

multiple indices, the *very last* of which is the Table of Contents.

The end of an E-text file is a very special place, because it is an easy

place to find; yet, unlike the front, few readers start there. It

should thus be the location of the most important navigation aid for the

document. Normally this is a full hierarchical list of the document's

contents with pointers back to the text.

 

With E-text, the notion of a Table of Contents and an Index is blurred.

In a book, the index really serves two purposes. It takes the place of

the SEARCH command in E-text, except that not every word is indexed

(barring the existence of a concordance, of course--a luxury in print).

 

It also serves as a schematic and *alternate* representation of how the

text might be organized. Most works could have been organized

profitably in more than one way. One way is fixed by the linear

organization of the text. The Index provides an alternate organization.

 

E-texts do not really need the first form of index. Computer programs

make their own search indices with lightening speed. In effect, you

have a concordance for every document. Alphabetic indices are of little

use. Not even hypertext programs can navigate them well. Either they

present a menu with 26 entries (too long!) or else you have to go

through two levels to get to your entry ("select A-G"). Even glossaries

are best arranged by topic and not alphabetically, since the

alphabetical order is irrelevant to the SEARCH command.**

 

**Not quite true: very long indices profit from "clustering", or

physical arrangement in search order.

 

Unless there is some reason that browsing topics in alphabetical order

might be interesting in itself, you shouldn't bother. Notice that this

is very different from electronic print, where the computer should

always be used to create an elaborate print index in the final print-

out.

 

The best way to think of an E-text index is as an alternate topical

organization of your work. It is especially useful if there are two (or

more) *hierarchical* ways to approach your subject. Your layout can

only show one way--echoed in your Table of Contents. The others have to

be represented by an index.

 

 

<Section 2.9> The General Theory of Markup (SGML)

 

The International Standards Organization (ISO) has developed a very

flexible standard for marking text, Standard Generalized Markup

Language.(SGML, or ISO-8879). SGML has a very flexible syntax for

describing the logical structure of documents. Its drawback is that,

like markup languages that are intended for print media, the burden of

the markup makes the text unreadable. SGML goes a long way towards

creating a text that can look good on paper, on the screen, or to a

program. The problem is that SGML software is not widely available, so

although SGML files are portable and *potentially* useful, there is

little use for them as yet. A widely available

 

SGML Tags are extraneous material used to mark a section of text. Along

with delimiters, they comprise the markup added to a text. A program

that uses the marked up text has to recognize delimiters and find the

tags. Since we are more or less following SGML, the tags themselves are

delimited by angle brackets, like this:

 

<outline>

 

The word "outline" is the =generic identifier= (GI) of the tag. The

left angle bracket is the Start-Tag-Open delimiter (STAGO); the right

angle bracket is the Tag-Close delimiter (TAGC). Ending tags look like

 

</outline>

 

The sequence "</" is the End-Tag-Open delimiter (ETAGO). The end tag

ends with TAGC, just like the opening tag. Thus paired tags themselves

become themselves a sort of delimiter, albeit at a higher level than the

delimiters they are built out of. They serve as a sort of named

parentheses to represent the "nesting" structure of the document.

 

Here is the hierarchical structure of the document represented as an

outline:

 

outline

 

chapter 1

 

section 1.1

 

footnote 1

 

chapter 2

 

section 2.1

 

footnote 2

 

section 2.2

 

In parenthesis notation (a common mathematical device), the same

structure looks like this:

 

(outline (chapter 1 (section 1.1) (footnote 1) ) (chapter 2 (section

2.1) (footnote 2) (section 2.2) ) ).

 

Maybe this is a bit more clear:

 

(outline

(chapter 1

(section 1.1)

(footnote 1)

)

(chapter 2

(section 2.1)

(footnote 2)

(section 2.2)

)

)

 

The parenthesis notation allows the tree structure of the outline, which

used to be represented only by the indentations, to be faithfully

represented even when the indentation is lost. I.e., we have a flexible

method of representing tree-structures in *running text*.

 

The parenthesis are delimiters whose purpose is to make clear the

nesting structure of the textual =elements=. If we think of SGML as

having "named parentheses" with <tag> being a left (opening) parenthesis

and </tag> being the matching closing parenthesis, we have:

 

<outline>

<chapter 1>

<section 1.1> Section 1.1 text ... </section>

<footnote 1> Footnote 1 text ... </footnote>

</chapter>

<chapter 2>

<section 2.1> Section 2.1 text ... </section>

<footnote 2> Footnote 2 text ... </footnote>

<section 2.2> Section 2.2 text ... </section>

</chapter>

</outline>

 

Notice the exact match between parentheses above and tags. Each text

element is clearly delimited. The section and footnote numbers only

appear in the opening delimiter as =attributes=. They would be

redundant in the closing delimiters.

 

The reason for the funny names, STAGO, ETAGO, TAGC, and GI, is that SGML

actually has an =abstract syntax=. The delimiters "<", ">", and "</"

could be any symbols at all (within reason). The choice shown here is

called the =Reference Concrete Syntax=. It is a particular choice for

the abstract syntax of SGML. In practice, you will almost always see

the standard choice.

 

In addition to the tagging of elements, SGML has a very general facility

for including text and making the sort of references we discussed in

=Section 2.6=. An =entity reference= is meant to be replaced either

with a character or with the contents of a file. It starts with an

ampersand (and-sign) and ends with a semicolon. Thus &file1; means

include file1 here. And if you can't type an "e" with an acute accent

on your keyboard you can use &eacute; to get the same effect. Of course

your entities have to be defined as part of your document's =entity

set=. SGML provides a way to do this.

 

SUMMARY: We have introduced the basic ideas of SGML: representing the

=logical structure= of textual =elements= using =tags= as delimiters;

the various parts of an opening and closing tag; entities for external

references and character substitution; and the notion of abstract vs.

concrete syntax. These ideas are useful in developing notations and

markup conventions.

 

 

<Section 2.10> Summary: Basic Tricks of the Trade

 

This part has covered a lot of ground. Creating E-text that is visually

pleasing and communicates effectively is an art. Some themes, driven by

the nature of the medium, recur over and over. I have summarized these

as a series of Tricks of the Trade:

 

TRICK 1: Replace visual rendering with delimiters and other markup,

but be sparing. The minimalist wins this game.

 

TRICK 2: Use a tree structure no more than three levels deep for the

basic hierarchy.

 

This trick goes hand in hand with the next:

 

TRICK 3: For more levels of hierarchy use data hiding techniques.

 

The point here is to remember that the reader has an unnaturally narrow

window on a very wide world. To avoid giving the reader the sense of

being helplessly lost, you *must* make an effort to keep the relevant

portion of reality small and easy to navigate.

 

TRICK 4: Use pointers to fill the roles of notes, cross-references,

bibliographic citations, hypertext links, etc.

 

Pointers are a recurring theme in computer science; they serve to unify

a whole series concepts that are visually distinct in the print media.

They are used to implement hierarchy and to allow "nonlinearity" in the

text.

 

TRICK 5: Think less in terms of traditional categories like "Table of

Contents" or "Index" and more in terms of data structure.

 

This trick follows naturally from the observation that logical structure

and not its rendering in a particular system should be primary. This is

a prerequisite for communicating with readers using *you know not what*

software or device.

 

TRICK 6: Use escape characters and tags to extend character set and

delimiter repertoire respectively.

 

TRICK 7: Formatting, rigorous markup that looks like visual layout,

can meet the needs of humans and computers.

 

The trick is to rigorously use sequences of characters (especially

"white space" like carriage returns and spaces) to create what appears

to be visual formatting. This simultaneously satisfies the human and

the computer. This is a nice trick, but hard to carry too far.

 

In all things use moderation. Being too clever or too idiosyncratic

usually marrs the effect for little gain. As always, the main trick is

to hide the effort that goes into the art, making the difficult look

easy.

 

 

 

<Part III> A Very Brief E-Text Style Manual

 

=Section 3.1= Backups and Saving Work

 

=Section 3.2= Compressed Files

 

=Section 3.3= Version Control

 

=Section 3.4= Use of Word Processing Features

 

=Section 3.5= Character Set and Font

 

=Section 3.6= Outlining and Hierarchies

 

=Section 3.7= Text Inclusions

 

=Section 3.8= Esoterica

 

This chapter is meant as a concrete example of the suggestions in the

previous two chapters, in the form of a "style manual". You should take

these guidelines as suggestions you may want to adopt, not as rigid

rules.

 

 

<Section 3.1> Backups and Saving Work

 

RULE 1.1 You should always keep two copies of any electronic text you

would mind not having one day, one on your hard disk and one on a

floppy. The floppy is far more likely to fail, so you should consider

keeping two floppies.

 

A common scheme if you don't work at home is to keep two backups, one at

home and one at work. Alternate which one you revise so that you will

always have the most recent one at home and the next most recent at

work. This is so that if a fire or other disaster destroys your work

records you still have the most recent copy.

 

If you work at home, make sure your two sets of backup disks are in

different places. That way an accident with a strong magnetic field

(found near motors, in telephones, in TV monitors, etc.)--or a spilled

cup of coffee--will not wipe out both copies.

 

RULE 1.2 (Archive copies) You should have *both* an archive copy of

each important "milestone" version *and* a set of backups. Backups are

usually snapshots of your system. If you delete a file from your hard

disk and then revise your backup, you will no longer have the file on

your backup disk! Even if you put your backup set aside from time to

time as an archive of "My System, December 1992", One day, you will

decide to recycle those disks and lose your copy.

 

The Moral: you need both an archive copy of each important project and

a revolving set of backup disks. (I call mine "A" for archives and "B"

for Backups).

 

Checklist:

 

o original working copy on hard disk

 

o second copy on hard disk for really important files

 

o daily archive of important work, organized by project

 

o most recent revolving backup set at another location (weekly or

monthly; more often for critical files).

 

o second most recent backup set on site.

 

Remember the basics: *at least* one backup and don't put your eggs all

in one basket. If you think I sound paranoid about this backup stuff,

trust me. Do this or you will get burned one day. I know what I am

talking about.

 

RULE 1.3 (Exception to Backups) An exception can be made for E-text

that can be easily obtained over the network if you don't modify it and

*if* getting a replacement would not be burdensome. In effect, the

network is your backup copy. But beware that what is on the network

today may not be there forever.

 

You can also "forget" about backups (but not archive copies) if your

computer is on a local area network and you know for a fact that backups

are made over the network on a regular basis. Many businesses,

recognizing that most persons would rather risk losing a months work

than spend five minutes backing it up, make systematic backups, often

using automatic systems that work at night, when the network is quite.

That is nice, but remember that you can still lose nearly an entire

day's work if disaster strikes just before you go home for the day.

 

RULE 1.4 (Saving Your Work) Unless your word processor has an autosave

and recover feature, you should develop the habit of saving your work at

least every fifteen minutes and whenever you get up to leave your

workstation.

 

 

<Section 3.2> Compressed Files

 

It is possible to compress text files to around half their original

size. Of course, you have to uncompress them before reading, but in

effect you can double your hard disk size with *software*. File

compression is becoming a standard feature of many programs and systems.

 

Compression works because text has very regular patterns that can be

encoded more compactly than the standard encoding. Files that have more

random bit patterns--binary files like programs or graphic images--

seldom compress more than a few percent.

 

RULE 2.1 Never compress any file except a text file.

 

I would be a bit leery of compression. It trades memory, which is

fairly cheap, for your time, which is expensive. Also, it complicates

the strategies your software has to use--what happens if your system

goes down in the middle of uncompressing an important file?

 

Compression is here to stay, but I recommend you follow this rule:

 

RULE 2.2 Only compress things you keep around for archival purposes--

old reports and projects, things you want at your finger tips but don't

use day-to-day.

 

To give some further guidelines, compression makes a lot of sense in

these cases:

 

o compressed files make good archive copies, at least if you are

keeping the file to feel safe and not because you need it regularly.

 

o compressed files are good for network transfers because, for text

files at least, they cut the time in half.

 

o more subtlely, there is a limit to the amount of hard disk you can

safely use--you shouldn't use more than you can backup in 10 minutes a

week or half an hour a month.

 

If you make your own backups on floppies, that means that 80 Megabytes

is about tops. More than that and you have 100 backup disks (times two

sets!) to deal with. Probably you get sloppy. File compression means

you can get twice as much stuff on your disk without increasing the

backup burden, so you save both time and space.

 

SUMMARY The most important thing to remember about file compression is

that there is a trade off between time and disk space. The fact that

you can get twice as much on your hard disk is traded against the fact

that it takes time to compress and uncompress files. Given that memory

is very cheap this is not always a good trade. The most likely outcome

is that by keeping too much useless stuff on disk you're setting

yourself up to waste a lot of time.

 

 

<Section 3.3> Version Control

 

Version control is important. It is easy to keep on top of *if* you

bother. If you don't, one day you will modify the second most recent

version of a long manuscript and then have to figure out the differences

between two variant documents and "merge" them into your next draft.

Then again, you could give up all the work you did and go back to the

old version. Or maybe you would like to follow this rule:

 

RULE 3.1 Versions should be numbered consecutively in "dotted decimal"

notation.

 

E.g., 2.4.1 means version 1 of sub-version 2.4 of main version 2.0. You

can add the version number to the heading of the file or make it part of

the file name. This is hardest to do in DOS, where filenames look like

DRAFT241.TXT meaning version 2.4.1.

 

Version 0.1 up to, but not including 1.0, are reserved for "drafts".

Version 1.0 is the first public release and Version 1.0.1 its first

minor revision.

 

RULE 3.2 In general, the primary version of your work should be in the

format your word-processing program considers to be "native". Plain

text files should be derived from this master copy.

 

Creating a plain text version and then re-importing it to the word

processor will often result in problems. The word processor's native

format (the one that understands all the nifty features) is proprietary;

i.e., it is not directly portable to other systems like plain text.

Something is lost translating proprietary format to plain text and back

again. The most common problems are:

 

o A "hard" return is located at the end of every line, making editing

difficult because you constantly have to adjust the length of each line

by hand, or else use the "fill" command on each paragraph;

 

o Unusual "line wraps" result from incompatible line lengths;

 

o Lists of items that are supposed to be on separate lines are

compressed into paragraphs;

 

o Visual formatting like the spaces or tabs before an indented block

quote, vertical bars alongside paragraphs, and similar things are

scrambled.

 

o Structures requiring elaborate spacing or tabbing like outlines,

tables, or section headings are confused;

 

o Double and single spacing is mixed up.

 

o Special symbols and codes are no longer readable.

 

These problems cause severe version control headaches unless you follow

the "master copy" strategy.

 

SUMMARY Strategies for avoiding these problems in general are given in

the next section. But in general you can avoid them if you follow this

basic strategy:

 

(1) Always consider native format the "primary" version and plain

text the "derived" version.

 

(2) Never use any feature of your word processor that can't be easily

translated into the plain text version.

 

The next two sections concentrate on just which features you can use.

 

 

<Section 3.4> Use of Word Processing Features

 

From the standpoint of creating effective E-text it is extremely

important to understand the following concepts:

 

hard return : a control character that signals the end of a line of

text. The actual code, an ASCII character, varies from computer to

computer. This is a source of many formatting problems.

 

filling : many word processors are capable of adjusting the length of

lines automatically in a process called paragraph filling. This can

either be automatic or on command. In the older method, the line

"wraps" when you reach the end, but if you make editing changes you have

to select the "fill" command. Newer word processors constantly refill

the paragraph as you make changes, adjust margins, etc.

 

formatting codes and markup : in order to represent all the effects

you can create on paper using a text file, it is necessary to add

additional characters that control the formatting of the document--

italics and underlining, fonts, superscripts, and the like. These codes

can be typed letters like ".cl" or "</p>"; or they can be "invisible" on

the screen but nevertheless present in the underlying file.

 

bit-mapped vs. character-oriented screens : The screen is represented

in the computer memory as a series of black and white dots, called

pixels ("picture elements"). There are two kinds of screens, those that

can only represent characters and those that can draw any graphic shape

(including any screen font ever devised, any line or shapes, patterns,

and complex artistic images like photographs and computer drawings).

Character-oriented terminals only have

 

WYSIWYG : "What You See Is What You Get" is a strategy adopted by many

word processing systems that run on bit-mapped terminals. A single

underlying file can create

 

font size and rulers : fonts in a traditional character-oriented

screen are all the same size--usually 80 or 132 characters per line. In

a bit-mapped system the fonts can have any size. Some fonts are fixed

width, meaning that any character takes up the same width (and hence

there are the same number in every line); in proportional fonts the

characters have different widths. The line expands and contracts when

you change letters.

 

 

With these concepts in mind, we can discuss how to create E-text

that is meant to be read as E-text. The main problem is that not every

word processor can read files from every other word processor. The

least common denominator is the plain text file, or ASCII file. ASCII

means "American Standard Code for Information Interchange". The ASCII

code includes the characters commonly found on an American typewriter

keyboard plus some "control characters" representing actions like

"carriage return" or "horizontal tab". The issue of which characters

you can use is discussed in the next section.

 

When using a word processor you have to be careful because it is not

always obvious which features will come out well in plain ASCII. Word

Processors compete on the basis of their wonderful features. Often,

however, the fancy features you paid for cannot be used in the real E-

text world. They are oriented towards producing pretty paper, but will

*confuse* other computers unless they are running identical software.

 

You will not be able to represent

 

o bolding

 

o italics

 

o underscores

 

o superscripts

 

o subscripts

 

o indenting and margins (except by spacing--not tabbing)

 

o soft returns

 

o multiple proportional fonts

 

o double columns

 

o special symbols or formulas

 

o included graphics and spreadsheets

 

and so on and so on. This means that you must forgo essentially

anything that needs a formatting code. In newer WYSIWYG word

processors, it may be hard to tell what is formatting and what isn't.

In general, you have to think like a typewriter. *sigh*

 

RULE 4.1 Change to a non-proportional font, preferably 10 point (elite)

or 12 point (pica) and 6 inch distance between margins. This works out

to 72 characters for elite or 60 for pica.

 

To be safe, lines should not exceed 72 characters; but in no event

should there be more than 80 characters without a hard return.

 

Actually, 60 characters per line (12-point non-proportional font with a

six inch ruler) is more portable, because it can be read both on

standard 80 character screens and with the default settings of most word

processors. If you use the 72 character line, some users may have to

select the whole text and convert it to Courier-10 to read it in a

WYSIWYG word processor without funny line wrapping. Not all users are

that sophisticated, so you are better off using a 60 character line

unless you have a special reason to go with 72. Also, short lines are

easier to read, as you will learn in any speed reading course.

 

RULE 4.2 Don't justify the text, but keep all text "ragged right", like

typescript.

 

RULE 4.3 Don't hyphenate words. Let the right column look uneven.

 

If someone is using a different screen width, your hyphenated word could

end up looking like "this in the mid-dle of the text". Also, SEARCH

commands choke on hyphenation. There is probably nothing you can do to

prevent your word processor from breaking words that have "real" hyphens

in them and happen to fall at the end of a line (remember this when

*you* have to search).

 

RULE 4.4 Start text flush with the left margin and don't add spaces to

create an indented effect. Do not use indentation, tab stops, or

spreadsheet like tables to format your text.

 

If you want to include spreadsheet data, use Comma Separated Value (CSV)

text like this:

 

"January Actual","January Budget" <hard return>

23201.45,20000.00 <hard return>

 

You can cut and paste this into any Spreadsheet program.

 

RULE 4.5 If you use the autofill feature to avoid having to type

return, make sure your word processing program has a feature that will

insert "hard" returns at the end of each line when you create your plain

text output file.

 

In Microsoft Word, this is the "Save as Text with Linebreaks" command.

If you use "Save as Text" you get returns at the end of every

*paragraph*, not every *line*. Someone with an old-fashioned text

editor--one that likes hard returns after every line--will see *very*

long lines (and probably truncate them to boot). You may have to

experiment to find the equivalent command in your system.

 

RULE 4.6 Don't use special characters like non-breaking spaces or

optional hyphens to dictate where line breaks occur. These features are

not portable.

 

RULE 4.7 Try to prevent your word processor from hyphenating words on

its own.

 

It's OK to break a word that has a "hard" hyphen at the hyphen. That

is, if a hyphen is a normal part of the word's spelling and the word

processor decides to break the word at the hyphen, don't worry. But you

should try to avoid breaking sentences that have dashes--like this--at

the double dash. Sometimes the word processor will break a double dash

in half.

 

RULE 4.8 Use single spacing with two hard returns between paragraphs.

 

Many WYSIWYG word processors allow single, double, or triple spacing

between lines. In the text file, however, there is not necessarily two

returns between each paragraph. Double spaced text *is* much easier to

read on a screen, but it is hard to re-paragraph. The two returns

between each line tend to make word processors think that each line is a

paragraph.

 

In general, it is easier to

 

RULE 4.9 Keep paragraphs short, say around 10 lines.

 

Paragraph breaks form a visual guide for the eye. A book that has

paragraphs spanning whole pages is hard to read. Similarly, on a 24

line screen it may be difficult to read paragraphs longer than 20 lines.

Even if you naturally express yourself in paragraphs of 7 to 10

sentences, you should break your progression of thought into shorter

segments after writing it down, if you want to reach your audience. If

I see a paragraph that fills the whole screen, I tend to want to scroll

down and skip ahead.

 

 

<Section 3.5> Character Sets and Fonts

 

In order to be portable, a document must be coded as a text file. The

American Standard Code for Information Interchange (ASCII) represents

each character as a seven bit number. There are variant dialects of

ASCII, especially for languages other than English, but the variations

do not affect the subset we will be discussing. In particular, there

are many extensions of ASCII to eight bits, of which Latin-1 is the most

popular. These extensions are *not* portable, and hence not discussed

further.

 

In order to be as portable as possible, ASCII text , or plain text, must

observe a number of conventions:

 

Rule 5.1 Use only the 84 character subset of ASCII consisting of the

twenty-six letters of the English alphabet (both upper and lower case),

the ten digits, and twenty-two punctuation marks in Table 1 below. Do

*not* use the ten bad characters:

 

o dollar sign

 

o pound sign (number sign)

 

o at-sign

 

o carat (circumflex)

 

o tilde

 

o back quote

 

o backslash

 

o vertical bar, and

 

o curly brackets

 

These symbols do not translate well into character sets in other

countries.

 

TABLE 1. The 22 Legal Punctuation Marks

o comma

 

o period

 

o colon

 

o semicolon

 

o exclamation point

 

o percent sign

 

o ampersand

 

o asterisk

 

o parentheses

o hyphen

 

o underscore

 

o plus sign

 

o equals sign

 

o square brackets

 

o apostrophe

 

o double quote

 

o angle brackets (less-than and greater-than signs)

 

o question mark

 

o and (forward) slash.

 

More briefly:

 

!%&*()-_=+[];:'",.<>?/

 

The reason why these characters are fine and others aren't is obscure.**

 

** There is an international standard, ISO-646 that adapts ASCII to

non-English languages. Part of its character set, the "invariant

subset", is the same on all keyboards. There are also obscure problems

translating ASCII to its IBM mainframe equivalent, EBCDIC. Even the 22

legal characters are too many in some circles.

 

RULE 5.2 The only "white-space" allowed are spacebar and line endings

(carriage returns). Horizontal tabs and other "control characters" are

not portable.

 

Actually you can use tabs for text that is not going to pass through

unusual or difficult conversions. For example, if you are sharing a

Spreadsheet by E-mail you can probably exchange a tab-formatted file

rather than using the (safer) Comma Separated Value format.

 

Sticklers will point out that Rule 5.2 means we allow an 87 character

subset of ASCII.

 

 

<Section 3.6> Outlining and Hierarchies

 

RULE 6.1 Impose a relatively rigid outline (hierarchy) on your

manuscript and reflect that hierarchy in a rigid formatting scheme for

the section and chapter headers.

 

E.g., this manual uses angle brackets *plus* two spaces *plus* a section

title. Each section is preceded by two blank lines, each part by three.

Sections are numbered in dotted-decimal form.

 

Conventions like these allow casual searching, or "navigation" of the

document. Unless you have a "hypertext" document that lets you skip

around easily, such guideposts are necessary.

 

 

In designing markup conventions, you should keep in mind that it is

more valuable to represent *logical* structure than to try to mimic the

*physical* appearance of a printed page. Thus,

 

o it is wasteful to use vertical space to try to mimic vertical

layout of a printed page, because the resulting effect looks

disconcerting on the screen. Use the number of blank lines to represent

the logical structure of the document instead.

 

o use flush left headers for the top levels, indent a couple of

spaces for lower level. At the very lowest logical level, just skip an

extra line between paragraphs and don't bother with a separate title for

the header.

 

o try "tagging" important breaks with special characters like angle

brackets, a row of hyphens "----------", or a decorative break like

this:

 

+ + +

 

o don't overuse all caps in titles, especially for Section breaks.

They scream too loudly. You can't really mimic the print-based effect

of small caps on the screen.

 

o don't bother developing elaborately different formats for headers

that are seen infrequently (e.g. chapters, parts, or "books").

Concentrate instead on the sections, sub-sections and minor breaks. The

"wide-area" structure is more simply represented by dotted-decimal and

the low level structure by visual formatting.

 

Remember that the global appearance of the document is much less

important than it is for a book, since the user never sees the document

as a whole, only small local sections. In fact, the highest level

logical divisions are probably not visual at all--they are the breaks

between computer *files*, or even a directory hierarchy. And--ever more

commonly--hierarchies of *computers*! This leads us to the next rule.

 

In preparing your outline, remember the following rule:

 

RULE 6.2 Never nest a hierarchy or outline more than three levels deep

without hiding some of the structure.

 

There is a great deal of structure in the computer world.

 

Countries contain

 

domains contain

 

networks contain

 

companies contain

 

individual computers (nodes) contain

 

directories contain

 

subdirectories contain

 

documents contain

 

chapters contain

 

sections . . . (*whew* that was ten levels).

 

You *must* try to hide some of this structure from your reader. The

easy way to do this is to narrow in on the local focus and pretend that

what we're looking at right now is the *only* thing in the world. It is

impossible to read a document and simultaneous think of its place in the

wide world. Forget the tree structure of the whole network or computer

system; let the reader focus on the local tree-structure.

 

And, whatever you do, don't let the reader know they are more than three

levels deep.

 

 

<Section 3.7> Text Inclusions

 

We have already discussed basic formatting issues like paragraphing,

line length, and basic layout. This section concentrates on the myriad

details that bedevil the typist. We save most of the *really* technical

stuff like tables, foreign languages, and formula, for =Section 3.9=.

In this section we discuss very common inclusions in text--

 

 

<Section 3.7.1> Alternate Fonts

 

RULE 7.1 Use markup to represent *logical* emphasis rather than

particular font effects.

 

Here are some typical reasons and traditional *print* renderings:

 

o emphasis (italics or underlining)

 

o strong emphasis (bolding, all caps)

 

o interior dialog (italics)

 

o editor's emphasis (italics)

 

o foreign language phrase (italics)

 

o book title (italics, underline)

 

o article title (quotation marks)

 

o new term, index term, glossary item (italics, quotes, underline)

 

As you see, italics are overused and the choices are not always

consistent. In order to make your meaning PERFECTLY CLEAR, it is best

to observe this rule:

 

RULE 7.2 Prefer delimiters for marking inclusions. Use different

delimiters for different purposes.

 

A delimiter is a character or pair of characters that is used fore and

aft to set off text.

 

It is not a bad idea to develop a set of guidelines for how to render

each sort of inclusion. Here is what I use:

 

o now *this* is emphasis (and *strong* emphasis)

 

o as I said, markup is part of =la vie=.

 

o or we can introduce a new "term" like this (See "taxonomy").

 

o book titles, like _Elements of Style_, are a snap.

 

I also have a series of conventions I use for special situations that

arise in scholarly text, such as multiple languages or included math

text.

 

By the way, avoid the effect that results when you try to

_mimic_print_media_by_underlining_in_this_fashion_. The result is

tedious and leads to long words that don't wrap well. In E-text, a pair

of underlines is just another delimiter, nothing more.

 

RULE 7.3 In E-text, always place punctuation *outside* delimiters.

 

Otherwise, the E-text looks "silly." Better: "silly".

 

In print, you put the punctuation after a quotation on the "inside."

This looks good in print but terrible on the screen. If your E-text is

destined for computer screens (and automated search programs) it is

better put the punctuation on the "outside". If this disturbs you,

remember that in the last century the printers rule (as I have seen in

many books,) was to put *commas* inside parentheses as well as inside

quotation marks. We are allowed to change these conventions from time

to time.

 

 

<Section 3.7.2> Quotations and Included Blocks of Text

 

There are a number of ways to include quoted or included

materials. One, favored in print, is to push the margin

of included text inwards, like this.

 

You should use this technique *very* sparingly. It requires a hard

return and hand spacing for each line. Reformatting (to shorten the

passage, say) is very difficult. WYSIWYG word processors let you shift

margins on a per-paragraph basis. This feature is not transportable so

you can't use it for E-text.

 

In E-mail correspondence you often see the convention that a right angle

bracket in the left column sets off correspondence. Often, this

continues to the point of inanity:

 

>>> I said I don't like the President's new policy

>> O yeah?

> Yeah.

O yeah?

> Not only that, you're an idiott

Well so are you. And you don't spell good either.

 

Our ability to reconstruct the whole train of correspondence is a poor

trade for legibility.

 

Another device to avoid is the frequent use of vertical bars alongside

text to indicate changes. Although most computer keyboards have a

"vbar" (usually a shift-backslash) this character does not travel well

and the visual effect is lost in some fonts or if the line length

changes.

 

An alternative to the vertical bar is to mark changed sections with

double brackets:

 

[[Our new improved widget has

a longer lifetime and

higher customer satisfaction

rating.]]

 

More elaborate schemes for marking changes are discussed in the section

on Editing and Marked Sections.

 

In summary, we have this rule:

 

RULE 7.4 Avoid block quotes and text with vertical lines to represent

additions or changes. Just use conventional quotation marks or a

special "delimiter" like double square brackets.

 

 

<Section 3.7.3> Lists

 

There are two basic kinds of list, ordered** and unordered. Unordered

lists often have "bullets" in front of the items.

 

** Also called enumeration's.

 

RULE 7.5 Indent list items at least two spaces and make sure list items

are in separate "paragraphs", i.e. with a blank line between each item.

 

This prevents formatting problems that occur when the word processor

decides that a list is actually a paragraph and pours it, bullets and

all, into a rectangular shape.

 

RULE 7.6 Do not use a "hanging indent" for list items. Let subsequent

lines run to the left margin.

 

o This is an example of a list item

that looks good in print but

is hard to re-format in E-text.

 

o This second list item is more typical

of E-text. You can reformat it without deleting

lots of spaces at the beginning of each line.

 

Also, as mentioned in Part II, the visual effect of straight line

margins is less important in E-text. You don't gain all that much

visually by going for the pretty-but-hard-to-format look.

 

 

<Section 3.7.4> Cross References, Hypertext, and Embedding

 

References to other parts of the text should be set off so they can be

found. Cross-references are of several sort, all related:

 

o Cross-References to other parts of the document: See Section 3.4,

See "UNIX" in glossary, Page 43.

 

These cross references are essentially pointers that urge you to leap

over the intervening text. This is easy in print media, where you have

all the pages in your hand. With a computer program you have to use the

comparatively clumsy method of manipulating the keyboard or mouse to

move around. With plain text, the only rational approach is to use the

"search" or "find" command of the word processor to locate the passage.

The art comes in guessing good "strings" (sequences of letters) to

"search" for.

 

o Hypertext references (outline overview, hypertext menu and

references)

 

Many word processors allow you to "navigate" a document by traversing an

outline overview. In what amounts to the same thing, "hypertext"

programs often implement the natural tree-structure of a document by a

series of menus representing the possible "branches" available at each

"node". This is the computer equivalent of the dime-store "interactive

adventure book" in which you get to choose the plot developments by

making choices like "If you want to rescue the damsel go to page 43; if

you want to kill the ogre, go to page 136."

 

o External File References

 

Here the point is that we can name other files and directories--and even

other computers, e.g. "rtfm.mit.edu:/pub/usenet" means subdirectory

"usenet" of directory "pub" on computer node "rtfm" at M.I.T.

 

o "Bibliographic Citations" of print media

 

The Bibliographic citation, either as a hypertext link in the text

(footnote) or as a list of references (menu) is a subject of great

attention in print media, with all sorts of elaborate formatting rules.

 

o Embedded Figures and Included Files

 

Very often, word processors (and long computer programs) have a master

file that looks something like this:

 

include <Front.Matter>

include <Chapter.1>

include <Chapter.2>

include <Chapter.3>

include <Chapter.4>

include <Chapter.5>

include <Appendix.A>

include <Index>

 

This master document sews together a bunch of smaller files. In

advanced programs, you may be unaware that this process, called file

inclusion, or embedding, is taking place.

 

File inclusion is especially common as a solution to the following

problem: how do you include material that is "foreign" to textual

matter, say a graphic image or drawing. If you just cut and paste the

text, the program will mistake it for part of running text, often with

dire consequences. The solution is to keep the offending material in a

separate file and have only the file reference in the text itself. Then

all the word processing program has to do is

 

You can immediately see that all these are applications of a single

idea, the idea of a "pointer", or "reference". One part of the document

points to another. We are supposed to imagine--and the program is

supposed to make us think--that there is a bridge from one place to

another, or that the reference can be expanded to that we can enter into

the other file or location and get back again. Thus, the "See

Reference", hypertext link, or external file reference really amount to

the same thing.

 

The point is that in all cases we need is someway to represent the

starting point (reference or pointer) and ending point (anchor point) of

the arrow. The World Wide Web uses Hypertext Markup Language (HTML).

An HTML cross-reference looks like this:

 

 

The corresponding target, or anchor, is marked this way:

 

 

 

One soon tires of making up unique names to allow each cross-reference

to mate with its anchor. It is more natural to use the document's

natural tree structure (perhaps represented by dotted decimal) for

anchor identification. Admittedly, this lends itself to dangling

references like "See page 25" when page 37 is the correct page for

version 2.3. Correcting these references is probably less work than

typing the ungainly syntax of an HTML cross-reference.

 

If we are not creating a source document to connect to the World Wide

Web, a simpler method is to delimit the reference with equals signs,

=See Index=, and the anchor point with angle brackets. This has an

added advantage if you are using equals signs to delimit italic text,

since glossary entries are often rendered in italics. You can see how

natural this is given the section marking scheme adopted here (See

=Section 26.6.4= below).

 

<=Index> This is the anchor point for the index reference made in the

above paragraph. The equals sign is optional. It just serves to mark

the tag <index> as an anchor point.

 

RULE 7.7 Delimit glossary entries, index entries, See references, and

so on with equals signs. Use a consistent notation, such as angle

brackets, to mark the anchor points.

 

The World Wide Web attempts to link documents with cross-references

(hypertext links) on a global scale. The notation developed for this

project is called a universal reference locator (URL) and is very

similar to

 

protocol://node:/directory/file:port

 

E.g.:

 

ftp://ftp.ncsa.uiuc.edu:/pub/education/README:80.

 

news://comp.sys.mac

 

The "protocol" part has to do with the method of getting the document

(and thus implicitly with the classification scheme). The examples here

are File Transport Protocol and Usenet News, two common document

retrieval systems. "ftp.ncsa.uiuc.edu" is a computer, "comp.sys.mac" is

a "newsgroup". "/pub/education/README" is a file in a directory called

"/pub/education"; and "80" is a "port number". These details only

concern the retriever, who may be just a computer program.

 

The URL notation is easily adapted to other hierarchical schemes used

outside the computing world, especially if the syntax rules are relaxed

a bit. Here are some ideas:

 

For Books:

 

dewey://stcharles.pub.lib:270.23.07:gilson:4 (St. Charles Public

Library, Dewey Decimal, Author Ettienne Gilson, copy 4).

 

LoC://QA.22.4: (a library of Congress citation)

 

ISBN://123-24-55

 

For a Journal Article:

 

journal://Time:1990.23.56-69

 

For the Phone System:

 

voice://1.708.840.8069 (A voice number)

 

fax://1.708.840.8069 (A FAX number)

 

internet://jgoodwin:adcalc.fnal.gov (E-mail address)

 

postal://Box.6022:St.Charles:IL:60174 (Surface mail)

 

Or something like that.

 

RULE 7.8 Use Universal Reference Locators (URLs) for worldwide computer

file references. Campaign for its extension to other obvious (paper and

telephonic) information sources.

 

 

<Section 3.7.5> Editing and Marked Sections

 

RULE 7.9 Indicate short deletions [and additions] with square brackets.

If you need to tell them apart add a plus or minus sign in front.

Indicate the version of the change by a version number (single number or

dotted decimal) after the sign.

 

This regulation shall apply to each +1[and every] tax payer -2[,

except members of this legislature].

 

We can thus reconstruct the history of this text:

 

Version 0: This regulation shall apply to each taxpayer, except

members of this legislature.

 

Revision 1: This regulation shall apply to each and every

taxpayer, except members of this legislature.

 

Revision 2: This regulation shall apply to each and every

taxpayer.

 

This principle can be extended to whole sections of text except that it

is better to use double square brackets since the text itself may

contain "innocent" brackets.

 

-2.3[[ . . . ]] means that this section is omitted in Version 2.3.

 

This notation soon becomes wearisome after multiple and intricate

revisions. Jim Warren has devised a visual format that makes collating

multiple versions in tabular or outline form:

 

012

This regulation shall apply to each

and every

taxpayer

, except members of this legislature

.

 

RULE 7.10 For complicated additions and deletions, such as those found

in legal matter, use Warren format.

 

Here are three examples of the formats we have been discussing:

 

 

[[include example here]]

 

 

One final rule:

 

RULE 7.11 Don't space between ellipsis. Instead, leave one blank space

before and after: ( ... ).

 

Word processors do not necessarily recognize ellipses as a single

"thing". The gracious effect of spacing created by a typewriter seems

lost on a computer screen.

 

 

<Section 3.7.6> General Style and Conventions

 

This section is about rules that are conventional to almost all typing.

A brief list is included here for completeness:

 

RULE 6.12 Add two spaces after each major break (period or question

mark, colon, etc.) and two spaces after minor pauses (comma, semicolon).

 

An exception is made for periods that are part of an abbreviation or

initials of a name, where the rule is:

 

RULE 6.13 Allow one space after each initial in a name but not between

initials of an abbreviation: J. E. Goodwin, St. Charles, Ill., U.S.A.

 

RULE 6.14 Represent a double dash with two hyphen and do not allow

spaces on either side of the dash--instead like this.

 

RULE 6.15 Certain Latin abbreviations do not have internal spaces, nor

are they in italics: i.e., e.g., etc.

 

 

 

<Section 3.8> Esoterica

 

99% of all ordinary E-text written in English does not need this

Section. But the issues discussed here greatly effect certain kinds of

text:

 

1. Texts requiring traditional scholarly adjuncts such as citations,

cross-references, indexing, bibliographies, glossaries, critical

apparatus, and figures;

 

2. Scientific and mathetmatical texts that use formulas extensively;

 

3. Statistical text with frequent use of numbers, uncertainties (plus

or minus), scientific notation, and tabular material. Such text occurs

commonly in the physical and social sciences, e.g. reports of

experiments.

 

4. Texts in one language that discuss another (language textbooks,

grammars, dictionaries, commentaries, many works in the humanities);

 

 

<Section 3.8.1> Inclusions in Languages Other than English

 

In English, where diacritical marks are rare, foreign languages are. It

is important to distinguish between =transcription= and

=transliteration=. In transcription, an attempt is made to render the

word as nearly as possible using the English alphabet, with or without

diacritics. Precision . Transliteration is an attempt to represent the

*spelling* of the word in the non-English alphabet. Great effort is

made, in designing the tranliteration system, to make the

transliteration reversible, so that the exact original text can be

recovered by a knowledgable human or program.

 

These two possible approaches to including non-English text lead to two

different rules, depending on intent:

 

RULE 8.1 Set off foreign phrases with the same delimiters used in place

of italics (usually equals signs).

 

RULE 8.2 Use special delimiters (for example plus signs or asterisks)

to signal special notations used for *tranliteration*.

 

No attempt is made to distinguish three uses of "equals-italics"--

foreign language italics, cross-reference signal, and miscellaneous

italics. As in print, these can usually be distinguished by context.

 

 

Beyond representing foreign phrases exactly, one might want an

informal notation for representing the diacritic marks that do

occasionally occur in English. Using these is probably pedantic in

ordinary E-text, but from time to time they may be useful, e.g. in

grammatical discussions:

 

RULE 8.3 In ordinary English texts it is not usual to use diacritical

marks, even when the English word technically has them, such as:

fac?ade, ro=le, coo%rdinate, blesse!d.

 

If absolutely necessary, we recommend:

 

acute accent: ne/e

 

grave accent: blesse!d

 

circumflex accent, tilde, or macron: ro=le, nolo= contendere

 

diaeresis or umlaut: coo%dinate

 

cedilla: fac?ade

 

The choice of symbols is based in portability (which excludes, for

example a tilde or circumflex). Also, the notation is just a little

ugly to discourage its overuse.

 

 

E-texts that discuss foreign languages present special problems.

Here are some suggestions:

 

1. The basic convention is that the primary language is unmarked, and

the secondary language delimited by asterisks: *E pluribus unum*, or by

equals signs =E pluribus unum=.

 

The choice of delimiter used requires some thought. In Latin, asterisks

should be used so that equals signs can be used to represent macrons:

 

Ve=ni=, vi=di=, vi=ci=.

 

Unless there are considerations like these, the asterisk is chosen for

the most frequent use in the text (usually italics-for-emphasis) because

it is less obtrusive and most conventional.

 

Since such text do not usually contain quotations, double quotes may be

used to represent translations or definitions:

 

=E pluribus unum= means "from many, one."

 

In printing, both the foreign text and the translations are often

rendered in a different style. If italics are needed for other

purposes, they should be delimited by asterisks:

 

=E pluribus unum= is *so* Eighteenth Century.

 

2. If the text contains a selection of many different languages,

special delimiters are used to segregate languages that use the Latin

alphabet from others. In this case no effort is made to choose one

secondary language as "the" secondary language. Instead, the delimiters

are used to mark alphabets that differ visually from the Latin alphabet.

 

= = Languages using the Latin Alphabet, other than the primary

language (in effect "language italics").

 

* * Greek

 

+ + Hebrew

 

/ / International Phonetic Alphabet

 

Other delimiters can be constructed =ad hoc=, such as &&[ ... ]&& or

+/ ... /, (* ... *) and so on.

 

Just a reminder: the recommendations here are strictly for informal use

in the context of "flat" ASCII files, e.g. for casual communication, or

as character-oriented output from a program that uses a proprietary

format or SGML for internal use. Any substantial work with multiple

languages is probably worth the effort to use something other than E-

text for the *underlying* representation. In particular, scholars

should consider the Text Encoding Initiative's recommendation.

 

Even with an elaborate underlying markup system, however, the problem

remains of how to render the foreign language text, perhaps a text that

does not even use the Latin alphabet, on a character-oriented screen.

 

 

<Section 3.8.2> Footnotes, Cross-References, and Bibliographic

Citations

 

There are two issues here: how to write the citation and where to put

it. As to the first issue, citation schemes that work well in print are

often cumbersome in E-text. The answer to the second issue is

 

RULE 8.4 Place footnotes at the foot of the paragraph, or else gather

them in an appendix at the end of the work.

 

Another common place to put notes, at the end of a Chapter, should be

avoided since it is a relatively hard place to find, compared to the end

of the file.

 

The inclusion of footnotes in the body of the text with special

delimiters, as is done by any word processors, is a concession to print-

oriented production of text. It places the footnote where the *program*

wants it. From the standpoint of the reader, there may as well not be a

footnote at all!

 

RULE 8.5 The footnote mark should be as unobtrusive and short as

possible: usually ** or ++, [34], or [Wells85].

 

. . . as discussed in the paper by Wells.[Wells85] Another . . .

 

. . . again makes this point in Ref.[36], where the bias . . .

 

. . . See the Nichomachean Ethics+[NE,1150a]. . . .

 

 

Footnotes with a single asterisk could be confused with an "emphasis"

delimiter. Putting asterisks in brackets, [*], seems long-winded.

 

RULE 8.6 Footnote sequencing should not continue across physical files.

Use dotted decimal notation to refer to "long-range" footnotes: [2.15]

means footnote 15 in chapter 2.

 

 

Designing a good bibliographic citation scheme for E-text means

breaking away from print models. Long dashes and hanging indents are

useless in E-text. Also, most readers, if they read notes at all, will

synchronize two windows so that notes can be read in one and the text in

another. *Therefore* it is better to make your annotated bibliography

follow chapter organization than to make it alphabetical or

chronological.

 

In general, it is a good idea to gather bibliographic references in one

place and *not* put them in footnotes, as is common in print. This is

because many of the citations will be URL's (see =Section 3.7.4=), which

mar the appearance of the text.**

 

** This assumes the E-text is not being prepared for linkage to the

World Wide Web! In this context, our discussion applies more to the

output of a WWW server than to its input.

 

 

<Section 3.8.3> Formulas and Statistical Text

 

There is a great deal of scope for developing new mathematical notations

that work well with E-text. I can only make a few recommendations and

observations here.

 

RULE 8.7 Use square brackets to set off "math italics", especially

variable names embedded in ordinary text. Omit the brackets for

displayed equations.

 

This rule is necessary to make variables stand out. Human eyes that are

used to picking out subtle font differences find it hard to read text

that refers to variables like a where a is the unknown. To repeat, [a],

where [a] is the unknown.

 

RULE 8.8 Separate displayed material by one blank line before and

after, and indent consistently (five spaces recommended).

 

Here is a well know example:

 

E = m c[2]

 

 

E[2] = p[2]c[2] + m[2]c[4]

 

where [E] is the total energy, [m] is the rest mass, and [c] is the

speed of light in a vacuum.

 

 

Scientific notation is a travesty in type. One commonly sees such

attempts as 1e12, 2.005+/-.01, or 2 x 10 5. We recommend quoting

numbers in the following fashion:

 

1.0E+12, 2.005(10), and 2.E+5.

 

To my eye, at least, the following rules are useful:

 

RULE 8.9A. Always use a sign after the "E" in exponential notation;

 

RULE 8.9B. Always express the decimal in floating point numbers and

precede a decimal point by a zero, i.e. 0.05, not .05.

 

RULE 8.9C Represent symmetric tolerances in parenthesis after the base

number.

 

A little care here is considerate of the reader and helpful for

subsequent typesetting.

 

RULE 8.10 In running text, superscripts and subscripts could be

represented the same way as footnotes in the main guidelines, viz.

 

2+[20] = 4+[10],

 

although the FORTRAN notation 2**20 = 4**10 is more perspicuous.

 

RULE 8.11 Subscripts and superscripts that do not represent powers but

represent labels, are conveniently handled like array subscripts:

 

a(1,3) = b(2,4) instead of a+[1]-[3] = b+[2]-[4].

 

The array indices might use square brackets instead of parentheses.

 

RULE 8.12 For the mixed case of subscripts for labeling and

superscripts for powers, we recommend:

 

a1[2] = a2[2] or a1**2 = a2**2 or a(1)[2] = a(2)[2].

 

The first approach is better suited for long formulas with many powers:

 

(x+y)[3] := x[3]+x[2]y+xy[2]+y[3]

(x+y)**3 := x**3 + x**2*y + x*y**2 + y**3.

 

RULE 8.13. Complex expression like summations and integrals can be

handled informally as follows:

 

(1/n)*sum(i=0,n; x(i)[2]) or int(x=0,infty;x[-2]).

 

RULE 8.14 Matrices, tables, and outlines are handled in a consistent

fashion.

 

7, 18, 19

-43, 72, 930.1

-1.1, 18, 100

 

Whereas in print vectors and Matrices are represented by boldface

letters, in E-text it is probably best to adopt Paul Dirac's bra-ket**

notation, first developed for Quantum Mechanics. Here, the vector "v"

is represented as [v>. This notation is well-developed and *can* be

typed in E-text.

 

** The name comes from the following construction: <bra] c [ket>.

The vector is called a "ket", the dual vector a "bra", and [c] is the

operator matrix.

 

 

<Section 3.8.4> Verse, Drama, and Liturgy

 

RULE 8.15 Each line is a separate paragraph. There should be two hard

returns between lines and three between stanzas.

 

Alternatively, two returns may mark stanzas, with lines beyond the first

indented by white space (one space recommended). Three returns can mark

longer segments. Only one of these two methods should be used in any

one work.

 

RULE 8.16 Do not try to mimic vertical or horizontal spacing of a

printed source, unless the visual effect of the poem is the main

concern.

 

RULE 8.17 Run on lines (say past 80 characters) can be represented by a

slash (/) at the beginning of the line.

 

RULE 8.18 An asterisk, *, is used to mark caesura, pause, or breathing

mark.

 

This should be preceded and followed by a space (or return) to prevent

its confusion with a footnote or emphasis delimiter.

 

RULE 8.19 Use asterisks to delimit stage directions or rubrics.

 

RULE 8.20 Use special delimiters to mark speakers, roles, or questions

and answers. Follow these with two spaces.

 

This helps the reader skip from part to part. Ampersands and periods

make unobtrusive delimiters. Brackets are visually more striking:

 

&Ham. To be or not to be.

 

&Pol. That is the question.

 

*or this*

 

&V. The Lord be with you.

 

&R. And with thy spirt.

 

*or this*

 

&Q.1.5 What is LINUX?

 

&A. LINUX is a small, free UNIX-like operating system for 386

computers.

 

 

<Section 3.9> Electronic Forms and Tests

 

E-text is often used as a medium for distributing forms, tests, and

other items to be filled out and returned. Often, these forms mimic

paper counterparts at the expense of their purpose--to be easy to fill

out and return. Here are some rules:

 

RULE 9.1 Avoid the multiple column format common on paper forms.

 

As soon as you start to fill out the form, the columns don't line up.

 

RULE 9.2 Skip a line between questions.

 

This avoids the dread re-formatting problem.

 

RULE 9.3 Place a left open bracket wherever an answer is required, but

not a right closing one at the end.

 

In order to fill in a checkbox, you have to position the cursor exactly

in the middle of the box, delete a character and type and "x". It is

easier to position a cursor at the end of the line and start typing

right away.

 

RULE 9.4 Avoid checkboxes. Ask for a one-character typed answer

instead.

 

RULE 9.5 Leave four hard returns (three blank lines) between "short

answer" questions

 

The responder begins typing at the beginning of the second blank line.

 

RULE 9.6 Do not use spaces or underscores to show blanks; use periods

or hyphens instead. Put them on the line *below* the response area (so

the responder doesn't have to erase them and lose count!).

 

Your state or province: [

--

 

Your zip or postal code: [

-----

 

This cues the responder as to desired length of the response. Blanks

are invisible, except in certain word processors, and underscores are

often run together, so you can't count them easily.

 

This sort of form is easy to fill out:

 

Your city of residence (20 characters max): [Chicago, Illinois

--------------------.

 

 

<Section 3.10> The E-Mail Business Letter

 

The paramount rule in writing an effective E-mail business letter is

brevity.

 

RULE 10.1 In general, you should omit as much of the traditional

apparatus of the business letter as you can,

 

since the mailing system may well add lots of unwanted detail. An

effective letter can be as short as:

 

From: jegoodwin

To: anotheruser

Subject: E-mail

<blank line>

This is what I have to say. =John=

 

RULE 10.2 Always begin E-mail with a single blank line.

 

This is to allow some visual separation from the mail header.

 

RULE 10.3 For short (one paragraph) messages, use only the paragraph

and your name, in-line with the last sentence.

 

Since brevity is the rule, anything beyond a one-paragraph note should

be carefully trimmed. The model below is about the *maximum* you can do

and still have a brief effective letter. Feel free to omit anything

unnecessary.

 

At most, an E-mail letter will have the following parts:

 

1. Mail Header

 

Do not add a letterhead** or mailing address. The mail system will add

enough garbage as it is. Your info goes at the end of the letter.

 

** An exception is in resumes and advertisements, where catching the

readers attention is of paramount importance. There, lots of whitespace

and visually arresting designs are welcome. The effect wears off

quickly, however, so think twice before adding eye-catching effects to

all your E-Mail.

 

2. Greeting

 

This is optional. "<skip one line>Dear Sir or Madam<Skip another line>"

(if you don't know the sex of the person you are writing--very

frequently the case, with E-mail), or "Dear George" or simply "George--"

 

3. Body

 

This follows the principles in the rest of this manual. Remember:

flush left.

 

4. Closing and Signature

 

The closing optional. "<skip line>Your Name<skip line>" is fine.

If you want one, don't indent it a half page, as is customary in print.

 

Suggested formal closings are "Sincerely", "[Best] Regards", and

"Thanks". I generally avoid "Thanks in advance", since it implies that

either you aren't thankful if the person doesn't respond (which is

ungracious); or you don't plan to thank them if they do (which is

churlish).

 

You may use special delimiters to mark your signature, but keep these

light and tasteful. I sign =John Goodwin=. Other persons use two

slashes before there name or add a plus (for clergy), etc., etc. This

is more distinctive than a signature file.

 

5. Contact information

 

Since the reader is most likely to contact you just after reading the

letter, but info here.

 

RULE 10.4 Keep contact information short, probably only your E-mail

address and phone number (two of each, at most)

 

RULE 10.5 Use the international style for phone numbers: e.g.,

+1 708 840 8069 (work).

 

Note: "+1" is the Country Code for the U.S.A.

 

RULE 10.6 Never, NEVER, include a character-drawing or funny quote in a

signature file.

 

////

[oo] <-- This is me!!! "Remember O Man that Dust Thou Art"

----

 

Many persons use a "dot-signature" file that is automatically appended

to all their E-mail. The effect is almost invariably puerile and

tasteless. If you include it twice you can add "incompetent" to the

list.

 

Here is how it looks all together:

 

To: blah blah

From: blah blah

Subj: blah blah

<--blank line required

Dear Sir or Madam: <-- or Dear George, or Dear Ms.Smith

 

[Body of text]

 

[Body of text]

 

[Last paragraph]

 

Sincerely, <--optional close

 

=Your name= <--use signature delimiters for visual effect

 

[Your Contact information]

 

 

<Section 3.11> The Final Rule

 

And lest the reader forget,

 

RULE B. All Rules are Made to Be Broken.

 

Rules summarize experience and judgment. In this manual I have tried to

reflect my own judgment as to what is appropriate, functional, and

aesthetically pleasing. I have not always succeeded. If I have spurred

the reader to consider their own style and refine it for their own

purposes, I will have achieved all my end in writing this manual. Above

all, remember, dear reader,

 

Question Authority. It's wrong.

 

 

+ + +

 

<Appendix A> Technical Details: Relationship to SGML and TEI

 

Many of the concerns addressed in this manual are common to participants

in the Text Encoding Initiative (TEI) and other users of the ISO

standard, Standard Generalized Markup Language (SGML, see =Section

2.9=). I would like to emphasize, for their benefit, that this manual

describes a *presentation format* and not an encoding format. It is

perfectly possible to create an SGML- or TEI-compliant file that uses

the format discussed in this manual as a visual output format.

 

There are very distinct advantages to having a visually appealing,

informal, character-oriented format, like the one advocated here, in

which the logical structure (i.e. markup) is still present, but not

visually intrusive. SGML compliant systems may well produce such a flat

file at the request of a user, or the screen output may be cut from the

program's display window and pasted into such a file. This style manual

has tried to describe design principles that will make the resulting

flat file useful and appealing to read.

 

Naturally, there are many uses for such a format outside SGML systems as

well; and a certain uniformity, or at least attention to design

principles, can only help make the texts created more useful.

 

The advantages of SGML or TEI encoding will only come about if word

processors that hide the markup process from the casual user become

commonplace and interoperable. Probably, a low-end freeware editing

system will have to be created.** Until that time, welcome or not, flat

ASCII is not only a visual format, but an interim interchange standard

as well.

 

** Such a system is being created for the LINUX operating system.

 

Once again: this is not a new encoding or input format, nor is it

primarily intended as an interchange standard; it is a suggested format

for visual *output* that happens to be maximally transportable at the

present moment.

 

+ + +

 

<Table I> Table of Contents

 

=Part I= Writing for an E-text Audience

 

=Section 1.1= Why Write for an E-text Audience?

 

=Section 1.2= Is it Possible to Write E-Text and Print at the Same

Time?

 

=Section 1.3= Differences between E-Text and Print Media

 

=Section 1.4= Version Control

 

 

=Part II= Specific Differences of Style and Mechanics

 

=Section 2.1= Differences Traceable to Physical Media

 

=Section 2.2= Differences in Style

 

=Section 2.3= Differences in Process

 

=Section 2.4= Differences in Repertoire

 

=Section 2.5= Differences in Layout

 

=Section 2.6= Searching and Hypertext

 

=Section 2.7= Copyright Issues

 

=Section 2.8= The Parts of a Book

 

=Section 2.9= The General Theory of Markup (SGML)

 

=Section 2.10= Summary: Basic Tricks of the Trade

 

 

=Part III= A Very Brief E-Text Style Manual

 

=Section 3.1= Backups and Saving Work

 

=Section 3.2= Compressed Files

 

=Section 3.3= Version Control

 

=Section 3.4= Use of Word Processing Features

 

=Section 3.5= Character Set and Font

 

=Section 3.6= Outlining and Hierarchies

 

=Section 3.7= Text Inclusions

 

=Section 3.7.1= Alternate Fonts

 

=Section 3.7.2= Quotations and Included Blocks of Text

 

=Section 3.7.3= Lists

 

=Section 3.7.4= Cross-References, Hypertext, and Embedding

 

=Section 3.7.5= Editing and Marked Sections

 

=Section 3.7.6= General Style and Conventions

 

=Section 3.8= Esoterica

 

=Section 3.8.1= Inclusions in Languages Other than English

 

=Section 3.8.2= Footnotes, Cross-References, and Bibliographic

Citations

 

=Section 3.8.3= Formulas and Statistical Text

 

=Section 3.8.4= Verse, Drama, and Liturgy

 

=Section 3.9= Electronic Forms and Tests

 

=Section 3.10= The E-Mail Business Letter

 

=Section 3.11= The Final Rule

 

 

+ + +

 

(end of _Elements of E-Text Style_)