UEWSG 0.2.0

Uniform English Writing Style Guide 0.2.0 (***beta version***)


Released on 2018-10-17



Dedicated to St Adrian Of Poshekhonye, hieromonk and martyr (March 5)


Table Of Contents

  1. 1. Introduction

  2. 2. Basic Orthography

    1. 2.1. Characters

      1. 2.1.1. Spaces

      2. 2.1.2. Line Breaks

        1. Fallback Mechanism

      3. 2.1.3. Printable Characters

        1. Fallback Characters

    2. 2.2. Capitalization And Cases

      1. 2.2.1. Sentence Case

      2. 2.2.2. Title Case

      3. 2.2.3. Snake Case

    3. 2.3. Filenames

    4. 2.4. Nesting

    5. 2.5. Precedence

    6. 2.6. Precision And Tone

  3. 3. Inline Constructs

    1. 3.1. Names And Titles

    2. 3.2. Abbreviations

    3. 3.3. Foreign Words

    4. 3.4. Special Terms

    5. 3.5. Numbers

      1. 3.5.1. Times And Dates

      2. 3.5.2. Variables

      3. 3.5.3. Math

      4. 3.5.4. Units

    6. 3.6. Quotations

    7. 3.7. Preformatted Quotations

    8. 3.8. Inline Lists

    9. 3.9. Note Markers

    10. 3.10. Citations

    11. 3.11. Marked Emphases

      1. 3.11.1. Standard Marked Emphases

      2. 3.11.2. Strong Marked Emphases

      3. 3.11.3. Critical Marked Emphases

    12. 3.12. Keyboard Keys

    13. 3.13. Censored Text

    14. 3.14. Directions

    15. 3.15. Links

    16. 3.16. Other Interactive Text

  4. 4. Block Constructs

    1. 4.1 Divisons And Headings

      1. 4.1.1. Main Titles

      2. 4.1.2. Chapters

      3. 4.1.3. Sections

      4. 4.1.4. Subsections

      5. 4.1.5. Extended Subsections

    2. 4.2. Paragraphs

    3. 4.3. Breaks

      1. 4.3.1. Dinkuses

      2. 4.3.2. Ellipses

    4. 4.4. Blockquotes

    5. 4.5. Preformatted Blockquotes

    6. 4.6. Lists

      1. 4.6.1. List Items

      2. 4.6.2. Bulleted Lists

      3. 4.6.3. Numbered Lists

      4. 4.6.4. Description Lists

      5. 4.6.5. Other Lists

    7. 4.7. Notes

      1. 4.7.1. Footnotes

      2. 4.7.2. Chapter Notes

      3. 4.7.3. Endnotes

    8. 4.8. Asides

    9. 4.9. Tables

    10. 4.10. Other Block Constructs

  5. 5. Document-Level Styling

    1. 5.1. Alignment

    2. 5.2. Margins And Line Length

    3. 5.3. Widows And Orphans

    4. 5.4. Font Sizes

    5. 5.5. Line Height

    6. 5.6. Typefaces

      1. 5.6.1. Sans-Serif Fonts

      2. 5.6.2. Monospaced Fonts

      3. 5.6.3. Serif Fonts

      4. 5.6.4. Other Fonts

    7. 5.7. Colors

    8. 5.8. Code

      1. 5.8.1. Indentation

      2. 5.8.2. Comments Syntax

      3. 5.8.3. Markup Syntax


1. Introduction

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.


2. Basic Orthography

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.


2.1. Characters

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.


2.1.1. Spaces

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”.


2.1.2. Line Breaks

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.

~~~~~ Fallback Mechanism

If, for whatever reason, a document must be displayed on a single line or in a stream, the UEWSG provides a straightforward fallback mechanism:

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.


2.1.3. Printable Characters

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:

~~~~~ Fallback Characters

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:

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.


2.2. Capitalization And Cases

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:


2.2.1. Sentence Case

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


2.2.2. Title Case

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


2.2.3. Snake Case

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.


2.3. Filenames

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.


2.4. Nesting

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.


2.5. Precedence

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.


2.6. Precision And Tone

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


3. Inline Constructs

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.


3.1. Names And Titles

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:


3.2. Abbreviations

In the Uniform English Writing Style Guide, abbreviations are covered by 4 simple rules:

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.


3.3. Foreign Words

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:


3.4. Special Terms

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:


3.5. Numbers

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:


3.5.1. Times And Dates

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:


3.5.2. Variables

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:


3.5.3. Math

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:


3.5.4. Units

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:

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:

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


3.6. Quotations

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”.


3.7. Preformatted Quotations

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:

For longer preformatted quotations, see “4.5. Preformatted Blockquotes”.


3.8. Inline Lists

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…”).


3.9. Note Markers

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:

For more information on displaying notes themselves, see “4.7. Notes”.


3.10. Citations

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.


3.11. Marked Emphases

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.


3.11.1. Standard Marked Emphases

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.


3.11.2. Strong Marked Emphases

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.


3.11.3. Critical Marked Emphases

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.


3.12. Keyboard Keys

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:


3.13. Censored Text

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


3.14. Directions

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:


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:


3.16. Other Interactive Text

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


4. Block Constructs

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.


4.1. Divisions And Headings

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.


4.1.1. Main Titles

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.

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.


4.1.2. Chapters

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.


4.1.3. Sections

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.


4.1.4. Subsections

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.


4.1.5. Extended Subsections

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.


4.2. Paragraphs

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:


4.3. Breaks

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.


4.3.1. Dinkuses

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 (“***”).


4.3.2. Ellipses

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:


4.4. Blockquotes

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.


4.5. Preformatted Blockquotes

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.


4.6. Lists

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.


4.6.1. List Items

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:


4.6.2. Bulleted Lists

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.


4.6.3. Numbered Lists

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:


4.6.4. Description Lists

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.


4.6.5. Other Lists

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.


4.7. Notes

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”.


4.7.1. Footnotes

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.


4.7.2. Chapter Notes

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.


4.7.3. Endnotes

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.


4.8. Asides

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:


4.9. Tables

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.


4.10. Other Block Constructs

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.


5. Document-Level Styling

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.


5.1. Alignment

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.


5.2. Margins And Line Length

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:


5.3. Widows And Orphans

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:


5.4. Font Sizes

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:


5.5. Line Height

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:


5.6. Typefaces

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.


5.6.1. Sans-Serif 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. 1. **Arial**

  2. 2. Helvetica

  3. 3. Arimo

  4. 4. Liberation Sans

  5. 5. Arial Unicode MS


5.6.2. Monospaced Fonts

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

  2. 2. Liberation Mono

  3. 3. DejaVu Sans Mono

  4. 4. Hack

  5. 5. Andale Mono


5.6.3. Serif Fonts

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. 1. Times New Roman

  2. 2. Times Roman

  3. 3. Tinos

  4. 4. Liberation Serif


5.6.4. Other Fonts

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.


5.7. Colors

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.


5.8. Code

In addition to defining fallback characters for more restricted environments (see “ 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.


5.8.1. Indentation

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.


5.8.2. Comments Syntax

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”.


5.8.3. Markup Syntax

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.


Appendix A. Alternate Formats And Sample Stylesheets


Alternate Formats


Sample Stylesheets


Appendix B. Bibliography

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:

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


Appendix C. Changelog

This changelog is *not* exhaustive; however, it covers at least the significant changes from the *previous version* of the guidelines.