🚀 go-pugleaf

------------------------(repeated header)-------------------------
Elements of E-Text Style
Version 1.0
9 August 1993

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


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

You may make and distribute verbatim copies of this work for non-
commercial purposes using any means, provided this copyright notice is 
included in all such copies.

Contact:  John E. Goodwin
          P.O. Box 6022
          St. Charles, IL  60174
          jegoodwin@delphi.com

[John Goodwin is available to consult, write, and teach courses on E-
text issues and Internetworking]


Abstract:  This manual discusses how to use electronic text (E-text) as 
a communications medium distinct from the print media.  The manual is 
written in a non-technical style, such as a humanist-of-little-brain 
might enjoy reading.  

  o  You can learn how to write effective E-text for personal, business, 
and scholarly communication.  

  o  It includes sections on preparing forms and texts for electronic 
response and on writing effective and business-like E-mail letters.  

  o  There is a brief section on Standard Generalized Markup Language, a 
coding standard of interest to humanists.


Just to prove how non-technical it all is, here is an exceptional lapse 
into technical jargon, in case you know what the Internet and FTP 
archives are:

    This work is a companion volume to _E-Mail 101_, available free as
    ftp://mrcnext.cso.uiuc.edu:/etext/etext93/email025.txt.


<title>  Elements of E-Text Style

  =Preface=     An Apology for E-Text

  =Part I=      Writing for an E-Text Audience

  =Part II=     Specific Differences of Style and Mechanics

  =Part III=    A Very Brief Style Manual

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

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

--------------------------(begin part II)----------------------------

<Part II>  Specific Differences of Style and Mechanics

This part enumerates some of the differences between E-text and print 
media and discusses them in a general way.  Actual recommended practice 
is deferred until Part III, which takes the form of a conventional style 
manual.  

In the long run, the reader will find the material in this part more 
valuable than the style manual.  The manual, after all, is only one 
possible concrete realization of the principles discussed here.  It is 
better to give thought to these principles in the context of your own 
writing than to slavishly follow the manual.

  =Section 2.1=   Differences Traceable to Physical Media

  =Section 2.2=   Differences in Style

  =Section 2.3=   Differences in Process

  =Section 2.4=   Differences in Repertoire

  =Section 2.5=   Differences in Layout

  =Section 2.6=   Searching and Hypertext

  =Section 2.7=   Copyright Issues

  =Section 2.8=   The Parts of a Book

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

  =Section 2.10=  Summary:  Basic Tricks of the Trade


<Section 2.1>  Differences Traceable to Physical Media

The basic differences between E-text and print can be traced to the 
physical differences of the media, and to the fact that the needs of the 
human reader and computer must coexist.**  

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

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

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

  (4)  The limited possibilities of different renderings of the 
characters, e.g. by font and placement on the page; and 

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

Taken together, these factors account, in the first instance, for most 
of the differences that their are.between E-text and print.  In this 
Part we will primarily be working out the implications for representing 
text and developing techniques for dealing with the limitations.

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

The small viewing window of E-text--commonly 24 lines and often less--
has a number of consequences.  Combined with the fact that moving around 
within a document requires one of:

  scrolling (moving a scroll bar with a mouse);

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

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

we can see why E-text is hard to navigate, or, as I say, E-text is less 
perspicuous than print.  I think this limitation of the medium is a 
greater bar to its widespread acceptance than visual resolution.  

This limited window and lack of perspicuity has a number of immediate 
consequences for writing style:

  (1)  paragraphs must be short enough to present at least one break in 
any given 24 line window.  

For practical purposes paragraphs much over 10 lines are anathema.  This 
means that the flow of thought must be broken up on a finer scale than 
is common in print--though not, perhaps, as radically as in newspapers.

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

Signposts, such as enumeration and other cues, organization, and 
arrangement in sequence are much more critical.  The trick is to 
structure your argument so that the mainline reader can read it in 
sequence.  Side-trips have a much higher penalty for the reader than in 
print.

This statement, that E-text is more linear than print, seems to go 
against the promise of "hypertext", i.e. documents in which you can skip 
around to your heart's content.  In fact, it is precisely because E-text 
is so linear that hypertext is important.  It makes navigating E-text 
manageable.  

The high penalty for skipping around (or passing through long sections) 
has a number of other implications:  

  (1) tables of contents should be distributed throughout the text, as a 
sort of preview of the following section.

In effect, these tables become "hypertext menus", allowing the reader to 
locate the appropriate section with a SEARCH command.  This gives as 
much aid as possible to the reader.  However, if the text is long and 
there are many logical levels, then the full table of contents should be 
provided at the *end* of the document (Not the beginning! We don't want 
the reader to have to scroll past a very long table to begin reading.).  
The Table of Contents is discussed at length in =Section =.

  (2) footnotes should be located immediately after the paragraph to 
which they refer.

An E-text is logically a scroll.  There is no such thing as a "page", 
except as a arbitrary marker added to synchronize the E-text version 
with a print version.  Because of the small viewing window, the only 
place you can put a footnote is after the paragraph.  In effect, it 
becomes a "small print" section with added detail.

  (3) bulleted lists should be relatively short and should not turn into 
full-fledged tables.  

Instead, they should be broken up into sub-lists if possible, with no 
more than ten items in one run.  Tables and long lists should be placed 
in appendices or separate files unless they are exceptionally compact or 
unless viewing them is necessary to the flow of ideas.


<Section 2.2>  Differences in Style

The most marked characteristic of E-text style is brevity.  We have 
already commented on brevity of paragraphs.  The same can be said for 
the overall work.  200k, or about 70 printed pages, is already quite 
long.  A larger work should probably be broken up into 100-150k 
segments.  

Two other stylistic characteristics are =hierarchy= and =rigidity=.  
Given that computers, in popular culture, are often associated with 
mindless authority or fascism, these are not promising characteristics 
for the would-be writer of E-text.  The words "hierarchy" and "rigidity" 
are just convenient labels, however.  We could use more complimentary 
terms, such as "logical organization" and "consistency of style".  

In any event, the hierarchy and rigidity apply to the formatting and not 
the ideas expressed.  Qualities such as brevity, an organizational 
structure that helps the reader, and consistency in spelling, grammar, 
punctuation, and layout, are generally accounted hallmarks of good 
style.  In fact, their is a trend in print media towards these 
qualities, as well as towards shorter paragraphs, perhaps occasioned by 
the widespread use of computers for preparing printed text.

It might be said that the style advocated is essentially that of 
journalism and the classic pyramid scheme for writing newspaper 
articles.  This is true to a point.  E-text, however, is much more 
linear than a newspaper article.  Above the article level the typical 
newspaper is a jumble of many articles bundled together in a very large 
package.  The E-text equivalent of a newspaper will almost certainly be 
a large number of separate files, indexed and arranged in a directory 
hierarchy.**  Long files purporting to be E-journals are very tedious to 
read, precisely because they violate the brevity maxim.

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


    Another stylistic difference is repetition.  Saying the same thing 
in different contexts, even verbatim, is more acceptable in E-text than 
in print.  Since it is harder to navigate E-text, repitition** saves the 
readers time looking up references.  Material that is repeated in 
several places is a good candidate for a footnote or "small print" 
section. 

  ** Repetition is a technique widely used in computer programming to 
save the time needed to follow up a reference.  In this context it is 
called "in-line coding".

On top of the major stylistic differences, there are numerous minor 
points of grammar and markup (punctuation) that are covered in Part III.  
These are almost at the quirk level, and have little effect on style 
=per se=, so we don't consider them here.


<Section 2.3>  Differences in Process

Electronic text and printed text created on computers are prepared in a 
different fashion from print.  E-text typically passes through more 
stages and is in a rougher form than print.  This does not prove that 
print is a superior medium because the product is more polished; rather, 
the capital investment required to produce *any* edition is so high that 
intermediate drafts are too expensive to circulate.  E-text creation is 
more collaborative and not punctuated by such monumental milestones as 
"first draft to printer" or "second edition".  The stages tend to be so 
incremental as to blend into each other.

Thus, "publishing" an incomplete or rough draft is appropriate for E-
text.  The medium seems to invite statements that "this section is under 
construction".  I call this the =cathedral model= of text production.  A 
premium is placed on the execution of one's art, collaboration among 
successive "generations", and grand design, but the product itself is 
never really finished.  The stages of the E-text production process are 
discussed at greater length in =Section 2.3=.

The pervasive sense of hierarchy in E-text affects the writing process.  
You might think that the rigid hierarchy leads to a top-down process in 
which each section is outlined in excruciating detail and the writing 
fills in the gaps.  In fact, the actual process is a combination of this 
and a bottom-up one in which sections are created piecemeal and tacked 
together as ideas emerge.  The ideal working style, like that of 
building a cathedral, works from both ends.  There is both a grand 
design (far more ambitious than what the author can produce at the 
moment) and whole sections that are created of a piece.  Unlike 
cathedrals, the parts can be re-organized with ease after construction.


    There is another respect in which the E-text production process 
differs from its print analogue.  In E-text, self-publishing is the 
norm.  The low capital investment, both in equipment and training 
required to create the text, all points to self-publishing as the most 
economical distribution method.  The traditional segmentation into 
author, publisher, printer, distributor, follows the logic of the print 
production process.  E-text needs only an author and a distributor--the 
distributor being a friendly archive site or bulletin board.  

Print media can use this same simplified distribution scheme *if* it is 
in electronic format.  It is important to differentiate between 
distributing E-text and distributing files that are intended to be 
printed.  The later are likely to have special markup, commands, or 
formatting codes.  Often they are binary (i.e. not text) files.


    Since E-text is easily copied, far more so than text locked up in 
proprietary formats, it presents a problem for compensating the author.  
There are four suggested compensation schemes:

  (freeware model)  no compensation--the text is either in the public 
domain or copyrighted but with a license for free distribution

The advantage of this model is that the work gains the widest possible 
distribution.  Without fee, license, or undue copyright restriction, the 
work travels wherever it is wanted.

  (shareware model)  distribution is unrestricted but there is a 
licensing fee for use.

This is an elegant solution to the compensation problem.  Its reliance 
on the honor system has drawbacks, however.

  (proprietary model)  distribution is restricted by licensing and 
copyright.

This is the common method for distributing commercial software.  In 
effect it assimilates E-text to print media by artificially taking away 
the natural ease of copying E-text.

  (patron model)  the work is commissioned and paid for by a patron--a 
university, government, or other buyer.  Since the work is paid for by 
the patron, distribution can be free or by any of the other methods.

In fact, the patron model is the common, since royalties.  Thus cries 
that free distribution of E-text will destroy intellectual property are 
have little merit.  In fact, except in the commercial world, 
intellectual property has little market value and is almost always a 
public, not a private, good.


<Section 2.4>  Differences in Repertoire

In addition to physical, stylistic, and process differences, E-text has 
a different repertoire of visual techniques--and consequently different 
problems.  The major problem is the limited number of characters.  
Unlike even the typewriter, E-text is limited to letters, numbers, and a 
few punctuation characters *in a single font*.  Print-oriented word 
processors eliminate these restrictions, of course, but they remain for 
E-text.

In addition, the visual effects are more limited even than the 
typewriter's.  Super- and subscripting are not possible, and certain 
layouts involving lots of vertical space are ill-advised.**  Finally, 
graphic images are presently hard to include with text--at best they are 
separate files distributed with the text and viewed with difficulty--and 
such visual effects as parallel columns, and tabular layout do not work 
well.  They are not very robust in the E-text environment.

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

The solutions to the character repertoire problem is to extend the 
character set by a number of techniques:

  o  escape characters, 

  o  delimiters, and

  o  tags.

An =escape character= is a rarely used character, such as the ampersand 
or percent sign, that indicates the next character or characters is not 
to be interpreted literally but as a symbol for some other character.  
In effect, it acts as a sort of shift key to shift the character set.  
Thus, "&e" might represent a Greek epsilon instead of an English [e].  

=Delimiters= are pairs of characters used to mark off text.  The equals 
signs I have been using in place of italics are delimiters.  So are the 
asterisks I use if I *really* want to emphasize something.  Delimiters 
are so-called because they serve to "delimit" the text they enclose.  
This strategy, widely used in E-text, replaces *rendering* by 
*delimiting*.

A final technique is =tagging=.  Tagging is discussed at length in 
=Section 2.9= on markup.  It extends the repertoire of delimiters by 
combining delimiters and escape characters in a construct called a 
<tag>.  The tag is a logical unit that indicates an entity or logical 
unit ("element") in the text.

The character repertoire problem becomes most acute when different fonts 
or formulae are needed.  Fonts are effectively handled by the techniques 
discussed above, but formulas are a very sticky problem.  Probably the 
only solution is to realize that the notation we use for formulas grew 
up in the handwritten environment.  It has been brilliantly adapted to 
print, but it's adaptation to E-text is new and awkward.  All we can do 
is let notation for formulas occurring in E-text evolve *without 
reference to their print analogues*.  The solution is not to

  (a) give up and wait for multimedia; or

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

Programming languages have of necessity experimented with representing 
mathematical formula.  As E-text communication becomes more common, 
conventions *will* evolve that are elegant and empower, rather than 
hinder, communication.  Some suggestions (and they are only that) for 
mathematical notation are contained in Part III.


<Section 2.5>  Differences in Layout

Layout of text on the page is one of the major differences between E-
text and print media.  Naturally, this consideration is dominated by the 
small viewing window of E-text.  In E-text, the paragraph, not the page, 
is the fundamental frame of reference for the reader.  

  o  footnotes, as mentioned above, should be placed at the foot of 
their *paragraphs*;

  o  manifestations of hierarchy at the chapter level or above do not 
need the differentiated rendering (special indentation, typefaces, 
capitalization, and the like) that they have in print media.  

Instead high-level headings are optimized for searching, using a 
consistent numbering scheme such as dotted decimal (e.g. 3.5.2)--or else 
replaced by breaking the document into separate files.


    Vertical and horizontal space is less important visually, because 
the reader is conceptually "closer" to the text and unable to appreciate 
such effects as indentation and vertical spacing.  In particular:

  o  paragraphs should not be indented except to mark structural 
features such as:

    list items;

    sub-paragraphs;

    "small print"; and

    minor section breaks.

Minor section breaks should have a larger indent than list items, to 
distinguish the two.

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

  o  lines printed with deep indentation in print media, e.g. letter 
signatures, date and place of writing, and run-on lines in poetry, 
should use some other device to set them off.

  o  unlike print, the visual effect of a block of text carries less
     weight in E-text.  Consequently you should not go to great
     efforts to block text by hand like this paragraph--your
     efforts will be wasted in a proportional font anyway.

Just as pushed margins are to be avoided in E-text, so attempting to 
line up blocks of text in list items should be avoided.  While this 
visual effect works well in print, it is actually harder to read in E-
text.

On the whole, vertical and horizontal spacing merges with formal markup 
in E-text, so that it becomes just one more way of delimiting text.  Its 
role in creating visually pleasing forms is very muted in E-text.  Since 
the reader is so close to the "painting", the effect, which depends on a 
certain distance, is lost.  E-text is not a medium that lends itself to 
impressionism.  

Combining "white space" role with the delimiting role is very much an 
art.  Functionality and minimalism are the main virtues of this art.  
Mostly, it is a matter of being sensitive to the different needs of E-
text and print, and avoiding elaborate markup that mimics print 
techniques that have little meaning for E-text.


    Tables, multiple columns, and the like do not adapt well to E-text.  
Although you might think that E-text is the medium =par excellence= for 
tabular material, tables--perspicuous as they are in print--are very 
difficult to navigate in E-text.  They tend to be long *and* wide.  This 
is especially true of double-spaced tables common in typewritten text.  
Also, E-text tables are difficult to transport and maintain, since 
whitespace is the most unstable part of E-text.  Various programs may 
trim, condense, and reinterpret spaces, tabs, and returns.

A far better solution to viewing tables is to treat them as 
spreadsheets.  Spreadsheet programs, unlike word processors, are 
optimized for viewing tables.  I would rather have an table in Comma 
Separated Value format that I can cut and paste into a spreadsheet 
program than one formatted with spaces.**

  ** Admittedly, some, but not all, spreadsheet programs can handle 
space formatting.

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

  o  Put tabular material in appendices or in a separate file so the 
reader is not forced to traverse it. 

Last ditch:  tell the reader how to jump over it, if it absolutely must 
interrupt the flow of text.

  o  Redesign the data structure of the table so that it is as narrow as 
possible, e.g. by breaking it into several logical units--sub-tables--
that can be related by an =index= or =key= column.

  o  Tabular material should have field delimiters other than spaces.  
Commas are something of a standard, as are tabs, if portability is not 
an issue.

Very often, a table that looks good in print has to be redesigned 
altogether for E-text.  You should constantly ask yourself *why* the 
table is effective.  

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

  Does the tabular arrangement make the right comparison;

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

One example of an organizing principle useful in print but less so in E-
text is alphabetical ordering.  An alphabetical list is very effective 
in print because it aids searching.  It is also effective in E-text that 
has to be *modified by hand*.  But it is not effective in E-text that is
meant to be searched, because it gives up the chance for an alternate 
organization of the material.

Besides tables, layout effects such as =parallel columns= should be 
avoided altogether in E-text.  The likeliest result is that the text 
will be corrupted and rendered unreadable by a program somewhere along 
the line.

E-text has very different visual needs from print.  These are strongly 
reflected in layout design.  Writing visually appealing E-text requires 
a conscious effort to meet the needs of the E-text medium on its own 
terms.  Whitespace, markup, and structure are all handled differently in 
this new medium.


<Section 2.6>  Searching and Hypertext

We have already discussed the SEARCH capability of E-text on a number of 
occasions.  In the present section we tie some of these strands 
together, the most important of which is that

     The author must be constantly aware of the need of the reader to 
navigate their text by searching.

This imperative leads to a pervasive tendency in E-text:  all manner of 
references, cross-references, and indexing are replaced by a single 
concept, the =pointer=.  The pointer is a sequence of characters that 
allows the reader to find the reference.  This reference may be in the 
present file, somewhere else in the same computer system, or in print.  
In print, pointers take the following forms:

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

  o  glossary and index references

  o  bibliographic citations

  o  mailing and telephony addresses

  o  subject classifications and shelf locations

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

  o  network and other information retrieval references

  o  hypertext links and menus

In E-text, the mechanism of pointing is the same for all these 
categories, and =consequently the syntax should be the same also=.  
Merely mimicking print forms of expression, with its elaborate 
formatting rules for footnotes and bibliographies, obscures the 
underlying unity of the "pointer" notion.  In print, the visual 
differentiation cues the reader in to the process required to resolve 
(look up) the reference.  

In E-text, great efforts should be expended to make the lookup process 
the same for all manner of references.  The main practical distinction 
is between internal references and external ones.  Part III discusses 
this topic in greater depth.


<Section 2.7>  Copyright issues

The most prominent characteristic of E-text, the ease with which it is 
copied, leads to endless copyright headaches.  Even the simplest E-text 
is likely to sport a copyright, even if the author wishes to distribute 
it for free, since otherwise who will know that it's for free?

Here we just present a few basic copyright concepts:

  o  Everything you "fix in a medium" (e.g., type into E-text) is 
copyrighted, whether or not you have a notice, which merely announces 
the fact that you have a copyright; or whether you have a registration, 
which is legal evidence of your rights.

  o  *WHO* has the copyright is complicated.  Usually the author; but it 
could be their employer.

  o  Copyrights include the right to (1) copy, (2) distribute, (3) 
display publicly, and (4) create derivative works.  For other rights, 
such as the right to sell these rights to other people and so on, 
consult a legal manual.

  o  Copyrights, claimed or otherwise, remain in effect for a *long* 
time.  The "public domain" ends around 1917, with rare exceptions.  If 
you *place* your work in the public domain, that's another matter.

  o  A compromise between retaining all your copyrights and is a 
"freelore copyright"++ like this manual's.  You retain a copyright but 
let others copy and distribute your work for free.  

This is the preferred approach unless you think your work has commercial 
value--or if you want to restrict distribution.  It lets the work 
circulate widely and, most importantly, gives permission to do so 
without losing the work to the public domain.

You cannot use this method if you want others to be able to produce 
"derivative works", however.  For that, the Public Domain is your only 
choice.**

  ** You could try to write an elaborate general public license, but 
with few exceptions it is not worth it.  Software source code and 
educational curricula are likely exceptions to this rule.

  ++ The term "freelore copyright" is not a legal term.  In programming 
circles you will sometimes hear it called a GNU-like copyright, after 
the GNU project, the first programming project to make extensive use of 
a non-restrictive copyright for copyrighting software.


<Section 2.8>  The Parts of a Book

In this section we take a brief tour of the typical book and make a few 
observations along the way.

The front matter of an E-text differs somewhat from its print cousin, 
the main virtue being brevity.  No reader wants to scroll through page 
after page of apparatus to get to text.  In a book, it makes a great 
deal of sense to put tables and reference material at both ends of the 
book, these being the places one can find most easily.  They are also 
easy to reach in E-text, but most likely the reader wants to begin 
reading quickly, so the front of the work, at least, is forbidden 
territory.

An E-text should have the following frontmatter:

  o  cataloguing information (the title, author's name, preferred name 
for the text file, subject classification, and how to get an electronic 
copy, since the reader may, after all, be looking at a printout);

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

  o  copyright information or terms of use (if too lengthy these should 
be placed at the end with a pointer too them after the copyright 
statement itself);

and THAT'S ALL.  Do not ask your reader to scroll through more than 
this.  Tables of Contents and the like belong in appendices at the end 
or in another file.

Whether or not you have an official Table of Contents or other indexing 
material in an appendix, you should, at the beginning of each major 
division, have a list of the contents of that section.  You can think of 
these as "menus".  A merged version of all these local menus is needed 
so the reader does not have to search through the entire document to get 
an overview; neither should the reader have to scroll back and forth to 
the beginning or end for help navigating.  E-texts thus always have 
*two* tables of contents.

The body of E-text is much like that of a print work, except for 
comments pertaining to length, the pervasive sense of hierarchy (no more 
than three local levels!), and the placement of footnotes after their 
paragraphs.

The endmatter is likely to contain tables and bibliographies and 
multiple indices, the *very last* of which is the Table of Contents.  
The end of an E-text file is a very special place, because it is an easy 
place to find; yet, unlike the front, few readers start there.  It 
should thus be the location of the most important navigation aid for the 
document.  Normally this is a full hierarchical list of the document's 
contents with pointers back to the text.

With E-text, the notion of a Table of Contents and an Index is blurred.  
In a book, the index really serves two purposes.  It takes the place of 
the SEARCH command in E-text, except that not every word is indexed 
(barring the existence of a concordance, of course--a luxury in print).  

It also serves as a schematic and *alternate* representation of how the 
text might be organized.  Most works could have been organized 
profitably in more than one way.  One way is fixed by the linear 
organization of the text.  The Index provides an alternate organization.

E-texts do not really need the first form of index.  Computer programs 
make their own search indices with lightening speed.  In effect, you 
have a concordance for every document.  Alphabetic indices are of little 
use.  Not even hypertext programs can navigate them well.  Either they 
present a menu with 26 entries (too long!) or else you have to go 
through two levels to get to your entry ("select A-G").  Even glossaries 
are best arranged by topic and not alphabetically, since the 
alphabetical order is irrelevant to the SEARCH command.**

  **Not quite true: very long indices profit from "clustering", or 
physical arrangement in search order.

Unless there is some reason that browsing topics in alphabetical order 
might be interesting in itself, you shouldn't bother.  Notice that this 
is very different from electronic print, where the computer should 
always be used to create an elaborate print index in the final print-
out.

The best way to think of an E-text index is as an alternate topical 
organization of your work.  It is especially useful if there are two (or 
more) *hierarchical* ways to approach your subject.  Your layout can 
only show one way--echoed in your Table of Contents.  The others have to 
be represented by an index.


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

The International Standards Organization (ISO) has developed a very 
flexible standard for marking text, Standard Generalized Markup 
Language.(SGML, or ISO-8879).  SGML has a very flexible syntax for 
describing the logical structure of documents.  Its drawback is that, 
like markup languages that are intended for print media, the burden of 
the markup makes the text unreadable.  SGML goes a long way towards 
creating a text that can look good on paper, on the screen, or to a 
program.  The problem is that SGML software is not widely available, so 
although SGML files are portable and *potentially* useful, there is 
little use for them as yet.  A widely available 

SGML Tags are extraneous material used to mark a section of text.  Along 
with delimiters, they comprise the markup added to a text.  A program 
that uses the marked up text has to recognize delimiters and find the 
tags.  Since we are more or less following SGML, the tags themselves are 
delimited by angle brackets, like this:  

     <outline>

The word "outline" is the =generic identifier= (GI) of the tag.  The 
left angle bracket is the Start-Tag-Open delimiter (STAGO); the right 
angle bracket is the Tag-Close delimiter (TAGC).  Ending tags look like 

     </outline>

The sequence "</" is the End-Tag-Open delimiter (ETAGO).  The end tag 
ends with TAGC, just like the opening tag.  Thus paired tags themselves 
become themselves a sort of delimiter, albeit at a higher level than the 
delimiters they are built out of.  They serve as a sort of named 
parentheses to represent the "nesting" structure of the document.

Here is the hierarchical structure of the document represented as an 
outline:

     outline

       chapter 1

         section 1.1

         footnote 1

       chapter 2

         section 2.1

         footnote 2

         section 2.2

In parenthesis notation (a common mathematical device), the same 
structure looks like this:

   (outline (chapter 1 (section 1.1) (footnote 1) ) (chapter 2 (section 
2.1) (footnote 2) (section 2.2) ) ).

Maybe this is a bit more clear:

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

The parenthesis notation allows the tree structure of the outline, which 
used to be represented only by the indentations, to be faithfully 
represented even when the indentation is lost.  I.e., we have a flexible 
method of representing tree-structures in *running text*.

The parenthesis are delimiters whose purpose is to make clear the 
nesting structure of the textual =elements=.  If we think of SGML as 
having "named parentheses" with <tag> being a left (opening) parenthesis 
and </tag> being the matching closing parenthesis, we have:

   <outline>
      <chapter 1>
         <section 1.1> Section 1.1 text ... </section>
         <footnote 1> Footnote 1 text ... </footnote>
      </chapter>
      <chapter 2>
         <section 2.1> Section 2.1 text ... </section>
         <footnote 2> Footnote 2 text ... </footnote>
         <section 2.2> Section 2.2 text ... </section>
      </chapter>
   </outline>

Notice the exact match between parentheses above and tags.  Each text 
element is clearly delimited.  The section and footnote numbers only 
appear in the opening delimiter as =attributes=.  They would be 
redundant in the closing delimiters.  

The reason for the funny names, STAGO, ETAGO, TAGC, and GI, is that SGML 
actually has an =abstract syntax=.  The delimiters "<", ">", and "</" 
could be any symbols at all (within reason).  The choice shown here is 
called the =Reference Concrete Syntax=.  It is a particular choice for 
the abstract syntax of SGML.  In practice, you will almost always see 
the standard choice.

In addition to the tagging of elements, SGML has a very general facility 
for including text and making the sort of references we discussed in 
=Section 2.6=.  An =entity reference= is meant to be replaced either 
with a character or with the contents of a file.  It starts with an 
ampersand (and-sign) and ends with a semicolon.  Thus &file1; means 
include file1 here.  And if you can't type an "e" with an acute accent 
on your keyboard you can use &eacute; to get the same effect.  Of course 
your entities have to be defined as part of your document's =entity 
set=.  SGML provides a way to do this.

SUMMARY:  We have introduced the basic ideas of SGML:  representing the 
=logical structure= of textual =elements= using =tags= as delimiters; 
the various parts of an opening and closing tag; entities for external 
references and character substitution; and the notion of abstract vs. 
concrete syntax.  These ideas are useful in developing notations and 
markup conventions.


<Section 2.10>  Summary:  Basic Tricks of the Trade

This part has covered a lot of ground.  Creating E-text that is visually 
pleasing and communicates effectively is an art.  Some themes, driven by 
the nature of the medium, recur over and over.  I have summarized these 
as a series of Tricks of the Trade:

  TRICK 1:  Replace visual rendering with delimiters and other markup, 
but be sparing.  The minimalist wins this game.

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

This trick goes hand in hand with the next:

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

The point here is to remember that the reader has an unnaturally narrow 
window on a very wide world.  To avoid giving the reader the sense of 
being helplessly lost, you *must* make an effort to keep the relevant 
portion of reality small and easy to navigate.

  TRICK 4:  Use pointers to fill the roles of notes, cross-references, 
bibliographic citations, hypertext links, etc.

Pointers are a recurring theme in computer science; they serve to unify 
a whole series concepts that are visually distinct in the print media.  
They are used to implement hierarchy and to allow "nonlinearity" in the 
text.

  TRICK 5:  Think less in terms of traditional categories like "Table of 
Contents" or "Index" and more in terms of data structure.

This trick follows naturally from the observation that logical structure 
and not its rendering in a particular system should be primary.  This is 
a prerequisite for communicating with readers using *you know not what* 
software or device.

  TRICK 6:  Use escape characters and tags to extend character set and 
delimiter repertoire respectively.

  TRICK 7:  Formatting, rigorous markup that looks like visual layout, 
can meet the needs of humans and computers.

The trick is to rigorously use sequences of characters (especially 
"white space" like carriage returns and spaces) to create what appears 
to be visual formatting.  This simultaneously satisfies the human and 
the computer.  This is a nice trick, but hard to carry too far.

In all things use moderation.  Being too clever or too idiosyncratic 
usually marrs the effect for little gain.  As always, the main trick is 
to hide the effort that goes into the art, making the difficult look 
easy.

-------------------(end part 2 of 3)--------------------------