[[formatting]]
=== Formatting Your Text

[role="summary"]
Information for contributors to the project_name on how to format text using the
AsciiDoc formatting language.

On this page:

* <<asciidoc>>
* <<formatting-paragraph>>
* <<style-sections>>
* <<style-crosslinks>>
* <<style-glossary>>
* <<style-index>>
* <<formatting-images>>
* <<style-literals>>
* <<style-code>>
* <<style-comments>>
* <<formatting-todo>>


[[asciidoc]]
==== AsciiDoc reference

The documentation in this project is formatted using
http://asciidoc.org[AsciiDoc], which is a fairly generic markdown-style
syntax. The
http://asciidoc.org/userguide.html[AsciiDoc user guide] explains the markup
syntax in detail, and a more concise but less complete
http://powerman.name/doc/asciidoc[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.


[[formatting-paragraph]]
==== Paragraph and list formatting

* A few paragraphs have "role" attributes set. For example, an attribute line
saying `[role=summary]` indicates that the following paragraph is a summary of
the topic or chapter. Summaries do not appear in the output directly, but they
still need to be copy edited and translated by looking at the source
file. *They must not go over 140 characters.* Note: do not translate the role
attribute lines themselves.

* Wrap your text in 80-character or less lines. Line breaks do not affect
the output, but for people reviewing the text source, 80-character limits
help.

* A completely blank line makes a paragraph break.

* When making lists (see also <<guideline-lists>>), format the source similar to
this:

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

* For a paragraph break within a bullet or numbered list item, use a + sign as
shown above. See the
http://asciidoc.org/userguide.html#X15[AsciiDoc documentation]
for more details.


[[style-sections]]
==== Creating chapters, topics, and sections

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


[[style-crosslinks]]
==== Making cross-links

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


[[style-glossary]]
==== Formatting glossary entries

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


[[style-index]]
==== Making index entries

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: <<composing-index-entries>>


[[formatting-images]]
==== Including images and videos

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:

* All of these lines must start at the left margin of your text file.

* The "--" lines make the image embed properly into the list item. You can
use them in bullet lists as well.

* There cannot be a space before the [ in the image line.

* Use regular plain-text ASCII quote characters in the text file, not
"curly-quote" characters.

* Always include "alt" text that describes what is in the image. The alt text
should be in quotes.

* Always include a comment before the image include statement, which
describes how to generate the image. See <<style-comments>>.

* When writing a topic as a contributor, make a rough screenshot or image, and
attach it as a File to the issue (see <<practicalities-submitting>>). Do not
worry about making it perfect in the first draft.

* Images should be PNG files.

* If an image is meant for inclusion in source file _my-filename.txt_, then the
file name should be _my-filename-short-description.png_ (replace
_short-description_ with a suffix describing what the image is. However, do not
ever use two - characters in a row in an image name.

* If you annotate an image, be sure to use an annotation color with good
contrast to both foreground and background colors. But keeping in mind that
all images will need to be regenerated when the UI changes and for each
translated language, avoid annotations if possible.

* See <<good-writing-text>> for guidelines on what images should be included.


The syntax for embedded videos is similar:

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

Notes and guidelines:

* The video line must start at the left margin of your text file.

* At this time, only YouTube videos are supported, and the URL must not have
a ? in it or any URL parameters (various parameters are added by the formatting
scripts).

* Consider using https://www.youtube-nocookie.com as the base URL instead of
https://www.youtube.com, which ensures that YouTube won't store information
about visitors to the page unless they play the video.

* See <<guideline-additional-info>> for guidelines on embedding videos.



[[style-literals]]
==== Typography formatting

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


[[style-code]]
==== Formatting code blocks

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.


[[style-comments]]
==== Adding comments to source files

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


[[formatting-todo]]
==== How to indicate a topic is incomplete

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
https://www.drupal.org/u/jhodgdon[Jennifer Hodgdon],
https://www.drupal.org/u/eojthebrave[Joe Shindelar],
and https://www.drupal.org/u/batigolix[Boris Doesborg].
