Help | Home » Technical Notes

The Elements of
ATI Style

by John Bullitt

Copyright 2005 © John Bullitt


These notes are intended for my own use; I refer to them often. But just in case anyone else might find them useful, here they are.

Although I have found the traditional editorial tools (see the References) indispensable, the peculiarities of HTML and the idiosyncrasies 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.

Here and there I include references (in bold) to pertinent sections or pages in the References.

Text like this is an example that illustrates a point.

This style sheet is under constant development. Known errors (FIXMEs) are marked with special text.


¡!Important note: In early 2005 I began converting the website to Cascading Style Sheets (CSS). Until every page in the website is fully CSS-enabled, there will be some glaring inconsistencies of style between the CSS- and non-CSS pages. I am also in the process of migrating to a more consistent and flexible file naming scheme that accommodates translations of the same text by different authors. The sections in this document that refer to these and other issues that are not yet fully implemented across the entire website are marked thus: ¡!.


Contents


Three principles to live by [go up]

1. Protect 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.

Exception: When I extract individual suttas from books, I may remove the footnotes for ease of reading. There are always links from the suttas back to the books, where the original notes may be found. 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. FIXME: This example doesn't link back to the book.

2. 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).

3. Consistency doesn't have to be absolute.

This website includes texts from 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.


Spelling [go up]

Use American English spelling.
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
Regexp search: [a-xz]our

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
characterise
criticise
memorise
authorize
characterize
criticize
memorize
Search for oris.
skilful
fulfil
skillful
fulfill
 
centre
centring
lustre
meagre
metre
center
centering
luster
meager
meter
Be careful with global changes: changing *centre* to *center* would change centred to centerd!
cheque, chequered check, checkered  
learnt learned  
plough plow  
Other words to watch out for:

Geek note:To hunt down British spellings, commas outside quotes, etc., scattered across the website I use a rudimentary typo detector and spell checker. Its associated list of suspect words and word fragments contains my most up-to-date list of variant spellings.


Pali [go up]

Pali style depends on context.
Some ATI booklets use only familiar Pali or Sanskrit terms (Dhamma, Karma, Nibbana, etc.), while others draw from a wider palette (dana, sila, tanha, etc.). Still others use Pali compounds and phrases (e.g., viññanakkhandha, vipassana-ñana, Buddham saranam gacchami). And most make reference to canonical and extra-canonical texts by name, as well as to Pali proper names. When should Pali words be italicized? When are diacritics important?

It all depends on context. An informal essay treats Pali in one way. A chanting guide calls for another style. And articles containing detailed explorations of the etymology and meaning of Pali phrases call for something else altogether.

Pali words appear on this website in either of two forms: (1) "stripped" form, in which the diacritical marks are omitted (except for the palatal nasal ñ); and (2) Velthuis form, which is summarized here:

Two basic rules are observed: (1) long vowels are doubled: aa ii uu. (2) For consonants, the diacritic mark precedes the letter it affects. Thus, the retroflex (cerebral) consonants (usually typeset with a dot underneath) are: .t .th .d .dh .n .l. The pure nasal m (niggahiita; typeset with a dot underneath) is .m. The guttural nasal (n with a dot above) is represented by "n . The palatal nasal (n with a tilde) is ~n. Example: paa.naatipaataa verama.nii sikkhaa-pada.m samaadiyaami.

The particular Pali style is determined by the type of article or book. The style should be consistent throughout the entire document, or at least within its major sections.

Keep sutta titles readable
If a sutta title contains a long compound word that should be broken, break the word with hyphens (not spaces) and keep in lower case:

Maha-satipatthana Sutta (not Maha Satipatthana or Maha-Satipatthana)
Cula-kammavibhanga Sutta (not Cula Kammavibhanga or Cula-Kammavibhanga)

When the title contains a proper noun, use hyphens and capitalize the name:

Cula-Malunkyovada Sutta (not Cula-malunkyovada Sutta)
Maha-Saccaka Sutta (not Maha-saccaka Sutta)
Aggi-Vacchagotta Sutta (not Aggi-vacchagotta Sutta)


Alphabetization [go up]


Punctuation [go up]

Quotation mark order is " ' " ' ... (10.24CMS13)
Nested quotes are first double, then single, then double, etc. . The back quote (`) is never used for a left single quote. No spaces between quote marks. Commas and periods are always inside quote marks. (6.8CMS15)

Exceptions: (1) 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.") (2) If a sentence ends with an ellipsis in quotes, the final period is omitted.

Be it a pleasant feeling, be it a painful feeling, be it neutral, one's own or others', feelings of all kinds [SN XXXVI.2; It's an apostrophe, not a quotation mark!]

The discussion in the four paragraphs beginning with the phrase, "Vision arose...," takes two sets of variables [SN XLVI.11]

To avoid misunderstanding it is better to be quite specific, such as — "Bhante, if you need any more food...," "If you need a new pair of sandals..." Unless specified an invitation can only be accepted for up to four months. [The Bhikkhus' Rules: A Guide for Laypeople; The period is omitted before "Unless" because of the preceding ellipsis.]

Neither a . (except for an abbreviating one) nor a , ever accompanies a ? or a ! (6.123CMS15)

WRONG: Then the Blessed One uttered the exclamation: "Kondañña knows! Kondañña knows!," and that is how [SN XLVI.11]

BETTER: Then the Blessed One uttered the exclamation: "Kondañña knows! Kondañña knows!" — and that is how [SN XLVI.11]

en dash (5.92ffCMS13)
Use one hyphen with no spaces.
¡! em dash (5.82ffCMS13)
Use the &emdash; entity 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). Simulation of the em dash as " -- " is DEPRECATED.
¡! Ellipsis (10.38CMS13)
Always use three points (...), never four. Never use the … entity, as it complicates text searches. The 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. (PTO98 and 5.54CMS13)
Always followed by a comma.

File names [go up]

Note: I am slowly migrating ATI's files to conform to the standards outlined below. It will take me at least until the end of 2005 to bring the entire website in line with this standard.
File names are lowercase.
This prevents an entire class of bad links. Example: is it "Samma-Ditthi.html" or "Samma-ditthi.html"? It's always "samma-ditthi.html."
File names contain only a-z, 0-9, - and .
Do not use underscores (_), as these disappear in underlined and hyperlink text. (Example: can you_see the_underscores here? Can_you see_them here?)
File names have intrinsic meaning.
Each file name should be chosen carefully so that it possesses meaning independent of its directory. For example, instead of this:
/tipitaka/sutta/digha/22.html WRONG!

do this:

/tipitaka/sutta/digha/dn-22.html BETTER

If the file should ever get separated from its directory (as, for example, when it's sent as an e-mail attachment) you can tell at a glance what it is. If I receive a file named "22.html" I can't tell immediately if it's chapter 22 from the Dhammapada, sutta 22 from the Majjhima Nikaya, or something else altogether.

¡! File names contain a translator code.
Translations from Pali contain a three-byte code signifying the translator. This code usually consists of of two (lowercase) letters followed by a single digit (0-9). The letters usually stand for the translator's first and last initials. When multiple translators share the same initials, use the digit to distinguish between them.

Examples:

/tipitaka/sutta/digha/dn-02-tb0.html BEST

I maintain a list of reserved translator codes.

¡! Sutta file names are logical.

Sutta file names have intrinsic meaning and contain translator codes.

Section Template
[FIXME: these examples need links.]
Notes
DN dn-SS-ttt.html

dn-02-tb0.html

SS = sutta number (01, 02,... 34)
ttt = translator code
MN mn-SSS-ttt.html

mn-018-tb0.html

SSS = sutta number (01, 02,... 152)
ttt = translator code
SN sn-YY-SSS-ttt.html

sn-07-018-tb0.html

YY = samyutta number (01, 02,... 51)
SSS = sutta number (001, 002,... 999)
ttt = translator code
AN an-BB-SSS-ttt.html

an-03-065-st0.html

BB = book number (01, 02,... 11)
SSS = sutta number (001, 002,... 999)
ttt = translator code
Khp khp-ttt.html

khp-tb0.html

ttt = translator code
It doesn't make practical sense to split up Khp's small sections into separate files.
Dhp dhp-CC-ttt.html

dhp-01-ab0.html

CC = chapter code (01, 02, ... 26)
ttt = translator code
Ud ud-C-SS-ttt.html

ud-6-09-tb0.html

C = chapter code (1, 2,... 8)
SS = sutta code (01, 02, ... 99)
ttt = translator code
Iti iti-N-ttt.html

iti-1-tb0.html

N = nipata code (1, 2, ... 4)
ttt = translator code
Each nipata contains up to 50 suttas. Someday it may be prudent to subdivide Iti into individual suttas (itiSSS-ttt.html), but not until we have translations from more translators.
Sn snp-V-SS-ttt.html

snp-1-04-tb0.html

V = vagga code (1, 2, ... 5)
SS = sutta code (01, 02,...)
ttt = translator code
Thag
Thig
thag-CC-PP-ttt.html
thig-CC-PP-ttt.html

thag-05-09-kn0.html
thig-06-04-hk0.html

CC = chapter number (00, 01, 02,... 99)
PP = poem number (00, 01, 02,... 99) (note that chapter 1 contains > 99 poems. But they're small and will always be kept in a single file.)
PP = 00 stands for a chapter that is "complete," either because it contains (a) just one poem or (b) a complete chapter.
ttt = translator code
Miln miln-ttt.html

miln-jk0.html

ttt = translator code
I don't have enough suttas yet to justify more granularity.

White space [go up]

Use minimal white space.
Avoid the use of leading or trailing white space (spaces or tabs). Blank lines should be added sparingly, and only to the extent needed to make the HTML source readable. Big exception: Preformatted text!
¡! Tabs are used only two ways:
(1) To make HTML source more readable; and (2) to control layout in preformatted text. The use of three consecutive non-breaking spaces (   ), followed by a space, to simulate tabs is DEPRECATED.
¡! Tabs in preformatted text are used only to control line indent.
The use of tabs to control spacing between words (e.g., in poetry) is DEPRECATED. If you must fiddle with inter-word spacing, use spaces, but be aware that this won't look the same on every browser.
¡! Vertical spacing.
Use styles to control vertical white space. The use of <p><br><p> or the like to simulate blank lines is DEPRECATED.

Suttas [go up]

For html details, see the sutta template.

Number suttas using the PTS as a guide.
See "Sutta Reference Numbers" in the Abbreviations for details.
Entries in the index.html files have a standard format.
Simple: PALI NAME (REFERENCE NUMBER) — ENGLISH NAME [TRANSLATOR]. BLURB.

Complex: PALI NAME (REFERENCE NUMBER) — ENGLISH NAME {ALTERNATE REFERENCE NUMBER} [TRANSLATOR1 | TRANSLATOR2 | ...]. BLURB. {ADDITIONAL NOTE}

Examples:

¡! Subheadings use CSS styles.
For examples, see DN 12 and MN 125 . [FIXME: These examples aren't yet CSS-enabled.]

...Namo tassa bhagavato arahato samma sambuddhassa. Namo tassa bhagavato arahato samma sambuddhassa. Namo tassa bhagavato arahato samma sambuddhassa. Namo tassa bhagavato arahato samma sambuddhassa.

This is a Subheading

Namo tassa bhagavato arahato samma sambuddhassa.Namo tassa bhagavato arahato samma sambuddhassa. Namo tassa bhagavato arahato samma sambuddhassa. Namo tassa bhagavato arahato samma sambuddhassa.

This is a Subheading

This is a Sub-subheading

Namo tassa bhagavato arahato samma sambuddhassa. Namo tassa bhagavato arahato samma sambuddhassa. Namo tassa bhagavato arahato samma sambuddhassa. Namo tassa bhagavato arahato samma sambuddhassa...

¡! Translator's Introduction
A "long" note (say, longer than a ¶ or two) is a "Translator's Introduction" (e.g., MN 1):

Translator's Introduction

Here is a long chunk of introductory text for this sutta...
Translator's Note
A "short" note (a short ¶ or two) is a "Translator's note (e.g., MN 44):
Translator's note: Here is a short bit of introductory text for this sutta...

Miscellany [go up]

Keep HTML simple and consistent.
Use HTML 4.01 Transitional. Keep it clean and consistent because:
  1. Simple HTML simplifies managing and debugging a large website.
  2. Simple HTML creates fewer browser-compatibility issues.
  3. These texts are meant to be read. There's no need to spice them up with all the latest HTML bells and whistles.
  4. Consistent HTML makes global changes easier.
HTML anchors follow the same conventions as filenames.
NO YES
index.html#Ananda index.html#ananda
index.html#Samma-Ditthi index.html#samma-ditthi
index.html#samma_ditthi index.html#samma-ditthi
Style markup goes inside hrefs.
Keeping the markup inside the links allows for easier editing, should I want to change the look later on.
NO YES
... <b><a href="foobar.html">click here</a></b> ... ... <a href="foobar.html"><b>click here</b></a> ...
In the left-hand example, if I decide later on to make only the word "here" bold, I'd have to move both the <b> and the </b> tags. In the other example, I'd have to move only one tag. (The downside, of course, is that this way it's harder to shift the clickable text: I'd have to move two tags to click on the word "here." But I'm probably more likely later on to want to tweak the appearance than the clickable text.)
Italicized text includes adjacent punctuation.
This avoids some ugly typographical collisions — especially between letters and parens.
NO YES
It is stream-winning (sotapatti).
It is stream-winning (<i>sotapatti</i>).
It is stream-winning (sotapatti).
It is stream-winning <i>(sotapatti).</i>
Block quotations are not quoted.
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 square brackets are used 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? —
...
Endnotes, not footnotes.
Notes appear at the bottom of page, except in anthologies of sutta passages and a few other situations wherein it's useful for the notes to appear immediately after each passage. If there is only one note use "Note."

Remember to leave no space before the note tag,1 and to put if after any punctuation.

Namo tassa bhagavato arahato
	Samma sambuddhassa
In preformatted text there is a space before the tag 2
Namo tassa bhagavato arahato
...

Notes

1. To return quickly to the text, just click on this note's number.

2. Without the space the text gets cluttered.

Endnote tags come after all punctuation.
Endnote tags always come immediately after any punctuation, in a style determined by CSS. When they occur in preformatted text they are preceded by a space and enclosed in square brackets (preformatted text can't include markup).
"See also" comes at the end of the document.
Use "See also" rather than "Related reading."

In suttas:

See also: SN V.7; SN VI.15

In Indexes:

See also Buddha; Nibbana.

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)

Titles of books, essays, and chapters
Book titles in indexes are italicized. Essays or chapters from books are put in "quotation marks."
Short tables use 5 points.
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
Glossary entries are bold.
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...
Sign all comments.
When embedding comments in HTML text, use the <!-- ... --> tags, and "sign" the comment with my initials and the date in yymmdd format:
<!-- jtb 010203 This is my comment, which is dated Feb 3, '01. -->

In my comments "AG" refers to Ajaan Geoff (a.k.a. Thanissaro Bhikkhu).


References

The Chicago Manual of Style. 13th ed. Chicago: University of Chicago Press, 1982. ("CMS13")

The Chicago Manual of Style. 15th ed. Chicago: University of Chicago Press, 2003. ("CMS15")

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")

Webster's Tenth New Collegiate Dictionary. Springfield, Mass.: Merriam-Webster, 1998. ("W10")


Revised: Wednesday 2005-07-13
http://www.accesstoinsight.org/tech/style.html