Help |
Home »
Technical Notes
The Elements of
ATI Style
by John Bullitt
Although I have found traditional editorial tools (see the References) indispensible, the peculiarities of HTML and the ideosyncrasies of this website call for something more: hence this style sheet. These notes summarize some of the trickier points of style that I've had to address in my work on Access to Insight, plus a few basic matters of style that I always seem to forget. These notes were originally intended for my own use (I refer to them often), but just in case anyone else might find them useful, here they are.
Here and there I include references (in bold) to pertinent sections or pages in the References.
Three Principles:
- Preserve the integrity of the texts
The superficial aspects of texts (layout, spelling, obviously misplaced commas, etc.) may be modified, but never the content, without the approval of the author or publisher.
When I extract individual suttas from books, however, I sometimes simplify or remove the footnotes for ease of reading. The original notes are always left intact in the books. Compare, for example, Piyadassi Thera's translation of the Ratana Sutta as it appears in his book The Book of Protection with its appearance as an individual sutta.
- Consistency is the goal.
There are many different rules for spelling: American or British? brahmin or brahman? Nibbana or Nirvana?. Pick one or the other and stick to it. Mixing up styles distracts the reader. It is inexcusable for a single document to contain both "flavour" (British) and "color" (American).
- Absolute consistency is not the goal.
This website includes texts provided by many different authors and publishers, each of whom has his or her preferred standards of style. Rather than try to blindly force everything into a single, unified style, I've instead tried to preserve consistency within each particular genre or category of texts: sutta translations tend to follow one style; books in the Buddhist Publication Society's Wheel series follow another; articles by the Thai forest ajaans follow another; and so on.
For the most part I use a very limited subset of HTML 3.2, for several reasons:
1. The simpler the HTML, the easier it is to develop and manage a large website.
2. The simpler the HTML, the less likely that compatibility problems will arise with any particular browser software.
3. These texts are meant to be read. There's no need to spice them up with all the latest HTML bells, whistles, and other cute distractions.
4. Some people like to reformat HTML files into other text file formats (such as plain, unformatted ASCII). It's a simple matter to strip off the HTML tags. But what happens, for example, to "ordered lists" (<ol>...</ol>)? When the HTML disappears, so do the numbers. This can make the converted ASCII files hard to read. Nowadays there are lots of programs for converting HTML into all sorts of other formats, but never assume that everyone has access to these programs.
Use American English (color, flavor, practice, etc.) throughout (6.3CMS13). Webster's Ninth New Collegiate Dictionary (W9) is usually my referee (see 6.1CMS13), although sometimes the OED is a helpful background tool. Where W9 gives two or more spellings for a word, I use the first (preferred) spelling. Spellings are never altered in proper names (e.g., "International Meditation Centre" and The Splendour of Enlightenment: A Life of the Buddha).
British |
American |
Notes and tips |
arbour
behaviour
colour
endeavour
favour
fervour
flavour
harbour
honour
humour
labour
odour
savour
splendour
|
arbor
behavior
color
endeavor
favor
fervor
flavor
harbor
honor
humor
labor
odor
savor
splendor
|
Be careful when making global changes -- you don't want to change devour, nourish, flourish, etc. And watch for prefixes and suffixes (dis-, un-, -able, -ite, -ing, -ably, etc.). |
practise |
practice |
|
analyse |
analyze |
Beware of analyses (pl. of analysis) |
authorise
criticise
memorise
|
authorize
criticize
memorize
|
Search for oris. |
skilful
fulfil
|
skillful
fulfill
|
|
centre
centring
lustre
meagre
metre
|
center
centering
luster
meager
meter
|
Don't change centred to centerd! |
cheque |
check |
|
learnt |
learned |
|
plough |
plow |
|
Other words to watch out for:
- English words:
- catalog, but dialogue, epilogue, prologue (W9)
- quarreled, quarreler, quarreling (W9)
- traveled, traveler, traveling (W9)
- website (one word -- not web site or web-site)
There is no consensus yet on the "correct" spelling of this word. There are good arguments either way: website would find good company alongside other familiar contractions, such as bandwagon, heartbeat, and meatball, while web site is consistent with band shell, heart attack, and meat locker. I can't think of any good examples of hyphenated compound nouns that might lend support to web-site (heart-like and meat-flavored don't count, as each one is built from a noun plus an adjectivial combining form). Some people prefer Web site (capitalized), in deference to "World Wide Web" (always capitalized). But I prefer the simple, unadorned, compactness of website. Time will tell.
- Awakening is capitalized only when specifically referring to the enlightenment experience (bodhi):
- "a factor for Awakening" (MN 118)
- "Before my Awakening, when I was still an unawakened Bodhisatta" (MN 4)
- "I describe this as an awakening to the truth" (MN 95)
- "Directly awakening & breaking through to that" (SN XII.20)
- Foreign words:
- ajaan (not ajarn, ajahn, achaan, etc.)
- brahman (not brahmin, as preferred by W9).
Ajaan Geoff has pointed out that brahman is more sensible since it's more akin to the Pali brahmana from which the English word is derived.
- "a historical" (not "an historical"). (6.49CMS13)
Some authors claim that "an historical" avoids confusion with the word ahistorical, but I stick with CMS13.
- ñ comes after n
- Be alert to the peculiarities of word order in Asian titles and honorifics. These names:
Ajaan Lee
Bhikkhu Bodhi
Phra Ajaan Thate
Sayadaw U Ba Khin
Thanissaro Bhikkhu
Upasika Kee Nanayon
would be correctly alphabetized thus:
Ba Khin, Sayadaw U
Bodhi, Bhikkhu
Kee Nanayon, Upasika
Lee, Ajaan
Thanissaro Bhikkhu
Thate, Phra Ajaan
- en dash (5.92ffCMS13). Use one hyphen with no spaces.
- em dash. Use two hyphens surrounded by single spaces. Leading space is omitted when the dash appears at the beginning of a line (e.g., at the beginning of a line in a block quote).
- Quotation marks: Nested quotes are first double, then single, then double, etc. (10.24CMS13). The back quote (`) is never used for a left single quote. No spaces between quote marks. Commas and periods are always inside quote marks. Exceptions: if including the punctuation inside the quote marks would introduce some sort of ambiguity, then keep that punctuation outside the quote marks. For example, if a filename containing a period is quoted, any following punctuation should appear after the closing quote mark. (e.g., Download the file "bulk.zip". -- not Download the file "bulk.zip.")
- Ellipsis. Always use three points (never four) (10.38CMS13). Ellipsis immediately follows the last letter or punctuation mark, and is usually followed by a single space. When the ellipsis begins a quote or paragraph, it is not followed by a space.
- "He directly knows water as water... fire as fire... wind as wind..." [MN 1]
- "Then does Master Gotama hold the view: 'The cosmos is finite: only this is true, anything otherwise is worthless'?"
"...no..." [MN 72]
- "...'after death a Tathagata neither exists nor does not exist'... does not lead to disenchantment, dispassion, cessation; to calm, direct knowledge, full awakening, Unbinding." [MN 72]
- I.e. and e.g. Always followed by a comma (PTO98 and 5.54CMS13).
Block quotations (usually verse), are not enclosed by quotation marks, since the context usually makes clear that it is an utterance (10.28CMS13). Where there is a dialogue taking place within the verse, however, quote marks are used.
If the translator uses square brackets to attribute a verse passage, the attribution should be italicized. Example (SN IX.6):
They don't know bliss
who haven't seen Nandana,
abode of the eminent devas,
glorious,
of the Thirty-three.
[Ven. Anuruddha:]
You fool, don't you know
the arahants' maxim? --
...
- Use minimal white space in source files. The HTML source files should be free of blank lines (except, of course, in preformatted blocks of text). No line should contain either leading or trailing white space. Use only single spaces between words and sentences. Where wider spacing is necessary (as in preformatted text, or in free verse), use as needed (see Tabs, below). Exception: tabs may be included in a source file if they are needed to make the HTML code readable.
- Tabs. These are simulated with the use of three consecutive non-breaking spaces ( ), followed by a space. If the tab comes after a word or punctuation, be sure to precede it with a space. For example:
"With what is the world tied down?
- Two blank lines. To insert two consecutive blank lines, use:
<p>
<br><p>
Sutta file names
- File names should allow for sensible alphabetic sorting. For example, consider these files, arranged in alphabetical order:
an10-176.html
an3-35.html
an4-37.html
an4-5.html
Not very helpful. Instead, use zeroes as placeholders:
an03-035.html
an04-005.html
an04-037.html
an10-176.html
- When there is more than one version (translation) of a sutta, append a letter to the filename, starting with 'a':
mn010.html
mn010a.html
mn010b.html
mn010c.html
Use left adjusted <h4>, preceded by two blank lines, followed by one blank line (for friendly tag-stripping). Text in the subheading is Title Case, in parens.
... here is the end of the previous section.
(This is a Subheading)
And here we begin a new section...
E.g., DN 12. (Note: MN 125 also uses <h5> sub-subheadings.)
In Glossaries, entries should be in bold, followed by a colon:
Abhidhamma (Pitaka): The third of the three collections forming the Pali Canon...
Arahant: A "worthy one" or "pure one," i.e., a person whose heart no longer...
- Short tables. Use five consecutive points to simulate tabs in short lists (or tables) of items:
AN ..... Anguttara Nikaya
MN ..... Majjhima Nikaya
SN ..... Samyutta Nikaya
Vism ..... Visuddhimagga
-
Avoid using ordered lists (<ol>...</ol>). They look nice on most browsers, but the numbers evaporate when stripping the tags to make a text-only version. Here's one solution:
Here is a list of things, using the standard HTML ordered list:
- This is the first thing.
- This is the second thing.
- This is the third (and final) thing.
And here is the text that follows the list...
And here is the same list, without using an HTML ordered list:
i. This is the first thing.
ii. This is the second thing.
iii. This is the third (and final) thing.
And here is the text that follows the list...
- "Long" notes (say, longer than a ¶ or two) are <H3>Translator's Introduction</H3> (left, not center). E.g., MN 1.:
Translator's Introduction
Here is a long chunk of introductory text for this sutta...
- "Short" notes (a short ¶ or so) are <b>Translator's Note:</b> (e.g., MN 44):
Translator's note:
Here is a short bit of introductory text for this sutta...
- Endnote tags always come immediately after any punctuation (no space), in square brackets (not superscript).
- At bottom of page, "Notes" is flush left, not centered; if only one note, use "Note".
...
and so therefore thus and henceforth it was, nonetheless, "such-and-such."[1] On the other hand, therefore, in conclusion, it should be said, however, that, thanks to the obfuscatory possibilities of language,[2] the absence of sense is the sine qua non of nonsense.
...
Notes
1. This should not be confused with "this-and-that." [Go back]
2. Not to mention that which is unworthy of mention. [Go back]
- Abbreviate "translator" with "trans." and "editor" with "ed." (16.24CMS13):
The Lion's Roar: Two Discourses of Buddha (Bhikkhu Ñanamoli, trans.; Bhikkhu Bodhi, ed.; BPS WH 390, 1993)
- Book titles are usually italicized (except in Indexes, where cross-references are italicized and book titles are bold). Essays or chapters from books are put in "quotation marks".
- When embedding comments in HTML text, use the <!-- ... --> tag, and "sign" the comment with my initials and the date in yymmdd format. For example,
<!-- jtb 010203 This is my comment, which is dated Feb 3, '01. -->
The Chicago Manual of Style. 13th ed. Chicago: University of Chicago Press, 1982. ("CMS13")
The Compact Oxford English Dictionary. 2d ed. Oxford: Oxford University Press, 1991. ("OED2")
O'Connor, Patricia T. Woe is I: The Grammarphobe's Guide to Better English in Plain English. New York: Riverhead Books, 1996. ("PTO")
Strunk, W., Jr. and E.B. White. The Elements of Style. 2d ed. New York: Macmillan, 1972. ("SW2")
Webster's Ninth New Collegiate Dictionary. Springfield, Mass.: Merriam-Webster, 1983. ("W9")
Revised: Wed 10 April 2002
http://world.std.com/~metta/tech/style.html