<!- Wiki Help Pages in Chinese.-> // I can't read English，so I tranlate these word by word.

贡献者指南Contributor's guide

在Wiki上贡献文章是简单的，本指南将帮助任何人通过简单编辑快速开始, 以在几分钟内开始完善文章！

补充和完善文章是开始向Gentoo项目做贡献的最简单的途径之一。不需要成为“linux专家”，做出不同的，甚至微小改善的任何人都是值得赞赏的。比如纠正一处在阅读Wiki时发现的错误。

本wiki上大多数文章都是公开可编辑的，同时也是由每位志愿撰稿的用户编写的。请帮助建设本wiki：所有纠正、补充以及有用的改变对自由软件社区带来巨大的效益。

Gentoo wiki项目让人们围绕创造最好的Linux和类Unix文章的目标，这些文章包括使用和维护Gentoo Linux操作系统各方面细节。

See also
向Gentoo项目做贡献的其他方式，可阅读贡献相关文章

Important
Please follow the code of conduct when engaging in all wiki activity. The wiki project aims to maintain a respectful, constructive environment - please be polite and considerate of other users. All wiki edits should be made in the spirit of moving the project towards the common goals. Documentation and discourse should be objective and rooted in fact. The project is consensus-based - please listen to the admins, devs, and other editors.

See also
See the help pages for comprehensive information on how to work with the wiki. The wiki Guidelines article in particular is essential reading, to learn how to properly write and lay-out articles - anyone making nontrivial changes should give it a read. If specifically looking to fix an error on the wiki, the what to do when noticing an error on the wiki page can help.

See also
For in-depth information about the project, see about the Gentoo wiki. The Gentoo wiki project page helps coordinate the effort to improve the documentation.

Please, read on, and happy editing!

Getting started

It's easy for any reader to help improve the wiki - and there is no reason to wait! Just create an account to start editing pages, all that is required is a valid email address.

Note
If having any issues creating an account, please get in touch on #gentoo-wiki (webchat) on IRC. We can even provide the answer to the "CAPTCHA" to anyone having difficulty. Please be patient on the channel, replies can take time: stay connected waiting for a response, as people may be away from keyboard or even in different time zones. If a solution cannot be found in IRC, try sending an email about any issue to wiki@gentoo.org. If not receiving the account creation confirmation email, check the "spam" folder.

Once logged in with the new account, it only takes a few clicks to make a change: click the "Edit source" (or "Edit") button at the top of a page, make changes (edits) to the text, add a brief summary of the edit, and click the "Save page" button - done!

An edit can add information, make a correction, provide a useful link, etc., and can be as simple as fixing a typo. Aim to do something which improves the contents of the wiki: try to write clearly and concisely and to add useful information - with that, it's difficult to go wrong!

Be bold - other wiki contributors can correct mistakes later, so have confidence. Dive in and make changes - the rule is that changes must make an article better than before. Starting out, minor formatting and language issues can be left to be fixed by more experienced editors: getting information into the wiki is key, layout can be adjusted later.

Start by making small edits to pages, to get a feel of how things are done. Experienced editors and admins will provide leeway to new contributors, but will eventually make corrections to edits to bring them up to the quality requirements. Follow changes by other editors to learn the right way to write and format text.

Tip
Keep in mind that when more experienced editors and administrators rework additions, this is not a criticism, simply part of the process. Think of edits to previous work as "how about this", rather than "that was wrong" ;).

Note
Remember that there is an active community at work, with some having contributed extensively over years - the reasons behind edits from experienced contributors and administrators may not always be immediately clear, but there will usually be good reason. Sometimes edits will get reverted, but don't take offense, this is part of the process. It may be just that an edit is too far-off usual practices - this doesn't necessarily mean that there is no value to a change, but the edit may need work, perhaps to follow the wiki guidelines more closely.

The wiki preserves a history of every modification, so nothing can ever be "broken" by a change: do not be afraid to make an edit. The worst thing that can happen is to have the edit undone by someone with more editing experience, but often an edit that needs work will serve as a basis for improvement by another editor.

See the next section, general editing advice, for practical information on editing articles - and by all means check out the rest of this article as well.

Tip
Ask for help or clarification through the talk pages, which is where wiki-related discussion takes place. Suggestions can be made on talk pages, though it is nearly always much more constructive to directly make changes to articles. Bringing up an issue on a talk page is still better than nothing though (be sure to describe where an issue is located, so that other contributors can easily find it).

Note
Anyone editing wiki pages, please come join us on IRC on the #gentoo-wiki (webchat) channel! This is where the editors come to chat about the wiki and what is currently happening. Questions, comments, or suggestions welcome! The channel can be quiet sometimes, but everyone will try to answer any questions the best they can!

General editing advice

Screenshot of editing this page with the source editor.

Edit wiki source just like in any modern text editor, by clicking the Edit source button (or just Edit if so configured in the preferences).

Tip
There is also a visual editor that is opened with the Edit button (when activated in the preferences), which allows articles to be modified with a "WYSIWYG" editor resembling a word processor. The source editor should provide more precise control over layout though, and is what will be covered in this guide.

Note
Certain articles contain "translation tags", that look like <--T: 15-->. Do not edit, create, or unnecessarily delete or move these tags, they should stay with the content they were assigned to. See the section on translation tags about how to deal with these tags.

Before saving a contribution, a short note describing the changes that were made should be entered in the Summary: box. Just quickly describe what was changed, and why the changes were made, e.g. "fixed typo" or "added more information about Larry the cow".

Check the "minor edit" box for small changes, that couldn't reasonably need any further modification. Add the page to the watchlist by clicking the Watch this page checkbox, to be notified of subsequent changes to the article.

It is a good idea to use the Show preview button to see what the change will look like before saving - get into the habit of eliminating mistakes by using the preview, to help avoid the need for corrections after an edit has been made.

Another option is the Show changes button which highlights the differences between the existing version and the edited version. This feature can be helpful when attempting to determine what information to include in the edit summary.

Discuss any changes that need to be coordinated with other editors, to ask for help, or to explain edits that could be misunderstood.

Important
Edits should preferably be short and change just one aspect of an article, so that glancing over the recent changes with the edit summary should give other editors a good idea of what changed and the reasoning behind the edit. It is usually preferable to make one edit per section at a time, if possible. An ideal edit often has a specific impetus to it, and makes clear in what way it makes things better. Other editors need to be able to understand why things were changed, to be able to decide if an edit should be kept or not.

Note
Some pages, such as the handbook or projects, may be protected, in which case they are not publicly editable. To get changes made to these pages, suggest the edits on the corresponding talk page.

Wiki markup primer

Content is set out in the source editor by using wiki markup, for example to add headings, links, or to make text bold or italic. There is a toolbar that can help when starting out, it can be toggled in the preferences.

This section will very succinctly present some of the most common syntax, just as a quick indicator of basic usage, to give a feel of what the markup means, and to allow some quick edits.

See also
Refer to the wiki guidelines for more information on how to best use syntax on the wiki. See the help pages for in-depth information about formatting syntax.

Headings

Add = signs around text on a line on its own to make headings. For example, == Heading 1 == to make a main title.

Add more = signs to make secondary headings: === Heading 2 ===.

Add more equals signs for smaller level headings. A "level zero" heading with just one equal sign is never used on the wiki.

Text formatting

Use two single quotes '' around text to make it italic.

Use three single quotes ''' to make text bold.

Use the {{c}} template around commands that are to be typed into the terminal:

{{c|<command>}}

Use the {{Path}} template to indicate a path, or filename:

{{Path|<path>}}

Start lines with an asterisk * to create a "bullet list".

See also
The guidelines have a section on inline layout elements providing many more elements that can be used to format content on the wiki.

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.

Writing good articles

The main resource for writing good quality articles are the Gentoo wiki guidelines. Editors making more than a few trivial edits should read and follow the guidelines. The guidelines provide precise information on what good articles should look like, laying out a standardized style, format, and structure.

Getting familiar with the wiki help pages will go a long way to help write better articles. These pages provide comprehensive reference material for contributors.

Structure articles in a clear and helpful way, and write in a neutral style. Refer to "the user", and not "you".

Stay on topic: the wiki is for documenting Gentoo, and relevant Linux and Unix(like) subjects, and topics should be organized and classified into to-the-point sections that are easy to find.

Always aim for objectivity and facts. Never use articles to promote personal opinions or agendas.

There are article blueprints to help the wiki maintain a consistent style and layout throughout, and to make creating some articles from scratch a little easier. For articles that don't have a corresponding blueprint, inspiration can be drawn from the structure of preexisting articles.

Becoming a skillful contributor means doing the research necessary to produce quality articles. A proficient contributor will look into why things work the way they do, and provide the theory along with the practice in their articles. Articles should presume that readers have little to no understanding of the software or hardware being documented. Skillful article creation takes time and effort, only practice will make perfect.

If something is known to work locally, but generalization isn't guaranteed, use the conditional mood: "users may find that they have to <do x> to <achieve y>". Of course, only add information to the wiki that will be of general interest to other uses.

For experiments, the sandbox page can be used. The User namespace may be used to begin draft articles. Please do not apply categories to articles in the User namespace - they clutter up the category listings with pages that other user's can't contribute to.

Tip
Please don't let drafts languish in the User namespace. When work is no longer ongoing, and if an article has reached sufficient content to become at least a small stub, please move the article to the main namespace so that others may work to improve it. Aim to let others contribute to articles as soon as possible.

Areas for contribution

For contributors who are beginners, or do not know where to start, the easiest thing to do is to proofread articles - and this can even be done during everyday use of the wiki.

Typos, spelling, incorrect information, dead links, formatting, and other errors can be found by simply reading through the articles. More generally, change anything that can be improved, especially things that are likely to be of use to others!

There are lists of pages marked as having specific areas in need of improvement in the Todo category.

Another easy way to start helping out is to create articles about individual software packages of particular interest, following the software article blueprints. There are 10,000+ packages in the official Gentoo repository, many of which do not have corresponding articles on the Wiki. Anyone having installed, configured, and used a package of note can document the process for others in a wiki article - see starting a new page.

A list of articles that have been requested, but do not yet exist, can be found on the requested articles page. Even a skeleton {{stub}} article, is a meaningful contribution - providing basic information, and more importantly, a basis for other editors to flesh out a subject.

Using Gentoo, it will sometimes be necessary to work out for oneself how to do certain things. If any time is spent setting up something specific, this could be a perfect candidate to add to the wiki!

The same goes when having solved a particular issue: resolutions can be of valuable help to other users, and the troubleshooting sections can be a great place to add such information. After asking for support, it is particularly useful to contribute solutions back to the wiki, to the benefit of users, and so that people providing support might avoid future requests for the same issue.

Closing discussions (see the list of open discussions), for example after replying to a user's question or integrating proposed changes to the wiki, is a great way to contribute to the Gentoo wiki! Discussions are a way of making propositions and decisions about wiki contents, so they are best resolved in a timely manner, which will keep things more focused.

See also
See common wiki tasks to help out for things that regularly need looking out for on the wiki.

Further contribution

Once familiar with editing, assisting other users, especially new users, can be particularly productive. Learning from each other will propel the wiki forward, and helping to get new contributors on board is great for the community.

Help can be provided through the talk pages, on IRC, and especially - following the "wiki way" of working - through edits: correcting, adding formatting, links, references or complimentary information to recent edits. Try to be friendly when providing assistance, and explain reasoning in edit summaries.

Following recent changes provides valuable information about what is going on on the wiki. Watch for changes to important articles, and lookout for any problematic edits.

Beware of people abusing the system, which can unfortunately occasionally happen. Spamming, or third parties trying to subvert the wiki to promote their products, should be quickly reverted. If necessary, get in touch with a wiki administrator, if conflicts cannot be resolved.

Thank others in the community (especially new contributors) for their contributions: everyone enjoys being appreciated for their work. This can be done via the Thank link, found on an article's Revision history page (click More→History, then find the Thank link next to the specific revision). Thanks on a user's talk page (be sure to leave a signature), or via the #gentoo-wiki (webchat) channel on IRC will surely also be appreciated.

Why guidelines?

The guidelines come with multiple benefits for the wiki, among which are:

The guidelines help maintain a consistent look and feel across articles, providing a cleaner and more professional presentation. Consistency helps the reader to not get distracted by needless changes in style and layout, and allows them to get comfortable with the wiki.
The guidelines allow for better cooperation, since all editors work using the same reference. They help avoid repeated purely cosmetic edits: without a clear reference, things like switching variable names from <code> to <var> and back can happen (such needless changes would send users unnecessary notifications and pollute change history, which would be distracting and make following article changes difficult).
The guidelines can help contributors get accustomed to writing for the wiki. By providing an adaptable structure around which to articulate articles, they can guide changes and provide reassurance when deciding how to organize content.
They provide a good reference from which to discuss how to best make progress both on articles and on policy.

Note that the guidelines are not meant to be fully exhaustive, as being overly-prescriptive could overwhelm new editors.

Writing style

The writing style of wiki articles covers the language aspects of the content. It aims to be clearly understandable, professional, and give a consistent style across articles.

Avoid first and second person writing

Since the wiki is a community-effort and the content pages are informational, there should be no mention of pronouns such as "I", "we", or "you". Articles should be written in third person: reported as a fact to the reader.

Third person and passive voice are preferred^[1]; we argue these sound more professional and objective; especially for technical instructions, which is the majority of the wiki's content.

The user can be addressed as "you" where appropriate (which is called "second person writing"), but contributors are discouraged from writing in this manner. For instance, do not use "You should now install the package" instead use "Next, install the package". Similarly, "You can opt to only install the client software" can be rephrased as "It is possible to only install the client software".

Another commonly found example across the wiki is the possessive second person pronoun "your". It is seen in the context of "install the package on your system" or "run emerge --depclean to clean up your unused dependencies". Contributors are encouraged to rewrite these sections as "install the package on the system" or "run emerge --depclean to clean up the unused dependencies".

Editors are encouraged to clean up articles that use first and second person writing by rephrasing sections of text as is appropriate to the article.

Use lead-in sentences

Before any operation, create a lead-in sentence or topic sentence^[2]. This creates a nice flow of the text towards the action-oriented parts^[3].

For instance, instead of immediately starting with an Emerge box when explaining how to install a package, precede the step with a simple lead-in sentence such as "Install the software on the system:".

Use serial commas

Serial commas should be used when defining lists. A serial comma is a comma placed after each item in a list of three or more items, including the penultimate term. Consider the following sentences as examples:

Without serial comma: CPU, RAM and motherboard are all common components in a desktop workstation.
With serial comma: CPU, RAM, and motherboard are all common components in a desktop workstation.

The second example is the preferred one: a comma follows each item in the list, including the item preceding the coordinating conjunction ("and" in the aforementioned examples).

Use American English

There are several flavors of English in the world. To keep a consistent layout of the content throughout the wiki, it is advised to stick with the American English (also known as US English). This will keep spelling and terminology homogeneous, and help avoid flip-flopping edits between different versions of spelling.

An exception to this guideline exists when directly quoting documentation that includes spelling or terminology inconsistent with American English. For example, when citing a man page of software written in British English, the corresponding British English style should be maintained without words being translated into their American English counterparts. This exception does not mean the entire section or article should be re-written in British English, as it applies exclusively to the citation.

Use clean language

Language used on the wiki is to be kept to a "G" rating. The "G" in this case does not stand for Gentoo; it stands for general audiences. Wiki content should be acceptable for all ages to consume. In practice, editors should avoid unhelpful speech such as obscenities, crassness, profanities in their edits to articles and summary messages. Please see the Gentoo Code of Conduct for more details.

Formatting

Contributors should try to follow these formatting principles when possible, since they directly impact the overall readability of articles across the wiki.

Those who are new to MediaWiki in general may find the generic formatting page helpful. It covers some elements not found in the sections below such as bullet, numbered, and definition lists, indentation, Unicode, and other topics.

Article description property

The [[Article description::]] property should be set on articles to provide a descriptive handle that can be automatically reused on other pages. Article descriptions are conventionally set in the lead-in sections of articles.

Article descriptions "capture" a section of text from an article to be used as the description property of that page, but in no way alter the rendering of pages. Select or write a section of text that properly describes the content or intention of an article, and surround it with the [[Article description:: and ]] tags.

The Article description property can be used in multiple ways across the wiki, for example the {{See also}} template leverages article descriptions to provide automatically-formatted, user-friendly, links in See also sections at the bottom of articles.

Here is a usage example:

Source input	Rendered output in article	Use with {{See also\|Firefox}} template
`Firefox is [[Article description::Mozilla's web browser.]]`	Firefox is Mozilla's web browser.	Firefox — Mozilla's web browser.

The full list of pages with the Article description property on the wiki can be found here. Take a look at the source of any of those pages for concrete examples of how to use this property.

Semantic MediaWiki is used by the Gentoo wiki to add support for annotating semantic data within wiki pages, and this extension provides the article description text property.

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
`''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. (See also the "Warning" block-level element below.)	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.
`{{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: `[[#anchorname\|link text]]` - When linking from elsewhere on the same page. `{{Link\|#anchorname\|link text}}` - When using the {{Link}} template to link to elsewhere on the same page. `[[Pagetitle#anchorname\|link text]]` - When linking to an anchor on a different page. `{{Link\|Pagetitle\|section=#anchorname\|link text}}` - When using the {{Link}} template to link to an anchor on a different page. 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..
`{{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	Used for files and directories. Be sure to include the leading "/" if it is an absolute path. In the case of directories, a trailing "/" (forward slash) may be helpful for easy readability. (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.

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). It replaces the <tt> tag which has been deprecated in HTML5.

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 -l` total 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 --help` Usage: 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 --help` Usage: 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.conf`Setup 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 links) in this template is to be avoided.	CODE An example ebuild function src_compile() { escons CC="$(tc-getCC)" FOO=1 }

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

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.

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:

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

Use ISO 8601 for date and time representatio

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

Article structure

This section describes how articles should be structured both in general, and for specific types of article which have their own particular structures (for example those describing a piece of software; or "meta articles" which describe a whole category of software).

Important
Article blueprints aid with article creation by providing a predefined structure for pages of various types - articles should follow these structures to provide consistency across the wiki.

Titles and section headings

The title of an article should be short, specific and unambiguous.

Titles both of articles and of sections within an article ("section headings") should start with a capital letter, with the rest of the title using lower case (with the exception of proper nouns). This is called sentence case. Full capitalization (also known as "title case") should be avoided.

Section headings should be level 2 or higher (3, 4, ...). A level 2 heading uses two equals signs, i.e.: "== <title> ==".

Note
The use of a level 1 heading is meant only for the title of the article itself, and is automatically used. As such, level 1 headings (i.e. "= <title> =") should not be defined in the article's text by wiki contributors.

Links and HTML formatting should not be used in section headings.

Start of an article

A wiki article should start with a short introductory paragraph, without any heading. The introductory paragraph should include a description of the article itself, and often these description sentences will be used as the Article description property.

Headings such as Introduction or Overview are highly discouraged: this information should usually just be included in the article header (the text at the top of an article, before the first section heading).

If an article requires any conceptual knowledge before the operational content of the article can be given (such as installation instructions, required configuration, package administration tasks, etc.) name these prerequisite sections according to the concept.

Documenting a package or software title

Note
This section gives an overview of how to layout a specific type of article: articles for packages or software titles. For guidance on how to layout other common types of article, see the article blueprints.

When documenting a package or software title, add an {{InfoBox}} template to the beginning of the article, with external resources such as the project homepage, the category/package information (links to packages.gentoo.org), wikipedia article, ohloh statistics, etc.

Examples of what can be usefully added as InfoBox entries can be found in the software blueprint. Example of an InfoBox layout:

CODE <software title>

{{InfoBox stack
|{{InfoBox homepage|https://url/to/homepage|header=true}}
|{{InfoBox package|category/package}}
|{{InfoBox wikipedia|TitleOnTheWikipedia}}
|{{InfoBox ohloh}}
}}

Important
Remember to use HTTPS whenever possible when adding external links to an InfoBox.

Following the blueprint: software articles should start with the "Installation" section with installation instructions, USE flag information and so on. A "Configuration" section will usually follow that can have info about configuration files, environment variables, and configuring the launch of daemons for different init systems, for example.

The central part of these articles will usually be one or more sections on the operational aspects of the software title or package. Try to structure this part on a use-case basis, with each subsection containing an entire operation. Examples of good sections could be "Manipulating the boot entries" or "Encrypting volumes with cryptsetup". It is good prictice to split sections up, so that their subsections each cover just one operation; "Manipulating the boot entries" could for example be split into "Listing boot entries" and "Adding a boot entry", etc.

Body

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

Tip
New sections (or even whole articles) can be drafted in userspace and moved to articles in the main namespace when finished.

End of an article

An article should finish up with links to related material: other Gentoo wiki articles, external websites, or references to source material (through <ref> tags in the article body). These sections are optional, but should be included if any useful resources are available.

Tip
Remember to add the "References" section when any <ref> tags are used in the article.

At the end of the article, add the following sections, as appropriate:

External resources section

An external resource provides more information about the subject at hand than is available on the wiki. These sections are similar to See also lists, but link to pages outside the Gentoo wiki. These are often resources to help delve deeper into a topic, reference material, complete documentation, etc.

"External resources" sections should consist of bullet lists of URLs to external websites. It is useful to add a short description of each link, and as with "See also" sections it can be helpful to add a short sentence to to inform the user how each element is related to the current article, or why it may be of interest.

References section

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 automatically generated - just add the header and the {{reflist}} template:

== 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^[4] in the given order (as far as that information is known):

Author of the source;
Title of the source (as a hyperlink);
Main origin of the source, such as the main site (as a hyperlink);
Date of publication; and
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 -^[5] and use those flags in their CFLAGS and CXXFLAGS variables."

References

↑ Geoff Hart. Use of first, second, and third person in technical writing?, Technical Writing lists, August 17, 2005. Retrieved on January 1st, 2015
↑ Placement of the Topic Sentence, Rochester Institute of Technology, October 10, 2014. Retrieved on January 1st, 2015
↑ Alan S. Pringle, Sarah S. O'Keefe. "Technical Writing 101: A Real-World Guide to Planning and Writing Technical Content", Page 112 on "Introducing the procedure", Scriptorium Publishing Services, Inc. ISBN 978-0970473363
↑ Referencing for beginners, Wikipedia. Retrieved on January 1st, 2015
↑ Michał Górny. Inlining -march=native for distcc, Michał Górny blog, June 23rd, 2014. Retrieved on January 1st, 2015.

[1] Geoff Hart. Use of first, second, and third person in technical writing?, Technical Writing lists, August 17, 2005. Retrieved on January 1st, 2015

[2] Placement of the Topic Sentence, Rochester Institute of Technology, October 10, 2014. Retrieved on January 1st, 2015

[3] Alan S. Pringle, Sarah S. O'Keefe. "Technical Writing 101: A Real-World Guide to Planning and Writing Technical Content", Page 112 on "Introducing the procedure", Scriptorium Publishing Services, Inc. ISBN 978-0970473363

[4] Referencing for beginners, Wikipedia. Retrieved on January 1st, 2015

[5] Michał Górny. Inlining -march=native for distcc, Michał Górny blog, June 23rd, 2014. Retrieved on January 1st, 2015.

[1]

[2]

[3]

[4]

[5]

User talk:Mantic