- Bias-free Language
- Syntax Terminology and Rules
- Title, Author, and Article Metadata
- Text
- Abstract
- Section Titles
- Terms and Definitions
- Source Code and Program Output
- Admonitions
- Sidebar
- Quotes, Prose Excerpts, and Verses
- The Image Macro
- URLs and Cross References
- User Interface Styles
- Mathematical and Chemical Formulas
- Tables
- Footnotes
- Resources
- Bibliography
This guide describes NFJS, the Magazine’s preferred tone, structure, and grammar styles. When applicable, it provides examples of the corresponding AsciiDoc syntax.
Please avoid language, images or code examples that allude to beliefs or stereotypes regarding race, ethnicity, gender, sexual orientation, disability, or religion. Also, please use gender neutral language instead of he, she, or s/he.
- Omit the pronoun
-
Instead of
the programmer should fetch the upstream repository before the data is allocated to her by the analytics team,'' writethe programmer should fetch the upstream repository before the data is allocated by the analytics team''. - Repeat the noun
-
Instead of
a programmer should not antagonize users because his karma will suffer,'' writea programmer should not antagonize users, because the programmer’s karma will suffer''. - Use a plural antecedent
-
Instead of
a programmer must test himself with algorithm puzzles every day,'' writeprogrammers must test themselves with algorithm puzzles every day''.
- Header
-
The first line and immediately consecutive lines in an AsciiDoc document. The header contains the article title, author name, document metadata, and document attributes. The header can not contain any blank lines but can contain line comments. The header must be separated from the first content element of the article by a single black line. In the case of NFJS, the Magazine, the first content element is the abstract.
- Element
-
A component of an AsciiDoc document. Examples: section, ordered list, inline URL.
- Block Element
-
A component that is separated from adjacent elements by a blank line. Examples: paragraph, image macro, table.
- Inline Element
-
A component that is nested within the contents of a block element. Examples: bold text formatting, attribute reference.
- Attribute
-
A key/value pair that activates and defines a property of an element. Attributes can be set on a whole AsciiDoc document or on individual block and inline elements.
- Key
-
An attribute’s name. The key toggles on or sets the attribute. Most attributes, such as style, are automatically set when the document is parsed. Attributes can be toggled off when the key is preceded by a bang (!).
- Value
-
The data, data type, or operation assigned to an attribute. Some values are implicit.
- Document Attribute
-
A key/value pair set in the header. The attribute’s key is immediately preceded and followed by a colon. The optional value is separated from the second colon by a single space. Example:
:key: value - Attribute List
-
A comma separated list of attributes enclosed in a set of square brackets (
[]). Attribute lists are set on a single instance of an element and take precedence over document attributes. Attribute lists contain positional and named attributes. Example:[positional-attribute-value,key=value] - Positional Attribute
-
A key/value pair that is implicitly set when a value is assigned to a position, typically the first or second comma separated location, in an attribute list. The style attribute in an example of a positional attribute.
- Named Attribute
-
A key/value pair in an attribute list. The attribute’s key is immediately followed by an equals sign and a value. Example:
[key=value] - Delimited Block
-
An element where a set of attributes are implicitly set when the parser encounters a line of two or four continuous symbols and unset when it encounters a second line of the same four symbols. The line of symbols is called a delimiter.
The main title, subtitle, author information, metadata, and other document attributes are all part of the header.
The main title and subtitle should be direct and brief. A subtitle is optional. Capitalize the main title and subtitle headline style.
When an article is part of a series, the main title should remain the same throughout the series and be followed by a part number. Additionally, if you use a subtitle in the first article of a series, all of the articles in the series must have a subtitle. The subtitle should reflect the primary focus of that part.
On separate lines beneath the author information, include values for the running head text (slug), table of contents teaser summary (description), and keywords attributes.
= iOS Development in Ruby with RubyMotion, Part 3: Backend as a Service (1) (2) (3)
Brian Sam-Bodden <[email protected]> (4) (5)
:css-signature: rubymotion-3
:slug: mobileDev (6)
:description: In this part of the RubyMotion series, learn how to connect a simple iOS application to a Parse backend in order to provide a server-side component to a mobile offering. (7)
:keywords: Ruby, iOS, Parse, mobile (8)
:codedir: code
:imagesdir: images
:hide-uri-scheme:-
The main title is preceded by one equal sign and followed by a single space.
-
The part number follows the main title. Use a comma to separate the part number from the main title.
-
A subtitle is entered on the same line as the main title. Text entered after a colon is considered the subtitle. If you want to use a colon in your title without making it a subtitle, precede the colon with a backslash.
-
Your name is entered on the line directly below the title.
-
Your email is separated from your name by one space and bound in a set of angled brackets.
-
The slug is one word or two words that are joined in camel-case style. Use the same slug for all of the articles in a series.
-
A description can not be more than two sentences.
-
Choose two to four words or phrases to describe your article.
= It's the End of the Cloud as We Know It
Andy Piper <[email protected]>; Matt Stine <[email protected]> (1)-
Multiple author names and emails are listed on the same line and separated by a semicolon followed by one space.
To begin a new paragraph, separate it by one blank line from the element above it. Do not indent the first line of a paragraph.
As of May 2014, a number of EPUB and K8 text-to-voice readers don’t speak with respect to punctuation. However, when each sentence is entered on its own line in an ADOC file, this accessibility error is corrected. And don’t worry, single line breaks between sentences are not significant in AsciiDoc so your content won’t render with each sentence on its own line.
Sentence per line formatting also has numerous benefits for the author and editor.
-
Comments can be directed at a sentence
-
Line comments can be added between sentences
-
-
Sentences can easily be reordered
-
Changes in diffs are more apparent
-
Revisions do not cause unnecessary “reflow” of the text
-
Sentences can be compared in isolation
-
-
Encourages good sentence structure and rhythm
-
Long sentences are easier to detect
-
Word and sentence structure repetition is easier to spot
-
-
Avoids common problems with parsing AsciiDoc content (limits scope of pattern matching)
-
Counteracts writer’s block (try it and you’ll likely agree)
Sentence per line should be natural for developers since it uses the same line-oriented approach developers use when writing code.
Also, don’t hard wrap your article. Hard wrap causes reflow hell during the editing process and disguises long or run-on sentences. Instead, get cozy with soft wrap.
Notice that +ContactController+ is annotated with +@ConfigurationProperties(name="app")+.
This is a special annotation that tells Spring Boot to automatically inject any properties on +ContactController+ using values configured external to the application.Notice that ContactController is annotated with @ConfigurationProperties(name="app"). This is a special annotation that tells Spring Boot to automatically inject any properties on ContactController using values configured external to the application.
Not sure what speaking with respect to punctuation means? Hear it for yourself. Load an O’Reilly book into the Kindle App, and have it read. Notice how the voice seems to pause at random places, making it hard to comprehend phrases or sentences. Then load the April 2014 issue of NFJS, the Magazine, and have it read. Now you can hear when one sentence ends and another begins.
Within the normal content of your article, please use curved quotation marks (also known as smart quotes).
`single curved quotes' (1) ``double curved quotes'' (2)
-
One leading backtick ({backtick}) and one trailing single quote ({apos}) around a word or phrase encloses it in single curved quotes.
-
Two leading backticks ({backtick}{backtick}) and two trailing single quotes ({apos}{apos}) around a word or phrase encloses it in double curved quotes.
|
Warning
|
When single and double quotation marks are entered using the ' and " key, they will render as straight (typewriter) quotation marks. |
An abstract states the key topics and findings of the article and is the article’s first content block. You must always include an abstract. Separate the abstract from the header with a single blank line.
[abstract] (1) (2)
-- (3)
Spring Boot offers a greatly simplified development model for Spring that requires little or no configuration. (2)
This article picks up where last month's article left off, showing more Spring Boot tips and tricks.
---
Assign the abstract value to the open block using an attribute list.
-
Place the attribute list above the open block delimiter. Do not insert a blank line between the attribute list and the delimiter.
-
The boundaries of an open block are defined by lines consisting of two hyphens (--).
|
Tip
|
If the abstract is a single paragraph, you don’t need to enclose it in an open block. |
Section titles reflect the main topic or important message of a section’s content. The titles should be capitalized headline style.
-
Capitalize the first letter of the first and last words of the title.
-
Capitalize the first letter of all the other nouns, pronouns, verbs, adjectives, and adverbs.
-
Lowercase prepositions (about, as, for, versus, etc.,) except when used adverbially or adjectivally (Sign Up, Log In).
-
Lowercase articles (a, an, the).
-
Lowercase conjunctions (and, but, for, or, nor)
-
Lowercase proper nouns that are lowercased in the text (@object, motion-cocoapods).
|
Warning
|
Do not use the setext markup style for headings. |
The first time you present and define a concept that is vital to your article or that your readers may not be familiar with, annotate it with [.term] and enclose the word or phrase with italic marks ({underscore}).
In Java 8, [.term]_lambda expressions_ are anonymous functions that can stand in where instances of single abstract method interfaces are expected.If you’re defining multiple concepts in a row, use a labeled list (also known as a definition list). You don’t need to apply the term role or italic formatting to terms in a definition list.
Fixed-width (monospace) formatting is used to emulate the look of source code in consoles, text editors, and integrated development environments (IDEs). Enclose inline code in a set of plus signs ({plus}) or backticks ({backtick}) when you want it rendered using the monospace style. Don’t mark up program, library, class, and gem names (e.g., Collections class, the Asciidoctor gem) or when referring to a term in a generic sense.
Next we define our +ColorPoint+ type as a +struct+.To insert several, continuous lines of source code into your article, follow these steps:
-
Write the code in a separate file and save it in your repository’s /code directory.
WarningBreaking SyntaxDon’t indent the source code or console output in your code files using the tab key. Tabs are criminal.
-
In your article, create a delimited listing block where you want the code to be displayed.
-
Insert an include function in the listing block and direct it to the code file’s location.
Source code block syntax.A greedy groovy coin changer (1) [source,groovy] (2) (3) ---- (4) include::{codedir}/GreedyCoinChanger.groovy[] (5) (6) -----
Listing captions are preceded with a period (.). See Section xxx for more information about writing captions.
-
If you want syntax highlighting applied to the block’s content, enter source in the first attribute list position.
-
In the second position, set the code example’s language. See Syntax Highlighting for more information.
-
Listings are delimited by a set of four hyphens.
-
The include function is followed by two colons, the code directory’s attribute reference, the code example’s file name and extension, and a closed set of square brackets.
-
To display all of the file’s content, leave the brackets empty (e.g.,
[]). To only display a portion of the code from the code file, set the tags attribute and its assigned value inside the square brackets.
-
You can also apply the literal and monospace styles to one or two lines of code without using a listing block or include file.
Let's add it to our project's Gemfile and bundle the application. (1) gem 'motion-cocoapods' (2)
-
Insert a single blank line between the previous element and the source code.
-
To implicitly use the literal style, indent the line of code by one space from the left margin.
Instead of inline comments or a paragraph, use code callouts (i.e., annotations) to explain source code examples or console output.
A callout is a number enclosed in angled brackets (e.g., <1>).
Offset it from a line of code by a single space.
You can also precede the callout by a line comment.
Directly below the second block delimiter, type the callout again, followed by a single space, and then the explanatory text that corresponds to the line of code annotated inside the block.
.Query and Local Processing
[source,java]
----
db = conn.db();
List partialAnswer = q(queryPartA, db); // <1>
List enhanced = localProcess(partialAnswer); // <2>
List finalResult = q(queryPartB, db, enhanced); // <3>
----
<1> Define the query
<2> Do some local processing
<3> Build on first query, still consistent!|
Tip
|
|
Tags are useful when you want to display specific regions of content from an include file instead of all of its content. The example below shows how you tag a region of content inside a file containing multiple code examples.
public class Routing {
// tag::methods[] // (1) (2)
public String concat(String op1, String op2) { return op1 + op2; }
public static String combine(String op1, String op2) { return op1 + op2; }
// end::methods[] // (3) (4)
public static void main(String[] args) {
List<String> names = Arrays.asList("Matt", "Brian", "Nate", "Ken");
// tag::asArgLambda[] // (5)
names.forEach(name -> System.out.println(name));
names.forEach(name -> String.valueOf(name));
// end::asArgLambda[]-
To specify the beginning of a tagged region, insert a comment line in the code.
-
Assign a unique name to the tag::[] macro. This tag is called methods.
-
Insert another comment line where you want the tagged region to end.
-
Assign the name of the region you want to end to the end::[] macro.
-
This is the start a tagged snippet named asArgLambda. This snippet is called by the include function in the next example.
[source,java]
----
include::{codedir}/Routing.java[tag=asArgLambda] (1)
----
-
In the function’s brackets, set the tag attribute and assign it the unique name of the code snippet you tagged in you code file.
The source attribute and source code language attribute are applied to listing blocks that require syntax highlighting. NFJS, the Magazine uses the Pygments library to apply highlighting. Visit the Pygments website to see the programming, template, and markup languages it supports.
|
Note
|
NFJS may switch to the Coderay or Prettify highlighter. |
If you need to set the source-highlighter attribute in your article’s header to make a preview tool work (such as the Asciidoctor Chrome plugin), put it inside the ifndef::env-editions[] conditional directive.
ifndef::env-editions[]
:source-highlighter: pygments
endif::[]If you’re rendering your article using Asciidoctor, pass the source-highlighter attribute as a command line flag.
$ asciidoctor -a source-highlighter=coderay article.adoc
|
Tip
|
If most of the code examples are the same language, you can assign the language name to the language attribute in the article’s header and them omit it in the listing block attribute lists. |
Console commands should be indented by a single space and begin with a dollar sign ($) followed by a space. Using this convention provides the semantics to allow the magazine to style them appropriately.
$ gem install asciidoctorIf you only need to display one or two lines of console output, put it on a line that begins with a hash (#) followed by a space.
$ file -b --mime-encoding article.adoc
# utf-8If you need to display several lines of console output, insert it in a literal block.
$ mvn compile (1)
.Command output (2)
.... (3)
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building asciidoctorj 1.5.0-SNAPSHOT
[INFO] ------------------------------------------------------------------------
[INFO]
[INFO] - maven-enforcer-plugin:1.0:enforce (enforce-maven) @ asciidoctorj
[INFO]
[INFO] - gem-maven-plugin:1.0.0-rc4:initialize (default) @ asciidoctorj
[INFO]
[INFO] - maven-resources-plugin:2.5:resources (default-resources) @ asciidoctorj
[INFO] Using 'UTF-8' encoding to copy filtered resources.
[INFO] Copying 1 resource
[INFO]
[INFO] - maven-compiler-plugin:3.1:compile (default-compile) @ asciidoctorj
[INFO] Nothing to compile - all classes are up to date
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
....-
A console command is indented by one space and marked with a dollar sign ($).
-
An optional title can be applied to the output.
-
A literal block is delimited by four periods (
….).
|
Note
|
Additional info pending |
Figures should include a caption. The caption describes the key observations or results of the figure. Captions can be an incomplete sentence, complete sentence, or several sentences. Complete sentence captions should have closing punctuation. Caption style should be consistent throughout your article, i.e. use either complete sentences or sentence fragments. If one or two captions are fragments, but the majority are complete, use closing punctuation on the fragments. If the figure requires a credit line, include it after the caption.
Precede the figure with an ID. To reference the figure in the article text, use the reference ID. Don’t precede the text reference with the block label (figure, listing, example), this will be generated with the ID. Mark the credit line with [.cite].
An admonition draws the reader’s attention to auxiliary information. It’s rendered style is determined by the assigned label (i.e., value).
There are five available labels:
-
NOTE
-
TIP
-
IMPORTANT
-
CAUTION
-
WARNING
Use a sidebar for ancillary content that doesn’t fit into the flow of the article’s narrative. A sidebar must be titled. Capitalize the title headline style. The sidebar’s contents shouldn’t be more than one or two paragraphs.
The quote and verse styles can be set on paragraphs and delimited excerpt blocks. Include complete attribution and citation information for quotations and prose excerpts.
Photographs, screenshots and graphics not created with PlantUML or Graphviz are inserted into the document with the image::[] macro.
-
The image macro must be on its own line.
-
The image must have a caption.
.Figure or image caption (1) image::image_name.jpg[] (2) (3)
-
Place the image’s caption above the macro directly after a leading dot (.).
-
Set the image:: macro and the image’s file name.
-
Optional attributes can be set inside the square brackets ([]).
|
Important
|
|
We recommend that you assign URLs to document attributes in order to keep your article text readable and to avoid parsing errors.
= iOS Development in Ruby with RubyMotion, Part 3: Backend as a Service
[...]
:imagesdir: images
:hide-uri-scheme: (1)
:parse-uri: https://parse.com (2)
:sansref-uri: http://www.rubymotion.com/developer-center/guides/project-management/#_vendoring_3rd_party_libraries
One such service, and the focus of this article, is {parse-uri}[Parse]. (3)
[...]
- Sansonetti, Laurent. _RubyMotion Project Management Guide_. {sansref-uri}. (4)
-
Set the hide-uri-scheme attribute when you need to include a URL in the text without link text and without the scheme (i.e., http://).
-
Assign the URL to an attribute.
-
Place the attribute reference directly in front of the link text. Enclose the link text in square brackets (
[]). -
When an attribute reference isn’t associated with link text, it will be replaced with the active URL value, but the scheme won’t be displayed.
In your biography, place URLs inline.
Stuart Halloway is a founder and the President of http://cognitect.com[Cognitect, Inc].A URL may not render correctly when it contains characters such as underscores (_) or carets (^).
This problem occurs because the processor misinterprets parts of the link target as valid text formatting markup.
Most lightweight markup languages have this issue because they don’t use a grammar-based parser.
Asciidoctor plans to move to a grammar-based parser in the future, but for now, it is best to assign URLs to document attributes.
Use the Asciidoctor UI macros to represent keyboard shortcuts, menu selections, and UI buttons.
- Keyboard macro
-
key - Menu selection macro
-
menu-name › menu-item - UI button macro
-
button-name
|
Important
|
You must set the experimental attribute in the document header to enable these macros. |
Use tables for tabular data only. Do not use tables for transcripts, chronologies, lists, sidebars, or any other formatting purposes. For the best user experience, table cells should not contain paragraphs of text or images.
Title your tables using headline style. Titles should be as succinct as possible and should not suggest any interpretation of the data. Important explanatory or statistical information may be included in parentheses in a title, but don’t use headline-style capitalization for such material.
[[table-id]] (1) .Title of Table (2) |=== (3) |Name of Column 1 |Name of Column 2 (4) (5) (6) |Cell in column 1, row 1 |Cell in column 2, row 1 (7) |Cell in column 1, row 2 |Cell in column 2, row 2 |===
-
Give the table a unique id if you want to directly or parenthetically cite the table to your article’s text.
-
Tables should have titles.
-
The table’s content boundaries are defined by a vertical bar and three equal signs (
|===). -
A new cell is marked by a vertical bar (
|). -
The first row of a table is rendered as a header row. Enter all of the cells of the header row on a single line. The number of cells in the first line directly following the table delimiter implicitly indicates the number of columns the table contains.
-
Rows are separated by blank lines.
-
Consecutively stack the cells of non-header rows.
|
Warning
|
UX #Fail
Tables that exceed these length and width restrictions will not display correctly on some Kindle devices. Also, large tables are difficult to view and navigate on devices with small displays. |
A compilation of links used in the article and to resources the author feels are useful - this list is not the same as the bibliography.
NFJS uses the author-date bibliography system. In this system, parenthetical citations are located in the body of the article and correspond to a reference entry in the References section. Parenthetical citations typically include the author’s last name, year of publication, and page number.
This is a sentence. (<<ref-entry-id,author-last-name year>>) (1) (2) (3) (4)-
Parenthetical citations are enclosed in a set of parentheses and a double set of angled brackets.
-
The reference entry ID is a unique identifier you create. The citation and the corresponding reference entry must share the same ID.
-
Separate the ID from the author’s last name with a comma. Do not insert a space between the comma and the author.
-
Use a single space to separate the author’s name and the publication year.
The citations are amplified in a list in the References section, located at the end of your document. The list of reference entries should appear in alphabetical order by primary author last name.
- [[[ref-entry-id]]] Last-name, first-name. publication-year. _title_. publisher. (1) (2)-
Entries that correspond to a parenthetical citation must have a reference entry ID. Enclose the ID in a triple set of square brackets.
-
Separate the ID from the reference entry by a single space.
The format of a reference list entry is dependent on its source (i.e., journal articles, books, websites, etc.,). In general, bibliographic information includes the author, date of publication, publication title, publisher, page numbers, URL, and DOI, where applicable. When no author is available, begin the bibliography with the publication title.
The following examples illustrate citations using the author-date system. Each parenthetical citation is accompanied by an example of a corresponding reference list entry.
... improvements to the support for concurrent code execution on multicore hardware in iOS and OS X. (<<appleref,Apple 2013>>) (1)
... the pros and cons of each of these options must be weighed. (<<chaconref,Chacon 2009, chap. 2>>) (2)
... transform them into a habit and eventually mastery. (<<kellerref,Keller and Papasan 2013, 113-114>>) (3)
Years ago I read the famous book by William Zinsser, On Writing Well, 25th Anniversary: The Classic Guide to Writing Nonfiction. (4)
[bibliography] (5)
== References
[bibliography]
- [[[appleref]]] Apple. 2013. _Grand Central Dispatch Reference_. Last modified December 12, 2013. {gcdref-uri}. (6) (7)
- [[[chaconref]]] Chacon, Scott. 2009. _Pro Git_. Apress. http://git-scm.com/book. (8)
- Cohn, Mike. 2010. _Succeeding with Agile: Software Development Using Scrum_. Addison-Wesley. Kindle edition. (9)
- [[[kellerref]]] Keller, Gary, and Jay Papasan. 2013. _The ONE Thing: The Surprisingly Simple Truth Behind Extraordinary Results_. Bard Press. (10)
- Zinsser, William. 2001. _On Writing Well, 25th Anniversary: The Classic Guide to Writing Nonfiction_. New York: Harper Resource.-
Parenthetical citation for a corporate reference.
-
Parenthetical citation for a chapter of an online book.
-
Parenthetical citation for a reference with two authors.
-
When a citation is part of the article’s text, a parenthetical citation and reference entry ID are not necessary.
-
The bibliography style is set on the References section title and the reference entry list.
-
A corporate-authored, online document. Italicize book titles and use headline-style capitalization.
-
Online content is subject to change, so include an access date or, if available, a date when the web page was last modified.
-
An online book.
-
A book published in multiple electronic formats.
-
A printed book by two authors. For four or more authors, list all of the authors in the reference list. In the parenthetical citation, list only the first author, followed by et al. (``and others'').
Journal article and blog post parenthetical citations use the same structure and syntax as book citations. However, their reference entries include additional information and different formatting.
- Fowler, Martin. 2005. ``CommandQuerySeparation.'' Accessed August 15. http://martinfowler.com/bliki/CommandQuerySeparation.html. (1) - Kossinets, Gueorgi, and Duncan J. Watts. 2009. ``Origins of Homophily in an Evolving Social Network.'' _American Journal of Sociology_ 115:405–50. Accessed February 28, 2010. doi:10.1086/599247. (2) - Weinstein, Joshua I. 2009. ``The Market in Plato’s Republic.'' _Classical Philology_ 104:439–58. (3)
-
Blog entries may be cited as part of the article’s text (``In Martin Fowler’s May 5, 2005 blog post…'') and omitted from the References section. If the citation isn’t part of the text, enter a parenthetical citations and reference list entry. Blog post comments should only be cited in the article’s text.
-
An article in an online journal. If the online journal article does not have a DOI number, use the web page URL where the article was accessed.
-
An article in a printed journal.
For additional reference examples, see the Chicago-Style Citation Quick Guide’s Author-Date: Sample Citations.