UEWSG 0.1.0


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


By JBT


Released on 2015-4-5


http://uewsg.org/uewsg_0.1.0/uewsg_0.1.0.html


+++


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. 2.1.2.1. Fallback Mechanism


      3. 2.1.3. Printable Characters


        1. 2.1.3.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. Difficult 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. Interactive Content


      1. 3.15.1. Links


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


    2. 4.2. Paragraphs


      1. 4.2.1. Adjectival 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. Code Fonts


      3. 5.6.3. Monospaced Fonts


      4. 5.6.4. Serif Fonts


      5. 5.6.5. 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


    9. 5.9. At-Rules And Stylesheets


      1. 5.9.1. At-Rules


        1. 5.9.1.1. Strictness


        2. 5.9.1.2. Syntax


        3. 5.9.1.3. Location


      2. 5.9.2. Stylesheets


        1. 5.9.2.1. Targeting Constructs


        2. 5.9.2.2. Changing Markers


        3. 5.9.2.3. Adjusting Line Breaks


        4. 5.9.2.4. Complex Styling


        5. 5.9.2.5. Comments



+++

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, 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? Is a given quotation part of a sentence or part of a separate blockquote? 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 [web] version of this specification from any reasonably standards-compliant browser (as of 2015, that means anything using the Blink or WebKit rendering engines, like Chrome, Opera, or Safari) into a basic text editor (Notepad, Notepad++, vi, etc.). *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. 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 compatbility 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, the guidelines can also be extended or modified as needed with a special, UEWSG-compatible stylesheet format, based off the rules of CSS. So, even in these situations, the guidelines can still be of use.


Finally, I must 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 also want to thank the contributors—past, present, and future, known and unknown—for their help. 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 (e.g., “<”, “>”, and “&” must be escaped in HTML). Unless otherwise contraindicated, all digital documents must be written in **UTF-8**, the universal standard for digital text.



---

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 (e.g., 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 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, a note should be placed in the stylesheet clearly stating which particular space characters are being utilized.


Spaces must never be used for indentation outside of special cases (e.g., 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 (e.g., 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.


///

There is really no good reason to have a competing standard, so other line breaks sequences (such as a single LF, which is a self-admitted hack from 1960s-era Multics machines that, for reasons unclear or unknown, found its way into Unix) should not be used unless absolutely required by a specific file format, an old program, or an ancient OS.

\\\

Line breaks should be made with the newline characters **CR+LF**, or carriage return and line feed. This is the most semantic way to break lines as it is how real teletype machines work: the carriage begins returning to the beginning of the line and, while this [sometimes slow] process takes place, the machine also feeds the paper through to the next line. This standard sequence is also 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 (e.g., HTTP, FTP, etc.) explicitly require it. Thus, even on systems where CR+LF isn’t the default, it should be used whenever possible for the sake of compatibility; most non-legacy operating system and/or their text editors have simple ways to adjust this setting.


~~~
2.1.2.1. 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. While writing in technical contexts, like mathematics or programming, is naturally exempted from these rules in cases of unresolvable conflict, documents must otherwise adhere to the following rules:



~~~
2.1.3.1. 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 and must therefore be thoroughly noted in a stylesheet [in the “human” property].


===

2.2. Capitalization And Cases


Capitalization is an important way to orthographically distinguish certain constructs from surrounding text. For instance, many 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 (e.g., “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 (a.k.a. ALL CAPS) are obvious 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. This includes the first letter of a quoted sentence that begins inside another sentence (e.g., “Jesus said, ‘You search the scriptures because you think that in them you have eternal life; and it is they that testify on my behalf. Yet you refuse to come to me to have life.’, as recorded in John 5:39–40 (NRSV).”) but *not* quoted phrases or incomplete fragments of sentences (e.g., “St. Paul refers to the Church, not the Scriptures, as ‘the pillar and ground of the truth’ in 1 Timothy 3:15 (KJV).”).


---

2.2.2. Title Case


///

While other forms of title case exist, they are convoluted and simply confusing—in addition to generally being quite arbitrary—and should be avoided.

\\\

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 should *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 (e.g., 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 **strongly recommended**.


///

Lest these restrictions seem overly burdensome, a little bit of math is in order. There are supposedly about 10^80 atoms in the universe, while a limit of 255 characters in a filename with a choice of 40 characters (the allowance of slashes (“/”) to separate directories and other characters for protocol-specific segments would increase that number noticeably if full URLs or paths are considered) provides 40^255 combinations. This is over 10^408 combinations, or over 10^328 times more combinations than the number of atoms in the universe, based on calculations done with WolframAlpha. Basically, that means there aren’t very many good excuses for not using short, strict-snake-case-based filenames.

\\\

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 (e.g., “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. 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 freely 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 the end of a paragraph, it must either be quoted (like “text ‘+++’. ¶ More text”) or rewritten in some other way.


Content that would be parsed as—but is not being used as—a marker (e.g., representing a sample at-rule; see 5.9.1. At-Rules) or breaks the 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, 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 (e.g., rendering bugs in certain browsers make borders and margins conflict), the procedure for precedence is left up to the author: authors have discretion in choosing which of the rules is more vital to the proper styling of the UEWSG.


===

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 writer 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.). The Uniform English Writing Style Guide makes particularly precise use of the words “must”, “may”, and “should” (as defined in RFC 2119; see https://www.ietf.org/rfc/rfc2119.txt); authors should consider consistently using these terms, as well.


+++

3. Inline Constructs


With a practical understanding of the basic rules for UEWSG-conforming documents, 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 media and consistent in every media.


===

3.1. Names And Titles


All proper nouns must be written in title case. This includes, but is not limited to, names (e.g., “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 (e.g., “Battle Of Thermopylae”, “Battle of the Milvian Bridge”, and “World War I”), ships and units (“NKN Soggy Bottom”, “Varangian Guard”, etc.), compass points (e.g., “East”), musical notes (“C”, “F♯”, etc.) and work titles (including book, article, play, poem, music, video, and website titles). Some proper nouns require additional styling:



===

3.2. Abbreviations


In the Uniform English Writing Style Guide, abbreviations are covered by 5 uncomplicated 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. All 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 (e.g., 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. Difficult Terms


In technical writing, authors may have to use terms that, while in the same language as the rest of a work, may be unfamiliar to readers. Such difficult terms, especially if they will later be defined in some type of glossary, 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 are optional or 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 the local conventions when writing out dates in full (e.g., “April 20, 2008”), appending the standard suffixes “AD” or “BC” as needed (e.g., “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 p.m.” 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 (e.g., in while 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 not too difficult to handle 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 (e.g., “$20” for “20 dollars”).


===

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 (i.e., 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 (e.g., 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 quotes. 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. While this rule is slightly more verbose than certain alternatives, it is the safest, most precise, and most semantic way to handle quotations. Tagging is *not* recommended:



For longer quotations, see 4.4. Blockquotes.


===

3.7. Preformatted Quotations


Preformatted quotations are similar to regular quotations, but more strict. Used frequently to handle small snippets of code 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


///

There are many, well-known examples where the loss of a serial comma creates confusion, but no known instances where a serial comma creates more ambiguity: in the few so-called counterexamples, serial commas *change* the type of ambiguity, but do not actually *add* ambiguity. The real lesson is this: authors should use appositives clearly and carefully!

\\\

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 good 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 (i.e., 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 comma and a space or with a space alone (“a. [list item a], b. [list item b],…” and “1., [list item 1]; 2., [list item 2];…” are both perfectly acceptable). The use of closing parenthesis alone for this purpose (e.g., “a.)”) is forbidden, due to potentially-catastrophic parsing issues, though full sets of parentheses are permitted (e.g., “(a.)”).


===

3.9. Note Markers


Note markers are the inline constructs which reference notes. As note markers are inserted material, they should 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 (e.g., 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 (i.e., 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 should make use of various forms of emphases to reflect the variable “tonal” quality of their writing. Much of the emphases will need no markup: readers naturally process the text and add some emphasis on their own. Similarly, authors can use other tools (repetition, capitalization, etc.) to draw attention to text. But sometimes, particularly important concepts, statements, or warnings need to be specially marked. For these cases, the UEWSG defines three degrees of marked emphasis. And while all types of emphases nest and their effects are cumulative (e.g., a word repeated and displayed in all caps would be more important (3rd degree) than a word which was only emphasized with single repetition (1st degree) or all caps (2nd degree) alone), marked emphases also stack visually. For example, if a sentence that has been marked with standard emphasis contains a strongly emphasized word, that word would be critically emphasized and displayed identically to any other critically emphasized content. Marked emphases will also stack visually inside description list terms, which are strongly emphasized 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 degree of emphasis and are equivalent to a single repetition. 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 degree of emphasis and are equivalent to double repetition (e.g., “Lord, have mercy. Lord, have mercy. Lord, have mercy.”) and/or writing in all caps (A METHOD OF EMPHASIS TO USE VERY SPARINGLY; indeed, all caps is not recommended for use outside of circumstances such as legal disclaimers, branding, and actual shouting). 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.



---

3.11.3. Critical Marked Emphases


Critical marked emphases are the most powerful emphases, reserved for serious warnings or vital content that absolutely cannot be missed. They constitute the 3rd degree of emphasis, have no direct equivalent in the UEWSG, and text emphasized in this way cannot be further emphasized (i.e., the 3rd degree of emphasis is the highest level defined). 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.



===

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 (e.g., “Shift”). Combinations of keys should 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), characters should be replaced 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 (e.g., “…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 (e.g., “A g…d plan today…better t…perfect plan…morrow”).


===

3.14. Directions


Directions to a speaker in dialogue (e.g., directions in a prayer book) must be written inside parenthesis and further styled:



===

3.15. Interactive Content


In digital media, and especially HTML, interactive content is fundamental. However, in order for users to recognize such interactivity, authors must give all purely text-based interactive content extra styling (this excludes buttons, images, etc.):



---

Links are the most common type of interactive textual content and, perhaps more than any other construct, define the World Wide Web. In addition to being styled like other forms of interactive content, text-based links must be further styled:



+++

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 except the last in a containing construct must be followed be a double line break (i.e., a blank line; in HTML, that means a <br/> tag), block opening markers (including division markers) and constructs at the end of a container must followed by only 1 line break (in HTML, this is usually taken care of by its own block model), and the last construct in a document must be followed by no 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 (i.e., 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 subsubsection [level 5]. 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 should not begin or end with a visible division marker of any kind.


Division markers themselves are composed of 1 character repeated 3 times. As with markers of all types, division markers must not have any spaces whatsoever. Headings may contain just about anything except for block markers without closing 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 also allowed via adjectival paragraphs (see 4.2.1. Adjectival Paragraphs). All headings must be written in title case.


---

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 does not have any structural function and doesn’t override the current division in any way.



///

Unless the specific stylesheet or filetype demands otherwise, it is a best practice to place the author of the document in an adjectival paragraph directly below the title (see 4.2.1. Adjectival Paragraphs). Further front matter can be separated into another chapter (see below), if needed.

\\\

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 (e.g., 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 technically the end of the previous chapter 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 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 level 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 hypens (“---”); the marker itself is technically the end of the previous subsection [if present] and “closes” all preceding divisions up to, and including, the subsection level. A level 4 heading follows this marker and is the title of the division.



---

4.1.5. Subsubsections


Subsubsections are the lowest level of organization inside of a document; they are level 5 divisions. As evidenced by their belabored and terribly uncreative name, subsubsections can split a document down into amazingly fine parts; 3 or 4 levels of headings are usually more than enough for most works, but some, more technical documents may need this deepest level of division. Subsubsections begin directly following 3 tildes (“~~~”); the marker itself is technically the end of the previous subsubsection [if present] and “closes” the preceding subsubsection. A level 5 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 unrecognized content in preformatted blockquotes, all text is, by default, part of a paragraph. Paragraphs must not be indented. Like all block constructs, paragraphs have a marker: “¶” followed by a space. However, because blank lines also communicate the syntax, these markers are hidden by default and will not appear outside of rare cases. Minimal styling is needed:



---

4.2.1. Adjectival Paragraphs


Paragraphs used to directly provide more information about other constructs are called adjectival paragraphs. For example, it is nearly always necessary to name the author of a document; such a paragraph is considered adjectival. If the target of an adjectival paragraph is unclear, it is understood to refer to the content contained by the last *preceding* block construct of any type (excepting other adjectival paragraphs). For example, a “by” adjectival paragraph can follow a heading and its associated division marker, which means it refers to that entire division. Or, it could follow a blockquote, referring to only its contents. In most cases, adjectival paragraphs should be as concise as possible: it is recommended that they contain no more than a name, date, location, and/or other brief ancillary information, as needed.


No specific syntax is mandated for such paragraphs, though words or phrases such as “by”, “to”, “from”, “for”, “in memory of” and the like are all common, with or without capitalization and/or a colon; adjectival paragraphs may even start with an em dash (e.g., “—by Fr. Josiah Trenham”). Regardless of media, adjectival paragraphs must have the same alignment and/or floating behavior as the construct they refer to. Thus, an adjectival paragraph referring to a main title (and by extension, the whole document) would be centered, but not bolded or styled in any other way. Adjectival paragraphs referring to the document as a whole but disjunct from the main title may be centered, at the discretion of the author.


===

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 three breaks can be used.


---

4.3.1. Dinkuses


///

If it is difficult to distinguish one or more adjectival paragraphs from later, normal paragraphs (see above), use a dinkus. Dinkuses should generally not be used directly after lists, however, as this can cause a potential syntax conflict in an ASCII environment.

\\\

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. 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, blockquotes are often the best solution. Like inline quotations, blockquotes are opened and closed with opening and closing quotation marks, respectively (i.e., “ “” ” 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 should 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; while blockquotes are structurally separate from surrounding content, it is recommended that authors use the next-highest-level division when subdividing them, for visual consistency with the rest of the document.



===

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 the document must necessarily span multiple lines. This construct is not only used for containing blocks of code, but can be very handy 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 (i.e., “ “““””” ” or “ ‘‘‘’’’ ”); as with all other quotations, the Uniform English Writing Style Guide allows local custom to dictate which type (i.e., 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. 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; while preformatted blockquotes are structurally separate from surrounding content, it is recommended that authors use the next-highest-level division when subdividing them, for consistency with the rest of the document.



===

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 (i.e., 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. 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. Asides can be placed between list items or paragraphs within a list item, as they do not nest normally but remain structurally independent. List items, and their markers, need quite a lot 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 (i.e., 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.


///

Bulleted lists items may also be used to send corrections in informal communication, such as SMS and IM: the common format “* [corrected text]” is not only semantic, but fully UEWSG compatible!

\\\


---

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 an incrementing Arabic number followed by a period and a space (“1. ”). 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. 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 (e.g., “**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 (e.g., “**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 stylesheet definition. They will nest, and display, exactly the same as bulleted lists.


===

4.7. Notes


Block-format notes are crucial in scientific 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. Within this dedicated division, notes can be displayed in the proper block list type, corresponding to the note markers (e.g., numbered note markers would correspond to a numbered list). In all media, note divisions begin directly following 3 underscores (“___”) and the division’s heading directly controls where and how the notes will be displayed. 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.



---

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.



---

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, which is displayed as a separate chapter at or near the end of a document. The preceding chapter must still close with the chapter division marker (“+++”), but the note division marker and subsequent heading are treated syntactically like the chapter marker’s heading (i.e., the chapter marker, note division marker, and heading are only separated by single line breaks).



===

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 very vital explanation due to the dangers involved in a particular use of the product. Thus, asides are a valuable tool, particularly for technical writers. 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. 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 in any aside; it is recommended that authors use the next-highest-level division when subdividing them, despite their structural separation, for visual consistency with the rest of the document. 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. Therefore, tables are only given a general treatment; there is no particular way to gracefully handle tables across all media and the Uniform English Writing Style Guide provides no default alignment or width 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 and must be further defined in the stylesheet; they must, of course, follow the conventions of the containing file’s format (i.e., <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, but still require documentation in a work’s stylesheet.


===

5.2. Margins And Line Length


///

Alas, line length is one of the most misunderstood parts of typography: “gurus” will quote all sorts of numbers like 60, 66, or 72 characters per line as the ideal. That is fine and well, but these numbers are all based on various assumptions which may or may not hold for a given document and, more than that, are mostly just vestiges of historical typographic customs and limitations. In actuality, line length (and a work’s margins) is a multi-variable problem based upon document size, font, font size, font weight, viewing angle, and many other factors both physical and psychological. This may partly explain the varied and sometimes conflicting opinions and studies, many of which do not agree with the aforementioned typographic “wisdom” (see http://psychology.wichita.edu/surl/usabilitynews/72/LineLength.asp for one such study).

\\\

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 media 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


///

According to lawyer and typographer Matthew Butterick, line spacing is broken in Word and Pages (http://practicaltypography.com/line-spacing.html): actual line spacing is 7/6 of the quoted value. This flaw may also apply to other word processors, so beware!

\\\

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 writer 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!


///

Note that many newer and/or “free” typefaces are not listed in these stacks. Other than the obvious problem of them not being installed by default on most systems, many of these fonts are evidently not designed for rendering across different media and resolutions. For example, a font may look flawless on paper, but look faded and out of focus on a standard-definition monitor. Another may perform pretty well on a high-definition screen, but print poorly. Since one of the major focuses of the UEWSG is pan-media compatibility, all font families in the stacks must be legible and sharp; the brevity of the font stacks is largely a consequence of the dearth of well-balanced, open fonts that continues to this day.

\\\

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 in open formats, like OpenType. This format 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. In the case that a file format cannot accept an entire stack of typefaces as “the” font choice and the first typeface is unavailable, the alternative must be noted in the stylesheet. 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, good character density, and a strong, timeless style. The full stack is:


  1. 1. **Arial**


  2. 2. Helvetica


  3. 3. Arial Unicode MS


---

5.6.2. Code Fonts


Code fonts are the default stack for viewing and working with content—particularly code—in raw form; that means this the default font stack for text editors. The typefaces are from the sans-serif category, but are specially chosen for their ability to effectively display large amounts of unformatted text: they are wide and/or widely spaced, making it easy to pick out arbitrary segments of content. The preferred typeface in this stack is Verdana: it has a large x-height and spacious counters, making it very legible at small sizes. The stack is:


  1. 1. Verdana


  2. 2. Trebuchet MS


---

5.6.3. Monospaced Fonts


Monospaced fonts are the default stack for dealing with fixed-width (i.e., 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 Courier New: like the others in the stack, it has wide characters, sharp lines, and a natural feel that is relatively uncommon (but very desirable) in the monospaced category. The full stack is:


  1. 1. Courier New


  2. 2. Andale Mono


  3. 3. Lucida Console


---

5.6.4. 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 Georgia: while it is a larger typeface, it has a very balanced and inviting character. It is also one of the most—if not the most—professional-looking of the serif font families in wide use. The stack is:


  1. 1. Georgia


  2. 2. Palatino Linotype


---

5.6.5. 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, Garamond, and Times New Roman (including its main variants).


===

5.7. Colors


The default font color is **black** (#000000) and the default background/page color is **white** (#FFFFFF); these colors are already the most common across all types of media and time periods and provide good contrast. If a monitor cannot render these colors (e.g., it displays green on black) or if an ink or paper color is not *exact*, no note on the stylesheet is required.


===

5.8. Code


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.


---

5.8.1. Indentation


///

For a more complete list of the benefits of using tabs—including a lengthy [and sometimes acerbic] discussion on the subject—see http://lea.verou.me/2012/01/why-tabs-are-clearly-superior/ .

\\\

As code can be difficult to read, many authors choose to indent it according to a specific indent style (e.g., 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 (e.g., 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 the document, parsing is a little different than usual.


In comments syntax, the first line *after the first comment opening marker* is considered to be the main title of the document. For the purposes of the UEWSG, 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. Anything outside comments is assumed to be 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 act like block markers that open preformatted blockquotes and opening comment markers 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 [before the closing comment marker’s line] of a given comment block and a closing marker [if applicable] on the first line of the next comment. For 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 spacing should never be added for the sake of tags: tags must be inserted at the appropriate places without any further alteration of a document.


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 (e.g., a browser for HTML documents) can be used to display the 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 (e.g., 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.


===

5.9. At-Rules And Stylesheets


///

Remember that the Uniform English Writing Style Guide defines safe, efficient, and readable defaults for the largest number of use cases: not every document needs to—or should—be uniform.

\\\

At-rules and stylesheets are the final, but certainly not least, document-level concerns. To aid in identification and parsing of conforming documents, a **UEWSG at-rule is strongly recommended** for all but the most basic document types (labels, sticky notes, SMS, etc.) and is *required* for a document to be certified as strictly conforming. An at-rule defines the version of the Uniform English Writing Style Guide in use, if the document strictly conforms to it, whether the content is plain or contained in a special syntax (i.e., in comments or markup), and the location of any other UEWSG stylesheets. A stylesheet details the visual styling of a work, allowing a program and/or person to properly display a work in a given medium. Stylesheets can also define changes to the syntax and rules of the UEWSG; instead of enforcing an all-or-nothing conformity without any recourse, the Uniform English Writing Style Guide provides mechanisms so that the specification may be incrementally modified without sacrificing all the benefits of adherence to an unambiguous standard.


---

5.9.1. At-Rules


All UEWSG at-rules must begin with “““@UEWSG””” and must be followed by the version number (e.g., “0.1.0”). 3 declarations then follow the version, in parenthesis: strictness, syntax, and location. Each declaration must be followed by a semicolon. A given declaration [and its semicolon] may be omitted if the default value is used (marked in each preformatted blockquote below as strong text); if all declarations are omitted, the parenthesis themselves must also be omitted. An at-rule must be followed by an opening and closing curly brace (“{}”) if, and only if, an internal stylesheet is used; the braces will contain the internal stylesheet, if present. In formats where an at-rule has the possibility of conflicting with similarly-formatted rules (e.g., in CSS), it should be “commented out” so that it is only parsed by humans and UEWSG-compatible programs. Though there isn’t an absolute requirement that an at-rule be located at the very end of a document, it is highly recommended to place it as close to the end as is feasible.


~~~
5.9.1.1. Strictness

“““
**loose** | strict
”””

The “strictness” declaration defines if the document strictly conforms to the Uniform English Writing Style Guide. A plaintext document which follows the UEWSG exactly must be certified “strict” and requires no stylesheet. A document which has some type of styling (e.g., the HTML version of the Uniform English Writing Style Guide specification itself) or adds to the UEWSG in any way (e.g., it contains images) requires a stylesheet, but must still be certified “strict” if the styling and/or additions do not in any way violate the declared version of the UEWSG in use. All other documents are considered “loose” and must have a stylesheet noting the differences between it and the UEWSG specification.


~~~
5.9.1.2. Syntax

“““
**plain** | comments | markup
”””

The “syntax” declaration defines how the Uniform English Writing Style Guide syntax is parsed within the file. A document is “plain” if it is not contained in any tagging, markup, or comments; it is just bare text, even when viewed in raw form in a text editor. It is parsed normally.


Content that is displayed in and around code—in a file’s comments—receives the “comments” value. CSS takes non-code content within comments, as do most programming languages. Commented files require a notable change in the UEWSG parsing, as described in 5.8.2. Comments Syntax.


Syntax that has been tagged in any way receives the value “markup”. HTML documents are a prime example, but most [XML-based] word processor documents also use markup, though it is normally invisible and/or inaccessible to the user; these types of documents *must* be properly declared. Very specialized parsing is required for these types of documents, as described in 5.8.3. Markup Syntax.


~~~
5.9.1.3. Location

“““
**internal** | ["URI"]
”””

The “location” declaration defines the location of all Uniform English Writing Style Guide stylesheets associated with a document; stylesheets of other formats that do not contain any UEWSG-defined declarations relating to the document must not be listed. The location of a stylesheet must be given as a URI (whether a relative or absolute filename or URL) inside straight quotation marks (“ "" ”); multiple URIs may be used but must be separated by commas.


---

5.9.2. Stylesheets


///

While specific bug fixes are not explicitly required in the Uniform English Writing Style Guide, common rendering bugs should be addressed in the stylesheet (especially in CSS, as browsers have a variety of display issues). See the reference implementation in Appendix A. Alternate Formats And Sample Stylesheets for some of the most critical fixes.

\\\

///

External stylesheets, as documents themselves, should have their own at-rule—it is not uncommon for such stylesheets to follow a different syntax (e.g., markup vs. comments) or otherwise require different styling.

\\\

Documents that have a stylesheet in an existing format (e.g., CSS) do not necessarily need a UEWSG-defined stylesheet and/or rules. However, a Uniform English Writing Style Guide stylesheet and/or rules are required when a UEWSG at-rule is used and no other stylesheet format is defined or the chosen format is not powerful enough to fully capture the styling: such a stylesheet and/or rules not only handle such document’s styling, but are responsible for detailing changes to the Uniform English Writing Style Guide specification itself, if such changes are made. UEWSG-defined rules may be written internally, inside the braces at the end of the at-rule, or externally, inside a stylesheet of a different format; if used inside of another type of stylesheet, the UEWSG-defined rules must follow the conventions of that format as far as possible and may appear anywhere allowed, though it is a best practice to conspicuously distinguish them from the format-supported rules. The choice between an internal vs. external stylesheet is left up to the discretion of the author. All UEWSG-defined rules are based on a slightly-modified form of **CSS**: spaces, line breaks, and even blank lines within the stylesheet are completely optional, properties and values should be lowercase, and declarations within a declaration block must be delimited by semicolons.


~~~
5.9.2.1. Targeting Constructs

“““
[construct] {}
”””

///

To target an entire document, use the property “body”, just as in CSS.

\\\

Targeting a construct in a UEWSG stylesheet is nearly identical to targeting one in CSS, except that the singular, snake-case, UEWSG name must be used. For example, to target all list items, use the property “list_item”. Or to target chapter markers, perhaps to change their page-breaking behavior, use the property “chapter_marker”. Advanced CSS selectors (including combinators, complex selectors, pseudo-classes, etc.) are allowed, though the code should be as obvious as possible.


~~~
5.9.2.2. Changing Markers

“““
[construct] {marker:"[character(s)]"}
”””

///

Some markers have a trailing space character; those spaces are *integral* parts of the markers.

\\\

///

The marker for paragraphs can be changed because paragraphs already have a defined marker, the pilcrow (“¶”; see 4.2. Paragraphs); however, because it is usually redundant and thus untyped in most instances, the marker styling must be set to “display:inline”, *in addition* to any character changes, in order to actually display.

\\\

The UEWSG stylesheet also makes it easy to change the actual markers for any construct in the style guide. If using a different character set or constrained by some other necessity, any of the markers—division markers, list item markers, preformatted blockquote markers, and the rest—can be overridden and redefined. Any level of control is possible, from reassigning the “chapter_marker” to the more specific “blockquote_opening_marker” or “numbered_list_item_marker”; remember to use the singular, snake-case, UEWSG name of each construct or subconstruct. *Extreme* caution is recommended: the markers in the Uniform English Writing Style Guide are chosen for their near-universal support and, in many cases, internationally-recognized meaning (e.g., many books have chapters that end with the “+++” division marker). And these are not the only concerns. It is easy to create a clash with other characters or strings which have a pre-defined meaning in other style guides, programming languages, etc.; **beware**!


~~~
5.9.2.3. Adjusting Line Breaks

“““
[construct] {linebreaks:"[number]"}
”””

///

Trying to remove the blank lines between paragraphs (e.g., to save paper, as was a common historical practice when paper was extraordinarily precious)? This override is probably not the best choice. Consider using *negative margins* on paragraphs instead: this will provide the desired look in rich media, but will keep the normal UEWSG syntax intact when viewing the document as plaintext. In most cases, this is a win–win situation and immeasureably preferable to playing with the default line-breaking behavior.

\\\

Another feature of the UEWSG stylesheet is its ability to directly change the amount of line breaks after a given construct. If this needs to be adjusted, the property takes a numerical value; it may be reset using either the normal numerical value or the value “initial”. The last block construct in a series must be targeted separately, as it often has different behavior, with the pseudo-class “:last-block” attached to the *parent* container; the value “inherit” will allow the last child block construct’s breaking behavior to execute as if no container were present. For example, “list_item {linebreaks:1}” would remove the blank line between all list items [except the last one in a list, which would have to be targeted with something like “bulleted_list:last-block {…}”]. Similarly, the rule “body:last-block {linebreaks:inherit}” would prevent any line breaks after the last block construct in a document from getting cut off. Advanced CSS selectors (including combinators, complex selectors, pseudo-classes, etc.) are allowed, though the code should be as obvious as possible.


~~~
5.9.2.4. Complex Styling

“““
[construct] {human:"[…]"}
”””

In many cases, authors may not only want to move beyond CSS, but beyond anything a simple, CSS-like property:value pair can provide. In these cases, the UEWSG stylesheet proves the “human” property, where an author can describe further instructions or information. This declaration should only be used when absolutely necessary and be as concise, and clear, as possible. For instance, an author may define that a certain page of their work is to printed with a certain weight and color of paper; that would best be noted in this declaration.


~~~
5.9.2.5. Comments

To avoid any potential conflicts, all comments regarding the stylesheet and/or at-rule must be made before the at-rule or, preferably, after its closing marker (“}”). The recommended method is to place the comments after the at-rule, a blank line, and a new section with the heading “Comments”.


+++

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 writers 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, some Scripture quotations were taken from the New Revised Standard Version Bible, copyright © 1989 National Council of the Churches of Christ in the United States of America. Used by permission. All rights reserved.


+++


Ø JBT


http://uewsg.org


@UEWSG 0.1.0 (strict; markup; "uewsg_0.1.0.css")