Policies/Wiki Style/Example
From Mandriva Community Wiki
Contents |
[edit] Introduction
This is a page illustrating the example syntax that can be used on this wiki. It also illustrates the styles that should be used. The previous TWiki had absolutely no consistency whatsoever in the "markup" used, which made it look not very unified.
When you're discussing a file or directory, they should always use the {{file|foo}} markup, such as /etc/ssh/sshd_config or /usr/lib/X11.
When you're discussing a program, use the {{prog|foo}} markup, such as discussing urpmi or sudo.
When you're discussing a program such as rpmdrake and you want to illustrate the steps to take from the GUI menu, use the {{menu|foo->bar}} markup, such as File->Save As.
When you're discussing a package, use the {{pkg|foo}} markup, such as "install the package urpmi" or "download foo-1.0-1mdv2007.0.i586.rpm".
When referring to a version number (of a Mandriva product) use the {{version|foo}} markup, such as when discussing Mandriva Linux 2007. Do not use this markup when referring to the version of some software, such as "OpenSSH 4.5p1".
If you need to quickly refer to a command, do so using the {{cmd|foo}} markup, such as urpmi --auto-select. This way you don't have to break out into <pre></pre> tags. However, if you do need to illustrate something that will take more than one line, using the <pre> tags is preferred:
Every page must have a title, which is what the {{title|foo}} markup is used.
When you want to link to a bugzilla bug, there are two methods of doing it. You can use [[bugz:12345|Some nasty bug]] to have a named link, such as Some nasty bug. However, if you don't care about the link name, you can use {{bug|12345}} instead, such as 
Bug #12345.
When you have translated a page to another language, you will want to use the {{olang|[[:fr:Maison|French]]}} markup. This will end up looking like:
Other Languages: French
That particular markup should be at the end of a page, but before any category links.
$ uname -a Linux cerberus.annvix.ca 2.6.18.2-tmb-desktop-3mdv #1 Wed Nov 15 19:53:47 EST 2006 i686 AMD Athlon(tm) 64 X2 Dual Core Processor 4200+ GNU/Linux
However, when illustrating what the user would type and what they would see, be sure to use the "$" or "#" characters to denote what the input is. In the input above, the command uname -a is being used, and you can see it prefixed with "$" which indicates that a user can execute this. However, if something needs to be run as root, it should be prefixed with "#", just as if you were using a bash command prompt:
$ sudo su - # ps ax
This prevents confusion as to what is to be typed, and what the output from those commands are. As well, make sure there is a blank line around the <pre> tags. In fact, every paragraph or "break" in content should have a blank line, be that between headings or between lists that don't belong together or between single lines and %lt;pre< statements. For instance:
[edit] Header 1
[edit] Header 2
Some text
[edit] Header 3
is much preferred to:
[edit] Header 1
[edit] Header 2
Some text
[edit] Header 3
This is to make it visually easier on the editors to see what they are dealing with (presentation is everything, both to view the finished/rendered page and the edited text. It may look no different when it's rendered, but it makes a huge difference when editing the page.
Regarding headers, don't put links to other pages in headers. It might be tempting to write something like == Using [[Development/Packaging/Tools/rpmctl|rpmctl]] == but please don't do so. If you need to link, use the first instance in the first paragraph of an appropriate word (in this case, "rpmctl") to do the link. Links in headers make the headers not unified and this is something that happened a lot in the old TWiki.
For more details, refer to Policies/Wiki_Style#Style_and_Templates.
Finally, when referring to Mandriva, please use "Mandriva" or "Mandriva Linux" rather than "mandriva" or "mandriva linux" or any other variation. When referring to other projects or companies, please capitalize their names (such as "RedHat" instead of "redhat", etc.). While it might be tempting to use short-forms of words, such as "WM" instead of "Window Manager" please avoid temptation and spell the word out. It makes the document easier to understand (especially for newer users) and looks more professional (you don't see shortcuts like that in a book, for example). Likewise, when writing headers, capitalize every word (such as "How to Write Documentation" instead of "How to write docs").
The reasoning behind all of this is to keep things consistent and easy to read and easy to edit, and as clear and professional as possible. Instead of having documentation looking like it was written by people in a hurry, illiterate, or just plain lazy (or all three), we can produce some fantastic top-notch documentation that will be useful not only to Mandriva developers and users, but users of other distributions as well.
For your viewing pleasure, this text is now included below for you to view the syntax of everything written:
{{title|An Example of Wiki Style}}
= Introduction =
This is a page illustrating the example syntax that can be used on this wiki. It also illustrates the styles that should be used. The previous
TWiki had absolutely no consistency whatsoever in the "markup" used, which made it look not very unified.
When you're discussing a file or directory, they should always use the {{file|foo}} markup, such as
{{file|/etc/ssh/sshd_config}} or {{file|/usr/lib/X11}}.
When you're discussing a program, use the {{prog|foo}} markup, such as discussing {{prog|urpmi}} or {{prog|sudo}}.
When you're discussing a program such as {{prog|rpmdrake}} and you want to illustrate the steps to take from the GUI menu, use the
{{menu|foo->bar}} markup, such as {{menu|File->Save As}}.
When you're discussing a package, use the {{pkg|foo}} markup, such as "install the package {{pkg|urpmi}}" or
"download {{pkg|foo-1.0-1mdv2007.0.i586.rpm}}".
When referring to a version number (of a Mandriva product) use the {{version|foo}} markup, such as when discussing
Mandriva Linux {{version|2007}}. Do not use this markup when referring to the version of some software, such as "OpenSSH 4.5p1".
If you need to quickly refer to a command, do so using the {{cmd|foo}} markup, such as {{cmd|urpmi --auto-select}}.
This way you don't have to break out into <pre></pre> tags. However, if you do need to illustrate something that will take more
than one line, using the <pre> tags is preferred:
Every page must have a title, which is what the {{title|foo}} markup is used.
When you want to link to a bugzilla bug, there are two methods of doing it. You can use [[bugz:12345|Some nasty bug]]
to have a named link, such as [[bugz:12345|Some nasty bug]]. However, if you don't care about the link name, you can use
{{bug|12345}} instead, such as {{bug|12345}}.
When you have translated a page to another language, you will want to use the {{olang|[[:fr:Maison|French]]}} markup.
This will end up looking like:
{{olang|[[:fr:Maison|French]]}}
That particular markup should be at the end of a page, but before any category links.
< pre>
$ uname -a
Linux cerberus.annvix.ca 2.6.18.2-tmb-desktop-3mdv #1 Wed Nov 15 19:53:47 EST 2006 i686 AMD Athlon(tm) 64 X2 Dual Core Processor 4200+ GNU/Linux
< /pre>
However, when illustrating what the user would type and what they would see, be sure to use the "$" or "#" characters to denote what the
input is. In the input above, the command {{cmd|uname -a}} is being used, and you can see it prefixed with "$" which indicates that a user
can execute this. However, if something needs to be run as root, it should be prefixed with "#", just as if you were using a {{prog|bash}}
command prompt:
< pre>
$ sudo su -
# ps ax
< /pre>
This prevents confusion as to what is to be typed, and what the output from those commands are. As well, make sure there is a blank line
around the <pre> tags. In fact, every paragraph or "break" in content should have a blank line, be that between headings or between
lists that don't belong together or between single lines and %lt;pre< statements. For instance:
= Header 1 =
== Header 2 ==
Some text
=== Header 3 ===
is much preferred to:
= Header 1=
== Header 2 ==
Some text
=== Header 3 ===
This is to make it visually easier on the editors to see what they are dealing with (presentation is everything, both to view the finished/rendered
page and the edited text. It may look no different when it's rendered, but it makes a huge difference when editing the page.
Regarding headers, don't put links to other pages in headers. It might be tempting to write something like
== Using [[Development/Packaging/Tools/rpmctl|rpmctl]] == but please don't do so. If you need to link, use the first
instance in the first paragraph of an appropriate word (in this case, "rpmctl") to do the link. Links in headers make the headers not unified
and this is something that happened a lot in the old TWiki.
For more details, refer to [[Policies/Wiki_Style#Style_and_Templates]].
Finally, when referring to Mandriva, please use "Mandriva" or "Mandriva Linux" rather than "mandriva" or "mandriva linux" or any other
variation. When referring to other projects or companies, please capitalize their names (such as "RedHat" instead of "redhat", etc.). While
it might be tempting to use short-forms of words, such as "WM" instead of "Window Manager" please avoid temptation and spell the word
out. It makes the document easier to understand (especially for newer users) and looks more professional (you don't see shortcuts like that
in a book, for example). Likewise, when writing headers, capitalize every word (such as "How to Write Documentation" instead of "How to
write docs").
The reasoning behind all of this is to keep things consistent and easy to read and easy to edit, and as clear and professional as possible.
Instead of having documentation looking like it was written by people in a hurry, illiterate, or just plain lazy (or all three), we can produce some
fantastic top-notch documentation that will be useful not only to Mandriva developers and users, but users of other distributions as well.
For your viewing pleasure, this text is now included below for you to view the syntax of everything written:
