UEWSG 0.2.0
Uniform English Writing Style Guide 0.2.0 (***beta version***)
By JBT
Released on 2018-10-17
http://uewsg.org/uewsg_0.2.0.txt
+++
Dedicated to St Adrian Of Poshekhonye, hieromonk and martyr (March 5)
+++
Table Of Contents
1. Introduction
2. Basic Orthography
2.1. Characters
2.1.1. Spaces
2.1.2. Line Breaks
2.1.2.1. Fallback Mechanism
2.1.3. Printable Characters
2.1.3.1. Fallback Characters
2.2. Capitalization And Cases
2.2.1. Sentence Case
2.2.2. Title Case
2.2.3. Snake Case
2.3. Filenames
2.4. Nesting
2.5. Precedence
2.6. Precision And Tone
3. Inline Constructs
3.1. Names And Titles
3.2. Abbreviations
3.3. Foreign Words
3.4. Special Terms
3.5. Numbers
3.5.1. Times And Dates
3.5.2. Variables
3.5.3. Math
3.5.4. Units
3.6. Quotations
3.7. Preformatted Quotations
3.8. Inline Lists
3.9. Note Markers
3.10. Citations
3.11. Marked Emphases
3.11.1. Standard Marked Emphases
3.11.2. Strong Marked Emphases
3.11.3. Critical Marked Emphases
3.12. Keyboard Keys
3.13. Censored Text
3.14. Directions
3.15. Links
3.16. Other Interactive Text
4. Block Constructs
4.1 Divisons And Headings
4.1.1. Main Titles
4.1.2. Chapters
4.1.3. Sections
4.1.4. Subsections
4.1.5. Extended Subsections
4.2. Paragraphs
4.3. Breaks
4.3.1. Dinkuses
4.3.2. Ellipses
4.4. Blockquotes
4.5. Preformatted Blockquotes
4.6. Lists
4.6.1. List Items
4.6.2. Bulleted Lists
4.6.3. Numbered Lists
4.6.4. Description Lists
4.6.5. Other Lists
4.7. Notes
4.7.1. Footnotes
4.7.2. Chapter Notes
4.7.3. Endnotes
4.8. Asides
4.9. Tables
4.10. Other Block Constructs
5. Document-Level Styling
5.1. Alignment
5.2. Margins And Line Length
5.3. Widows And Orphans
5.4. Font Sizes
5.5. Line Height
5.6. Typefaces
5.6.1. Sans-Serif Fonts
5.6.2. Monospaced Fonts
5.6.3. Serif Fonts
5.6.4. Other Fonts
5.7. Colors
5.8. Code
5.8.1. Indentation
5.8.2. Comments Syntax
5.8.3. Markup Syntax
• Appendix A. Alternate Formats And Sample Stylesheets
• Appendix B. Bibliography
• Appendix C. Changelog
+++
1. Introduction
The Uniform English Writing Style Guide is designed to change the way we write: with the UEWSG (pronounced like the word “usage”), I aim to seamlessly integrate unambiguous syntax, clean styling, and clear semantics with wide compatibility and the simple, natural writing that most authors are used to. I encourage everyone to use the Uniform English Writing Style Guide whenever creating new works or updating old ones. I believe it will not only positively impact the way we write, but that it will further reduce the barriers—barriers we ourselves have created by poor planning, ambiguity, and lack of standardization—to sharing our work with others by making it easier to write across all different media, translate our work into different languages, and preserve our creations through the passage of time.
One of the key goals of the UEWSG is a clear syntax. Too often, writing relies on easily-lost styles to convey critical meaning: how many documents, if all styling—font size, indentation, and so forth—was removed, would be intelligible? Could a reader distinguish a heading from a short paragraph? Would they know if a number at the beginning of a line was really denoting a list item? Could they tell the difference between a quote that should be preformatted—like code—and any other quotation? Obviously, the current answers to these questions are not very encouraging: outside of non-human-friendly markup languages, there is no clear way to parse a random document. But with the UEWSG, I hope to make this trivial: by adhering to a simple syntax, all parts of a document are immediately clear—even if all styling is removed. And this requires very little work on the author’s part because, instead of trying to mark natural writing up with distracting computer code, the Uniform English Writing Style Guide incorporates the way we already write, only clarifying and enforcing basic rules and safe practices. Best of all, the syntax is designed to be the same for all types of writing and across all media: a quick note on a slip of paper, a plaintext file, a type-written manuscript, a website, and a professionally-typeset book all use the same rules. Want a quick demonstration? Copy the HTML version of this specification from any reasonably standards-compliant browser (as of 2018, Firefox still does not handle even ASCII characters correctly, but nearly any other browser should work) into a basic text editor (Notepad, Notepad++, Sublime Text, vi, etc)—and compare it to the plaintext version of the spec, for extra effect. *That* is why we need a style-independent syntax: clarity, power, and limitless compatibility.
Another primary focus of the UEWSG is clean styling. No single style will please everybody everytime, but I don’t believe that is a good reason not to have a sensible set of default styles which add to, not take away from, the message of an author. In the UEWSG, this styling is applied through progressive enhancement: starting with the most basic, widely-compatible formatting and adding to it, when needed, with straightforward modules. I’ve relied heavily upon typographic and orthographic styles and characters which have been both used across media for decades—or centuries—and which are equally compatible with modern, digital writing. Because only the style—not the underlying syntax—changes between media, any conforming document should be able to be copied into plaintext without losing any of its most vital information or structure. Additionally, since a lot of the math for measurements (font sizes, margins, and so forth) is based upon reciprocally-terminating numbers, calculations are considerably simplified for both man and machine: operations should produce values with a finite number of digits—and that means no more dealing with repeating decimals!
The Uniform English Writing Style Guide also covers markup and programming languages. Beyond addressing indentation, a clear method is provided for writing UEWSG-compatible notes within a language’s own comment syntax. The UEWSG is not averse to data formats, either: JSON is practically UEWSG-compatible “out of the box”. What about extreme environments where only ASCII characters can be used? This is covered, too. And while I wrote the UEWSG to form a semantic baseline for a document, it is also compatible with file formats that add even-more-precise semantic information, like HTML. Indeed, because HTML is so prevalent, specific examples are given throughout this specification so web developers can consistently integrate the Uniform English Writing Style Guide into markup.
Remember, all this clarity and compatibility is “baked” right into the Uniform English Writing Style Guide. Now especially, in the digital age, writing guidelines which actively promote unnecessary ambiguity and arbitrary rules, rely on markup which will become invisible and almost useless when it is rendered, or require more work to make even a simple document readable should be reconsidered. And since there is no longer a guarantee that a human will even be reading an author’s work—it could be read by a machine—inconsistent and incoherent guidelines are an even bigger liability. The UEWSG is designed to tackle all of these issues, with ease of digital parsing as a major topic of concern. Again, all of this requires minimal effort on the part of authors to implement and only a few seconds (if even) on the part of readers to pick up on the general syntax.
I do not want to imply that there is no place for extra artistry and professional design, nor do I want the defaults I’ve provided in the UEWSG to stifle creativity or provide the “only” solution. But, for the average document, most of the time, money, and brainpower put into styling adds nothing to the work and produces, at best, mediocre results. I want the Uniform English Writing Style Guide to serve as a baseline for authors, to help take away the time consumption, inconsistency, and ambiguity of routine formatting, style, and syntax decisions. While they should provide a strong, human-friendly, and machine-safe foundation, I realize that not every creative work will fully utilize them. Therefore, even when authors do not make use of the guidelines’s ability to be extended and modified, I hope that the guidelines can still be of use as a starting point or basis.
***
I want to maintain the UEWSG as a collaborative effort from people all over the world and to thank all of the contributors—past, present, and future, known and unknown—for their help. All contributions up to this point have been anonymous, but they are vital to the success and universal scope of the project. Everything from small bug fixes to big ideas are welcome. Want to contribute, either by name or anonymously? Visit Contribute (http://uewsg.org/contribute.html) for more information.
I must also unequivocally state that the real credit for the *good* parts of the Uniform English Writing Style Guide goes to God and all the letter-by-letter help He gives because, despite prayerfully working to ensure completeness, root out contradictions, and provide unambiguous clarity, I know that I have missed (or even ignored) most of things that He has shown me. I apologize for any mistakes in the UEWSG, as they are certainly my own. Notwithstanding, and if God wills, I hope this becomes a standard that will make human communication easier for generations to come. And I pray that He will bless your words, that you may write clearly, truthfully, and worshipfully of Him and to Him—Father, Son, and Holy Spirit—for this is the only true reason that we write.
+++
2. Basic Orthography
Before tackling more advanced concepts, authors need to familiarize themselves with the essentials: the characters they will use in writing, the capitalization of those characters, and the basic rules concerning their usage. If these elementary concepts are misunderstood, a document may become unwieldy or unreadable. Of course, as long as no rules are broken, authors are free to follow additional local customs, style guides, and their own inclinations—and this freedom applies to the entire UEWSG: the Uniform English Writing Style Guide is not designed to take away creativity and personality from works, but to foster a uniform baseline where those traits can be more clearly, and safely, expressed.
===
2.1. Characters
Characters are the buildings blocks of words, markers, and nearly every other part of a document. Characters should be directly typed or pasted; readers should never see a character’s Unicode code point unless a work is displayed in ASCII format or some other extraordinary rendering. On the other hand, some file formats, like HTML, require certain characters or sequences to be escaped so that they *will* display correctly to readers. In these cases, authors must follow the conventions of the file format (eg, “<”, “>”, and “&” must be escaped in HTML). Unless otherwise contraindicated, all digital documents must be written in **UTF-8**, the universal standard for digital text. All horizontal text—which is the default for writing—should flow from left to right and secondarily from top to bottom. Vertical text, like on the spine of a book, must flow from top to bottom and secondarily from right to left; no text or labels should be written bottom to top except for the axes of graphs where the common convention is to work within quadrant I and thus read the Y axis from bottom to top.
**HTML module**: HTML documents should begin with the document type declaration, “““”””, for legacy reasons. They require the tag “““””” around everything else, to set the language and text direction. They also require the “““””” tag in their “““”””. Similarly, CSS files require the at-rule “@charset "UTF-8";” before any other content—including comments. The tag “““””” is recommended for all HTML documents to ensure a consistent level of zoom on all screen sizes; it must also appear in the “““”””. If HTML is used with CSS, which is nearly always the case, the HTML document further requires a “““””” tag, with the correct media attribute (optional) and href, also in its “““”””. Finally, the actual content of the HTML document must appear within a single set of “““””” tags.
---
2.1.1. Spaces
Spaces may be the simplest characters, consisting of a defined amount of whitespace to separate printable characters visually, structurally, or both. In the UEWSG, the default spacing is unvarying: **1 space**. This applies to spacing between words, between sentences, between groups of digits, and between any other inline constructs that require separation. Spaces *must* be used between URLs, paths, and/or filenames and potentially conflicting characters (periods, hyphens, etc) for semantic clarity. Spaces may also be used, as needed, between similar characters for visual clarity (eg, a set of closing single and double closing quotation marks). Spaces are generally not permitted directly inside of delimited constructs (parentheses, quotations, emphases, etc), unless otherwise noted. For further guidance, see “2.1.3. Printable Characters” or a specific construct’s division.
Unusual space characters, such as the non-breaking space, should not be employed in normal writing; they are difficult or impossible to distinguish from regular spaces without special software. They may inadvertently get replaced with a regular space or—even worse—may start replacing regular spaces. If more fine-grained control is needed, especially when typesetting formal documents, this is beyond the scope of the UEWSG but other characters are not strictly forbidden.
Spaces must never be used for indentation outside of special cases (eg, ASCII art, text-based tables, etc) in preformatted quotes and preformatted blockquotes. For more information on how to properly indent code, see “5.8.1. Indentation”.
---
2.1.2. Line Breaks
Line breaks are similar to spaces, but create white space in the vertical dimension. In the UEWSG, single line breaks are used to separate division markers from headings and are generally allowed within a block construct’s content to help format text (eg, separating verses in The Nicene Creed). Double line breaks, or blank lines, are used to separate block constructs from each other (for more information on the rules of block formatting, see “4. Block Constructs”). Blanks lines are not permitted elsewhere and multiple blank lines are not permitted anywhere.
///
CR + LF 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.
\\\
Line breaks must be made with the newline characters **CR + LF**, or carriage return and line feed. This standard sequence is the most commonly used today: Windows and DOS-based systems use it natively, modern Unix-based systems support it, and most of the fundamental internet protocols (eg, HTTP, FTP, etc) explicitly require it. Thus, even on systems where CR + LF isn’t the default, it must be used for the sake of compatibility; most non-legacy operating system and/or their text editors have simple ways to adjust this setting.
~~~~~
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:
• All spaces must be preserved.
• All line breaks must be replaced with the escape sequence “\r\n”, corresponding to the control characters CR + LF.
Indeed, a fully-conforming document is already so well-formatted that only these few changes are necessary. Even if a document was sent like this one character at a time on a ticker tape, no syntactical information should be lost; despite the poor [human] readability in this format, any fully-conforming work should be able to be unambiguously and exactly recreated into its original form with an easy automatic or manual parsing. Few, if any, other writing guidelines or systems [outside of non-human-friendly markup languages, etc] can make this claim. Note that this fallback format can be used in an ASCII-only environment and it shouldn’t cause any syntax issues there, either.
---
2.1.3. Printable Characters
Printable characters are those that are visible: not just letters and numbers, but symbols, too. Because printable characters more directly hold the content of a document, it is crucial for authors to select the most appropriate characters and use them correctly in their writing; poorly chosen characters and/or improper usage can convey a lack of professionalism. Documents must adhere to the following rules:
• Quotations marks (“ “” ” and “ ‘’ ”; sometimes called “curly quotes”) must have no spacing on the inside; interior contents must directly touch the quotation marks (subject to the exceptions noted in “2.1.1. Spaces”). While it is customary in American English to start with double quotation marks, then use single quotation marks for the next-innermostly-nested quote, then use double quotation marks for the third-level of nested material, and so on, this usage is not required in the UEWSG: authors may use either single or double quotes as the primary delimiters, according to the requirements of the document or local custom, so long as they remain consistent.
^ Straight quotation marks (“ " ” and “ ' ”) are distinct characters and, while they appear conveniently on most keyboards, they may not be preferred for many kinds of publishing, where they may be perceived as inelegant and unprofessional. For other uses, however, straight quotes are perfectly acceptable: everyday writing (plaintext, SMS, certain types of e-mails, etc), code (where they are usually required), and ASCII-only environments (where they are most definitely required; see “2.1.3.1. Fallback Characters”, below). While there is no preference in the Uniform English Writing Style Guide towards either straight or curly quotation marks, limited use of straight quotes not only makes works more readable, but can help isolate syntax errors, as well; either way, authors should be consistent in their use.
• Apostrophes (“ ’ ”) are the same character as the closing single quotation mark and must also be used without spacing. In order to help distinguish these 2 uses of the same character, *apostrophes must have printable characters directly touching them on both sides*; any seeming apostrophes that are not surrounded by printable characters *must* be treated as single quotation marks. This means that possessives ending in an “s” must always have an additional “s” at the end of the apostrophe (eg, “Thomas’s”). While this rule may seem slightly redundant, it is more semantic, matches the spoken usage, and prevents all manner of potential parsing problems (for example, the sentence “I went to the ‘Two Towns’s’ restaurant…” would be unclear and shows just one possible danger if this seemingly “redundant” UEWSG rule is not strictly adhered to; when dealing with computer programs that automatically parse nested quotes, the problem is significantly magnified). Abbreviations and colloquialisms which violate this rule (eg, “get ’em” and “ ’till”) must be rewritten without spaces (eg, “get’em”), rewritten without the apostrophe (eg, “till”), or safely enclosed in a containing set of quotation marks to prevent ambiguity (either as a quotation or preformatted quotation, depending on the severity of the violation; see “3.6. Quotations” and “3.7. Preformatted Quotations”, respectively.). Authors should also remember the distinction (above) between the formal, “curly” apostrophe and the the straight version (found on keyboards) and use one or the other consistently.
• Parentheses (“()”), brackets (“[]”), and braces (“{}”; sometimes called “curly braces”) must have no spacing on the inside. They must be used for their proper functions: braces are reserved for special uses (eg, programming and math), brackets are most typically used for inserted material (including note markers, editorial notes and changes, and even ironic commentary by an author within his or her own work), and parentheses are used for most other purposes (inline notes, clarifications, elaborations, translations, definitions, in-dialog directions, and any other type of *parenthetical* information—as in this parenthetical construct).
• Hyphens (“-”; technically hyphen-minuses), present on most keyboards, are both a hyphen and minus character in one. In their hyphen form, they must be used without spacing and can break up words, connect words in compound adjectives (a not-so-uncommon usage), connect certain compound words (such as e-mail and non-breaking space), indicate that a word is to be spelled letter by letter (eg, “spell t-h-i-s out loud”), and more. An exception is made for suspended hyphens (as in the phrase “7- and 8-year-old children”) and line-wrapping hyphens (ie, those that break a word into smaller segments on multiple lines); a space [or line break] is permitted on the right for these cases. In their capacity as a mathematical minus sign, they may be used for both subtraction (when surrounded by spaces) and negative numbers (when only the side opposite the number, the left, is spaced); see “3.5.3. Math” for more examples.
• En dashes (“–”) must always be used unspaced. They can be used to separate ranges (eg, 3–8, pages 6–7; for more on ranges, see “3.5.3. Math”). Similarly, they can separate words denoting a physical or immaterial range or tension (eg, the North–South divide), though a slash (“/”) can also be safely (though slightly more obtrusively) used for that purpose in many instances.
• Em dashes (“—”) may be used, without spacing, to separate parenthetical content [in place of parentheses] or to denote a shift in thought or speech inside a sentence (interruption, epanorthosis, etc). They may be used with spacing on the right side only to denote censored text (see “3.13. Censored Text”). They can also be used to begin adjectival paragraphs, following a double line break (eg, “—by Leonard Wibberley”), or other adjectival content. Em dashes are not allowed to touch numbers on both sides and, if there is a chance a document may be viewed in an ASCII-only environment, care must be taken to avoid phrases that could imply subtraction (eg, “…the people—3 of them…” could create ambiguity; see “2.1.3.1. Fallback Characters” for more about how em dashes are handled in ASCII).
• Slashes (“/”) must be used unspaced when they are separating directories in a URL or path (“…/example/url/or/path/…”), representing fractions (see “3.5.3. Math”), and taking the place of the word “or” (eg, “left/right” and “strange/odd”). But, when used to represent a line or verse break—as is common in songs and poetry—and in division (eg, in place of an obelus), slashes must be spaced on both sides.
• Ellipses (“…”), whether written as a single character or the semantically-identical three periods, must be used unspaced, unless beginning a sentence or ending a paragraph. If they end a sentence within a paragraph, they still require trailing terminal punctuation. Ellipses must be used with brackets whenever an author adds them to a quoted phrase.
• Terminal punctuation marks (viz, “.”, “?”, and “!”), commas (“,”), semicolons (“;”), and colons (“:”) must have a trailing space when followed directly by another word, sentence, or opening punctuation mark of any kind. Outside of special cases (see “2.1.1. Spaces”), these punctuation marks must not be preceded by a space. Terminal punctuation marks may be overridden by another contiguous terminal punctuation mark (with the last one in the series taking parsing precedence), by a comma (in the case of a list item marker; see “3.8. Inline Lists” below), or by a semicolon (eg, “?;”). Further, these markers *do not “collapse”*: if a sentence ends with an ellipsis, for example, *4* periods are required, for clarity.
• Direct references to letters should be quoted (eg, when speaking about the letter “a”). Direct references to multiple instances of a letter must be quoted, for clarity (“ ‘i’s” are not the same as “is”, for instance).
~~~~~
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:
• Double quotation marks (“ “” ”) and single quotation marks (“ ‘’ ”; this includes apostrophes, which are the same character as the closing single quotation mark) must be replaced with their “straight quotes” versions (“ " ” and “ ' ”).
• En dashes (“–”) must also be replaced by hyphens (“-”); this will not be confused with subtraction because no spaces are present.
• Em dashes (“—”) must be replaced by hyphens with a space on either side (“ - ”), to distinguish them from the normal use of hyphens. Note that while this form also mimics the mathematical subtraction operation, the UEWSG does not allow em dashes between 2 numbers, so this should not create confusion. Em dashes which begin a paragraph (ie, an adjectival paragraphs) or which denote interruption or censoring (see “3.13. Censored Text”) must be replaced by hyphens, with spacing on the right side only.
• Ellipses (“…”) must be replaced with three periods in a row (“...”).
• Bullets (“•”), multiplication signs (“×”), and dot operators (“⋅”) must be replaced with asterisks (“*”).
• Division signs (“÷”) must be replaced with slashes (“/”).
• All remaining non-ASCII characters must be escaped with their proper hexadecimal character reference according to the document’s format. If no format is specified, HTML’s is the default (“&#x[…];”).
Authors should be careful defining their own fallbacks for other characters; the defined fallbacks (not to mention the original characters) have been rigorously researched and tested. For example, replacing prime marks (as used in coordinates like “35° 39′ 40″ N”) with similar-looking straight quotes is practically *never* a wise idea. In any case, any author-defined fallback characters are beyond the scope of the UEWSG.
===
2.2. Capitalization And Cases
///
Since content in “““ALL CAPS””” both looks like an abbreviation and many readers consider it to be a written form of shouting, that case should *only* be used for abbreviations (see “3.2. Abbreviations”)—or inside of preformatted quotes or preformatted blockquotes (see “3.7. Preformatted Quotations” and “4.5. Preformatted Blockquotes”, respectively) in rare situations like legal disclaimers.
\\\
Capitalization is an important way to orthographically distinguish certain constructs from surrounding text. For instance, most abbreviations are written in all caps, whereas filenames are written in a strict variant of the computer-friendly snake case. The rules for capitalization are simple, hierarchical, and unambiguous: all writing should follow sentence case, unless it is part of a construct that is otherwise styled according to the UEWSG. Names, trademarks, and/or other words that do not follow any of the defined cases (eg, “McDonald” and “OpenBSD”) or which follow a case other than their usage suggests (the titles “nginx” and “xkcd”, Latin/scientific names of organisms, etc) should be written in their special forms, though this is ultimately left to the discretion of the author. Since lowercase and all caps (or “““ALL CAPS”””) are clear enough, only 3 other cases need to be further defined:
---
2.2.1. Sentence Case
In sentence case, all letters are lowercase, except the first letter of a sentence, if it is also the first character; if a sentence begins with a number or some other non-construct-delimiting character, the first letter remains lowercase (eg, “12 stones were…”). This capitalization includes the first letter of a quoted sentence that begins inside another sentence (eg, “Jesus said, ‘You search the Scriptures, for in them you think you have eternal life; and these are they which testify of Me. But you are not willing to come to Me that you may have life.’, as recorded in John 5.39–40 (NKJV).”) but *not* quoted phrases or incomplete fragments of sentences (eg, “St Paul refers to the Church, not The Scriptures, as ‘the pillar and ground of the truth’ in 1 Timothy 3.15 (NKJV).”).
---
2.2.2. Title Case
///
While other forms of title case exist, they are convoluted and simply confusing—in addition to generally being quite arbitrary—and must 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 must *never* be used to replace spaces or underscores, as they have a different meaning.
===
2.3. Filenames
When creating or storing a document digitally, particular care must be given to its filename. The filename of a document should not only match its main title (see “4.1.1. Main Titles”), but must follow any restrictions imposed by the operating systems it comes into contact with (eg, filenames beginning with a period are considered “dotfiles” on most OSes and are normally hidden; see https://en.wikipedia.org/wiki/Filename for more such conventions). Because some restrictions are still so commonplace, however, the following suggestions are also *recommended*.
///
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 (eg, “file.txt”)—regardless of operating system—as this aids in human and machine parsing. For versioning, authors should adhere to the Semantic Versioning 2.0.0 spec (http://semver.org/spec/v2.0.0.html), which is almost fully compatible with strict snake case. Finally, it is recommended that authors follow any other useful traditions associated with the systems their files may come into contact with, unless contraindicated by the UEWSG.
===
2.4. Nesting
One fundamental rule underlies most of the standards relating to nesting constructs: authors must always close constructs in the reverse order that they were opened. If three quotations are nested together, for example, the innermost quote must be closed before the second may close, and the second must close before the outermost quote may close. Or, a segment inside parenthetical text that is given standard marked emphasis must be “closed” before the closing parenthesis. This rule is paramount for keeping documents readable and absolutely indispensable when a machine is parsing a work.
===
2.5. Precedence
In order to permit uniform parsing of the Uniform English Writing Style Guide, quotations and other constructs with opening and closing markers may be used to contain content that might be unclear; if a string can be parsed as either regular text or a marker, the marker takes precedence. For example, in a hypothetical ASCII-only environment where line breaks are not allowed, the content “text +++. More text” *must* be parsed as if “.” is a chapter heading. To be parsed as text, it must either be quoted (like “text ‘+++’. More text”) or rewritten in some other way. Content that would still break the parsing or formatting rules of the UEWSG (like the phrase “search for the file ‘‘‘*.*’’’ ”, many types of poetry, etc) must be set in preformatted quotations or preformatted blockquotes (see “3.7. Preformatted Quotations” and “4.5. Preformatted Blockquotes”, respectively), which are exempt from regular parsing rules.
If the rare situation presents itself where 2 or more styles are mutually exclusive in a given format (eg, rendering bugs in certain browsers make borders and margins conflict), authors must always follow the core rules first, then the rules of any modules; if there is still conflict, authors have discretion in choosing which of the styling rules is more vital to apply.
===
2.6. Precision And Tone
While the UEWSG is meant to foster uniformity, it is not a replacement for a dictionary or a full course on grammar: topics such as spelling, hyphenation of compound adjectives, and the general process of writing are outside its purview. Nonetheless, a few words on precision and tone are in order. Authors should understand their audience and use language that is appropriate. For example, most readers would expect a peer-reviewed article to be technical and serious, whereas a fiction novel might be more familiar and light-hearted. This is not to say that a technical author cannot use humor or a novelist cannot use specialized terminology, but that the language should not distract from the message. Second person pronouns, though not inappropriate in most forms of writing, must be used wisely: authors should not unquestionably address readers (“you must…” or even “you should…”), but should cautiously describe the conditions under which a direction should be followed—“if A, then you must…” is an acceptable approach.
///
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.
\\\
Language should be as precise as reasonably possible. For instance, while it may be common to call food “good”, a more precise word might be “tasty”. And, in a similar vein to the use of commands with personal pronouns, authors should be wary of stating that things “will” happen: unless the author has some extraordinary knowledge of future events, more conditional phrases are preferred (“should”, “is expected to…”, “…plan to…”, etc).
+++
3. Inline Constructs
With a practical understanding of the basic rules for UEWSG-conforming orthography, authors next need to consider inline constructs. Inline constructs include words, full sentences, and everything in between: abbreviations, quotations, and so on. Many of these constructs have special rules and formatting, but all of these constraints serve the same goal: to make a document readable on any medium and consistent in every medium.
===
3.1. Names And Titles
///
Many proper names have prepositions, conjunctions, and articles which are not ancillary but have become an integral part of the name. As per “2.2.2. Title Case”, such words must also be capitalized, as in “St Adrian Of Poshekhonye”—being “of” somewhere instead of “from” somewhere is usually strong evidence for a preposition’s importance to the title! But when a title is used as an adjective, any articles continue to follow the case of the nouns they modify, so “going to study The Bible” is not the same as “going to the Bible study”.
\\\
All proper nouns—including titles—must be written in title case. This includes, but is not limited to, names (eg, “Joseph” and “St Adrian”), places (physical or political: “New Kidron”, “Antarctica”, “Mount Athos”, etc), organizations (of any kind: “Internet Systems Consortium” and “NASA”, but also “Trader Joe’s”, “Asus”, “Ancient Faith Radio”, etc), time periods (“Spring”, “Iron Age”, etc), wars and battles (eg, “Battle Of Thermopylae”, “Battle Of The Milvian Bridge”, and “World War I”), ships and units (“NKN Soggy Bottom”, “Varangian Guard”, etc), musical notes (“C”, “B♭”, “F♯”, etc) and work titles (including book, article, play, poem, music, video, and website titles). Titles within titles (like “A Study Of ‘The SUN Study’ ”) must be quoted, for clarity. Some proper nouns require additional styling:
///
While most of the styling in the UEWSG is based on syntax and can therefore be applied automatically, a few of the complimentary styles—like italics for work titles—may need to be manually added to a document if it is copied from plaintext into a more expressive medium.
\\\
**Rich media module**: Work titles (including distinct works within a larger work, such as books of The Bible, but not mere subdivisions) and vessel names must be italicized in running text; italicization in headers and footers is left to the discretion of the author. A title of *another* work or division that falls within a heading must also be italicized, but a work’s own main title must not be italicized when it is presented [as a block construct] (see “4.1.1. Main Titles”). Words in titles that are already italicized for another reason (viz, vessel names and foreign words) must be *un*-italicized to communicate their meaning (eg, “The Legend Of The NKN Soggy Bottom”).
**HTML module**: Work titles in running text, as well as a title of *another* work that falls within a heading, must be wrapped in “““””” tags; quotation marks for a title must fall outside its “““””” tags. A work’s own main title [as a block construct] must not be wrapped in “““””” tags, but other references to its title must be. Vessel names in running text must be wrapped in “““””” tags.
===
3.2. Abbreviations
In the Uniform English Writing Style Guide, abbreviations are covered by 4 simple rules:
• Abbreviations must *not* have periods and must be written in the case of the surrounding text, unless otherwise excepted. This includes abbreviations of most personal titles (such as “St”, “Bp”, “Fr”, and “Dn”), books of The Bible (“Jer”, “Eccles”, “1 Macc”, “Jn”, and the rest), street names (such as “Ave” and “Rd”), and words from all other categories (such as “pg”, “vol”, and “anon”). This also includes abbreviations that, as defined in a dictionary, are written in a hyphenated form (such as “e-mail” and “wi-fi”) or have come to be used as words in their own right (eg, “ok”, “info”, “math”, “percent”, “sonar”, “radar”, “laser”, and “blog”); common Latin phrases (including “ie”, “eg”, “cf”, “viz”, “am”, and “pm”) fall into this category—and do not need italicization, being Anglicized.
• Acronyms, including initialisms and postal codes, (such as “JBT”, “NK”, “N”, “SSE”, “EST”, “UTC”, “HTML”, “RAM”, “FAQ”, “IMAP”, “PIN”, “NC”, “NA”, and even “R&D” and “W3C”) must be written in all caps and must not have periods or spacing; this includes Latin acronyms and initialisms that have at least one proper noun (like “AD” (“anno Domini”, or “in the year of our Lord”), “SPQR” (“Senatus Populusque Romanus”, or “the Senate and People of Rome”) and the lesser-known “DV” (“Deo volente”, or “God willing”)).
• In mixed abbreviations, where acronyms are mixed with longer abbreviations, only the longer abbreviations must receive spacing while the acronyms are dealt with normally, above (such as “CS Lewis”, “JK Rowling”, “M Div”, “Th D”, and “N America”).
• Abbreviations of work titles must retain italics (like “UEWSG”).
As noted in “2.2. Capitalization And Cases”, abbreviations that are commonly written in a different case may be written in their accepted style, at the discretion of the author. Any abbreviation that is unclear in a given context should not be used and uncommon abbreviations should be spelled out at or near their first occurrence to avoid confusion.
**HTML module**: Abbreviations may be wrapped in “““””” tags. If they are given a title attribute and thus become interactive, they must be further styled like interactive content (see “3.16. Other Interactive Text”).
===
3.3. Foreign Words
In various circumstances, authors may need to use foreign words or phrases. While some of the more common ones have been adopted into English dictionaries (eg, many Latin abbreviations), all other foreign words (including taxonomic designations) must have extra styling (as well as a definition, if necessary) when used in running text:
**Rich media module**: Foreign words and phrases must be displayed in italics.
///
While the “““””” tag is not very semantic for marking words in another language (or vessel names, above), HTML has no better option.
\\\
**HTML module**: Foreign words and phrases must be wrapped in “““””” tags.
===
3.4. Special Terms
In many types of writing, authors may need to use words or phrases that carry special meaning and/or require extra visibility but don’t really fit into another category: keywords, difficult terms that may be unfamiliar to readers (especially if they are defined elsewhere, like a glossary), questions on a test, and so forth. Such special terms may receive additional styling:
**Rich media module**: Special terms may be displayed in bold at their first instance in running text; further instances may also be displayed in bold, at the discretion of the author.
**HTML module**: Special terms may be wrapped in “““””” tags at their first instance in running text; as above, other instances may also be wrapped in these tags, at the discretion of the author.
===
3.5. Numbers
Numbers denote concepts like quantity, order, and value and are just as important in most forms of writing as letters. Alas, they may be some of the most confusing and contradictory parts of most style guides. More than a few of the oddities that are almost intrinsic in current usage cannot easily be removed, so many of the rules have optional components. The basic rules for dealing with numbers in the UEWSG are:
• Numbers should be represented in Hindu-Arabic numerals (viz, “0”, “1”, “2”, “3”, “4”, “5”, “6”, “7”, “8”, and “9”) for clarity in all types of writing. They may be written out in extraordinary cases, like emphasis (eg, “only 2—*two*—people!”), verbification (such as “zero the scale”), and article substitution (eg, “One day, I…” instead of the terribly awkward “A day, I…”); authors have discretion in other cases, but numerals are still recommended as they are far easier to read. Plural forms of numerals must have an “s”, but never an apostrophe (eg, “2000s” and “50s”). Other numeral systems, especially Roman numerals, are widely misused (particularly in outlines), sometimes unclear, and should be avoided.
• Ordinals (eg, “3rd”, “501st”, “13th”, “42nd”, etc) must not have superscripted ordinal indicators, as these, despite their historicity, could be confused with more modern usages of superscript. Authors have discretion when choosing whether or not to write ordinals out (“first”, “second”, and “third” up to common time-based phrases like “the eleventh hour” and “twelfth night” are often written out), but numeric ordinals are still recommended generally.
• Approximate or rounded numbers must use the approximation symbol (“≈”) if the context does not make their imprecision clear (eg, “…is about 1 L” but “…is ≈1 L”); if they are “large”, they may be written out in part, so long as the significant digits are retained as numerals (eg, “4.5 billion”). Numbers or quantities used with no precise significant digits (eg, “there were a million of them!”, “half of the bag”, and “a week or two”) should be written out in full.
• Spaces—and only spaces—may be used to group digits together for easier visual parsing. This extends to large numbers (eg, “1 000 000”), RGB values (such as “000 080 000”), phone numbers (eg, “+1 919 NNN NNNN”), and any other numerical constructs. Commas must never be used for this purpose, because this can mimic comma-separated values, lists, and other constructs, leading to potentially catastrophic ambiguity.
///
If a period follows a number, it is *never* parsed as the end of a sentence—a space, or quotes, must be used for a number at the end of a sentence.
\\\
• Periods (“.”) must be used as radix points separating the fractional (eg, “6.28319”) or other subordinate parts (as in “version 1.0.3”) of numbers or divisions in a numerically-subdivided work (as in Mark 6.31). This is the standard followed in a great deal of the world, in nearly all programming and web languages, and is much safer than using commas (see above) or other conventions. For further clarity, numbers must not begin or end with periods (ie, use “2.0” and “0.5”, not “2.” or “.5”), unless they are used as a list item marker (eg, “10.2.”). If their common usage dictates otherwise (eg, “.308 ammunition”), they must be quoted or otherwise set apart from the rest of the normally-parsed text.
---
3.5.1. Times And Dates
In general, authors can use local conventions when writing out dates in full (eg, “April 20, 2008”), appending the standard suffixes “AD” or “BC” as needed (eg, “2008 AD”). Days of the week may be freely used in non-technical writing; Sunday is traditionally considered the first day of the week. Times may also be written out in either 12- or 24-hour format, according to local convention (like “2:00 pm” or “14:00 hours”). If more precision is required or the time and/or date are not written out, the internationally-accepted ISO 8601 must be followed: times and dates in this format are easy to read, trivial for computers to parse and sort, and unambiguous. To heavily summarize, the standard requires that:
• Dates must be given in the format YYYY-MM-DD, with padding zeroes (eg, “2008-04-20”). For less precision, sets of values may be removed in order, starting from the smallest [right-most] increment (eg, “2008-04”).
• Times must be given in the format hh:mm:ss, with padding zeroes (eg, “14:00:00”). For less precision, sets of values may be removed in order, starting from the smallest [right-most] increment (eg, “14:00”). If a time follows a date, the date must not omit any values and must be separated by a “T” (eg, “2008-04-20T14”).
• Time zone information, if needed, must be appended to the time, usually in the format ±hh:mm, though the leftmost value can be omitted if unnecessary (eg, “2008-04-20T14-06”). Times given in UTC may use either the suffix “+00:00” or “Z” (“20+00:00” or “20Z” are both acceptable).
---
3.5.2. Variables
Variables are used to represent unknown and/or changeable quantities. Outside of opposing requirements, authors should consider defaulting to common variable usages: “x”, “y”, and “z” in place of unknowns that require calculation; “n” for input numbers; “i” and “j” for indexes (eg, in “““for””” loops); and “a”, “b”, and “c” for constants. Whatever the choice, variables require further styling:
**Rich media module**: Variables (but not any attached exponents, descriptive subscripts, etc) must be displayed in italics.
**HTML module**: Variables (but not any attached content, as above) must be wrapped in “““””” tags.
---
3.5.3. Math
While complex math equations are outside the purview of the Uniform English Writing Style Guide, being better-expressed in a more visual manner, most elementary operations are easy to communicate in running text:
• Unary operators must always touch the numbers they modify (eg, “-7”, “>2”, “10%”, and “5!”) unless written out as words (as in “negative 3”, “greater than 2”, “10 percent”, and “5 factorial”). This includes the radical sign (“√”) when it takes only a radicand, as is often the case.
• Operators that take at least two values, other than those excepted below, must be spaced, both for visual clarity and to prevent semantic confusion (especially since hyphens and minuses are the same character!). This includes the basic operations of addition (eg, “1 + 1” and “5 + -2”), subtraction (eg, “8 - 1” and “7 - -13”), multiplication (with either common symbol: “70 × 7” and “12 * 12”; it also applies when text is involved, as in “We had 2 × the enjoyment.”), division (again with either common symbol: “12 ÷ 2” and “255 / 3”), modulo (eg, “4 % 3” and “50 % 7”), and equality (eg, “2 + 2 = 4” and “8 + 5 = 13”).
• Exponentiation should be superscripted and must not have spacing. Exponents must contain a caret (such as “1.44 × 10^5” and “6.022 × 10^23”; note that the caret is *also* superscripted).
• Multiplication involving variables (“3n”, “τr”, and “ax^2 + bx + c”) must not have spacing unless a multiplication operator (eg, “×”) is present.
• Fractions, while technically a form of division, are a special case and must use a slash (“/”) without spacing and, in rich media, should always be properly super- and subscripted (“1/2”, “5/3”, etc). Improper fractions and decimals are generally preferred to proper fractions; if used, proper fractions must contain a space between their integral and fractional parts (eg, “Platform 9 3/4”). More complicated fractions require special care when written in text—the standard order of operations applies—though there is no preference in the UEWSG for separating out the fractional part of a formula (eg, “1/2τr^2”) vs writing the entire formula as a single fraction (eg, “(τr^2)/2”—and note the critical function of the parenthesis to prevent a fractional exponent!).
• Ratios denoted by a colon (“:”) must be unspaced; they are similar to fractions in both form and function.
• Subscripts maybe be omitted in textual representations of chemical formulas (eg, CH4 and O2) and in other cases where the meaning is obvious. However, where subscripts are still needed, they must be written in text using an underscore and braces (eg, M_{Earth} or M_{⊕}), with only the braces and their content subscripted.
• Ranges must use the en dash (“–”) with no spacing (eg, “70–72”) unless written out (eg, “between 70 and 72”). Undefined ranges (eg, “Open From 3–”) must always be written out unless they immediately precede terminal punctuation, the end of a paragraph, or a closing marker. Abbreviated ranges (“121–5”) may be used if they do not create ambiguity, but should generally be avoided.
---
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:
• Unit symbols must be separated from numbers by spaces (“500 m”, “20 °C”, “273.16 K”, “1.18 g/L”, etc).
• Units which are multiplied together must be separated by a dot operator (“⋅”) and contain no spaces (eg, “9.80665 N⋅m”), while those that are divided by another must use a slash (“/”), not contain spaces, and not be super- or subscripted (eg, “1.6 m/s^2”). Note that the dot operator is the only other binary operator which is *not* spaced and its use should be reserved for this special case.
• All units, even those derived from a name, must be written in sentence case when spelled out (“meter”, “gram”, “tesla”, “pascal”, “liter”, and so on); units must be written out in this form whenever an actual value is not present (eg, “How many grams are in…?”). Unit symbols are case sensitive and must be written in lowercase, Roman letters regardless of surrounding text (“m”, “g”, etc), except for those symbols which derive from a name (eg, “T” and “Hz”) or the liter (“L”; since it could be confused with other characters), which must always be written in title case. Prefixes are also case sensitive and must never be changed to a different case under any circumstance.
• Unit prefixes must be contiguous with the units they modify; no spaces are permitted (eg, “km”, “mL”, and “µg”).
Regrettably, because of semantic oversights or political concerns, the SI conventions are deficient in at least four areas and the UEWSG has stricter or divergent rules:
• The percent sign (“%”) must not be used with spacing lest it be confused with its common mathematical usage as the modulo operator (see above).
• Commas must not be used as an alternate radix point (see above).
• Spaces must not be used in place of dot operators and/or to imply multiplication. This can create great ambiguity because spaces are also the digit delimiter (eg, “1 000 000”), as noted above.
///
Using bits or bytes in a calculation? The differences between IEC and SI prefixes quickly add up: 1 GB (1 000 000 000 bytes) is only 954 MiB, for instance!
\\\
• Binary numbers should use IEC, not SI, prefixes unless explicitly contraindicated. These units (such as “kibibyte”, “mebibyte”, and “gibibyte”) and their symbols (such as “KiB”, “MiB”, and “GiB”—note the uppercase “K” for kibi, which is not the same as kilo’s symbol) imply not multiplication based on 1000 (ie, 10^3), but based on 1024 (ie, 2^10) and are more useful—and far more widely used—for binary math. Similarly, “B” should be used to represent bytes—not “b”, as SI suggests, as this usage is almost non-existent and conflicts with the symbol for bits.
Conventions for other units and symbols should follow the guidelines of the appropriate standards body or, if not defined, the common usage (eg, “$20” for “20 dollars” and “78° W” for the coordinate, both with no spacing).
===
3.6. Quotations
///
The HTML spec has changed and wavered significantly regarding which type of quotations should use “““””” tags, recommends some very strange and unsemantic things (such as not using quotation marks in writing and relying on fake (and usually non-copyable) browser-generated marks; see http://www.w3.org/TR/html5/text-level-semantics.html#the-q-element), and unnecessarily burdens authors while providing no actual benefits. Thus, the Uniform English Writing Style Guide does not use tagging at all for quotes, even in HTML.
\\\
Quotations can denote verbatim material which is from another source, but that isn’t their only use: they can signify a word or phrase is being directly referred to, convey irony, show an author’s reluctance to fully accept the common usage of a word or phrase, isolate ambiguous or unparsable content, and so on. Quotations begin and end with opening and closing quotations marks, respectively (either “ “” ” or “ ‘’ ”); the choice as to which type to use as the outermost set (ie, single or double) is left to the dictates of local custom. Punctuational games have no place—especially in the digital age, when the misplacement of a single quotation mark could literally cause an entire computer to fail—so the UEWSG has a very simple, but strict, rule: except for bracketed material (eg, editorial notes), only the content of the quote is permitted inside quotation marks. This means that no other punctuation from a sentence may “spill” into or out of quotes; this includes periods and commas. As an example, consider the nested sentences “Did he say ‘I want to go home.’, shout ‘I need to get home!’, or ask ‘Can I go home?’?”; each sentence must be properly punctuated or the entire meaning could be changed and/or lost. This rule is the safest, most precise, and most semantic way to handle quotations.
For longer quotations, see “4.4. Blockquotes”.
===
3.7. Preformatted Quotations
Preformatted quotations are similar to regular quotations, but more strict. They must be used to handle snippets of code, HTML, and/or any other inline content which might interfere with UEWSG-defined constructs. Preformatted quotes require all content—including whitespace—to be exactly and precisely represented inline; any contained constructs must not be given any styling whatsoever. To distinguish them from regular quotations, preformatted quotes open and close with sets of 3 contiguous opening and closing quotation marks, respectively (“ “““””” ” or “ ‘‘‘’’’ ”); again, the choice of single vs double quotation marks as the outermost set is outside the scope of the Uniform English Writing Style Guide and nesting works the same way, regardless. To ensure that the content is preserved and its preformatted nature is obvious, some styling is required:
**Rich media module**: Preformatted quotes, including the opening and closing markers, must be displayed in the first available font from the “Monospaced Fonts” stack.
**HTML module**: Preformatted quotations, including the opening and closing markers, must be wrapped in “““””” tags; this is the most semantic of all options—anything that would break the UEWSG is “code” of either a programmatic or lexical sort—and it also matches the most widespread use of this tag. The CSS “white-space” property must be set to “pre-wrap” to preserve formatting but allow automatic wrapping in browsers that don’t support the universal “word-wrap: break-word” declaration. No other [functional] HTML tags are allowed inside preformatted quotations, as this would negate their semantic meaning and potentially cause styling to applied.
For longer preformatted quotations, see “4.5. Preformatted Blockquotes”.
===
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 using appositives, 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 great example). If a list is used in a sentence, the last separator should be followed by a conjunction which denotes the relationship of the list items to each other (“and”, “or”, etc); the last list item may then follow this conjunction. In all inline lists with separators, the serial comma/semicolon (ie, a comma/semicolon between the second-to-last and last list item; this is sometimes called the Oxford comma) must be used. It not only shows typographic care and professionalism, but greatly aids in readability and prevents potentially-unresolvable imprecision.
///
Astute readers may notice the the Uniform English Writing Style Guide uses the alternative form for referencing list items when it comes to divisions within the UEWSG. This is for extra consistency in and programmatic generation of hyperlinks and anchors within the HTML version of the spec.
\\\
Inline lists that make use of inline list item markers (viz, numbers or letters) are allowed, so long as the inline list item markers end with a period (as in block-format lists; see “4.6. Lists”). Authors may follow the inline list item marker with a space alone or with a comma and a space (“a. [list item a], b. [list item b],…” and “1., [list item 1]; 2., [list item 2];…” are both perfectly acceptable); as noted in “2.5. Precedence”, parsing a period as a marker takes precedence over parsing it as the end of a sentence so this format is fairly unambiguous. The use of a closing parenthesis alone for this purpose (eg, “““a.)”””) is forbidden, due to catastrophic parsing issues, but full sets of parentheses are permitted (eg, “(a.)”). If a list item is referred to in text but *outside* a list, it must be written as regular text—*without* the period (eg, “In list item 1, note the…”)—or, as an alternative, enclosed in quotation marks (eg, “In list item ‘1.’, note the…”).
===
3.9. Note Markers
Note markers are the inline constructs which reference notes. As note markers are inserted material, they must always be enclosed in brackets (“[]”); this also helps to syntactically distinguish them from mere numbers or asterisks that may be used for other reasons in a text. If two or more different sets of notes are necessary (eg, the author’s original notes vs the editor’s notes), all secondary notes may be enclosed in 2 sets of brackets (“[[]]”) and labeled and listed separately, at the discretion of the editor; in any case, further clarification of the notes’s sources should be given in the note itself. While authors have freedom relative to which type of note marker they choose, numbered markers (ie, sequential numbers, starting with 1 (“[1]”)) resetting at the beginning of each chapter are *highly* recommended, both for clarity and ease of use. Note markers are also further styled:
**Rich media module**: Note markers, including their brackets, should be set in superscripted text. This is, however, left up to the discretion of the author.
**HTML module**: If note markers link to the actual notes, they should be marked with “““””” tags.
For more information on displaying notes themselves, see “4.7. Notes”.
===
3.10. Citations
Because citations and bibliography styles vary so widely across different academic fields and great controversy surrounds their relative merits, no specific format for citations is provided in the Uniform English Writing Style Guide. Instead, authors should choose the citation style most appropriate to their type of writing and follow it, as far as it does not conflict with the UEWSG.
===
3.11. Marked Emphases
Emphasis adds depth to a document. Just as speakers do not typically communicate in monotone, so too authors make use of various forms of emphases to reflect the variable “tonal” quality of their writing. Much of the emphasis will need no markup: readers naturally process text and add some emphasis on their own. Similarly, authors can use other tools like repetition to draw attention to text. But, sometimes, particularly important concepts, statements, or warnings need to be specially marked. For these cases, the UEWSG defines an arbitrary number of levels of marked emphases, though only the first 3 are given visual distinction; further levels of emphasis are styled identically to critical marked emphasis. These levels of marked emphasis can nest under the general rule of 1 set of asterisks per level of emphasis. They also stack visually, up to the 3rd level. For example, if a sentence that has been marked with standard emphasis (level 1) contains a strongly emphasized word (level 2), that word would be critically emphasized (level 1 + level 2 = level 3) and displayed identically to any other critically emphasized content. Marked emphases will also stack visually inside description list markers, which are strongly emphasized (level 2) by default.
---
3.11.1. Standard Marked Emphases
Standard marked emphases are the most basic degree of emphases, providing a reader a clue that the marked content has some additional value; in terms of importance, they are the 1st level of emphasis and are roughly equivalent to a single repetition, though they do not nest or otherwise interact with repetition visually or syntactically. Standard marked emphases are denoted by enclosing text within a single opening and closing asterisk (“*”), with no spacing on the inner sides of the asterisks.
**Rich media module**: Standardly emphasized text, including the opening and closing asterisks, must be displayed in italics.
**HTML module**: Standardly emphasized text, including the opening and closing asterisks, must be wrapped in “““””” tags.
---
3.11.2. Strong Marked Emphases
///
While writing in “““ALL CAPS””” is sometimes used to denote emphasis, it has no such semantic meaning in the UEWSG.
\\\
Strong marked emphases are more urgent than standard emphases, conveying a level emphasis that is ideal for very important points or phrases; in terms of importance, they define the 2nd level of emphasis and are roughly equivalent to double repetition (eg, “Lord, have mercy. Lord, have mercy. Lord, have mercy.”), though again they do not nest or otherwise interact with repeated words or phrases. Strongly emphasized text is marked by being enclosed within 2 opening and closing asterisks (“**”), also with no spacing on the inner sides of the asterisks; these asterisks may be used together to immediately begin a segment of strong marked emphasis or may be used separately to begin a portion of strong marked emphasis *within* text that already carries standard marked emphasis, following the general rule of 1 set of asterisks per level of emphasis.
**Rich media module**: Strongly emphasized text, including the opening and closing asterisks for the *2nd* level of nesting, must be displayed in bold but *not* in italics.
///
The “““””” tag has changed in meaning between various versions of HTML and should not be used; both its semantic meaning and its utility are dubious.
\\\
**HTML module**: Strongly emphasized text, including the opening and closing asterisks, must be wrapped in **2** sets of “““””” tags, each set individually surrounding their associated sets of asterisks. Only when these asterisks are separated (ie, if one level of emphasis is nested within a part of another) should the tags also be separated.
---
3.11.3. Critical Marked Emphases
Critical marked emphases are the most powerful emphases specially defined and are reserved for serious warnings or vital content that absolutely cannot be missed. They constitute the 3rd level of emphasis and text emphasized in this way probably should not be further emphasized (ie, emphasis can begin to lose meaning if it is overused, either in quantity or quality), though the Uniform English Writing Style Guide imposes no hard limit. Critically emphasized text is essentially a combination of strong and standard emphasized text, so it is marked by being enclosed within 3 opening and closing asterisks (“***”), again with no spacing on the inner sides of the asterisks; these asterisks may be used together to immediately begin a segment of critical marked emphasis or may be used separately to begin a portion of critical marked emphasis *within* text that already carries standard or strong marked emphasis, following the general rule of 1 set of asterisks per level of emphasis.
**Rich media module**: Critically emphasized text, including the opening and closing asterisks for the *3rd* level of nesting, must be displayed in both bold *and* italics.
**HTML module**: Critically emphasized text, including the opening and closing asterisks, must be wrapped in **3** sets of “““””” tags, each set individually surrounding their associated sets of asterisks. Only when these asterisks are separated (ie, if one level of emphasis is nested within a part of another) should the tags also be separated.
===
3.12. Keyboard Keys
When referencing keyboard keys, the name of the key must be written in title case, just as it appears on the keyboard (eg, “Shift”). Combinations of keys must be separated by plus characters, with spaces (like “Ctrl + Alt”). Styling is needed to fully distinguish them from surrounding content:
**Rich media module**: Keyboard keys (but not any separators) must be displayed in the first available font from the “Monospaced Fonts” stack.
**HTML module**: Keyboard keys (but not any separators) must be wrapped in “““””” tags.
===
3.13. Censored Text
While the process of censoring itself is outside the scope of the UEWSG, there are some guidelines for handling censored text. In encrypted fields (like passwords) or where the text is clearly isolated from other constructs, characters should be replaced with bullets (“•”) or, for even more security, be left completely invisible. For in-text censoring, where individual words or phrases are merely obfuscated, characters should be replaced with the sequence “!@#$%”, repeated as many times as is necessary to censor every character; any string that begins with the sequence “!@” is considered to be censored text, for the purposes of mechanical parsing. For fake censoring (such as for the sake of irony), the most media-independent option is epanorthosis (eg, “…the whole world, no, the entire galaxy!”). For the semi-anonymization of names, all but the first letter should be omitted to form an initialism; a trailing em dash may be added for further clarity (“Captain A” and “Captain A—” are both acceptable). Text that is missing or lost should be denoted by ellipses (eg, “A g…d plan today…better t…perfect plan…morrow.”).
===
3.14. Directions
Directions to a speaker reading a dialog (eg, directions in a prayer book or stage directions in a play) must be written inside parentheses like other parenthetical information but should also be further styled:
**Rich media module**: Directions must be displayed in italics (eg, “Lord, have mercy! (Thrice)”).
**HTML module**: Directions must be wrapped in “““””” tags.
===
3.15. Links
In digital media (especially HTML), links are the most common type of interactive content and, perhaps more than any other construct, define the World Wide Web. However, since they have no built-in fallback mechanism, hyperlinks—especially those that point to another page and moreso to another website—should be constructed from only the URL of the page they point to; in case the hyperlink itself somehow fails, this will still allow the content to be located. Textual hyperlinks are styled clearly and simply, in the traditional way:
**Rich media module**: Unvisited links must be colored “blue” (a default of #0000EE), active links must be colored “red” (a default of #EE0000), and visited links must be colored “purple” (a default of #551A8B); these colors follow both internet tradition (using the default colors given in both the HTML5 Phrasing Content spec and most HTML5-compatible browsers) and keep a balance between a contrast which is too high and too low. Links must also have a solid underline of the same color as their type, also in keeping with near-universal custom.
**HTML module**: Links must be wrapped in “““””” tags and given working URLs, meaningful titles, and other properties, as needed.
===
3.16. Other Interactive Text
Links are not the only form of interactive text and users need to be able to recognize these other forms of interaction. Authors must give all purely text-based interactive content extra styling (this excludes buttons, images, etc):
///
The rich media styling in the UEWSG, particularly with regards to concepts like margin, border, and padding, has the CSS box model in mind, even for non-HTML documents (see https://developer.mozilla.org/en-US/docs/Web/CSS/box_model).
\\\
**Rich media module**: Other interactive text must have a 0.0625 (1/16) em dotted bottom border.
**HTML module**: Other interactive text must be wrapped in the proper tags (ie, “““””” tags for abbreviations, etc) and given meaningful titles and other properties, as needed. Interactive text that isn’t part of a normally-interactive element may be given the property “class="interactive"” and, if required, wrapped in a “““””” with this class.
+++
4. Block Constructs
While it is important to rightly utilize constructs inline, it is just as important to properly organize a document at a higher level. The larger-scale constructs that perform this task are called block constructs and, as the name suggests, are always displayed in “block” format: they are separated from other block constructs by a blank line. This means that all block constructs must be followed by a double line break (ie, a blank line) unless they occur at the end of a container; the last construct in a document (which is itself a container of sorts) must be followed by no line breaks of any kind. (Nearly every other situation—such as a title or paragraph following a block opening marker—occurs *within* a block construct and thus is subject to the normal line-breaking rules in “2.1.2. Line Breaks”.) Spacing must also be correctly handled: blocks must not have any leading or trailing spaces on their opening and closing lines, respectively, any spacing between the characters that constitute their markers, or any spacing in between the marker and the content—unless the marker includes a space character. Block formatting may seem strange to those who have not done much formal writing or design, but it is the best—and probably least intrusive—way to preserve the readability of a work.
**Paged media module**: Page breaks must not occur between division markers and headings (subject to a few clearly-noted exceptions), immediately after division headings, immediately after opening markers, or immediately before closing markers.
**HTML module**: All block construct markers that need to be targeted for type-wide styling in the Uniform English Writing Style Guide must be wrapped in a “““””” tag with the class set the the singular, snake case, UEWSG name of the marker—the division headings for constructs in this specification constitute their canonical names, unless otherwise noted. For example, chapter markers must be wrapped in “““””” tags and note division markers in “““””” tags. Markers must not be part of any other block construct within the containing construct (eg, a paragraph in a blockquote would begin *after* the blockquote’s opening marker; the marker would *not* be part of the paragraph). All division markers and breaks must be given the additional properties “display: block” and “clear: both”, to prevent floating elements (viz, asides) from spilling over from other divisions and/or stacking horizontally. And, of course, “““ ””” tags *must* follow most block constructs (except the last block construct in a containing construct) in order to create a double line break.
===
4.1. Divisions And Headings
Divisions are the main structural constructs of documents. Along with their corresponding headings, they provide the general framework for communicating a clear, logical message to readers. A well-designed structure can serve to further an author’s points, while a poor layout can sink any chance they have to effectively argue their thesis. Therefore, it is crucial to thoroughly grasp the syntax and functioning of divisions and headers in the Uniform English Writing Style Guide to create readable, functional works.
Authors should clearly and hierarchically structure their works; numbered divisions (ie, headings that are also inline numbered list items, as used in the UEWSG spec itself) are encouraged, but not required. When subdividing content, the next-highest-level division must be used; for example, it is not permitted to jump directly from a chapter [level 2] to a subsection [level 4]. Division markers and headings are always displayed in block format as a unit, so the division marker and headings themselves are contiguous: they are on separate lines, but are not separated by an intervening blank line. Anything that is contiguous with the marker will be treated as the heading. Conversely, if no heading is desired for a division, it may be escaped: a blank line may be inserted directly after the division marker, preventing a division heading from displaying. A document must not end with a visible division marker of any kind.
Division markers themselves are generally composed of 1 character repeated 3 times. Division markers must not have any spaces whatsoever. Headings may contain just about anything, but must not contain block markers without closing markers (eg, further division markers); all other constructs are allowed, as long as the heading block remains contiguous with the division marker: multi-line headings, headings containing quotations, and all sorts of other creations are permitted (subtitles are usually provided via adjectival paragraphs). All headings must be written in title case, except for portions that are in some form of quotation.
---
4.1.1. Main Titles
The document is the highest structural level in normal writing, so documents can be considered level 1 “divisions”. The first line (or series of contiguous lines) of any document is its main title, a level 1 heading, by default; the filename of a document should match this heading (ideally in strict snake case, see “2.3. Filenames”). Titles should be as concise and descriptive as reasonably possible (the recommended limit on full URLs or paths is 255 characters); if needed, a subtitle can be used to convey extra information that would unnecessarily lengthen the title and thus the filename. If a document title is escaped from the usual location [by leaving a blank line at the beginning of a document], it must be placed elsewhere using the main title marker, 3 hashes (“###”), because all distinct documents *must* have a main title; the main title marker must only be used in this special case. The main title marker does not have any structural function—but does center any adjectival paragraphs below it (eg, subtitles)—and doesn’t override the current division in any way.
///
If using the base font size of 12 pt, main titles will be displayed at 24 pt with a line height of 30 pt.
\\\
**Rich media module**: Main titles must be centered, displayed in bold at 2 em (ie, 2 × base font size), and have a correspondingly-increased line height of 2.5 em (ie, 2 × base line height). A main title marker, if present, must also be centered.
**HTML module**: Main titles must be wrapped in “““