1.2. Formatting Your Text

The documentation in this project is formatted using AsciiDoc, which is a fairly generic markdown-style syntax. The AsciiDoc user guide explains the markup syntax in detail, and a more concise but less complete AsciiDoc Cheat Sheet is also available.

The remainder of this topic goes over some conventions that are specific to this project, and related to formatting.

* A single-line bullet item.

* A multiple-line bullet item. A multiple-line bullet item. A multiple-line
bullet item. A multiple-line bullet item. A multiple-line bullet item.

. A multiple-line numbered list item. A multiple-line numbered list item. A
multiple-line numbered list item. A multiple-line numbered list item. A
multiple-line numbered list item.
+
A second paragraph within the numbered list item.

AsciiDoc supports several syntax styles for indicating chapters and sections (not all of which are covered in all AsciiDoc manuals). This project uses the following syntax, with required identifiers on each chapter and topic:

= Overall Book Title

[[first_chapter_id]]
== Chapter Title One

[[first_topic_id]]
=== Topic One

[[first_section_id]]
==== Section title 1

[[first_subsection_id]]
===== Sub section title 1

For readability of the source, leave two blank lines before the start of each chapter, topic, and section of any depth. In this project, the main book title and chapters are created in an outline file that most contributors should not edit. Each topic within the chapter is in a separate include file, with an include statement in the outline file, and most contributors will be editing these files.

Chapter and topic titles should use "Title Case". Titles for any sections at levels below topics should use "Sentence case".

Once you have a chapter or topic defined with an identifier, you can make a cross-link by putting, for example:

 <<first_section_id>>

into your text. This will be formatted with the title of the section or chapter, and (depending on the output format) a link and/or page number. You can also change the link text by doing this:

Within a paragraph, you can <<first_section_id,change the link text>>
like this.

However, a preferable writing style is:

Within a paragraph, you can change the link text. See <<first_section_id>> for
details.

Glossary entries go into a separate glossary file. Keep them in alphabetical order and follow the format of existing items in that file. Example:

[[glossary-cms]] Content Management System (CMS)::
    A collection of tools designed to allow the creation, modification,
    organization, search, retrieval and removal of information on a web site.
    See <<intro-drupal>>.

This entry starts with the ID glossary-cms, followed by the glossary entry name and a double-colon. The definition starts on the next line, and is indented 4 spaces. It also includes a link to a topic that has more information — glossary entries should only be a couple of lines long.

To cross-link to a glossary item in text, use syntax like this:

<<glossary-cms,glossary entry for "CMS">>

Each topic should have at least one entry in the index. To define an index entry, put this just before the paragraph text related to the entry:

(((Block,creating)))

Note that there is no space after the comma. If the main entry text or sub-entry text needs to have a comma in it, you can enclose it in quotes. Example:

(((Block,"Creating, or whatever")))

See also: Section 2.4.4, “Composing index entries”

Here’s the syntax to include an image:

. Text of the step immediately before the image.
--
// Comment explaining how to regenerate the image, for future contributors.
image:images/filename.png["alt text goes here",width="100%"]
--

Notes and conventions:

The syntax for embedded videos is similar:

video::https://www.youtube.com/embed/HymQsDOcT3E[title="Name of video"]

Notes and guidelines:

File names and directories in text should be formatted in italics, as well as new terms that are introduced. Also, text that appears in the user interface should be formatted in italics. Use underscores to format text in italics:

_sites/default.settings.php_
_view_ (in the context of the Views module)
Click _Apply_

Programming details (functions, variables, etc.) and operating system commands embedded in text should be formatted in monospace. Use backticks to format text in monospace:

`my_function_name()`
`$foo`

Boldface should be used sparingly. Use asterix characters to format text in bold:

*A really important fact to note*

Blocks of code should go into a literal block. To make a literal block, leave a blank line, then a line containing just ----. Then put in your lines of code, and afterwards, another ---- line.

You can prefix this with an indication of what type of code is in the block, such as [source,php] for PHP. Other recognized code types include css, javascript, sql, html, etc. For generic source code, such as commands to type at an operating system prompt, you can omit the [source,php] line.

You can put comments into your AsciiDoc using double slashes, like PHP:

// This is a comment that is only relevant to someone reading
// the AsciiDoc source. It will not be displayed in the output.

If you write a topic, and you want to submit your work in an incomplete state (such as because you could not find needed information, ran out of time, or need to refer to other topics that do not yet exist), put text like this into your file:

@todo Explain what still needs to be done here.

Attributions

Written/edited by Jennifer Hodgdon, Joe Shindelar, and Boris Doesborg.