Subject: Elements of Electronic Text Style 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. 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 é 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_)