Help:Formatting essentials

This article demonstrates basic ways of formatting text.

Links

Links to other pages can be made by surrounding the page name with the {{Link}} template:

{{Link|<Page name>}}

To have a label that is different to the page name, the second argument can be adjusted:

{{Link|<Page name>|<label>}}

To make an external link, the address can simply be surrounded in single square brackets:

[https://example.com/...]

Important
Always use the HTTPS protocol rather than HTTP, whenever possible.

To have an external link with a label, provide a label after the URI, separated by a "space" character:

[https://example.com/... <label>]

Note
The "double square bracket" [[Link]] syntax should be avoided, as it does not work well with the translation extension.

See also
The help page on links.

Linking

Use HTTPS when possible

Gentoo infrastructure, as well as the majority of the web, long ago transitioned to HTTPS. Whenever possible use HTTPS for external links instead of HTTP. The developers behind Gentoo would like to facilitate safety and security wherever possible, documentation is no exception!

Avoid oversaturation

Article contributors should only link once to other articles or resources (or, in large articles, once per main section). Review Wikipedia's Repeated links section in the Manual of Style for more information.

Avoid linking in critical sections

In order to limit visual distraction, contributors should avoid linking in the small sections of text that that are critical to a document's visual structure such as section headers, page titles, templates, or template parameters (such as the title parameter of the {{FileBox}}, {{CodeBox}}, and {{KernelBox}} templates). Contributors who see links in these areas should remove them as necessary.

This linking guideline does not apply to template parameters that are intentionally supposed to be links such as {{InfoBox}}, etc.

Avoid URL shortening

Please do not use URL shortened links on the wiki. They are avoided for two reasons:

1. Users have no indication what the link destination is. It could be an inappropriate site or some other place they do not want to visit.
2. The link could be used for tracking purposes. This should not be happening unless the user makes the decision to actually travel to a destination server (so there should be no third party intercepting the request).

Avoid temporary file hosting sites

Linking to temporary file hosting sites such as pastebin, bpaste, or any other platform that removes links after a certain period of time should be avoided. Services such as GitLab's Snippets or GitHub's Gists are more favorable and can be conservatively used to link to larger amounts of text data (greater than 80 lines). This can be useful when sharing certain configuration files or scripts.

An exception to this guideline is granted for user namespace areas (User:) on the wiki.

General inline formatting

Input	Rendered output	Use case	Example within text
''italics''	italics	To emphasize something.	It is not possible to change the order of the configuration items.
'''bold'''	bold	To strongly emphasize something, when it is very important for the reader to notice it.	Using the hyphen is absolutely necessary as otherwise the system will fail to boot.
<var>foo</var>	foo	Used for in-paragraph variable names (such as USE, FEATURES, or CFLAGS).	Set the USE variable to alsa if audio support is desired.
<code>foo</code>	foo	Used for: In-paragraph variable values (such as -alsa, referring to a value to set in the USE variable). Small chunks of code that are displayed in-line. Arguments or options to a command (in explanatory paragraphs - if it is used for the user to actually type in, use {{C|...}}</kbd>).	Now set the USE variable to -alsa to disable ALSA support.
{{c|wheel}}	wheel	Denotes a command or technical concept. Used with: Items that have a specific meaning (a wheel is something on a car, while wheel is the Linux group whose members are allowed to execute su). Commands (such as less) that are either not to be invoked directly in the context of the paragraph, or which are shown in an example following the current paragraph. Note that this formatting behavior is implemented via the {{c}} template.	The root user is part of the wheel group (which can be updated through the gpasswd command).
{{Key|Alt}}+{{Key|F1}}	Alt+F1	Key combination that the user needs to type in, most of the time in reaction to a prompt or as a special key combination in an application environment. This is implemented by the {{Key}} template.	Switch back to the first terminal using Alt+F1.
{{Keyword|~arch}}	~arch	Use this template when referencing architecture keywords. See {{Keyword}} for more information.	Packages that are still in testing can be installed by adding ~amd64 to the end of each package atom in the /etc/portage/package.accept_keywords file.
{{Path|/path/to/file}}	/path/to/file	link=y can be added to link to a page with the same name as the path. See {{Path}} for other ways to use this template.	Next, edit /etc/hosts to add the newly created hostname.
{{Package|category/package}}	category/package	Provides an inline link to package information at https://packages.gentoo.org (see the {{Package}} template for more information). Note that this is not the same as {{InfoBox package}}, which adds the link in an InfoBox.	Puppet is provided by the app-admin/puppet package.
<nowiki>''no markup''</nowiki>	no ''markup''	Prevents some text from being interpreted as wiki markup.	In Vim, text can be surrounded with {{{ and }}} in order to create a fold.

Note that the use of the {{c}} template for commands is to ensure that commands are not mistaken for parts of the English sentence itself. Linux (and Unix in general) often borrows English words for commands (think about less, more, and so on).

Use ISO 8601 for date and time representation

Wherever possible, use ISO 8601 for date and time representation across the wiki. The ISO 8601 date format is structured as "YYYY-MM-DD", where "YYYY" is the year, "MM" is the month, and "DD" is the day.

A typical area the YYYY-MM-DD format should be used is the date parameter in the {{Talk}} template. For example, use the following format when closing an open discussion:

{{Talk|closed|date=2022-01-19}}

This will display a cartouche including the properly formatted date to indicate that the discussion is closed (and will remove the discussion from the global list of open discussions on the wiki).

Writing references

Whenever an article takes information from an external resource as "fact" or as source information, a <ref> tag should be used to cite that resource. The References section is meant solely for these in-article references, and constitutes a sort of simple bibliography. Once the appropriate <ref> tags are in place, these sections are automatically generated - just add the header and the {{reflist}} template to the end of the page, before any categories:

== References ==
 
{{reflist}}

There is a subtle difference between an external resource and a reference:

• An external resource is a location where the user can find more information about the subject which goes beyond a single claim used within the article.
• A reference is a location where the user can find more information (or proof) about a particular claim or statement made within the article.

When adding a reference, provide the following information in the given order (as far as that information is known):

1. Author of the source;
2. Title of the source (as a hyperlink);
3. Main origin of the source, such as the main site (as a hyperlink);
4. Date of publication; and
5. Date of retrieval of this information.

For example:

"Users should replace -march=native with the various compiler flags that GCC finds for the native system by using gcc -march=native -x -c - and use those flags in their CFLAGS and CXXFLAGS variables."

Unicode characters

Unicode characters which are not available on the keyboard can be entered indirectly by copy'n paste or, if one knows the unicode numbers, be written as numeric character references. As an example, the unicode character ✔ which has unicode number U+2714 can be written as ✔, being rendered as ✔.

HTML symbols

An HTML symbol entity is a sequence of characters that produces one particular character. For example, → produces a right arrow "→" and — produces an em dash "—". HTML symbol entities are allowed in MediaWiki and are sometimes used in advanced editing for two main reasons: to insert characters not normally available on keyboards:

&copy; → ©

&delta; → δ

and to prevent the parser from interpreting and displaying HTML tags and symbols:

&amp;euro; → &euro;

&euro; → €

&lt;span style="color:green;">Green&lt;/span> → <span style="color:green;">Green</span>

<span style="color:green;">Green</span> → Green

The following is a list of characters (including spaces, denoted with a dotted border:  ) that can be produced using HTML symbols. "Hover" over any character to see the HTML entity that produces it (see also the official list). Some symbols not available in the current font will appear as empty squares that produce nothing when hovered over. (If many of these appear in the table below, check out our recommendations on choosing good fonts).

HTML Symbol Entities
Á	á	Â	â	´	Æ	æ	À	à	ℵ	Α	α	&	∧	∠	Å	å	≈	Ã	ã	Ä	ä	„	Β	β	¦	•	∩	Ç	ç	¸	¢
Χ	χ	ˆ	♣	≅	©	↵	∪	¤	†	‡	↓	⇓	°	Δ	δ	♦	÷	É	é	Ê	ê	È	è	∅			Ε	ε	≡	Η	η
Ð	ð	Ë	ë	€	∃	ƒ	∀	½	¼	¾	⁄	Γ	γ	≥	>	↔	⇔	♥	…	Í	í	Î	î	¡	Ì	ì	ℑ	∞	∫	Ι	ι
¿	∈	Ï	ï	Κ	κ	Λ	λ	〈	«	←	⇐	⌈	“	≤	⌊	∗	◊	‎	‹	‘	<	¯	—	µ	·	−	Μ	μ	∇		–
≠	∋	¬	∉	⊄	Ñ	ñ	Ν	ν	Ó	ó	Ô	ô	Œ	œ	Ò	ò	‾	Ω	ω	Ο	ο	⊕	∨	ª	º	Ø	ø	Õ	õ	⊗	Ö
ö	¶	∂	‰	⊥	Φ	φ	Π	π	ϖ	±	£	′	″	∏	∝	Ψ	ψ	"	√	〉	»	→	⇒	⌉	”	ℜ	®	⌋	Ρ	ρ	‏
›	’	‚	Š	š	⋅	§	­	Σ	σ	ς	∼	♠	⊂	⊆	∑	⊃	¹	²	³	⊇	ß	Τ	τ	∴	Θ	θ	ϑ		Þ	þ	˜
×	™	Ú	ú	↑	⇑	Û	û	Ù	ù	¨	ϒ	Υ	υ	Ü	ü	℘	Ξ	ξ	Ý	ý	¥	ÿ	Ÿ	Ζ	ζ	‍	‌	(empty)