Help:Formatting basics
- Cover Template:Blockquote
- Cover Template:Verification
This page follows from the formatting essentials and demonstrates slightly more advanced formatting techniques that editors may add to their toolkits. This article will especially be useful to new contributors who are planning to add a new section to an article.
Adding new sections
The article body should include sections that are pertinent to the reader. For example, if an issue is frequently encountered when setting up a specific software package, then include a troubleshooting section about that issue.
Sections should be created on an as-needed basis, so new sections should not be added until there is content with which to fill them. Do not create empty sections expecting another contributor to provide the content (note that the {{Todo}} template may be used to show that required content has been identified for an article).
New sections (or even whole articles) can be drafted in userspace and moved to articles in the main namespace when finished.
Use of newlines
In the page source text, there should be an empty line above and below section headings and around any paragraph-breaking (not inline) templates. This improves readability by editors (wiki syntax) and simplifies the translation effort used by the community. Gentoo wiki editors should avoid the use of HTML's <br /> line break element, except where absolutely necessary to achieve the desired formatting results.
Keep paragraphs short; generally one to five sentences should be adequate. This makes the article easier to read and, as just mentioned, simplifies the translation effort used by the community.
Inline layout elements
Inline layout elements are rendered within the running text of a paragraph. They do not interrupt the flow of the text, unlike the block-level layout elements discussed in the next section. The wiki uses several different kinds of markup for inline text formatting, including wiki formatting, HTML tags, and wiki templates.
The following table shows the most common inline elements and their proper use cases:
| Input | Rendered output | Use case | Example within text |
|---|---|---|---|
{{Anchor|See also}}
|
Inserts one or more (up to 10) HTML anchors into a page at the specified location. This location can then be linked to using the syntax:
The {{Anchor}} template is required in section headers of base pages for pages that have been marked for translation (see the explanation below). |
This is a special paragraph describing how to use the Anchor template.. |
Block-level layout elements
These elements, all implemented using templates, are rendered on the block level. That is, they create paragraph-ending line breaks and are displayed inside of a "box". They typically involve more content, rendered with more complicated formatting than is possible using the inline elements mentioned above. The following table details the common block-level templates available on this wiki and their use cases.
Follow the linked template names to see further information about using these templates (see also Help:Templates and the complete list of all existing templates).
| Template | Use case | Example |
|---|---|---|
| {{Note}} | To show additional information that should be set off from (or maybe cannot be included in) the text or block element that precedes it. The example shown here might follow a {{RootCmd}} (explained below). | Note
Use grub2-install instead of grub-install if grub was installed with the multislot USE flag. |
| {{Tip}} | To provide a detail that is helpful to know, but not necessary to accomplish the preceding instructions. | Tip
It is wise to make regular backups using the 3-2-1 backup technique. 3) Data should exist in three places, one place being originating data and two backup copies of the data. 2) Each of the two backup copies should be on different device types. For example one copy could be on a hard drive and the other copy on a Bluray disk. 1) One copy of copies of backup data should be off site, outside of the area which a local disaster could occur. |
| {{Important}} | To emphasize an item deserving special attention: it gives a stronger signal to the reader than normal inline emphasis would give. | Important
Pay close attention to the following sections, as they provide crucial information to proper configuration of Portage. |
| {{Warning}} | To strongly emphasize something that the reader really needs to pay special attention to, as otherwise system breakage might occur. | Warning
Consider the security implications of running chmod --recursive 777 ${HOME} as it will mark every file in the user's home directory as writable by every user on the system. |
| {{Cmd}} | To display a non-administrative command with optional output. Please only use this for commands that an ordinary (non-root) user can execute. Note: If the command output is verbose (more than 5 lines) use the collapse-output=true parameter to create an 'Expand' link.
|
user $ls -ltotal 112 -rw-r--r--. 1 root root 2048 Dec 30 19:32 courier.fc -rw-r--r--. 1 root root 23 Dec 29 18:42 courier.if |
| {{RootCmd}} | To display a command running with superuser privilege (can optionally includes command output). Please only use this for commands (or in situations) that require elevated privileges. Note: If the command output is verbose (more than 5 lines) use the collapse-output=true parameter to create an 'Expand' link. This helps articles have a better flow for the reader.
|
root #umount /mnt/gentoo |
| {{Emerge}} | Provides a quick alias for installing software with superuser privileges. This template is typically utilized in the Installation sections of articles. At minimum, a package atom is expected for the unnamed parameter. | root #emerge --ask sys-apps/portage |
| {{Invocation}} and {{RootInvocation}} | Displays a user or administrative command's invocation options. These templates should only be used for command invocation; they presume output will be verbose and will create an 'Expand' link. | user $cat --helpUsage: cat [OPTION]... [FILE]...
Concatenate FILE(s) to standard output.
With no FILE, or when FILE is -, read standard input.
-A, --show-all equivalent to -vET
-b, --number-nonblank number nonempty output lines, overrides -n
-e equivalent to -vE
-E, --show-ends display $ at end of each line
-n, --number number all output lines
-s, --squeeze-blank suppress repeated empty output lines
-t equivalent to -vT
-T, --show-tabs display TAB characters as ^I
-u (ignored)
-v, --show-nonprinting use ^ and M- notation, except for LFD and TAB
--help display this help and exit
--version output version information and exit
Examples:
cat f - g Output f's contents, then standard input, then g's contents.
cat Copy standard input to standard output.
GNU coreutils online help: <http://www.gnu.org/software/coreutils/>
Full documentation at: <http://www.gnu.org/software/coreutils/cat>
or available locally via: info '(coreutils) cat invocation'
root #cat --helpUsage: cat [OPTION]... [FILE]...
Concatenate FILE(s) to standard output.
With no FILE, or when FILE is -, read standard input.
-A, --show-all equivalent to -vET
-b, --number-nonblank number nonempty output lines, overrides -n
-e equivalent to -vE
-E, --show-ends display $ at end of each line
-n, --number number all output lines
-s, --squeeze-blank suppress repeated empty output lines
-t equivalent to -vT
-T, --show-tabs display TAB characters as ^I
-u (ignored)
-v, --show-nonprinting use ^ and M- notation, except for LFD and TAB
--help display this help and exit
--version output version information and exit
Examples:
cat f - g Output f's contents, then standard input, then g's contents.
cat Copy standard input to standard output.
GNU coreutils online help: <http://www.gnu.org/software/coreutils/>
Full documentation at: <http://www.gnu.org/software/coreutils/cat>
or available locally via: info '(coreutils) cat invocation'
|
| {{KernelBox}} | To display details on kernel configuration. The content should make it obvious to users how to reach the particular configuration settings in, say, menuconfig. Do not use the short-hand CONFIG_FOOBAR notation. Note: HTML and wiki markup (including links) in this template is to be avoided. |
KERNEL Enabling evdev Device Drivers --->
Input device support --->
<*> Event interface
|
| {{FileBox}} | To display the contents (usually only partial contents) of a file. Syntax highlighting is supported for common programming languages. This example uses lang=bash. Note: HTML and wiki markup (including links) in this template is to be avoided. |
FILE /etc/portage/make.confSetup make.conf for LIRC# (Replace "devinput" with the proper driver)
LIRC_DEVICES="devinput"
USE="lirc"
|
| {{CodeBox}} | To display code (with optional syntax highlighting) that does not fall into any other category listed above. Note: HTML and wiki markup (including wiki style links) in this template is to be avoided due to how {{PreBox}} passes arguments to the underlying <syntaxhighlight> element. To highlight these markups use <syntaxhighlight> directly. |
CODE An example ebuild function src_compile() {
escons CC="$(tc-getCC)" FOO=1
}
|
Wiki markup
| Description | Type | To get |
|---|---|---|
| Headings of different levels | == Level 2 == === Level 3 === ==== Level 4 ==== ===== Level 5 ===== ====== Level 6 ====== Note
* Do not use a Level 1 heading, since it is used for the page title.
|
Level 2Level 3Level 4Level 5Level 6 |
| Horizontal rule | Text above ---- Text below |
Text above Text below |
| Bullet list |
* Start each line * with an [[wikipedia:Asterisk|asterisk]] (*). ** More asterisks gives deeper *** and deeper levels. * Line breaks<br>don't break levels. *** But jumping levels creates empty space. Any other start ends the list. |
Any other start ends the list. |
| Numbered list |
# Start each line # with a [[wikipedia:Number sign|number sign]] (#). ## More number signs gives deeper ### and deeper ### levels. # Line breaks<br>don't break levels. ### But jumping levels creates empty space. # Blank lines # end the list and start another. Any other start also ends the list. |
Any other start also ends the list. |
| Definition list | ;item 1 : definition 1 ;item 2 : definition 2-1 : definition 2-2 |
|
| Mixture of different types of list |
# one # two #* two point one #* two point two # three #; three item one #: three def one # four ## four sub 1 ### four sub 1 sub 1 ## four sub 2 |
|
| Preformatted text | Start each line with a space. Text is '''preformatted''' and ''markups'' '''''can''''' be done Note
This way of preformatting only applies to section formatting. Character formatting markups are still effective. |
Start each line with a space. Text is preformatted and markups can be done |
| Preformatted text blocks | <nowiki>Start with a space in the first column,
(before the <nowiki>).
Then block format will be
maintained.
This is good for copying in code blocks:
def function():
"""documentation string"""
if True:
print True
else:
print False</nowiki>
|
Start with a space in the first column.
(before the <nowiki>).
Then block format will be
maintained.
This is good for copying in code blocks:
def function():
"""documentation string"""
if True:
print True
else:
print False
|
While the various inline formatting templates like C, Keyword, Path, and Package may freely be used inside of the Note, Important, or Warning templates, they should never be used inside of Cmd, RootCmd, Emerge, Invocation, or any other *Box templates.
Paragraphs
MediaWiki ignores single line breaks. To start a new paragraph, leave an empty line. Force a line break within a paragraph with the HTML tag <br />.