Search:  
Gentoo Wiki

FAQ_Write_an_Article

This article is part of the FAQ series.
General Portage Wiki

Contents

Introduction

This article may be merged with some other in the future. The purpose of this page is to describe how to correctly create and format articles on this wiki. Feel free to look at the source code of this page by clicking the edit link above.

Development

This article is under development by the admins. If you have any suggestions, please bring them up on the talk page or the devel mailing list.

Trying this out

There is a safe place for you to try out what you learned. It's called the Sandbox.


Article Style: The Grammatical Person

Articles should be instructional, not accounts of what you did. An example of an incorrect sentence would be:

I switched on the usb USE flag and then emerged lircd

This should be correctly written as:

To install lircd you need to switch on the usb USE flag and then run emerge -a lircd


Another example:

I got an error message stating that the driver wasn't found. I was able to fix it be re-emerging the package.

This would be better written as:

Some users found that Xorg wasn't able to find the new driver. They were able to fix this by re-emerging the package.


The reason for this is two-fold. Primarily, most if not all of the articles on this wiki are instructions on how to install, configure and/or use a certain program or programs. Additionally, writing in the first person is pointless - especially on a well edited article it becomes impossible to determine who 'I' is.

Outlining your document

It's usually a good idea to put section headers between == tags. Simply put equal signs on both sides of the heading on its own line. While using = Someheading = as a heading is acceptable, it creates awfully large fonts. For most articles, two equal signs is the level that should be used for headings. To create sub-headings use more equal signs. For example, the following will create a heading called Introduction with some text, and a subheading Abstract with some text.

Code: Example of Headers
== Introduction ==
Hello World.
=== Abstract ===
This is the project abstract.  Its heading appears smaller, and at the top outline is indented.

Preventing Wikification

Everything between <nowiki> and </nowiki> will not be wikified (processed by the wiki engine).

There are two other ways. The first is to use the <pre> tag. It works just like the <nowiki> tag, except that the contents of the tag are put in a box and it looks better than <nowiki> when spanning over multiple lines.

The second way is to add a space at the beginning of the line. It works just like the <nowiki> tag, except that some basic formatting is still available and the contents of the tag are put in a box. For example, you can still

link to articles.

Beware, it doesn't work very well in boxes.

To combine <nowiki> and a leading space works, but avoid doing it. Rather use the <pre> tag in those cases.

Don't use HTML

It is usually not necessary to add raw HTML to wikis. Please use the formatting specified on the Help:Editing page. Bookmark that page and refer to it whenever you feel the itch to use plain HTML.

Line breaks

If you need to make space between paragraphs, hit the Enter/Return key twice (you should have one blank line between paragraphs). There is no need for double <br /> tags. You can use the <br /> tag if you need to insert a single line break
like this one.

Tables

Tables are explained in depth here.

Other tags

Boxes

The Gray Box

The gray box is what we use for code to be typed into a terminal, and also it's nested inside other boxes' content. To make a gray box you can:

  1. Put a space at the beginning of each line you want boxed. Note that if you use the '=' (equal sign) character, you should use the next method(s).
  2. Encapsulate the commands in <pre> tags
  3. Place a space at the beginning of a line followed by the <nowiki> tag, your content, and a </nowiki> tag at the end. Note, any extra spaces after the opening <nowiki> tag will be printed verbatim.
Code: Gray Box Nowiki Tags Example
<nowiki>This line contains the = character
and will not work if we don't use the <nowiki> tag.</nowiki>
 echo "bar" # this just has a space as the first character on the line

will produce:

This line contains the = character
and will not work if we don't use the <nowiki> tag.
echo "bar" # this just has a space as the first character on the line

Code, File, and Kernel Boxes

There are two colored boxes that gentoo-wiki uses. Boxes for Code and boxes for Files. Note: Code does not mean what you type into the terminal. Just use a gray box (see above) for that. Code boxes are used for program output, or actual programming code.

Colored boxes are a little more complex than what we've done so far. The format for creating a colored box is: {{Box Type|title|content}}. For editing readability, please start the content on a new line. Lets make one! The Code box is what you've seen throughout this wiki. The title is usually the program name. Then the output is placed in a gray box, with comments not in the gray box. Another example is the File box, which is red, and is used to denote the contents of a particular file. The last example, is the kernel box, which is "make menuconfig" for kernels. Here I chose to use a <pre> tag to make the gray box inside:

Code: making a kernel
{{Box Kernel| Kernel Box Example|
 Code maturity level options  --->
  [*] Prompt for development and/or incomplete code/drivers
  [*]   Select only drivers expected to compile cleanly
}}

will produce the following:

Linux Kernel Configuration: Kernel Box Example
Code maturity level options  --->
 [*] Prompt for development and/or incomplete code/drivers
 [*]   Select only drivers expected to compile cleanly

Explanations

If you need to explain what you doing in-line with your code/file, simply break out of the preformatted text or use appropriate comment characters. Example follows:

Code: bash script
#!/bin/bash
echo "here I am using preformatted text to show you code"
mutt # everything following the # character is a comment, so I can explain what I do

emerge gcc

This text is no longer preformatted, so I can use this space to explain the above command.

# and so on

Codeline/Commandline

This is probably the most misunderstood tag. But don't let that intimidate you, the {{Commandline}} tag can make your articles much more readable when used correctly. {{Commandline}} is just for that -- a line of code, which is usually a command to be entered at the prompt. Commandline is designed for a single line. It's just a quick "do this" in your article. {{Commandline}} does not go on its own line. For commands that span more than one line, use a gray box or the appropriate colored box.

Warning: Be careful. If for example the command contains an equal sign, all you get is a bunch of branches, no formatted command.

{{Codeline}} can still be used but is deprecated.

Good Example

Code: Appropriate use
After emerging your new kernel sources run {{Commandline|make menuconfig}} and 
configure your kernel.

which produces: After emerging your new kernel sources run make menuconfig and configure your kernel.

Bad Example

Code: Inappropriate use
Now emerge some kernel<br>
{{Commandline|emerge gentoo-sources}}<br>

which produces:

Now emerge some kernel
emerge gentoo-sources

Note: This was wrong because {{Commandline}} was placed on its own line, and because the author had to use a <br /> tag to do it.

Filename and Useflag

These are awfully simple commands. The {{Filename}} tag is used to display the location of a file, and {{Useflag}} is used to specify a use flag. For example:

Code: Using Filename and Useflag
And make sure that {{Useflag|gnome}} is specified as a useflag in {{Filename|/etc/make.conf}}.

will produce:

And make sure that gnome is specified as a useflag in /etc/make.conf.

ChangeLogs

There is no need to use ChangeLogs on the actual wiki pages. The wiki itself is capable of keeping track of changes. Just use the comment box when editing to specify what was changed.

Retrieved from "http://www.gentoo-wiki.info/FAQ_Write_an_Article"

Last modified: Tue, 22 Jul 2008 01:56:00 +0000 Hits: 33,612