SDB:Howto

From openSUSE

Situation

This SDB (support database) article explains how to write SDB articles.

Procedure

SDB articles are written to give solutions to problems with SUSE Linux, but also to give more detailed explanations of certain topics. If you have problems with SUSE Linux, the SDB should be the first place to look for help.

A SDB article should be subdivided into the following parts:

• Situation
• Procedure
• Links

or

• Symptom
• Cause
• Solution
• Links

Please note that SDB articles - if possible - should always describe the easiest solution. However, it is desirable to also show the fastest solution achievable using the command line or by editing configuration files. In this case, the section "Solution" should be split up into several subsections. Before going into details about the syntax, here is an example (in mediawiki syntax, to see this example as an article please go to SDB:Changing NTP Server - SDB Example.)

Creating a new article

In your web browser, enter the title of the new article after SDB: in the URL line. If the article doesn't exist yet, click "edit" to create and edit it. Please do not overwrite existing articles. If necessary, add a version number or "(new)" to the title.

All SDB articles must start with SDB:, this makes searching them easier and constitutes a separate section in the Wiki.

Conclusion

History

When you have finished editing your article, please add it to SDB:History. Use this syntax:

YYYYMMDD [[SDB:<articlename>]]

e.g.:

20051016 [[SDB:Howto]]

Please use the international date format. The list is sorted in descending order, so that new articles are always at the top of the list.

If you made substantial changes to an article, like updating it for a newer version, please also mention that in the History. Smaller changes or additions should not be added to the History.

Translations

At present the openSUSE wiki supports English, German, French and Spanish. If you like, and if you know one of these languages, please translate your article. If you don't, or are not sure if you are fluent enough in the foreign language, please write an email to the opensuse-wiki mailing list and ask for someone to translate your article.

If you have translated an article, please add the "Interwiki" links at the end of the article. As an example, if you have translated an article from German into English, you add the following at the end of the German article:

[[en:SDB:<articlename>]]

To the english version, add the following:

[[de:SDB:<articlename>]]

At present the following shortcuts are supported:

de German
en English
fr French
es Spanish

Changing existing articles

With the integration of the SDB into the openSUSE Wiki it is now possible to edit all articles. If you want to change an article substantially it might be a good idea to discuss this first with the original authors. Please use the "discussion" link shown at the bottom of every article to do this.

This is not compulsory, but it makes Wiki collaboration easier and more enjoyable. If you cannot agree on a solution, maybe an email to the opensuse-wiki mailing list can help to clarify the situation.

Smaller changes may be made without discussion.

SDB tags

Table of Contents

As soon as an article contains three or more sections marked with === Section ===, the wiki software automatically generates a table of contents. This means that if you use the standard SDB article outline "Situation, Procedure, Links", this happens automatically.

SDB meta information

Please include the following meta information at the top of a new article. It will not be displayed.

<!-- SDB information
SDB:title: Changing NTP Servers - SDB Example 
SDB:author: mlasars
SDB:date: 2005-10-17 -->

If you made major changes to an article, please add your user name to the author line, separated with a comma. Do not change any other meta information field, especially not SDB:date. All changes to an article can be viewed in the History of the article. The meta information is intended to keep the most important data directly in the article in case of a future reorganisation of the system.

Version

At the beginning of the article please define the version(s) of SUSE Linux for which the article is valid. There are several possibilities:

Version: 8.0
Version: - 8.0
Version: 8.0 -
Version: 8.0 - 8.1

If the article is not specific to a particular version, just leave out the version tag. If it is only applicable to a certain architecture or variant of SUSE Linux please include that, too:

Version: 9.2 x86_64
Version: 9.1 DVD
Version: 10.0 ppc

At present SUSE Linux supports the following architectures: i386, x86_64 (64bit, AMD64 and Intel EM64T) and ppc (PowerPC (Mac)).

You can further specify one of the following variants: Box (the retail version), FTP, CD, DVD, Torrent and OSS.

Please only add this tag when the problem is really specific to that variant.

Note: In order to have a nice box drawn around the version, please always start the version line with a space.

Categories

Every SDB article should be accessible through the categories. You can find a list of available categories at Category:SDB. Add the categories at the beginning of the article:

[[Category:SDB:8.0|C]]
[[Category:SDB:Network|C]]

The category is followed by a pipe character and the first character of the title. In the example above, the article is called "Changing NTP Servers", so the pipe character is followed by a "C".

Keywords

Add all keywords that you want your article to be associated with to the end of the article:

<keyword>ntp,time,xntp,synchronize</keyword>

You can use anything you like as keywords.

Syntax

Apart from the Wiki-Syntax, MediaWiki also supports plain HTML tags. Whenever possible please use Wiki markup, so that the article sources are easier to read and edit. The most important elements of Wiki markup are given below. For more detailed instructions, see: http://en.wikipedia.org/wiki/Wikipedia:How_to_edit_a_page.

Sections

• Level 1: == Top Level Header == (for Situation, Procedure, Links)
• Level 2: === Subheader === (z.B. for YaST2, Command line)
• Level 3: ==== one level below ==== (more subsections, e.g. different versions)

Situation and Procedure should always use the top-level header, other subsections are one level below that, and so on.

Formatting

You don't have to mark paragraphs with <p>paragraph</p> as you would in HTML, this is done automatically. Paragraphs are separated with two empty lines.

  
This is the first paragraph
which can be written in several lines.


This is the second paragraph.

Text (bold, italic, code)

To highlight paragraphs or words please use the following syntax:

Enumerations / lists

Examples for enumerations:

* Planets
** Mars
** Earth
*** Moon

#Travel
## Plane
## Car
### Taxi

For the links at the end of an article please use * Link without further subdivision.

Commands and config file excerpts

Lines containing a single command should start with a space

rcapache2 restart

to highlight the command. Commands included in normal text should use <code>command</code>.

For code listings and config files please use the following syntax:

<pre>
## Path:        Network/Remote access/SSH
## Description: SSH server settings
## Type:        string
## Default:     ""
## ServiceRestart: sshd
#
# Options for sshd
#
SSHD_OPTS=""
</pre>

## Path:        Network/Remote access/SSH
## Description: SSH server settings
## Type:        string
## Default:     ""
## ServiceRestart: sshd
#
# Options for sshd
#
SSHD_OPTS=""

nowiki

In certain situations you might want to disable wiki markup:

Links

Links to other SDB articles start with SDB: [[SDB:howto]], but it is not necessary to explicitly include a link label. It is also possible to jump to a specific location in the article, e.g. [[SDB:howto#Stil]], which will be displayed as SDB:howto#Stil. If you use these direct links to a section of an article, adding the link label may be helpful: [[SDB:howto#Stil|Stil]] will be displayed as Stil.

External links should have a link label if it isn't obvious what they point to, or to make the link shorter.

[http://www.suse.de SUSE] will be displayed as SUSE. In this case, link and link label are simply separated by a space.

Please note that in some countries, external links may be a violation of local laws. As an example, it is illegal in Germany to link to software which may be used to circumvent copy-protection technology. If you are unsure if you can use a certain link, please ask on the opensuse-wiki mailing list (see Communicate).

Tables

See http://en.wikipedia.org/wiki/Wikipedia:How_to_use_tables

Images

Up till now, SDB articles have not used images. Please use them only where necessary, in order not to disturb the layout and flow of the article. If possible, just include a preview of the image at the right margin of the article. For more information about uploading images to the Wiki see: http://en.wikipedia.org/wiki/Wikipedia:Image_markup.

Style

How to address your readers

German SDB articles should use the polite form of address with "Sie", as this is the standard in technical documentation. If this applies to your language, please use the polite form, too. English authors of course don't have that problem ;-).

Terminology in foreign languages

In languages other than English, it is sometimes difficult to do without the original english technical terms. Please try to write such in a way that the broadest group of SDB users will find your article useful, but do not try to find translations when the English terms are commonly understood and used in the target language. A good compromise may be to use both, like in this german example: : "gehen Sie auf die zweite console (Kommandozeile) mit STRG-ALT-F2"

Easy!

Even if using the shell sometimes seems easier, especially for you, please try to keep Linux beginners in mind and also explain how a problem can be solved with YaST2 or other tools.

A good SDB article should describe every single step. So, don't write:

In /etc/inittab, change the default runlevel to 3.

but:

Log in as the root user and open the file /etc/inittab with the
editor of your choice (e.g. vi or pico). Change the line
id:5:initdefault: to id:3:initdefault: so that the system won't boot
into the graphical user interface any more.

This is not meant to be a hard requirement! But please remember that many Linux newbies use SUSE Linux, too.

Maintenance

It is frequently necessary to adjust SDB articles to new versions of SUSE Linux, or even to write new ones if the changes are too fundamental. Please try to maintain your SDB articles. As an example, if you notice that your article doesn't apply any more with the latest version of SUSE Linux, please change the "version" line.

Links

• http://en.wikipedia.org/wiki/Wikipedia:How_to_edit_a_page