Uniform English Writing Style Guide 0.2.0 (***beta version***)
By JBT
Released on 2018-10-17
http://uewsg.org/uewsg_0.2.0.html
Dedicated to St Adrian Of Poshekhonye, hieromonk and martyr (March 5)
The Uniform English Writing Style Guide is designed to change the way we write: with the UEWSG (pronounced like the word “usage”), I aim to seamlessly integrate unambiguous syntax, clean styling, and clear semantics with wide compatibility and the simple, natural writing that most authors are used to. I encourage everyone to use the Uniform English Writing Style Guide whenever creating new works or updating old ones. I believe it will not only positively impact the way we write, but that it will further reduce the barriers—barriers we ourselves have created by poor planning, ambiguity, and lack of standardization—to sharing our work with others by making it easier to write across all different media, translate our work into different languages, and preserve our creations through the passage of time.
One of the key goals of the UEWSG is a clear syntax. Too often, writing relies on easily-lost styles to convey critical meaning: how many documents, if all styling—font size, indentation, and so forth—was removed, would be intelligible? Could a reader distinguish a heading from a short paragraph? Would they know if a number at the beginning of a line was really denoting a list item? Could they tell the difference between a quote that should be preformatted—like code—and any other quotation? Obviously, the current answers to these questions are not very encouraging: outside of non-human-friendly markup languages, there is no clear way to parse a random document. But with the UEWSG, I hope to make this trivial: by adhering to a simple syntax, all parts of a document are immediately clear—even if all styling is removed. And this requires very little work on the author’s part because, instead of trying to mark natural writing up with distracting computer code, the Uniform English Writing Style Guide incorporates the way we already write, only clarifying and enforcing basic rules and safe practices. Best of all, the syntax is designed to be the same for all types of writing and across all media: a quick note on a slip of paper, a plaintext file, a type-written manuscript, a website, and a professionally-typeset book all use the same rules. Want a quick demonstration? Copy the HTML version of this specification from any reasonably standards-compliant browser (as of 2018, Firefox still does not handle even ASCII characters correctly, but nearly any other browser should work) into a basic text editor (Notepad, Notepad++, Sublime Text, vi, etc)—and compare it to the plaintext version of the spec, for extra effect. *That* is why we need a style-independent syntax: clarity, power, and limitless compatibility.
Another primary focus of the UEWSG is clean styling. No single style will please everybody everytime, but I don’t believe that is a good reason not to have a sensible set of default styles which add to, not take away from, the message of an author. In the UEWSG, this styling is applied through progressive enhancement: starting with the most basic, widely-compatible formatting and adding to it, when needed, with straightforward modules. I’ve relied heavily upon typographic and orthographic styles and characters which have been both used across media for decades—or centuries—and which are equally compatible with modern, digital writing. Because only the style—not the underlying syntax—changes between media, any conforming document should be able to be copied into plaintext without losing any of its most vital information or structure. Additionally, since a lot of the math for measurements (font sizes, margins, and so forth) is based upon reciprocally-terminating numbers, calculations are considerably simplified for both man and machine: operations should produce values with a finite number of digits—and that means no more dealing with repeating decimals!
The Uniform English Writing Style Guide also covers markup and programming languages. Beyond addressing indentation, a clear method is provided for writing UEWSG-compatible notes within a language’s own comment syntax. The UEWSG is not averse to data formats, either: JSON is practically UEWSG-compatible “out of the box”. What about extreme environments where only ASCII characters can be used? This is covered, too. And while I wrote the UEWSG to form a semantic baseline for a document, it is also compatible with file formats that add even-more-precise semantic information, like HTML. Indeed, because HTML is so prevalent, specific examples are given throughout this specification so web developers can consistently integrate the Uniform English Writing Style Guide into markup.
Remember, all this clarity and compatibility is “baked” right into the Uniform English Writing Style Guide. Now especially, in the digital age, writing guidelines which actively promote unnecessary ambiguity and arbitrary rules, rely on markup which will become invisible and almost useless when it is rendered, or require more work to make even a simple document readable should be reconsidered. And since there is no longer a guarantee that a human will even be reading an author’s work—it could be read by a machine—inconsistent and incoherent guidelines are an even bigger liability. The UEWSG is designed to tackle all of these issues, with ease of digital parsing as a major topic of concern. Again, all of this requires minimal effort on the part of authors to implement and only a few seconds (if even) on the part of readers to pick up on the general syntax.
I do not want to imply that there is no place for extra artistry and professional design, nor do I want the defaults I’ve provided in the UEWSG to stifle creativity or provide the “only” solution. But, for the average document, most of the time, money, and brainpower put into styling adds nothing to the work and produces, at best, mediocre results. I want the Uniform English Writing Style Guide to serve as a baseline for authors, to help take away the time consumption, inconsistency, and ambiguity of routine formatting, style, and syntax decisions. While they should provide a strong, human-friendly, and machine-safe foundation, I realize that not every creative work will fully utilize them. Therefore, even when authors do not make use of the guidelines’s ability to be extended and modified, I hope that the guidelines can still be of use as a starting point or basis.
I want to maintain the UEWSG as a collaborative effort from people all over the world and to thank all of the contributors—past, present, and future, known and unknown—for their help. All contributions up to this point have been anonymous, but they are vital to the success and universal scope of the project. Everything from small bug fixes to big ideas are welcome. Want to contribute, either by name or anonymously? Visit Contribute (http://uewsg.org/contribute.html) for more information.
I must also unequivocally state that the real credit for the *good* parts of the Uniform English Writing Style Guide goes to God and all the letter-by-letter help He gives because, despite prayerfully working to ensure completeness, root out contradictions, and provide unambiguous clarity, I know that I have missed (or even ignored) most of things that He has shown me. I apologize for any mistakes in the UEWSG, as they are certainly my own. Notwithstanding, and if God wills, I hope this becomes a standard that will make human communication easier for generations to come. And I pray that He will bless your words, that you may write clearly, truthfully, and worshipfully of Him and to Him—Father, Son, and Holy Spirit—for this is the only true reason that we write.
Before tackling more advanced concepts, authors need to familiarize themselves with the essentials: the characters they will use in writing, the capitalization of those characters, and the basic rules concerning their usage. If these elementary concepts are misunderstood, a document may become unwieldy or unreadable. Of course, as long as no rules are broken, authors are free to follow additional local customs, style guides, and their own inclinations—and this freedom applies to the entire UEWSG: the Uniform English Writing Style Guide is not designed to take away creativity and personality from works, but to foster a uniform baseline where those traits can be more clearly, and safely, expressed.
Characters are the buildings blocks of words, markers, and nearly every other part of a document. Characters should be directly typed or pasted; readers should never see a character’s Unicode code point unless a work is displayed in ASCII format or some other extraordinary rendering. On the other hand, some file formats, like HTML, require certain characters or sequences to be escaped so that they *will* display correctly to readers. In these cases, authors must follow the conventions of the file format (eg, “<”, “>”, and “&” must be escaped in HTML). Unless otherwise contraindicated, all digital documents must be written in **UTF-8**, the universal standard for digital text. All horizontal text—which is the default for writing—should flow from left to right and secondarily from top to bottom. Vertical text, like on the spine of a book, must flow from top to bottom and secondarily from right to left; no text or labels should be written bottom to top except for the axes of graphs where the common convention is to work within quadrant I and thus read the Y axis from bottom to top.
**HTML module**: HTML documents should begin with the document type declaration, “““<!doctype html>”””, for legacy reasons. They require the tag “““<html lang="en" dir="ltr">””” around everything else, to set the language and text direction. They also require the “““<meta charset="UTF-8">””” tag in their “““<head>”””. Similarly, CSS files require the at-rule “@charset "UTF-8";” before any other content—including comments. The tag “““<meta name="Viewport" content="initial-scale=1">””” is recommended for all HTML documents to ensure a consistent level of zoom on all screen sizes; it must also appear in the “““<head>”””. If HTML is used with CSS, which is nearly always the case, the HTML document further requires a “““<link rel="stylesheet" type="text/css">””” tag, with the correct media attribute (optional) and href, also in its “““<head>”””. Finally, the actual content of the HTML document must appear within a single set of “““<body>””” tags.
Spaces may be the simplest characters, consisting of a defined amount of whitespace to separate printable characters visually, structurally, or both. In the UEWSG, the default spacing is unvarying: **1 space**. This applies to spacing between words, between sentences, between groups of digits, and between any other inline constructs that require separation. Spaces *must* be used between URLs, paths, and/or filenames and potentially conflicting characters (periods, hyphens, etc) for semantic clarity. Spaces may also be used, as needed, between similar characters for visual clarity (eg, a set of closing single and double closing quotation marks). Spaces are generally not permitted directly inside of delimited constructs (parentheses, quotations, emphases, etc), unless otherwise noted. For further guidance, see “2.1.3. Printable Characters” or a specific construct’s division.
Unusual space characters, such as the non-breaking space, should not be employed in normal writing; they are difficult or impossible to distinguish from regular spaces without special software. They may inadvertently get replaced with a regular space or—even worse—may start replacing regular spaces. If more fine-grained control is needed, especially when typesetting formal documents, this is beyond the scope of the UEWSG but other characters are not strictly forbidden.
Spaces must never be used for indentation outside of special cases (eg, ASCII art, text-based tables, etc) in preformatted quotes and preformatted blockquotes. For more information on how to properly indent code, see “5.8.1. Indentation”.
Line breaks are similar to spaces, but create white space in the vertical dimension. In the UEWSG, single line breaks are used to separate division markers from headings and are generally allowed within a block construct’s content to help format text (eg, separating verses in The Nicene Creed). Double line breaks, or blank lines, are used to separate block constructs from each other (for more information on the rules of block formatting, see “4. Block Constructs”). Blanks lines are not permitted elsewhere and multiple blank lines are not permitted anywhere.
Line breaks must be made with the newline characters **CR + LF**, or carriage return and line feed. This standard sequence is the most commonly used today: Windows and DOS-based systems use it natively, modern Unix-based systems support it, and most of the fundamental internet protocols (eg, HTTP, FTP, etc) explicitly require it. Thus, even on systems where CR + LF isn’t the default, it must be used for the sake of compatibility; most non-legacy operating system and/or their text editors have simple ways to adjust this setting.
If, for whatever reason, a document must be displayed on a single line or in a stream, the UEWSG provides a straightforward fallback mechanism:
• All spaces must be preserved.
• All line breaks must be replaced with the escape sequence “\r\n”, corresponding to the control characters CR + LF.
Indeed, a fully-conforming document is already so well-formatted that only these few changes are necessary. Even if a document was sent like this one character at a time on a ticker tape, no syntactical information should be lost; despite the poor [human] readability in this format, any fully-conforming work should be able to be unambiguously and exactly recreated into its original form with an easy automatic or manual parsing. Few, if any, other writing guidelines or systems [outside of non-human-friendly markup languages, etc] can make this claim. Note that this fallback format can be used in an ASCII-only environment and it shouldn’t cause any syntax issues there, either.
Printable characters are those that are visible: not just letters and numbers, but symbols, too. Because printable characters more directly hold the content of a document, it is crucial for authors to select the most appropriate characters and use them correctly in their writing; poorly chosen characters and/or improper usage can convey a lack of professionalism. Documents must adhere to the following rules:
• Quotations marks (“ “” ” and “ ‘’ ”; sometimes called “curly quotes”) must have no spacing on the inside; interior contents must directly touch the quotation marks (subject to the exceptions noted in “2.1.1. Spaces”). While it is customary in American English to start with double quotation marks, then use single quotation marks for the next-innermostly-nested quote, then use double quotation marks for the third-level of nested material, and so on, this usage is not required in the UEWSG: authors may use either single or double quotes as the primary delimiters, according to the requirements of the document or local custom, so long as they remain consistent.
^ Straight quotation marks (“ " ” and “ ' ”) are distinct characters and, while they appear conveniently on most keyboards, they may not be preferred for many kinds of publishing, where they may be perceived as inelegant and unprofessional. For other uses, however, straight quotes are perfectly acceptable: everyday writing (plaintext, SMS, certain types of e-mails, etc), code (where they are usually required), and ASCII-only environments (where they are most definitely required; see “2.1.3.1. Fallback Characters”, below). While there is no preference in the Uniform English Writing Style Guide towards either straight or curly quotation marks, limited use of straight quotes not only makes works more readable, but can help isolate syntax errors, as well; either way, authors should be consistent in their use.
• Apostrophes (“ ’ ”) are the same character as the closing single quotation mark and must also be used without spacing. In order to help distinguish these 2 uses of the same character, *apostrophes must have printable characters directly touching them on both sides*; any seeming apostrophes that are not surrounded by printable characters *must* be treated as single quotation marks. This means that possessives ending in an “s” must always have an additional “s” at the end of the apostrophe (eg, “Thomas’s”). While this rule may seem slightly redundant, it is more semantic, matches the spoken usage, and prevents all manner of potential parsing problems (for example, the sentence “I went to the ‘Two Towns’s’ restaurant…” would be unclear and shows just one possible danger if this seemingly “redundant” UEWSG rule is not strictly adhered to; when dealing with computer programs that automatically parse nested quotes, the problem is significantly magnified). Abbreviations and colloquialisms which violate this rule (eg, “get ’em” and “ ’till”) must be rewritten without spaces (eg, “get’em”), rewritten without the apostrophe (eg, “till”), or safely enclosed in a containing set of quotation marks to prevent ambiguity (either as a quotation or preformatted quotation, depending on the severity of the violation; see “3.6. Quotations” and “3.7. Preformatted Quotations”, respectively.). Authors should also remember the distinction (above) between the formal, “curly” apostrophe and the the straight version (found on keyboards) and use one or the other consistently.
• Parentheses (“()”), brackets (“[]”), and braces (“{}”; sometimes called “curly braces”) must have no spacing on the inside. They must be used for their proper functions: braces are reserved for special uses (eg, programming and math), brackets are most typically used for inserted material (including note markers, editorial notes and changes, and even ironic commentary by an author within his or her own work), and parentheses are used for most other purposes (inline notes, clarifications, elaborations, translations, definitions, in-dialog directions, and any other type of *parenthetical* information—as in this parenthetical construct).
• Hyphens (“-”; technically hyphen-minuses), present on most keyboards, are both a hyphen and minus character in one. In their hyphen form, they must be used without spacing and can break up words, connect words in compound adjectives (a not-so-uncommon usage), connect certain compound words (such as e-mail and non-breaking space), indicate that a word is to be spelled letter by letter (eg, “spell t-h-i-s out loud”), and more. An exception is made for suspended hyphens (as in the phrase “7- and 8-year-old children”) and line-wrapping hyphens (ie, those that break a word into smaller segments on multiple lines); a space [or line break] is permitted on the right for these cases. In their capacity as a mathematical minus sign, they may be used for both subtraction (when surrounded by spaces) and negative numbers (when only the side opposite the number, the left, is spaced); see “3.5.3. Math” for more examples.
• En dashes (“–”) must always be used unspaced. They can be used to separate ranges (eg, 3–8, pages 6–7; for more on ranges, see “3.5.3. Math”). Similarly, they can separate words denoting a physical or immaterial range or tension (eg, the North–South divide), though a slash (“/”) can also be safely (though slightly more obtrusively) used for that purpose in many instances.
• Em dashes (“—”) may be used, without spacing, to separate parenthetical content [in place of parentheses] or to denote a shift in thought or speech inside a sentence (interruption, epanorthosis, etc). They may be used with spacing on the right side only to denote censored text (see “3.13. Censored Text”). They can also be used to begin adjectival paragraphs, following a double line break (eg, “—by Leonard Wibberley”), or other adjectival content. Em dashes are not allowed to touch numbers on both sides and, if there is a chance a document may be viewed in an ASCII-only environment, care must be taken to avoid phrases that could imply subtraction (eg, “…the people—3 of them…” could create ambiguity; see “2.1.3.1. Fallback Characters” for more about how em dashes are handled in ASCII).
• Slashes (“/”) must be used unspaced when they are separating directories in a URL or path (“…/example/url/or/path/…”), representing fractions (see “3.5.3. Math”), and taking the place of the word “or” (eg, “left/right” and “strange/odd”). But, when used to represent a line or verse break—as is common in songs and poetry—and in division (eg, in place of an obelus), slashes must be spaced on both sides.
• Ellipses (“…”), whether written as a single character or the semantically-identical three periods, must be used unspaced, unless beginning a sentence or ending a paragraph. If they end a sentence within a paragraph, they still require trailing terminal punctuation. Ellipses must be used with brackets whenever an author adds them to a quoted phrase.
• Terminal punctuation marks (viz, “.”, “?”, and “!”), commas (“,”), semicolons (“;”), and colons (“:”) must have a trailing space when followed directly by another word, sentence, or opening punctuation mark of any kind. Outside of special cases (see “2.1.1. Spaces”), these punctuation marks must not be preceded by a space. Terminal punctuation marks may be overridden by another contiguous terminal punctuation mark (with the last one in the series taking parsing precedence), by a comma (in the case of a list item marker; see “3.8. Inline Lists” below), or by a semicolon (eg, “?;”). Further, these markers *do not “collapse”*: if a sentence ends with an ellipsis, for example, *4* periods are required, for clarity.
• Direct references to letters should be quoted (eg, when speaking about the letter “a”). Direct references to multiple instances of a letter must be quoted, for clarity (“ ‘i’s” are not the same as “is”, for instance).
Because ASCII-only environments are still relatively common, it is necessary to have clear defaults to fall back to when Unicode characters are unavailable. Because the wrong entry may not only make a document look sloppy, but could completely change its meaning and—in some cases—even cause computer programs to catastrophically fail, a semantic fallback for every non-ASCII character used in the UEWSG is defined. When converting to ASCII:
• Double quotation marks (“ “” ”) and single quotation marks (“ ‘’ ”; this includes apostrophes, which are the same character as the closing single quotation mark) must be replaced with their “straight quotes” versions (“ " ” and “ ' ”).
• En dashes (“–”) must also be replaced by hyphens (“-”); this will not be confused with subtraction because no spaces are present.
• Em dashes (“—”) must be replaced by hyphens with a space on either side (“ - ”), to distinguish them from the normal use of hyphens. Note that while this form also mimics the mathematical subtraction operation, the UEWSG does not allow em dashes between 2 numbers, so this should not create confusion. Em dashes which begin a paragraph (ie, an adjectival paragraphs) or which denote interruption or censoring (see “3.13. Censored Text”) must be replaced by hyphens, with spacing on the right side only.
• Ellipses (“…”) must be replaced with three periods in a row (“...”).
• Bullets (“•”), multiplication signs (“×”), and dot operators (“⋅”) must be replaced with asterisks (“*”).
• Division signs (“÷”) must be replaced with slashes (“/”).
• All remaining non-ASCII characters must be escaped with their proper hexadecimal character reference according to the document’s format. If no format is specified, HTML’s is the default (“&#x[…];”).
Authors should be careful defining their own fallbacks for other characters; the defined fallbacks (not to mention the original characters) have been rigorously researched and tested. For example, replacing prime marks (as used in coordinates like “35° 39′ 40″ N”) with similar-looking straight quotes is practically *never* a wise idea. In any case, any author-defined fallback characters are beyond the scope of the UEWSG.
Capitalization is an important way to orthographically distinguish certain constructs from surrounding text. For instance, most abbreviations are written in all caps, whereas filenames are written in a strict variant of the computer-friendly snake case. The rules for capitalization are simple, hierarchical, and unambiguous: all writing should follow sentence case, unless it is part of a construct that is otherwise styled according to the UEWSG. Names, trademarks, and/or other words that do not follow any of the defined cases (eg, “McDonald” and “OpenBSD”) or which follow a case other than their usage suggests (the titles “nginx” and “xkcd”, Latin/scientific names of organisms, etc) should be written in their special forms, though this is ultimately left to the discretion of the author. Since lowercase and all caps (or “““ALL CAPS”””) are clear enough, only 3 other cases need to be further defined:
In sentence case, all letters are lowercase, except the first letter of a sentence, if it is also the first character; if a sentence begins with a number or some other non-construct-delimiting character, the first letter remains lowercase (eg, “12 stones were…”). This capitalization includes the first letter of a quoted sentence that begins inside another sentence (eg, “Jesus said, ‘You search the Scriptures, for in them you think you have eternal life; and these are they which testify of Me. But you are not willing to come to Me that you may have life.’, as recorded in John 5.39–40 (NKJV).”) but *not* quoted phrases or incomplete fragments of sentences (eg, “St Paul refers to the Church, not The Scriptures, as ‘the pillar and ground of the truth’ in 1 Timothy 3.15 (NKJV).”).
In title case (or “Title Case”, also known as “Start Case” or “Proper Case”), the first letter of every word and hyphenated segment is capitalized (including *all* prepositions, conjunctions, and articles). This form of title case is not only easy to remember and trivial for machines to implement, but necessary to avoid ambiguity. For example, “God and Man” must always be read as two separate names, because the “and” is not in title case. Similarly, the hypothetical “All About Articles, a Definitive Guide” must be read as a work title (“All About Articles”) that is part of a larger series (the “Definitive Guide” series).
In snake case (or “snake_case”), all letters are lowercase, regardless of other exceptions, and all space characters are replaced with underscores, which are a semantic fallback for spaces. Hyphens must *never* be used to replace spaces or underscores, as they have a different meaning.
When creating or storing a document digitally, particular care must be given to its filename. The filename of a document should not only match its main title (see “4.1.1. Main Titles”), but must follow any restrictions imposed by the operating systems it comes into contact with (eg, filenames beginning with a period are considered “dotfiles” on most OSes and are normally hidden; see https://en.wikipedia.org/wiki/Filename for more such conventions). Because some restrictions are still so commonplace, however, the following suggestions are also *recommended*.
All filenames should be limited to 255 characters (including any URLs or paths) and further translated into strict snake case. Strict snake case uses only a subset of ASCII, specifically the 40 safest characters: 0-9, a-z, tildes (“~”), hyphens (“-”), underscores (“_”), and periods (“.”). These are largely the same characters that are unreserved in RFC 3986 §2.3 (minus the uppercase letters, as some systems can’t differentiate and regular snake case already precludes their use; see https://tools.ietf.org/rfc/rfc3986.txt), though the extra restrictions ensure near-universal compatibility: almost every file system and protocol can handle strict snake case, and human readability is high. Further, all filenames should have extensions (eg, “file.txt”)—regardless of operating system—as this aids in human and machine parsing. For versioning, authors should adhere to the Semantic Versioning 2.0.0 spec (http://semver.org/spec/v2.0.0.html), which is almost fully compatible with strict snake case. Finally, it is recommended that authors follow any other useful traditions associated with the systems their files may come into contact with, unless contraindicated by the UEWSG.
One fundamental rule underlies most of the standards relating to nesting constructs: authors must always close constructs in the reverse order that they were opened. If three quotations are nested together, for example, the innermost quote must be closed before the second may close, and the second must close before the outermost quote may close. Or, a segment inside parenthetical text that is given standard marked emphasis must be “closed” before the closing parenthesis. This rule is paramount for keeping documents readable and absolutely indispensable when a machine is parsing a work.
In order to permit uniform parsing of the Uniform English Writing Style Guide, quotations and other constructs with opening and closing markers may be used to contain content that might be unclear; if a string can be parsed as either regular text or a marker, the marker takes precedence. For example, in a hypothetical ASCII-only environment where line breaks are not allowed, the content “text +++. More text” *must* be parsed as if “.” is a chapter heading. To be parsed as text, it must either be quoted (like “text ‘+++’. More text”) or rewritten in some other way. Content that would still break the parsing or formatting rules of the UEWSG (like the phrase “search for the file ‘‘‘*.*’’’ ”, many types of poetry, etc) must be set in preformatted quotations or preformatted blockquotes (see “3.7. Preformatted Quotations” and “4.5. Preformatted Blockquotes”, respectively), which are exempt from regular parsing rules.
If the rare situation presents itself where 2 or more styles are mutually exclusive in a given format (eg, rendering bugs in certain browsers make borders and margins conflict), authors must always follow the core rules first, then the rules of any modules; if there is still conflict, authors have discretion in choosing which of the styling rules is more vital to apply.
While the UEWSG is meant to foster uniformity, it is not a replacement for a dictionary or a full course on grammar: topics such as spelling, hyphenation of compound adjectives, and the general process of writing are outside its purview. Nonetheless, a few words on precision and tone are in order. Authors should understand their audience and use language that is appropriate. For example, most readers would expect a peer-reviewed article to be technical and serious, whereas a fiction novel might be more familiar and light-hearted. This is not to say that a technical author cannot use humor or a novelist cannot use specialized terminology, but that the language should not distract from the message. Second person pronouns, though not inappropriate in most forms of writing, must be used wisely: authors should not unquestionably address readers (“you must…” or even “you should…”), but should cautiously describe the conditions under which a direction should be followed—“if A, then you must…” is an acceptable approach.
Language should be as precise as reasonably possible. For instance, while it may be common to call food “good”, a more precise word might be “tasty”. And, in a similar vein to the use of commands with personal pronouns, authors should be wary of stating that things “will” happen: unless the author has some extraordinary knowledge of future events, more conditional phrases are preferred (“should”, “is expected to…”, “…plan to…”, etc).
With a practical understanding of the basic rules for UEWSG-conforming orthography, authors next need to consider inline constructs. Inline constructs include words, full sentences, and everything in between: abbreviations, quotations, and so on. Many of these constructs have special rules and formatting, but all of these constraints serve the same goal: to make a document readable on any medium and consistent in every medium.
All proper nouns—including titles—must be written in title case. This includes, but is not limited to, names (eg, “Joseph” and “St Adrian”), places (physical or political: “New Kidron”, “Antarctica”, “Mount Athos”, etc), organizations (of any kind: “Internet Systems Consortium” and “NASA”, but also “Trader Joe’s”, “Asus”, “Ancient Faith Radio”, etc), time periods (“Spring”, “Iron Age”, etc), wars and battles (eg, “Battle Of Thermopylae”, “Battle Of The Milvian Bridge”, and “World War I”), ships and units (“NKN Soggy Bottom”, “Varangian Guard”, etc), musical notes (“C”, “B♭”, “F♯”, etc) and work titles (including book, article, play, poem, music, video, and website titles). Titles within titles (like “A Study Of ‘The SUN Study’ ”) must be quoted, for clarity. Some proper nouns require additional styling:
**Rich media module**: Work titles (including distinct works within a larger work, such as books of The Bible, but not mere subdivisions) and vessel names must be italicized in running text; italicization in headers and footers is left to the discretion of the author. A title of *another* work or division that falls within a heading must also be italicized, but a work’s own main title must not be italicized when it is presented [as a block construct] (see “4.1.1. Main Titles”). Words in titles that are already italicized for another reason (viz, vessel names and foreign words) must be *un*-italicized to communicate their meaning (eg, “The Legend Of The NKN Soggy Bottom”).
**HTML module**: Work titles in running text, as well as a title of *another* work that falls within a heading, must be wrapped in “““<cite>””” tags; quotation marks for a title must fall outside its “““<cite>””” tags. A work’s own main title [as a block construct] must not be wrapped in “““<cite>””” tags, but other references to its title must be. Vessel names in running text must be wrapped in “““<i>””” tags.
In the Uniform English Writing Style Guide, abbreviations are covered by 4 simple rules:
• Abbreviations must *not* have periods and must be written in the case of the surrounding text, unless otherwise excepted. This includes abbreviations of most personal titles (such as “St”, “Bp”, “Fr”, and “Dn”), books of The Bible (“Jer”, “Eccles”, “1 Macc”, “Jn”, and the rest), street names (such as “Ave” and “Rd”), and words from all other categories (such as “pg”, “vol”, and “anon”). This also includes abbreviations that, as defined in a dictionary, are written in a hyphenated form (such as “e-mail” and “wi-fi”) or have come to be used as words in their own right (eg, “ok”, “info”, “math”, “percent”, “sonar”, “radar”, “laser”, and “blog”); common Latin phrases (including “ie”, “eg”, “cf”, “viz”, “am”, and “pm”) fall into this category—and do not need italicization, being Anglicized.
• Acronyms, including initialisms and postal codes, (such as “JBT”, “NK”, “N”, “SSE”, “EST”, “UTC”, “HTML”, “RAM”, “FAQ”, “IMAP”, “PIN”, “NC”, “NA”, and even “R&D” and “W3C”) must be written in all caps and must not have periods or spacing; this includes Latin acronyms and initialisms that have at least one proper noun (like “AD” (“anno Domini”, or “in the year of our Lord”), “SPQR” (“Senatus Populusque Romanus”, or “the Senate and People of Rome”) and the lesser-known “DV” (“Deo volente”, or “God willing”)).
• In mixed abbreviations, where acronyms are mixed with longer abbreviations, only the longer abbreviations must receive spacing while the acronyms are dealt with normally, above (such as “CS Lewis”, “JK Rowling”, “M Div”, “Th D”, and “N America”).
• Abbreviations of work titles must retain italics (like “UEWSG”).
As noted in “2.2. Capitalization And Cases”, abbreviations that are commonly written in a different case may be written in their accepted style, at the discretion of the author. Any abbreviation that is unclear in a given context should not be used and uncommon abbreviations should be spelled out at or near their first occurrence to avoid confusion.
**HTML module**: Abbreviations may be wrapped in “““<abbr>””” tags. If they are given a title attribute and thus become interactive, they must be further styled like interactive content (see “3.16. Other Interactive Text”).
In various circumstances, authors may need to use foreign words or phrases. While some of the more common ones have been adopted into English dictionaries (eg, many Latin abbreviations), all other foreign words (including taxonomic designations) must have extra styling (as well as a definition, if necessary) when used in running text:
**Rich media module**: Foreign words and phrases must be displayed in italics.
**HTML module**: Foreign words and phrases must be wrapped in “““<i>””” tags.
In many types of writing, authors may need to use words or phrases that carry special meaning and/or require extra visibility but don’t really fit into another category: keywords, difficult terms that may be unfamiliar to readers (especially if they are defined elsewhere, like a glossary), questions on a test, and so forth. Such special terms may receive additional styling:
**Rich media module**: Special terms may be displayed in bold at their first instance in running text; further instances may also be displayed in bold, at the discretion of the author.
**HTML module**: Special terms may be wrapped in “““<b>””” tags at their first instance in running text; as above, other instances may also be wrapped in these tags, at the discretion of the author.
Numbers denote concepts like quantity, order, and value and are just as important in most forms of writing as letters. Alas, they may be some of the most confusing and contradictory parts of most style guides. More than a few of the oddities that are almost intrinsic in current usage cannot easily be removed, so many of the rules have optional components. The basic rules for dealing with numbers in the UEWSG are:
• Numbers should be represented in Hindu-Arabic numerals (viz, “0”, “1”, “2”, “3”, “4”, “5”, “6”, “7”, “8”, and “9”) for clarity in all types of writing. They may be written out in extraordinary cases, like emphasis (eg, “only 2—*two*—people!”), verbification (such as “zero the scale”), and article substitution (eg, “One day, I…” instead of the terribly awkward “A day, I…”); authors have discretion in other cases, but numerals are still recommended as they are far easier to read. Plural forms of numerals must have an “s”, but never an apostrophe (eg, “2000s” and “50s”). Other numeral systems, especially Roman numerals, are widely misused (particularly in outlines), sometimes unclear, and should be avoided.
• Ordinals (eg, “3rd”, “501st”, “13th”, “42nd”, etc) must not have superscripted ordinal indicators, as these, despite their historicity, could be confused with more modern usages of superscript. Authors have discretion when choosing whether or not to write ordinals out (“first”, “second”, and “third” up to common time-based phrases like “the eleventh hour” and “twelfth night” are often written out), but numeric ordinals are still recommended generally.
• Approximate or rounded numbers must use the approximation symbol (“≈”) if the context does not make their imprecision clear (eg, “…is about 1 L” but “…is ≈1 L”); if they are “large”, they may be written out in part, so long as the significant digits are retained as numerals (eg, “4.5 billion”). Numbers or quantities used with no precise significant digits (eg, “there were a million of them!”, “half of the bag”, and “a week or two”) should be written out in full.
• Spaces—and only spaces—may be used to group digits together for easier visual parsing. This extends to large numbers (eg, “1 000 000”), RGB values (such as “000 080 000”), phone numbers (eg, “+1 919 NNN NNNN”), and any other numerical constructs. Commas must never be used for this purpose, because this can mimic comma-separated values, lists, and other constructs, leading to potentially catastrophic ambiguity.
• Periods (“.”) must be used as radix points separating the fractional (eg, “6.28319”) or other subordinate parts (as in “version 1.0.3”) of numbers or divisions in a numerically-subdivided work (as in Mark 6.31). This is the standard followed in a great deal of the world, in nearly all programming and web languages, and is much safer than using commas (see above) or other conventions. For further clarity, numbers must not begin or end with periods (ie, use “2.0” and “0.5”, not “2.” or “.5”), unless they are used as a list item marker (eg, “10.2.”). If their common usage dictates otherwise (eg, “.308 ammunition”), they must be quoted or otherwise set apart from the rest of the normally-parsed text.
In general, authors can use local conventions when writing out dates in full (eg, “April 20, 2008”), appending the standard suffixes “AD” or “BC” as needed (eg, “2008 AD”). Days of the week may be freely used in non-technical writing; Sunday is traditionally considered the first day of the week. Times may also be written out in either 12- or 24-hour format, according to local convention (like “2:00 pm” or “14:00 hours”). If more precision is required or the time and/or date are not written out, the internationally-accepted ISO 8601 must be followed: times and dates in this format are easy to read, trivial for computers to parse and sort, and unambiguous. To heavily summarize, the standard requires that:
• Dates must be given in the format YYYY-MM-DD, with padding zeroes (eg, “2008-04-20”). For less precision, sets of values may be removed in order, starting from the smallest [right-most] increment (eg, “2008-04”).
• Times must be given in the format hh:mm:ss, with padding zeroes (eg, “14:00:00”). For less precision, sets of values may be removed in order, starting from the smallest [right-most] increment (eg, “14:00”). If a time follows a date, the date must not omit any values and must be separated by a “T” (eg, “2008-04-20T14”).
• Time zone information, if needed, must be appended to the time, usually in the format ±hh:mm, though the leftmost value can be omitted if unnecessary (eg, “2008-04-20T14-06”). Times given in UTC may use either the suffix “+00:00” or “Z” (“20+00:00” or “20Z” are both acceptable).
Variables are used to represent unknown and/or changeable quantities. Outside of opposing requirements, authors should consider defaulting to common variable usages: “x”, “y”, and “z” in place of unknowns that require calculation; “n” for input numbers; “i” and “j” for indexes (eg, in “““for””” loops); and “a”, “b”, and “c” for constants. Whatever the choice, variables require further styling:
**Rich media module**: Variables (but not any attached exponents, descriptive subscripts, etc) must be displayed in italics.
**HTML module**: Variables (but not any attached content, as above) must be wrapped in “““<var>””” tags.
While complex math equations are outside the purview of the Uniform English Writing Style Guide, being better-expressed in a more visual manner, most elementary operations are easy to communicate in running text:
• Unary operators must always touch the numbers they modify (eg, “-7”, “>2”, “10%”, and “5!”) unless written out as words (as in “negative 3”, “greater than 2”, “10 percent”, and “5 factorial”). This includes the radical sign (“√”) when it takes only a radicand, as is often the case.
• Operators that take at least two values, other than those excepted below, must be spaced, both for visual clarity and to prevent semantic confusion (especially since hyphens and minuses are the same character!). This includes the basic operations of addition (eg, “1 + 1” and “5 + -2”), subtraction (eg, “8 - 1” and “7 - -13”), multiplication (with either common symbol: “70 × 7” and “12 * 12”; it also applies when text is involved, as in “We had 2 × the enjoyment.”), division (again with either common symbol: “12 ÷ 2” and “255 / 3”), modulo (eg, “4 % 3” and “50 % 7”), and equality (eg, “2 + 2 = 4” and “8 + 5 = 13”).
• Exponentiation should be superscripted and must not have spacing. Exponents must contain a caret (such as “1.44 × 10^5” and “6.022 × 10^23”; note that the caret is *also* superscripted).
• Multiplication involving variables (“3n”, “τr”, and “ax^2 + bx + c”) must not have spacing unless a multiplication operator (eg, “×”) is present.
• Fractions, while technically a form of division, are a special case and must use a slash (“/”) without spacing and, in rich media, should always be properly super- and subscripted (“1/2”, “5/3”, etc). Improper fractions and decimals are generally preferred to proper fractions; if used, proper fractions must contain a space between their integral and fractional parts (eg, “Platform 9 3/4”). More complicated fractions require special care when written in text—the standard order of operations applies—though there is no preference in the UEWSG for separating out the fractional part of a formula (eg, “1/2τr^2”) vs writing the entire formula as a single fraction (eg, “(τr^2)/2”—and note the critical function of the parenthesis to prevent a fractional exponent!).
• Ratios denoted by a colon (“:”) must be unspaced; they are similar to fractions in both form and function.
• Subscripts maybe be omitted in textual representations of chemical formulas (eg, CH4 and O2) and in other cases where the meaning is obvious. However, where subscripts are still needed, they must be written in text using an underscore and braces (eg, M_{Earth} or M_{⊕}), with only the braces and their content subscripted.
• Ranges must use the en dash (“–”) with no spacing (eg, “70–72”) unless written out (eg, “between 70 and 72”). Undefined ranges (eg, “Open From 3–”) must always be written out unless they immediately precede terminal punctuation, the end of a paragraph, or a closing marker. Abbreviated ranges (“121–5”) may be used if they do not create ambiguity, but should generally be avoided.
For the sake of international compatibility, authors should use SI (sometimes called “metric”) units and symbols and write them according to SI conventions. In short, that means:
• Unit symbols must be separated from numbers by spaces (“500 m”, “20 °C”, “273.16 K”, “1.18 g/L”, etc).
• Units which are multiplied together must be separated by a dot operator (“⋅”) and contain no spaces (eg, “9.80665 N⋅m”), while those that are divided by another must use a slash (“/”), not contain spaces, and not be super- or subscripted (eg, “1.6 m/s^2”). Note that the dot operator is the only other binary operator which is *not* spaced and its use should be reserved for this special case.
• All units, even those derived from a name, must be written in sentence case when spelled out (“meter”, “gram”, “tesla”, “pascal”, “liter”, and so on); units must be written out in this form whenever an actual value is not present (eg, “How many grams are in…?”). Unit symbols are case sensitive and must be written in lowercase, Roman letters regardless of surrounding text (“m”, “g”, etc), except for those symbols which derive from a name (eg, “T” and “Hz”) or the liter (“L”; since it could be confused with other characters), which must always be written in title case. Prefixes are also case sensitive and must never be changed to a different case under any circumstance.
• Unit prefixes must be contiguous with the units they modify; no spaces are permitted (eg, “km”, “mL”, and “µg”).
Regrettably, because of semantic oversights or political concerns, the SI conventions are deficient in at least four areas and the UEWSG has stricter or divergent rules:
• The percent sign (“%”) must not be used with spacing lest it be confused with its common mathematical usage as the modulo operator (see above).
• Commas must not be used as an alternate radix point (see above).
• Spaces must not be used in place of dot operators and/or to imply multiplication. This can create great ambiguity because spaces are also the digit delimiter (eg, “1 000 000”), as noted above.
• Binary numbers should use IEC, not SI, prefixes unless explicitly contraindicated. These units (such as “kibibyte”, “mebibyte”, and “gibibyte”) and their symbols (such as “KiB”, “MiB”, and “GiB”—note the uppercase “K” for kibi, which is not the same as kilo’s symbol) imply not multiplication based on 1000 (ie, 10^3), but based on 1024 (ie, 2^10) and are more useful—and far more widely used—for binary math. Similarly, “B” should be used to represent bytes—not “b”, as SI suggests, as this usage is almost non-existent and conflicts with the symbol for bits.
Conventions for other units and symbols should follow the guidelines of the appropriate standards body or, if not defined, the common usage (eg, “$20” for “20 dollars” and “78° W” for the coordinate, both with no spacing).
Quotations can denote verbatim material which is from another source, but that isn’t their only use: they can signify a word or phrase is being directly referred to, convey irony, show an author’s reluctance to fully accept the common usage of a word or phrase, isolate ambiguous or unparsable content, and so on. Quotations begin and end with opening and closing quotations marks, respectively (either “ “” ” or “ ‘’ ”); the choice as to which type to use as the outermost set (ie, single or double) is left to the dictates of local custom. Punctuational games have no place—especially in the digital age, when the misplacement of a single quotation mark could literally cause an entire computer to fail—so the UEWSG has a very simple, but strict, rule: except for bracketed material (eg, editorial notes), only the content of the quote is permitted inside quotation marks. This means that no other punctuation from a sentence may “spill” into or out of quotes; this includes periods and commas. As an example, consider the nested sentences “Did he say ‘I want to go home.’, shout ‘I need to get home!’, or ask ‘Can I go home?’?”; each sentence must be properly punctuated or the entire meaning could be changed and/or lost. This rule is the safest, most precise, and most semantic way to handle quotations.
For longer quotations, see “4.4. Blockquotes”.
Preformatted quotations are similar to regular quotations, but more strict. They must be used to handle snippets of code, HTML, and/or any other inline content which might interfere with UEWSG-defined constructs. Preformatted quotes require all content—including whitespace—to be exactly and precisely represented inline; any contained constructs must not be given any styling whatsoever. To distinguish them from regular quotations, preformatted quotes open and close with sets of 3 contiguous opening and closing quotation marks, respectively (“ “““””” ” or “ ‘‘‘’’’ ”); again, the choice of single vs double quotation marks as the outermost set is outside the scope of the Uniform English Writing Style Guide and nesting works the same way, regardless. To ensure that the content is preserved and its preformatted nature is obvious, some styling is required:
**Rich media module**: Preformatted quotes, including the opening and closing markers, must be displayed in the first available font from the “Monospaced Fonts” stack.
**HTML module**: Preformatted quotations, including the opening and closing markers, must be wrapped in “““<code>””” tags; this is the most semantic of all options—anything that would break the UEWSG is “code” of either a programmatic or lexical sort—and it also matches the most widespread use of this tag. The CSS “white-space” property must be set to “pre-wrap” to preserve formatting but allow automatic wrapping in browsers that don’t support the universal “word-wrap: break-word” declaration. No other [functional] HTML tags are allowed inside preformatted quotations, as this would negate their semantic meaning and potentially cause styling to applied.
For longer preformatted quotations, see “4.5. Preformatted Blockquotes”.
A list is a collection of 1 or more list items. Inline list items are usually separated by commas, though semicolons are allowed as separators if the list items themselves contain conflicting commas (the list “a and b; c, d, and e; f; g and h” is a great example). If a list is used in a sentence, the last separator should be followed by a conjunction which denotes the relationship of the list items to each other (“and”, “or”, etc); the last list item may then follow this conjunction. In all inline lists with separators, the serial comma/semicolon (ie, a comma/semicolon between the second-to-last and last list item; this is sometimes called the Oxford comma) must be used. It not only shows typographic care and professionalism, but greatly aids in readability and prevents potentially-unresolvable imprecision.
Inline lists that make use of inline list item markers (viz, numbers or letters) are allowed, so long as the inline list item markers end with a period (as in block-format lists; see “4.6. Lists”). Authors may follow the inline list item marker with a space alone or with a comma and a space (“a. [list item a], b. [list item b],…” and “1., [list item 1]; 2., [list item 2];…” are both perfectly acceptable); as noted in “2.5. Precedence”, parsing a period as a marker takes precedence over parsing it as the end of a sentence so this format is fairly unambiguous. The use of a closing parenthesis alone for this purpose (eg, “““a.)”””) is forbidden, due to catastrophic parsing issues, but full sets of parentheses are permitted (eg, “(a.)”). If a list item is referred to in text but *outside* a list, it must be written as regular text—*without* the period (eg, “In list item 1, note the…”)—or, as an alternative, enclosed in quotation marks (eg, “In list item ‘1.’, note the…”).
Note markers are the inline constructs which reference notes. As note markers are inserted material, they must always be enclosed in brackets (“[]”); this also helps to syntactically distinguish them from mere numbers or asterisks that may be used for other reasons in a text. If two or more different sets of notes are necessary (eg, the author’s original notes vs the editor’s notes), all secondary notes may be enclosed in 2 sets of brackets (“[[]]”) and labeled and listed separately, at the discretion of the editor; in any case, further clarification of the notes’s sources should be given in the note itself. While authors have freedom relative to which type of note marker they choose, numbered markers (ie, sequential numbers, starting with 1 (“[1]”)) resetting at the beginning of each chapter are *highly* recommended, both for clarity and ease of use. Note markers are also further styled:
**Rich media module**: Note markers, including their brackets, should be set in superscripted text. This is, however, left up to the discretion of the author.
**HTML module**: If note markers link to the actual notes, they should be marked with “““<a>””” tags.
For more information on displaying notes themselves, see “4.7. Notes”.
Because citations and bibliography styles vary so widely across different academic fields and great controversy surrounds their relative merits, no specific format for citations is provided in the Uniform English Writing Style Guide. Instead, authors should choose the citation style most appropriate to their type of writing and follow it, as far as it does not conflict with the UEWSG.
Emphasis adds depth to a document. Just as speakers do not typically communicate in monotone, so too authors make use of various forms of emphases to reflect the variable “tonal” quality of their writing. Much of the emphasis will need no markup: readers naturally process text and add some emphasis on their own. Similarly, authors can use other tools like repetition to draw attention to text. But, sometimes, particularly important concepts, statements, or warnings need to be specially marked. For these cases, the UEWSG defines an arbitrary number of levels of marked emphases, though only the first 3 are given visual distinction; further levels of emphasis are styled identically to critical marked emphasis. These levels of marked emphasis can nest under the general rule of 1 set of asterisks per level of emphasis. They also stack visually, up to the 3rd level. For example, if a sentence that has been marked with standard emphasis (level 1) contains a strongly emphasized word (level 2), that word would be critically emphasized (level 1 + level 2 = level 3) and displayed identically to any other critically emphasized content. Marked emphases will also stack visually inside description list markers, which are strongly emphasized (level 2) by default.
Standard marked emphases are the most basic degree of emphases, providing a reader a clue that the marked content has some additional value; in terms of importance, they are the 1st level of emphasis and are roughly equivalent to a single repetition, though they do not nest or otherwise interact with repetition visually or syntactically. Standard marked emphases are denoted by enclosing text within a single opening and closing asterisk (“*”), with no spacing on the inner sides of the asterisks.
**Rich media module**: Standardly emphasized text, including the opening and closing asterisks, must be displayed in italics.
**HTML module**: Standardly emphasized text, including the opening and closing asterisks, must be wrapped in “““<em>””” tags.
Strong marked emphases are more urgent than standard emphases, conveying a level emphasis that is ideal for very important points or phrases; in terms of importance, they define the 2nd level of emphasis and are roughly equivalent to double repetition (eg, “Lord, have mercy. Lord, have mercy. Lord, have mercy.”), though again they do not nest or otherwise interact with repeated words or phrases. Strongly emphasized text is marked by being enclosed within 2 opening and closing asterisks (“**”), also with no spacing on the inner sides of the asterisks; these asterisks may be used together to immediately begin a segment of strong marked emphasis or may be used separately to begin a portion of strong marked emphasis *within* text that already carries standard marked emphasis, following the general rule of 1 set of asterisks per level of emphasis.
**Rich media module**: Strongly emphasized text, including the opening and closing asterisks for the *2nd* level of nesting, must be displayed in bold but *not* in italics.
**HTML module**: Strongly emphasized text, including the opening and closing asterisks, must be wrapped in **2** sets of “““<em>””” tags, each set individually surrounding their associated sets of asterisks. Only when these asterisks are separated (ie, if one level of emphasis is nested within a part of another) should the tags also be separated.
Critical marked emphases are the most powerful emphases specially defined and are reserved for serious warnings or vital content that absolutely cannot be missed. They constitute the 3rd level of emphasis and text emphasized in this way probably should not be further emphasized (ie, emphasis can begin to lose meaning if it is overused, either in quantity or quality), though the Uniform English Writing Style Guide imposes no hard limit. Critically emphasized text is essentially a combination of strong and standard emphasized text, so it is marked by being enclosed within 3 opening and closing asterisks (“***”), again with no spacing on the inner sides of the asterisks; these asterisks may be used together to immediately begin a segment of critical marked emphasis or may be used separately to begin a portion of critical marked emphasis *within* text that already carries standard or strong marked emphasis, following the general rule of 1 set of asterisks per level of emphasis.
**Rich media module**: Critically emphasized text, including the opening and closing asterisks for the *3rd* level of nesting, must be displayed in both bold *and* italics.
**HTML module**: Critically emphasized text, including the opening and closing asterisks, must be wrapped in **3** sets of “““<em>””” tags, each set individually surrounding their associated sets of asterisks. Only when these asterisks are separated (ie, if one level of emphasis is nested within a part of another) should the tags also be separated.
When referencing keyboard keys, the name of the key must be written in title case, just as it appears on the keyboard (eg, “Shift”). Combinations of keys must be separated by plus characters, with spaces (like “Ctrl + Alt”). Styling is needed to fully distinguish them from surrounding content:
**Rich media module**: Keyboard keys (but not any separators) must be displayed in the first available font from the “Monospaced Fonts” stack.
**HTML module**: Keyboard keys (but not any separators) must be wrapped in “““<kbd>””” tags.
While the process of censoring itself is outside the scope of the UEWSG, there are some guidelines for handling censored text. In encrypted fields (like passwords) or where the text is clearly isolated from other constructs, characters should be replaced with bullets (“•”) or, for even more security, be left completely invisible. For in-text censoring, where individual words or phrases are merely obfuscated, characters should be replaced with the sequence “!@#$%”, repeated as many times as is necessary to censor every character; any string that begins with the sequence “!@” is considered to be censored text, for the purposes of mechanical parsing. For fake censoring (such as for the sake of irony), the most media-independent option is epanorthosis (eg, “…the whole world, no, the entire galaxy!”). For the semi-anonymization of names, all but the first letter should be omitted to form an initialism; a trailing em dash may be added for further clarity (“Captain A” and “Captain A—” are both acceptable). Text that is missing or lost should be denoted by ellipses (eg, “A g…d plan today…better t…perfect plan…morrow.”).
Directions to a speaker reading a dialog (eg, directions in a prayer book or stage directions in a play) must be written inside parentheses like other parenthetical information but should also be further styled:
**Rich media module**: Directions must be displayed in italics (eg, “Lord, have mercy! (Thrice)”).
**HTML module**: Directions must be wrapped in “““<i>””” tags.
In digital media (especially HTML), links are the most common type of interactive content and, perhaps more than any other construct, define the World Wide Web. However, since they have no built-in fallback mechanism, hyperlinks—especially those that point to another page and moreso to another website—should be constructed from only the URL of the page they point to; in case the hyperlink itself somehow fails, this will still allow the content to be located. Textual hyperlinks are styled clearly and simply, in the traditional way:
**Rich media module**: Unvisited links must be colored “blue” (a default of #0000EE), active links must be colored “red” (a default of #EE0000), and visited links must be colored “purple” (a default of #551A8B); these colors follow both internet tradition (using the default colors given in both the HTML5 Phrasing Content spec and most HTML5-compatible browsers) and keep a balance between a contrast which is too high and too low. Links must also have a solid underline of the same color as their type, also in keeping with near-universal custom.
**HTML module**: Links must be wrapped in “““<a>””” tags and given working URLs, meaningful titles, and other properties, as needed.
Links are not the only form of interactive text and users need to be able to recognize these other forms of interaction. Authors must give all purely text-based interactive content extra styling (this excludes buttons, images, etc):
**Rich media module**: Other interactive text must have a 0.0625 (1/16) em dotted bottom border.
**HTML module**: Other interactive text must be wrapped in the proper tags (ie, “““<abbr>””” tags for abbreviations, etc) and given meaningful titles and other properties, as needed. Interactive text that isn’t part of a normally-interactive element may be given the property “class="interactive"” and, if required, wrapped in a “““<span>””” with this class.
While it is important to rightly utilize constructs inline, it is just as important to properly organize a document at a higher level. The larger-scale constructs that perform this task are called block constructs and, as the name suggests, are always displayed in “block” format: they are separated from other block constructs by a blank line. This means that all block constructs must be followed by a double line break (ie, a blank line) unless they occur at the end of a container; the last construct in a document (which is itself a container of sorts) must be followed by no line breaks of any kind. (Nearly every other situation—such as a title or paragraph following a block opening marker—occurs *within* a block construct and thus is subject to the normal line-breaking rules in “2.1.2. Line Breaks”.) Spacing must also be correctly handled: blocks must not have any leading or trailing spaces on their opening and closing lines, respectively, any spacing between the characters that constitute their markers, or any spacing in between the marker and the content—unless the marker includes a space character. Block formatting may seem strange to those who have not done much formal writing or design, but it is the best—and probably least intrusive—way to preserve the readability of a work.
**Paged media module**: Page breaks must not occur between division markers and headings (subject to a few clearly-noted exceptions), immediately after division headings, immediately after opening markers, or immediately before closing markers.
**HTML module**: All block construct markers that need to be targeted for type-wide styling in the Uniform English Writing Style Guide must be wrapped in a “““<span>””” tag with the class set the the singular, snake case, UEWSG name of the marker—the division headings for constructs in this specification constitute their canonical names, unless otherwise noted. For example, chapter markers must be wrapped in “““<span class="chapter_marker">””” tags and note division markers in “““<span class="note_division_marker">””” tags. Markers must not be part of any other block construct within the containing construct (eg, a paragraph in a blockquote would begin *after* the blockquote’s opening marker; the marker would *not* be part of the paragraph). All division markers and breaks must be given the additional properties “display: block” and “clear: both”, to prevent floating elements (viz, asides) from spilling over from other divisions and/or stacking horizontally. And, of course, “““<br>””” tags *must* follow most block constructs (except the last block construct in a containing construct) in order to create a double line break.
Divisions are the main structural constructs of documents. Along with their corresponding headings, they provide the general framework for communicating a clear, logical message to readers. A well-designed structure can serve to further an author’s points, while a poor layout can sink any chance they have to effectively argue their thesis. Therefore, it is crucial to thoroughly grasp the syntax and functioning of divisions and headers in the Uniform English Writing Style Guide to create readable, functional works.
Authors should clearly and hierarchically structure their works; numbered divisions (ie, headings that are also inline numbered list items, as used in the UEWSG spec itself) are encouraged, but not required. When subdividing content, the next-highest-level division must be used; for example, it is not permitted to jump directly from a chapter [level 2] to a subsection [level 4]. Division markers and headings are always displayed in block format as a unit, so the division marker and headings themselves are contiguous: they are on separate lines, but are not separated by an intervening blank line. Anything that is contiguous with the marker will be treated as the heading. Conversely, if no heading is desired for a division, it may be escaped: a blank line may be inserted directly after the division marker, preventing a division heading from displaying. A document must not end with a visible division marker of any kind.
Division markers themselves are generally composed of 1 character repeated 3 times. Division markers must not have any spaces whatsoever. Headings may contain just about anything, but must not contain block markers without closing markers (eg, further division markers); all other constructs are allowed, as long as the heading block remains contiguous with the division marker: multi-line headings, headings containing quotations, and all sorts of other creations are permitted (subtitles are usually provided via adjectival paragraphs). All headings must be written in title case, except for portions that are in some form of quotation.
The document is the highest structural level in normal writing, so documents can be considered level 1 “divisions”. The first line (or series of contiguous lines) of any document is its main title, a level 1 heading, by default; the filename of a document should match this heading (ideally in strict snake case, see “2.3. Filenames”). Titles should be as concise and descriptive as reasonably possible (the recommended limit on full URLs or paths is 255 characters); if needed, a subtitle can be used to convey extra information that would unnecessarily lengthen the title and thus the filename. If a document title is escaped from the usual location [by leaving a blank line at the beginning of a document], it must be placed elsewhere using the main title marker, 3 hashes (“###”), because all distinct documents *must* have a main title; the main title marker must only be used in this special case. The main title marker does not have any structural function—but does center any adjectival paragraphs below it (eg, subtitles)—and doesn’t override the current division in any way.
**Rich media module**: Main titles must be centered, displayed in bold at 2 em (ie, 2 × base font size), and have a correspondingly-increased line height of 2.5 em (ie, 2 × base line height). A main title marker, if present, must also be centered.
**HTML module**: Main titles must be wrapped in “““<h1>””” tags; any other tags or markers (eg, for a quotation, for emphasis, etc) must fall inside of these tags. A “““<br>””” tag must directly follow the closing “““</h1>””” tag. The main title marker, if present, must be wrapped in “““<span class="main_title_marker">””” tags and given the additional properties “display: block” and “clear: both”, to prevent floating elements (viz, asides) from spilling over from other divisions. It is also a best practice to put the page title in “““<title>””” tags (within the “““<head>””” of a document), followed by an em dash (or its ASCII equivalent, a hyphen with spaces on both sides; see “2.1.3.1. Fallback Characters”) and the website title.
Content which is not saved as a discrete document (IM, SMS, etc) and/or is in a format where the main title is disjunct from the content (eg, e-mail) is exempted from having a main title and the first line is therefore *not* the main title, though authors may still assign a main title via the main title marker; if such content is written with no line breaks and/or block-format markers, all text is treated as a single paragraph.
Chapters are the default type of division inside the content of documents; they are level 2 divisions. While chapters in the UEWSG can be compared to chapters in a book, they are not limited to such a narrow use. Chapters begin directly following 3 pluses (“+++”); the marker itself is also technically the end of the previous chapter [if present] and “closes” all preceding divisions up to, and including, the chapter level. A level 2 heading follows this marker and is the title of the division.
**Rich media module**: Chapter headings must be displayed in bold at 1.6 em (ie, 1.6 × base font size) with a correspondingly-increased line height of 2 em (ie, 1.6 × base line height). A 0.0625 (1/16) em solid border must be set above all level 2 headings, but below the division markers, and span the full width of the document (minus the document’s margins). Chapter markers must be centered.
**Paged media module**: A page break is required directly after the marker but before the heading. This will create a visual break but, if transferred to plaintext, the marker will be still be contiguous with its heading. No border or extra padding is allowed above the heading. Finally, no page breaks are allowed immediately before chapter markers.
**HTML module**: Chapter headings must be wrapped in “““<h2>””” tags; if there is no heading (ie, it is escaped), these tags must *still* be present, just empty. Any other tags or markers (eg, for a quotation, for emphasis, etc) must fall inside of these tags.
Sections are the next level of division inside the content of documents. While the word “section” may be used in many contexts as a synonym for a “division” of any sort, they must not be confused in the technical language of the UEWSG: sections are level 3 divisions. They can be thought of as subchapters, since they further divide content inside of chapters. Sections begin directly following 3 equal signs (“===”); the marker itself is also technically the end of the previous section [if present] and “closes” all preceding divisions up to, and including, the section level. A level 3 heading follows this marker and is the title of the division.
**Rich media module**: Section headings must be displayed in bold at 1.25 em (ie, 1.25 × base font size) with a correspondingly-increased line height of 1.5625 em (ie, 1.25 × base line height).
**HTML module**: Section headings must be wrapped in “““<h3>””” tags; if there is no heading (ie, it is escaped), these tags must *still* be present, just empty. Any other tags or markers (eg, for a quotation, for emphasis, etc) must fall inside of these tags.
Subsections are the next levels of organization inside of documents; they are level 4 divisions. They further divide sections in much the same way parts of a chapter are further broken down into specific topics by sections. Subsections begin directly following 3 hyphens (“---”); the marker itself is also technically the end of the previous subsection [if present] and “closes” all preceding divisions up to, and including, subsection level. A level 4 heading follows this marker and is the title of the division.
**Rich media module**: Subsection headings must be displayed in bold at 1 em (ie, 1 × base font size) with a corresponding line height of 1.25 em (ie, 1 × base line height).
**HTML module**: Subsection headings must be wrapped in “““<h4>””” tags; if there is no heading (ie, it is escaped), these tags must *still* be present, just empty. Any other tags or markers (eg, for a quotation, for emphasis, etc) must fall inside of these tags.
Extended subsections are the lowest levels of organization inside of a document; they are level 5 and higher divisions. As evidenced by their name, extended subsections extend the idea of subdivision to even finer levels and can split a document down into amazingly precise parts; 3 or 4 levels of headings are usually more than enough for most works, but some, more technical documents may need these deepest levels of division. Extended subsections begin directly following *5* or more tildes, according to their level (eg, “~~~~~” for a level 5 extended subsection); the marker itself is also technically the end of the previous extended subsection of the same level [if present] and “closes” any preceding extended subsection(s) of higher level. An extended subsection heading follows this marker and is title of the division.
**Rich media module**: Extended subsection headings must be displayed in bold at 0.8 em (ie, 0.8 × base font size) with a correspondingly-decreased line height of 1 em (ie, 0.8 × base line height). Deeper levels of extended subsections *are not* displayed in even smaller sizes; for readability, all extended subsections are displayed at one size.
**HTML module**: Extended subsection headings must be wrapped in “““<h5>””” “““<h6>”””, etc tags ), according to their level of nesting (eg, a “~~~~~~” would receive “““<h6>””” tags) tags; if there is no heading (ie, it is escaped), these tags must *still* be present, just empty. Any other tags or markers (eg, for a quotation, for emphasis, etc) must fall inside of these tags.
Paragraphs are the most basic block constructs and the primary elements for providing a document’s content. While divisions and headings provide the organization for an author’s thesis, paragraphs hold the meat, the substance of their argument. Nearly all text is treated as a paragraph: other than block construct markers, headings, and content in preformatted blockquotes, all text is, by default, part of a paragraph. Paragraphs must not be indented; because of this particular syntax, paragraphs do not necessarily need to end with a terminal punctuation mark, such as a period: they may end with any suitable character, such as a colon. Indeed, in the case of adjectival paragraphs—paragraphs which modify or qualify preceding content, like a subtitle after a title or the author of a blockquote (eg, “—Fr Stephen Freeman”)—sentence fragments are typical and no particular punctuation is required at all. Minimal styling is needed:
**HTML module**: Paragraphs must be wrapped in “““<p>””” tags. Note that text inside other constructs (lists, asides, etc) is *also* part of a paragraph, by default; therefore, after any tags or markers for the construct itself, the content must be further wrapped in “““<p>””” tags *within* the containing construct’s tags. An adjectival paragraph which modifies a main title [or by extension a whole document], which is centered, must be given the tag “““<p class="main_title">””” and also be centered; other adjectival paragraphs require no special markup.
Even with the framework provided by the divisional structure of a document, it is sometimes necessary to further break material up, omit certain points, or interject something quite tangential. In these situations, one of two breaks can be used.
A dinkus breaks up a division without beginning a new, lower-level division: it denotes a shift in topic or context. For example, a novel may shift abruptly from one scene to another. It can also be used to separate one or more adjectival paragraphs of a main title (eg, subtitles) from further front matter (like summaries, excerpts, and reviews). Dinkuses are denoted by 3 asterisks (“***”).
**Rich media module**: Dinkuses must be centered.
Much like its inline usage, an ellipsis breaks up a division by inserting a pause: it can stand in for an actual pause in time or thought, or denote that some information was omitted. The ellipsis is represented by the ellipsis character (“…”) and, like the dinkus, only minor styling is necessary:
**Rich media module**: Ellipses, when used as [block construct] breaks, must be centered.
When a quotation consists of an entire paragraph (or more) but needs no other, special treatment—a lengthy quotation from a book, a long test-question answer, a standout product testimonial, etc—blockquotes are often the best solution. Like inline quotations, blockquotes are opened and closed with opening and closing quotation marks, respectively (ie, “ “” ” or “ ‘’ ”). Nested blockquotes follow the same pattern as nested quotes, switching between single and double marks for each level of nesting; the quotation marks are block construct markers, though, and must never appear on the same line as any content. Blockquotes can contain paragraphs, lists, asides, or any other block constructs. As blockquotes do not technically constitute new divisions, no heading is implied by the first line of its content, though headings may be freely used, and the divisions within the construct remain structurally separate from the surrounding content.
**Rich media module**: Blockquotes must have a left and right padding of 1.25 em (ie, 1 × base line height).
**HTML module**: Blockquotes, including the opening and closing markers, must be wrapped in “““<blockquote>””” tags.
Preformatted blockquotes combine the ideas of preformatted quotations and blockquotes: they preserve the printable characters, whitespace, and line breaks in a content block of any size. Content in preformatted quotes must wrap automatically, though: while line breaks are preserved, long lines that would otherwise overflow the width of a document must necessarily span multiple lines. This construct is not only required for containing blocks of code, but must also be used for displaying ASCII art, text-based tables, or other creations that fundamentally depend on regular character width, precise spacing control, and/or non-UEWSG-compatible formatting. Preformatted blockquotes are opened and closed with 3 contiguous sets of opening and closing quotation marks, respectively (ie, “ “““””” ” or “ ‘‘‘’’’ ”); as with all other quotations, the Uniform English Writing Style Guide allows local custom to dictate which type (ie, single or double) will be used for the outermost instance. Like blockquotes, preformatted blockquotes can contain paragraphs, lists, asides, or any other block constructs—but any contained constructs must not have any styling whatsoever and are not parsed as constructs. As preformatted blockquotes do not technically constitute new divisions, no heading is implied by the first line of their content, though headings may be freely used, and the divisions within the construct remain structurally separate from the surrounding content.
**Rich media module**: Preformatted blockquotes must be displayed in the first available font from the “Monospaced Fonts” stack. All font sizes must be overridden and set to the default font size (ie, 1 em) and all styling must be overridden and set to match the base font style. Finally, preformatted blockquotes must be given a left and right padding of 1.25 em (ie, 1 × base line height).
**HTML module**: Preformatted blockquotes, including the opening and closing markers, must be wrapped in “““<pre>””” tags; this will preserve all spaces, tabs, and line breaks. The CSS “white-space” property must be set to “pre-wrap” to preserve formatting but allow automatic wrapping in browsers that don’t support the universal “word-wrap: break-word” declaration. No other [functional] HTML tags are allowed inside preformatted blockquotes, as this would negate their semantic meaning and potentially cause styling to applied.
From shopping lists to product assembly instructions, many types of material are very well-suited to being displayed in lists, particularly block lists. In some ways, these lists mimic the overall structure of a document: they can be nested, creating different levels of hierarchy and quickly organizing complex data. But, in contrast to divisions, list items usually contain only a small bit of information that can be easily skimmed. As lists are primarily defined as a “collection of list items”, block list items need to be defined first.
List items, in block lists, are constructs beginning with a list item marker. In list items containing only one paragraph, the item ends at the end of the paragraph (ie, after the first blank line). If a list item contains more than one paragraph, all subsequent paragraphs must begin with the list item continuation marker, a caret (“^”) and a space—it must *not* have a preceding blank line, however, unlike normal paragraphs. Only paragraphs and other lists are allowed to nest directly in list items: nesting other block constructs stretches the definition of lists and is not allowed, even though the “bulletproof” nature of the Uniform English Writing Style Guide can technically handle such cases. As list items are a special case of block constructs—almost sub-constructs in nature—a double line break (ie, blank line) must *not* follow the end of a list item, but normal block construct line-breaking behavior still applies to the list, or collection of nested lists, as a whole. Asides can be placed between list items or paragraphs within a list item, as they do not nest normally but remain structurally independent; however, they *cannot* be placed directly between two lists of the same type and level of nesting, since list items are distinguished by their lack of blank lines and thus must be treated as part of the same list, despite the blank lines surrounding an aside. List items, and their markers, need a moderate amount of styling:
**Rich media module**: List item markers must be inserted *manually*. The list items as a whole must be given a left margin of 1.25 em (ie, 1 × base line height) and a text indent (for the first lines of paragraphs) of -1.25 em—a *negative* indent. When combined, these indents will leave the list item marker flush against the left margin for the content while setting the subsequent lines at a 1.25 em indent. Nested list items must be indented a further 1.25 em for each level of nesting (eg, a 3rd-level list item would be indented 3 × 1.25 em, or 3.75 em) but retain the same negative text indentation.
**HTML module**: List items themselves must be wrapped in “““<li>””” tags. Regrettably, because lists are one of HTML’s greatest weaknesses, paragraphs don’t work as expected. Because of this, all list item markers must be wrapped in “““<p>””” tags, too. While this is technically a violation of the Uniform English Writing Style Guide’s underlying nesting principles, it is still considered “correct” because browsers can’t readily handle other methods and no actual UEWSG *syntax* violations occur (eg, cut/paste operations from browser into plaintext aren’t impacted). Everything else should be marked up [and work] as expected. As list items are a unusual case of block constructs, a “““<br>””” tag must *not* follow the closing “““</li>””” tag at the end of any list items. A final “““<br>””” must, however, be placed after the end of the list, or collection of nested lists, itself (eg, after the “““</ul>””” tag in a bulleted list).
Bulleted lists are the most common type of block lists and are useful for a wide range of textual materials and data. Because no particular order or importance is implied by bullets, this type of list is ideal for information that hasn’t been further structured or systematized, like a simple shopping list. The list item marker for bulleted lists is, not surprisingly, a bullet(s) (“•”) and a space. If one bulleted list nests inside another, its list item markers must contain one more marking character (ie, bullet) than the parent list’s item markers. For example, a third-level bulleted list would have 3 marking characters in its list item markers (“•••”); this is *very important* for properly parsing lists, especially in plaintext.
**Rich media module**: Non-UEWSG-compatible automatic list styling, if available, must be disabled or overridden.
**HTML module**: Bulleted lists must be wrapped in “““<ul>””” tags.
Numbered lists are excellent for ordered data: step-by-step instructions, a list of a person’s top 5 favorite foods, and notes all benefit from being cleanly displayed in a numbered list. The list item marker for numbered lists is one or more sets of an Arabic number followed by a period, with the set(s) as a whole followed by a space (eg, “1. ” and “42.0. ”). If one numbered list nests inside another, its list item markers *must* hierarchically contain all the numbers of the parent list item’s marker. For example, item 7 on a third-level numbered list, itself the child of item 3 on a second-level list and which is in turn the child of item 13 on a first-level list, would have 3 contiguous sets of numbers, each delimited by a period and the last one followed by a space, for its marker (“13.3.7. ”). This is the clearest, most powerful way to organize numbered lists and, just as with bulleted lists, styling is minimal:
**Rich media module**: Non-UEWSG-compatible automatic list styling, if available, must be disabled or overridden.
**HTML module**: Numbered lists must be wrapped in “““<ol>””” tags.
Description lists are helpful for describing or defining terms, but work well for any key–value pair. A glossary is a classic example of a description list, but a term (or multiple terms at once) can be given any sort of explanation, value, or treatment. The list item marker for description lists is a term marked with strong emphasis and immediately followed by a colon and a space (eg, “**Term**: ”). Multiple terms can be separated by commas or semicolons and point to the same value, as long as each term is individually marked, no other characters intervene, and the last term touches the colon (eg, “**One Term**, **Another Term**: ”). While this type of list can technically be nested, it will not convey the same hierarchal clarity as a bulleted or numbered list.
**Rich media module**: Non-UEWSG-compatible automatic list styling, if available, must be disabled or overridden.
**HTML module**: Description lists must be wrapped in “““<ul>””” tags. The list item markers must be wrapped in **2** sets of “““<em>””” tags, each set individually surrounding their associated sets of asterisks, just like any other strongly emphasized text (see “3.11.2. Strong Marked Emphases”).
Other block lists include checklists and fill-in-the-blank lists. All of these other list types are not treated separately in the Uniform English Writing Style Guide, but rather are assumed to be sub-types of bulleted lists. So, a checklist item would have exactly the same list item marker, a bullet (“•”) and a space, but might have an empty checkbox character (“☐”) as the first part of its content. Likewise, a fill-in-the-blank list item would start with a bulleted list item marker, but could utilize any number of underscores (“_”) as the first part of its content. By treating all other lists this way, they can be used in conforming documents without any extra definition. They will nest, and display, exactly the same as bulleted lists.
Block-format notes are crucial in academic writing: they can provide more specific information about in-text citations, point to third-party sources of evidence, or clarify difficult terms or concepts. Granted, they can be used for other purposes, too: notes can point out puns, provide author commentary, and shed light upon the “why” of a subject. More generally, they are used when an in-text citation or parenthetical note would be inappropriate but, whatever their use, they must be clearly and properly marked.
Actual notes are always located in a note division, which must occur at the end of a chapter, after all other subdivisions. Within this dedicated division, notes must be displayed in the proper block list type, corresponding to the note markers (eg, numbered note markers would correspond to a numbered list). Note divisions begin directly following 3 underscores (“___”) and no chapter may contain more than a single type of note. There are 3 defined headings, corresponding to 3 types of notes: “Footnotes”, “Chapter Notes”, and “Endnotes”.
Footnotes are the most directly helpful kind of block notes, as they appear closest to the content they describe; this type of note is best when information needs to be quickly referenced in order to understand the text. The heading “Footnotes” triggers this display type, but the heading may optionally be escaped: all escaped note division markers will be treated as footnotes. While the notes will still be located at the end of a chapter syntactically and will thus be displayed there in non-paged media, in paged media this display type will signal that the notes must be displayed on the same page as their marker.
**Rich media module**: “Footnotes” headings [if unescaped] are equivalent to and must be displayed like subsection headings (ie, at 1 em, in bold, etc; see “4.1.4. Subsections”), except that they use the note division marker.
**Paged media module**: The note division marker and “Footnotes” heading [if unescaped] must be displayed at the bottom of the page containing the first note marker. After the marker [and, if present, heading], the first note must be displayed in the proper type of block list. All subsequent notes must appear at the bottom of the page their note marker appears in. Subsequent note divisions on other pages still require a note division marker (“___”) followed by a blank line, but the heading must be escaped.
**HTML module**: “Footnotes” headings must be wrapped in “““<h4>””” tags.
Chapter notes are useful when the content of the notes is more citational in nature and merely glancing at a note will not necessarily help the reader understand the material better. The heading “Chapter Notes” triggers this display type, which displays the notes where they occur syntactically—at the end of the chapter—even in paged media. Chapter notes should not be used in documents containing only 1 chapter—or no chapters!: footnotes or endnotes may be used in such cases, however.
**Rich media module**: “Chapter Notes” headings are equivalent to and must be displayed like section headings (ie, at 1.25 em, in bold, etc; see “4.1.3. Sections”), except that they use the note division marker.
**Paged media module**: The note division marker and “Chapter Notes” heading must be displayed at the end of the division containing the notes. After the heading, the notes must be sequentially displayed in the proper type of block list.
**HTML module**: “Chapter Notes” headings must be wrapped in “““<h3>””” tags.
Endnotes are the least accessible type of note, as they can be difficult for readers to locate and glean information from. However, when the content of the notes is composed mostly of extraordinarily verbose citations, this may be the least disruptive way to display them. The heading “Endnotes” triggers this display type, in which the notes are both syntactically written and displayed as a separate chapter at or near the end of a document—the note division marker and subsequent heading are treated syntactically like the chapter marker’s heading (ie, the note division marker and heading are only separated by a single line break). While footnotes or chapter notes may be used on any further chapters that follow the endnotes, only *1* endnotes division is allowed in any document.
**Rich media module**: “Endnotes” headings are equivalent to and must be displayed like chapter headings (ie, at 1.6 em, in bold, etc; see “4.1.2. Chapters”), except that they use the note division marker and must not have a top border or extra top padding.
**Paged media module**: The note division marker and “Endnotes” heading must be displayed at or near the end of the document, starting on a new page (the note division marker, unlike the chapter marker, *must* be on the same page as the heading). After the note division marker and heading, the notes must be sequentially displayed in the proper type of block list(s). Regardless of medium, all endnotes must be divided into lists based upon their chapter, with a section division and heading (level 3) for each chapter’s list.
**HTML module**: “Endnotes” headings must be wrapped in “““<h2>””” tags.
Asides allow authors to insert more content within a division: they can contain any amount of text or other constructs (such as their own internal divisions and headings), except for more asides. Many types of documents have no need for asides, but some specialized works can make great use of them. For instance, a history textbook may need to provide a tangential, but crucial, fact about a faraway political decision which nonetheless subtly influenced the events under discussion. Or, a product manual may need to provide a lengthy explanation due to the dangers involved in a particular use of the product. Thus, asides are a valuable tool, particularly for technical authors. An aside opens with three forward slashes (“///”) and closes with three backslashes (“\\\”). They are structurally separate from the surrounding syntax (except that they can be contained within blockquotes and preformatted blockquotes), can only be inserted in between other block constructs, and must not cross a divisional boundary. They may also be inserted between list items within a block list, so long as they also have a *preceding* blank line. And unlike adjectival paragraphs or code comments, asides do not need to follow the content they describe—they can also *precede* their targets, a structural option which may display better in some rich-media formats (like HTML); all that is required is that asides be within the same division as the content they refer to. Because they do not technically constitute new divisions, no heading is implied by the first line of an aside’s content, though headings may be freely used, and the divisions within the construct remain structurally separate from the surrounding content. A *lot* of styling is necessary:
**Rich media module**: Asides must span 40% (2/5) of a document’s width (ie, 40% of the width of a full-width paragraph). They must have a 1.25 em (ie, 1 × base line height) left margin and 1.25 em of padding on the left and right. Asides must be fixed to the right edge of a document [just inside the margins], display a solid, black (#000000), 0.0625 (1/16) em-wide border around the padding [but inside of the left margin], and have all margins reduced by 0.0625 em to compensate for the border.
**HTML module**: The content *and markers* of asides must be wrapped in “““<aside>””” tags with the proper border, padding, and border-compensating negative margin. Because of the way HTML renders line breaks with floating elements and other issues, the aside must be further wrapped in “““<div class=aside>””” tags and this div must have the rest of the styling applied to it: the width, left margin, floating, and the property “clear: both” (to prevent horizontal stacking of asides). Also because of the way HTML works, the “““<br>””” tag must *precede* the closing “““<div>””” tag directly, after the closing “““<aside>””” tag.
Tables are extremely useful for presenting relationships among many different values or data points. But they also straddle the line between writing and drawing: tables convey much of their information via their layout. Thus, there is no particular way to gracefully handle tables across all media and the Uniform English Writing Style Guide provides no default alignment, width, or other styling for tables as a whole.
In many cases, it may be necessary to insert other constructs into a document, such as images and videos, which are not primarily textual in nature and thus largely fall outside the scope of the UEWSG. The display for all such constructs should probably be in block format; in HTML, this can be accomplished either by inserting *2* “““<br>””” tags after them or even changing their display to block via CSS. They must, of course, follow the conventions of the containing file’s format (ie, “““<img>””” for images in HTML, etc). Any such additional constructs and their associated styling (including various alignments and widths), so long as they not violate the UEWSG, do not negatively affect a document’s conformity to the Uniform English Writing Style Guide.
Both before a document is created and after the final characters are written, authors must have styling in mind. Thankfully, the UEWSG makes many of the most common, time consuming decisions—text alignment, margins, font size—easy: straightforward defaults are provided for all of these tedious choices and should greatly aid authors in the majority of use cases.
Text alignment can communicate many things: relative strength, importance, relationships, and so on. For most types of content, only two alignments are appropriate: left-aligned and justified. Unfortunately, outside of professional typesetting, justification is very difficult to execute well and often results in poorly spaced characters, excessive internal whitespace, and other typographic problems. Therefore, all text and markers, unless otherwise noted, must be **left-aligned**: this forms clean visual blocks, with sharp left sides drawing readers’s attention to the beginning of the content.
The UEWSG provides no specific guidance regarding columns, headers, footers, and similar displays. Authors are free, so long as they remain within the other constraints of the Uniform English Writing Style Guide, to make discerning use of these options. Headers and footers may make use of centered, left-, or right-aligned text, as needed. All such displays do not negatively affect a work’s strict conformance to the UEWSG.
Margins frame a document; they not only provide a convenient place to grip a printed work, but visually accentuate the content through the active use of whitespace. Margins also determine the line length—or vice versa, depending on the point of view. While long line length has many drawbacks (foreboding density, poor readability, the loss of safe physical handling points, etc), so does short line length (unprofessional thinness, structural disorientation, jarring eye movements, etc)—and both of these extremes must be weighed against respecting readers’s preferences. The best option for standardized documents is to set appropriate margins and let the actual medium dictate the line length; in the case of rich, digital media, this allows the reader to retain a great deal of control. Thus, the UEWSG’s rules regarding margins and line length are very basic:
**Rich media module**: Margins must be set to only **1.25 em** (ie, 1 × base line height) in rich media. In addition to being satisfactory from the perspective of the user (ie, it is generally very easy for readers to change the viewport size and further adjust digital documents, so humbler margins give larger amounts of control), this width is also ideal for smaller screens (eg, on many phones), where a bigger margin would be problematic.
**Paged media module**: Margins must be set to **2.5 cm** (about 1 in; 1 in—exactly—is currently allowed for compatibility with legacy American measurements). This width is an ideal balance between overpowering amounts of whitespace and overwhelmingly long lines and, thankfully, is already in widespread use.
**HTML module**: All elements must be given the property “word-wrap: break-word” to limit line length and prevent horizontal scrolling, such as when long URLs, paths, and/or filenames are used in a document.
In paged media, content sometimes gets cut off at the top or bottom of a page. Content that begins at the bottom of a page is said to be orphaned, while content that ends at the top of a page is said to be widowed. Widows, in particular, are not only unsightly but can make it difficult for readers to follow the flow of an author’s writing and can interrupt the reading experience. Therefore, a measure of control is needed:
**Paged media module**: Widows must be limited to a minimum of **2 lines**.
One of the most common decisions that authors must make is font size: how big should different headings be? In order to make both the writing and design of documents quicker and easier, the Uniform English Writing Style Guide already has pre-defined sizes for such constructs. But these values are all relative: they are all multipliers of the base font size. Indeed, most other measurements (line height, margins, padding, etc) are also derived from it, so the base font size needs to be carefully selected. Too big, and a document becomes inefficient and goofy. Too small, and a work becomes difficult, or impossible, to read. Therefore, the defaults are sensible:
**Rich media module**: The base font size must be set to **12 pt** (16 px).
**HTML module**: The base font size must be set to **1 em**; as most web browsers have their default font size preset to 16 px, this both falls within the rich media default of the UEWSG and gives readers more direct control over the display, if desired, as screen sizes and reading distances vary immensely.
Line height, or “leading”, is a more subtle way to affect the layout of a document and one of the key factors in giving a work its “rhythm”. Lines that are too closely spaced will make text seem dark and dense, overcrowded, and uninviting. Lines that are too far apart will make text seem sparse and wispy, unconnected, and insignificant. Both extremes, if implemented in running text, can make a document very difficult to read and serve to take away an author’s credibility. A wise middle ground is needed:
**Rich media module**: Line height must be set to **1.25 em** (ie, 125% of or 1.25 × the base font size). Most typefaces work extremely well at this height; it is short enough to prevent the text from becoming fragmented but tall enough to give an uncluttered feel. And, of course, it is a reciprocally-terminating value.
**HTML module**: Due to various line height bugs, all tags that provide rich media styling (“““<cite>”””, “““<var>”””, “““<i>”””, etc) should have their line height explicitly set to 1 em. Further, both the “““<sup>””” and “““<sub>””” tags should have their line height explicitly set to “0”.
The choice of typefaces, or collections of fonts from the same family, is one of the more rudimentary forms of control an author has over a document; just about every type of document that isn’t handwritten uses pre-designed fonts. A document not only needs to display the full character set that the work requires, but it should render those characters well. A strong use of typefaces can seamlessly help to “sell” the author as a thoughtful communicator and their message as credible. But poor font choices can make a document look unprofessional, silly, or even unreadable. The overall typographic strength of a document depends on much more than an individual font choice, though!
Of course, while a typeface can break a document, systems can break fonts: by default, most typefaces are unavailable on most systems. And some specialty fonts or font formats may be poorly supported by a wide range of systems. Therefore, it is essential to use typefaces that are also well-distributed and, ideally, in open formats, like OpenType. This format, for example, is not only supported on just about every modern system, it also supports more typographic features and sharper rendering than many older formats.
Instead of defining just one font family for each use, typefaces are listed together in “stacks”. Authors must use the first typeface in the stack that is supported on their platform; the rest act as fallbacks. The fallback typefaces are similar enough to the [preferred] first typeface so as not to cause egregious display issues. The default from each typeface is the Roman, normal-weight, unstyled font—text should be as readable as possible. Kerning is recommended, when available, for all fonts.
Sans-serif fonts are the default stack for all documents. They are closer to natural writing than serif typefaces, with clean ascenders and descenders and a keen look. These particular sans-serif font families are especially well-suited to screen display but, of course, render well even in high-quality prints. The preferred typeface in this stack is Arial: it may be the single-most-compatible sans-serif font family in existence. Despite its reputation among some typographers, Arial simultaneously features high legibility, great character density, and a strong, timeless style. The full stack, followed by a generic “sans-serif” placeholder if possible, is:
1. **Arial**
2. Helvetica
3. Arimo
4. Liberation Sans
5. Arial Unicode MS
Monospaced fonts are the default stack for dealing with fixed-width (ie, monospaced) text and data, either when viewing such a file in raw form or displaying a segment of such content in a preformatted quote or preformatted blockquote (see “3.7. Preformatted Quotations” and “4.5. Preformatted Blockquotes”, respectively). For example, ASCII art, text-based tables, and old computer files may not render intelligibly in other categories of fonts. The preferred typeface in this stack is Cousine: like the others in the stack, it has wide characters, sharp lines, dotted zeroes, and a natural feel that is relatively uncommon (but very desirable) in the monospaced category. The full stack, followed by a generic “monospace” placeholder if possible, is:
1. Cousine
2. Liberation Mono
3. DejaVu Sans Mono
4. Hack
5. Andale Mono
Serif fonts are not a default stack for any specific purpose in the Uniform English Writing Style Guide, but they are so common that it would be almost scandalous to ignore them. And in case a stylesheet for a non-strictly-conforming document does make use of this category of typefaces, it is important to utilize well-tested font families. Serif fonts convey a sense of tangibility and a classical look to works; perhaps this is why they are very common in books and printed materials. The preferred typeface in this stack is Times New Roman: while it is a smaller typeface, it is also one of the most—if not the most—widely used and recognized serif fonts in the world. The full stack, followed by a generic “serif” placeholder if possible, is:
1. Times New Roman
2. Times Roman
3. Tinos
4. Liberation Serif
If authors require even more typeface choices outside of these stacks for a loosely-conforming work, they should still not completely abandon the principles of the UEWSG, like strong legibility across different renderings and wide distribution. Other fonts, though not quite able to make any of the stacks, nonetheless have some typographic merit outside of very narrow and/or artistic uses. The top alternatives are, in no particular order: Tahoma, Century Gothic, Trebuchet MS, Bitstream Charter, Georgia, Palatino Linotype, Garamond, and Courier New.
Foreground elements (eg, text and borders) must be colored *black* (#000000) and the background (eg, the page color) must be colored *white* (#FFFFFF), unless otherwise noted; these colors are already the most common across all types of media and time periods and provide high contrast which is, usually, within the reader’s ability to adjust.
In addition to defining fallback characters for more restricted environments (see “2.1.3.1. Fallback Characters”), the UEWSG allows some amount of flexibility when dealing with code. Not only is extra formatting allowed, but exceptional parsing rules are provided for using the UEWSG inside comments or markup. In general, though, even code should follow the conventions of the Uniform English Writing Style Guide as far as possible. The two major exceptions are variable assignment and quotation marks. In languages which use only a single space to separate expressions (eg, HTML), variable assignment (usually with the “=” sign) should be *unspaced* for clarity. And quotation marks in code should follow the *opposite* convention of that used in regular writing, in order to simplify nesting and reduce the potential for error. For example, if a document uses double quotation marks as the default, any code should use single quotation marks, which will allow code to nest in the text and vice versa without any conversion.
As code can be difficult to read, many authors choose to indent it according to a specific indent style (eg, the stricter and extremely popular 1TBS variant of the K&R/ANSI style for C, JavaScript, and other programming languages). And while the Uniform English Writing Style Guide does not require any specific indentation style (or any indentation at all, though it is *highly* recommended), any indentation within code must be made with **tabs**. Not only are tabs far more semantic—they were invented for the purpose of consistent indentation—and fully backwards-compatible (they are a basic ASCII character), they have many other advantages: they use less disk space than an equivalent length of spaces, make finding certain syntax errors (eg, multiple spaces in a row) extraordinarily easy, and can be personalized—unlike spaces, users can readily adjust tab width to a length that suits them without making any modifications to a file. For an example of practical indentation in HTML, see this specification’s own source code.
Formats which require comments to contain the UEWSG-defined markers and syntax, such as CSS files and most types of code, are very similar to plaintext works: within the comments, documents in such a format must be identical to plaintext works and follow the normal rules of the Uniform English Writing Style Guide. Outside of comments, a file format’s normal rules apply, as well as the rules regarding indentation (above). But because of the distinctive way in which comments interact with the rest of a document, parsing is a little different than usual.
In comments syntax, the first line *after the first comment opening marker* (eg, the line after “““/*”””) is considered to be the main title of a document. In the case of single-line comment markers [which do not have closing markers] (like “““//””” and “““#”””), all text after the marker—which includes a trailing space—is considered to be the main title. For the purposes of UEWSG parsing, all lines of content above the first comment are syntactically appended between the end of the first comment and the beginning of any content following that comment—this is critical for languages like CSS where the first line of a document must be an “““@charset””” declaration, not a comment. Anything outside comments is treated as if it were wrapped in preformatted blockquotes—this allows even documents with complex code to adhere to the Uniform English Writing Style Guide, as content in preformatted blockquotes doesn’t negatively affect a document’s conformance. Closing comment markers (or, in the case of single-line comment markers, a single empty comment line) act like block markers that open preformatted blockquotes and opening comment markers (or, again, in the case of single-line comment markers, a single empty comment line) act like closing preformatted blockquote markers. Naturally, they must be formatted identically: the blank lines that normally follow block constructs must be placed *inside* the comments and any content directly following a closing comment marker (which, again, is treated as a preformatted blockquote opening marker for the purposes of the UEWSG) must be written with no intervening blank lines. The default preformatted blockquotes may be overridden, if needed, by placing a marker for a different construction on the last line of a given comment block and a closing marker [if applicable] on the first line of the next comment; if using multi-line comment markers (eg, “““/*””” and “““*/””” ) *with* multi-line comments, the overriding marker(s) should be placed on the line preceding the closing comment marker and [if applicable] on the line following the next opening comment marker (ie, in multi-line comments with multi-line comment markers, the comment markers should *always* be on lines by themselves for clarity). Comments that share the same line as code (eg, “““function some_function() {…} // Creates a function that…”””) are also treated in a special way: a space is required after the code and before each marker and the comments are considered to automatically break out of the implied preformatted blockquotes, get parsed as a[n adjectival] paragraph immediately following the implied preformatted blockquotes, and end by automatically returning to preformatted blockquotes for the next portion of code (unless, of course, the next line immediately begins a comment). When single-line comments are used, single-line comment markers are preferred, when available. For some examples, see the commented CSS file in “Appendix A. Alternate Formats And Sample Stylesheets”.
Formats which require tagging, such as HTML, use the markup syntax. In addition to the rules regarding indentation (above), the general rule for markup applies: tags must wrap around and compliment, not override, the Uniform English Writing Style Guide markers and syntax. That means that line breaks and spaces should never be added for the sake of tags: tags must be inserted at the appropriate places without any further alteration of a document, besides the use of tabs. Generally, as markup can be added by other forms of code, it should follow the *same* convention for quotation marks as is used in regular writing.
Unlike comments syntax, markup requires significantly different parsing to properly render the UEWSG markers and syntax. No single rule exists for parsing these types of documents manually, as there are many markup languages, but there are two general options. On one hand, a proper rendering engine (eg, a browser for HTML documents) can be used to display a document, ensuring the correct rendering of both the underlying markup and the UEWSG syntax itself, and the result then transferred to plaintext (such as with a copy/paste operation) for parsing. Or, the source code can be copied, stripped of all tagging and extra formatting (eg, with a sequence of precise regular expressions), and then parsed directly. In any case, successfully parsing marked-up documents requires that they both adhere to the Uniform English Writing Style Guide and their own file format. For examples of proper markup syntax, see this specification’s own source code.
• HTML: uewsg_0.2.0.html (172 KiB)
• Text: uewsg_0.2.0.txt (140 KiB)
• CSS: uewsg_0.2.0.css (3.21 KiB; gently commented)
• Commented CSS: uewsg_0.2.0_commented.css (10.6 KiB; fully commented)
The Uniform English Writing Style Guide wouldn’t be possible without many other people’s labors; I offer my sincere thanks to those authors who provided the most helpful and distilled information for my project. My chief primary and secondary sources in creating the UEWSG, in roughly their order of usefulness to my research, were:
• Wikipedia: https://en.wikipedia.org/wiki/Main_Page .
• The University of Chicago Press. The Chicago Manual of Style, 16th Edition. Chicago: University of Chicago Press, 2010.
• Mozilla Developer Network: https://developer.mozilla.org/en-US/ .
• CSS3: http://www.w3.org/TR/2011/REC-CSS2-20110607/ and the level 3 modules.
• SI Brochure, 8th Edition: http://www.bipm.org/en/publications/si-brochure/ .
• RFC Index: https://tools.ietf.org/rfc/ .
Of course, I used a far greater number of works for ideas, brief reference, fact-checking, and so forth; some of these works are mentioned or cited in the specification itself, but most are not. I offer thanks to the authors of those sources, as well.
Finally, all Scripture quotations marked “NKJV” were taken from the New King James Version® (Copyright © 1982 by Thomas Nelson. Used by permission. All rights reserved.).
This changelog is *not* exhaustive; however, it covers at least the significant changes from the *previous version* of the guidelines.
• Added (+): changelog (but of course!; it now forms Appendix C)
• Added (+): dedication to St Adrian of Poshekhonye in CSS files
• Added (+): extended subsections (4.1.5): these replace subsubsections and are infinitely extensible
• Changed (Δ): “““<br>””” is now the preferred form for the HTML module (a separate option for XML/XHTML compatibility may be added later)
• Changed (Δ): intra-UEWSG links: quotation marks added (as per a clarified rule in 3.8)
• Changed (Δ): language: many recommendations (“may”s and “should”s) are now “must”s (as per 2.6)
• Changed (Δ): Scripture references: they are now from the NKJV and correctly use a period, not a colon (as per 3.5)
• Changed (Δ): media-specific and other styling: styling and options continue to be broken into modules; this is an ongoing process
• Changed (Δ): characters (2.1): text direction is now explicit, as are more of the basic HTML tags used in all documents
• Changed (Δ): printable characters (2.1.3): slashes are now unspaced in most cases, ellipses are clarified, and a clear method to override terminal punctuation marks is now in place
• Changed (Δ): sentence case (2.2.1): non-alphabetic sentence beginnings now unambiguously preclude capitalization
• Changed (Δ): names and titles (3.1): clarification that title case applies to all words (including prepositions, conjunctions, and articles) that are integral to a title
• Changed (Δ): abbreviations (3.2): down from 5 rules to 4, with more simplification; of particular note is that abbreviations do *not* have periods anymore!
• Changed (Δ): foreign words (3.3): consistent treatment throughout a work
• Changed (Δ): special terms (3.4): given a wider scope; formerly called difficult terms
• Changed (Δ): math (3.5.3): the caret is now required for all exponentiation, even when it involves units, and methods for handling ratios and subscripts have been added
• Changed (Δ): units (3.5.4): dot operators are now only permitted, unspaced, for multiplying units together
• Changed (Δ): preformatted quotations (3.7): these now use “““<code>””” tags and have been more consistently applied throughout the Uniform English Writing Style Guide
• Changed (Δ): inline list item markers (3.8): clarification of more use cases
• Changed (Δ): marked emphases (3.11): these are now infinitely extensible (like extended subsections), the order of tag application is much simpler and easy to remember (and implement!), and “““ALL CAPS””” no longer has any emphatic meaning at all
• Changed (Δ): links (3.15): defaults are now more consistent with both current and historical practices, plus there is now a recommended fallback mechanism to ensure the integrity of hyperlinks
• Changed (Δ): other interactive text (3.16): renamed for more accurate description of its scope
• Changed (Δ): main titles (4.1.1): clarification of how to use the marker, when needed, and how the title affects the following [adjectival] paragraphs
• Changed (Δ): paragraphs (4.2): paragraphs no longer have a hidden marker
• Changed (Δ): preformatted blockquotes (4.5): no more silver background (though this may be added back as a module)
• Changed (Δ): block lists (4.6): not quite as elegant visually, but they are now far less verbose, easier to explain, and trivial to implement; also, the list item override module has been removed (hopefully to reappear in a later version of the spec) and the behavior of contained asides is clarified
• Changed (Δ): notes (4.7): streamlined; handling of the actual note placement is also heavily clarified
• Changed (Δ): asides (4.8): these now use the current “““<aside>””” tags (backwards compatibility may be added back in the form of modules targeting different version of HTML); also, they may *precede* their targets and their behavior within block lists is clarified
• Changed (Δ): font sizes (5.4): only the 12 pt option remains and all the examples [in 4.1] have been updated to reflect this (more fine-grained control may reappear as a module but 12 pt is the safest default for many reasons)
• Changed (Δ): line height (5.5): fixes for line height bugs are now explicit
• Changed (Δ): font stacks (5.6): larger, more uniform, and more widely compatible
• Changed (Δ): code (5.8): single-space-delimited languages are now excepted from needing spaces in variable assignment
• Changed (Δ): comments syntax (5.8.2): clarifications, plus expanded to include nearly all common use cases
• Removed (-): lots of fallback mechanisms [for line breaks] (2.1.2.1), which were either not 100% reversible (ie, not content-preserving) and/or would be better served as a module
• Removed (-): adjectival paragraphs (4.2.1): mostly unnecessary, especially with manually-applied modules [hopefully] coming in the future, and it did not unambiguously and algorithmically solve the problem of what content was being modified; the useful ideas from this division have been worked in elsewhere
• Removed (-): code fonts (old 5.6.2): too redundant with monospaced fonts in purpose
• Removed (-): at-rules and stylesheets (5.9): too redundant relative to other formats, confusing, and rarely needed