slackdocs:tutorial

Enjoy Slackware 15.0!
Welcome to the Slackware Documentation Project
Trace:
====== Wiki Tutorial and Guidelines ======


===== Namespaces =====

Please get acquainted with the concepts behind namespaces in DokuWiki: [[https://www.dokuwiki.org/namespaces]]

==== Plain Articles ====

When you are creating just a //single// page then it is OK to use one of our existing namespaces:
  * ''[[/start?idx=howtos|howtos:]]'' \\ The logical place for all your tutorials
  * ''[[/start?idx=security|security:]]'' \\ Documentation about how to deal with security issues on Linux (not particularly just Slackware); HOWTO's about securing your Linux computer and applications; how to safely surf the Internet; etcetera.
  * ''[[/start?idx=slackware|slackware:]]'' \\ Articles directly related to the distro
  * ''[[/start?idx=wiki:user|wiki:user:]]'' \\ Where every Wiki user can dress up his own "home page"
  * Or any of the localized namespaces (''[[/start?idx=nl|nl:]]'' ''[[/start?idx=de|de:]]'' ''[[/start?idx=fr|fr:]]'' etcetera) which in turn contain the same sub-namespaces as mentioned above


==== Complex Articles ====

If you add new tutorials etc which are split into //multiple articles, contain screenshots etc//, it is advisable that you put these in their own sub-[[https://www.dokuwiki.org/namespaces|namespace]]. Otherwise you will flood the current namespace and maintaining uploaded files will become a mess for the users and admins alike.

When you add a link inside an existing page which points to your new page in its own sub-namespace, you have to add your own namespace in the link too.

You do this by using [[wp>Colon_(punctuation)|colons]], and if you start your "namespacing" with a dot '.' you make the namespace relative to the current pages namespace, which is standard.

<note tip>Imagine that you are editing the main HOWTOs page and want to add your own HOWTO called "icecast streams" and you want to use multiple connected pages with screenshots. You would normally add a link to it in the [[howtos:start|HOWTOS main page]] by using the pagename ".icecast_streams:start". \\ //In this Wiki, the [[howtos:start|HOWTOs index]] page is automatically populated by using the tag "howtos" so use your tags wisely.// \\ 
Such a name (inside a normal internal link) would put the page under the ''howtos:icecast_streams:'' namespace. You can then put all your uploaded files in that same namespace. \\ 
//Note that I replaced the space in "icecast streams" with an underscore. Prevent spaces in the pagenames and namespaces!//
</note>

Please try to maintain a clean namespace structure, it will be very hard to fix all the links if we have to make corrections to page locations and namespaces.


===== Syntax and Formatting =====

First make yourself familiar with the [[wiki:syntax|DokuWiki syntax]]. It is not the same as MediaWiki syntax.

Try to keep the page formatting as clean as possible:
  * A page's main title heading should be in **H1**, the headings under that **H2**, headings under **H2** should be **H3** etcetera.
  * Don't use horizontal rulers unless necessary (for instance they are not necessary if there is a heading right above or beneath where you want to mark a "new section").
  * Surround text strings containing example commands, filenames and computer text with a "code text" markup. For example: ''man rc.inet1.conf''. There is a "TT" button in the button bar above which will insert exactly that markup.

Here is an example of what a small page could look like, using namespaces for sub pages etc: <code>
====== This is the page ======

You would write a description of your article here.
Remember that you can use sub-pages (sub-namespaces), where appropriate.

===== The First Section =====

Some bla bla

[[.subpage:start | My in depth article]]

===== The Second Section =====

More text

[[.another_subpage:start | More information with screenshots]]

<!-- You can leave comments in your page - they will not be visible in the resulting Wiki article -->
<!-- Tags are essential for creating a Table Of Contents (TOC) -->
{{tag>howtos software}}
</code>

===== Images =====

You might want to include rather big screenshots within your articles, but having them displayed full size directly inside the article can make things look bad. Fortunately you can resize the image directly within the article. You can also set the alignment of the picture, some examples will show more than words:

Resize to given width:            
  {{wiki:dokuwiki-128.png?50}}
And left/center/right alignment like this: 
  {{ wiki:dokuwiki-128.png}}
  {{wiki:dokuwiki-128.png }}
  {{ wiki:dokuwiki-128.png }}

See [[wiki:syntax#images_and_other_files|DokuWiki information about images and other files]] for more info.


===== Code =====

You can insert [[wiki:syntax#code_blocks|code]] using the ''code'' tag, like this:
  <code c> float a; </code>
<code c>
float a; 
float b;
a = b * 10 + 2 * sin1(x);
</code>
Like this example shows, the readability is enhanced a lot if you apply code [[wiki:syntax#syntax_highlighting|syntax highlighting]] when documenting shell scripts and such.


===== Spell Check =====
Please spell check your work, either with UK or USA English; many visitors do not have English as their primary language. Grammar checks in particular are hard for non-english authors, so do not hesitate to [[slackdocs:contact|contact one of our site Editors]] to assist you in creating legible and fluent english texts.


===== Text Template =====

You will notice that whenever you create a new page, you will already have some text pre-filled. This text comes from one of our templates- every namespace has a slightly different template text. \\ The most important aspect of the template is that it adds default [[https://www.dokuwiki.org/plugin:tag|tags]] to your page. These tags will allow us to populate our Table Of Contents automatically.

An example of a template text: <code>
<!-- Add your text below. We strongly advise to start with a Headline (see button bar above). -->


<!-- Please do not add anything below, except additional tags.-->
<!-- However we request that you remove the tag-word "template" below. Otherwise your page will not show up in the Table of Contents -->

<!-- Do not remove this line and the tag definition below. Thanks! slackdocs@-->
{{tag>howtos template}}
</code>

===== Use of Discussion Pages =====

It is a good idea to use the "discussion" pages (linked as a tab at the top of each article) to discuss the content of the article, point out errors, clarify doubts, bring something to the attention of the author, and/or propose any major changes.

If you want to add a comment to a discussion page, take a few moments to think about what you want to write //before// clicking the **edit this page** tab. Try to keep the time during which you keep the page locked as short as possible, so that you are not an obstacle to other people who also want to comment.

When you decide to add a comment to a discussion page, there are some guidelines you should follow in order to keep discussions legible and orderly:

  * Sign all your comments by clicking the **insert signature** button on the top WYSIWYG editor toolbar or by using <key>ALT</key>+<key>SHIFT</key>+<key>Y</key> keyboard shortcut
  * Use a **Level 2 Headline** to add a completely new comment by clicking the blue **H** on the top WYSIWYG editor toolbar or by using the <key>ALT</key>+<key>SHIFT</key>+<key>2</key> keyboard shortcut
  * Add all comments at the bottom of the page, unless you are replying. In that case, add your comments directly underneath the post you are replying to. Use the ''>'' characters to thread your discussions, adding as many as needed. For example:
<code>
===== Topic =====

Original Comment
> The first reply
>> The second reply
>>>The third reply
</code>
Will look somewhat like this:

{{ :slackdocs:threaded-talk-page.png?640 |}}

You can subscribe to the talk page's changes if you want to be notified of replies by clicking on the **manage subscriptions** tab while on the talk page. 
===== Language Considerations ===== 

==== In English, Please ====

English is the primary language of the Slackware Documentation Project. This seems only natural since Slackware Linux has an English-only installer and English-only documentation. The admin team wants to prevent this project from getting stuck in [[wp>Confusion_of_tongues|a Babylonian mess]].

==== So How Are non-English Contributions Being Handled? ====

Please check [[slackdocs:translation_guide#creating_a_page_in_your_own_language|Creating a Page in Your Own Language]] in the Translation Guidelines.


<!-- Do not remove this line and the text below. Thanks! slackdocs@-->
{{tag>slackdocs tutorial needs_attention}}
Navigation

Search

Toolbox

In Other Languages

SlackDocs

Slackware Links

QR Code
