Difference between revisions of "Help:Funtoo Editing Guidelines"

From Funtoo
Jump to navigation Jump to search
 
m (remove IRC reference)
 
(147 intermediate revisions by 2 users not shown)
Line 1: Line 1:
This guide is meant to serve as a reference for those who are interested in helping improve the Funtoo wiki.
{{Subpages|Basics,Images,Headings,Inline Code,Tables,Page Tools,Tips and Warnings,Source Code,Text Files,ConsoleOutput,Packages,Kernel,Translations,User Pages}}


= document hierarchy structure =


The above top-level section was inserted using:


<pre>= document hierarchy structure =</pre>
'''Thanks for your interest in contributing to the Funtoo Wiki!'''
== document hierarchy sub structure ==


Sub-sections can be created as follows, or use these as your main sections:
Before we get started, it's a good idea to review what kinds of changes to the wiki
we're looking for, and what kind of changes we're not looking for.


<pre>== document hierarchy sub structure ==</pre>
Most of the time it's good to document stuff. But because we want Funtoo Linux to be as seamless an experience as possible, sometimes the best approach is to use IRC or forums for support, or file a bug on our bug tracker. See the table below for the types of wiki edits we consider to be OK:
this is the primary structure most pages, talk pages will use instead of main heading example above. some pages will call for main heading.
=== document hierarchy sub sub structure ===


Now, we can create third-level sections:
{{TableStart}}
 
<tr class="active"><th>Type of Edit</th><th>OK?</th></tr>
<pre>=== document hierarchy sub sub structure ===</pre>
<tr><td>Grammar/spelling fixes</td><td>Yes</td></tr>
==== document hierarchy sub sub sub structure ====
<tr><td>New wiki content</td><td>Yes</td></tr>
 
<tr><td>New package information</td><td>Yes</td></tr>
<pre>==== document hierarchy sub structure ====</pre>
<tr><td>Adding to existing article</td><td>Yes</td></tr>
 
<tr><td>Adding missing/incomplete information</td><td>Yes</td></tr>
to implement pipe {{!}} in documents, wrap with brackets.
<tr><td>Making corrections</td><td>Yes</td></tr>
<pre>{{!}}</pre>
<tr class="danger"><td>Adding workarounds to problems experienced, esp. install issues</td><td>Maybe not - try forums or Discord/Telegram first, and possibly open bug first on [https://bugs.funtoo.org bug tracker].</td></tr>
 
{{TableEnd}}
{{fancyimportant|below template is not instated yet}}
to use equals signs with out conflicting with document structure wrap with brackets.
<pre>{{=}}</pre>
 
{{=}} http://en.wikipedia.org/wiki/Template:%3D
 
== &#60;console&#62; ==
To display console output, use the <tt>&#60;console&#62;</tt> tag:
 
For a root console:
<pre>
<console>
###i## run a command as root
</console>
</pre>
Produces:
<console>
###i## run a command as root
</console>
 
{{Fancyimportant|The <tt>##i##</tt> text tags the rest of the line as being ''user input'' ("i" is for "input"). It is then highlighted in a noticeable color so it stands out from text that is not typed in by the user.}}
 
Examples of usage:
* [[Rootfs over encrypted lvm]]
* [[Boot-Update]]
* [[Fonts]]
For a non-root console:
<pre>
<console>
$ ##i##run a command as user
</console>
</pre>
Produces:
<console>
$ ##i##run a command as user
</console>
 
{{fancyimportant|1=
Note that we use a <tt>#</tt> prompt for <tt>root</tt> and a <tt>$</tt> prompt to denote a non-root user.}}
 
Examples of usage:
* [[Zope HOWTO]]
* [[Benchmarking]]
 
or a more concise syntax
 
== Fancy Notes ==
notes, warnings, tips, and important templates will help bring emphasis to articles drawn up.
<pre>{{fancynote|this is a fancy note}}</pre><br />
{{fancynote|this is a fancy note}}<br />
 
<pre>{{fancyimportant|this is a fancy important}}</pre><br />
{{fancyimportant|this is a fancy important}}<br />
 
<pre>{{fancywarning|this is a fancy warning}}</pre><br />
{{fancywarning|this is a fancy warning}}<br />
 
<pre>{{fancytip|this is a fancy tip}}</pre><br />
{{fancytip|this is a fancy tip}}<br />
 
 
<pre>bridge returns will help you edit articles also <br /> starts a new line</pre><br />
bridge returns will help you edit articles also <br /> starts a new line
 
== &#123;&#123;Kernelop&#125;&#125; ==
To display kernel options, we encourage you to use the <tt>kernelop</tt> template. To use the <tt>kernelop</tt> template, create an entry similar to the following example:
<pre>
{{kernelop|title=foo,bar|desc=
kernel options pasted from "make menuconfig"
<&#47;pre>}}
</pre>
 
Adding this entry will give you the following output:
{{kernelop|title=foo,bar|desc=
kernel options
}}
 
Here's a more concrete example:
{{kernelop|title=File systems|desc=
<M> Second extended fs support         
[ ]  Ext2 extended attributes         
[ ]  Ext2 execute in place support   
<M> Ext3 journalling file system support
}}
 
Examples of usage:
* [[Fglrx]]
* [[Acpid]]
* [[Microcode]]
 
== links ==
 
internal:<pre>[[pagename]]</pre><br />
[[pagename]]<br />
internal with text:<pre>[[pagename|some text]]</pre><br />
[[pagename|some text]]<br />
external: <pre>[http://funtoo.org/ http://funtoo.org/]</pre><br />
[http://funtoo.org/ http://funtoo.org/]<br />
external with text: <pre>[http://funtoo.org/ this is some text]</pre><br />
[http://funtoo.org/ this is some text]
 
== Displaying Source Code ==
 
To display source code, use the <tt>&#60;syntaxhighlight&#62;</tt> tag, which has the ability to perform syntax highlighting on the source code for easier reading:
<pre>
<syntaxhighlight lang="python">
import system
</syntaxhighlight>
</pre>
 
This will produce the following output:
 
<syntaxhighlight lang="python">
import system
</syntaxhighlight>
 
 
Note that the language should be specified in the <tt>lang</tt> attribute. For a list of supported languages, see [http://www.mediawiki.org/wiki/Extension:SyntaxHighlight_GeSHi#Supported_languages this list].
 
== Displaying Files ==
To display the contents of a file that is not source code, use the <&#47;pre> tag. The <&#47;pre> tag preserves formatting. Example file contents:
 
<pre>
foo
bar
oni
</pre>
 
 
Examples of usage:
* [[UEFI Install Guide]]
* [[MediaWiki]]
* [[Clang]]
 
== &#60;tt&#62; and &#60;code&#62; ==
To emphasize filenames, commands, and other technical jargon when they appear inline in a paragraph, use the  <tt>&#60;tt&#62;</tt> or <tt>&#60;code&#62;</tt> option. To use these, follow the example below:
<pre>
The <tt>/etc/fstab</tt> file is an important one. Another important file is <code>/boot/grub/grub.cfg</code>.
</pre>
 
This example produces the following output (notice the difference between the fonts?): <br> The <tt>/etc/fstab</tt> file is an important one. Another important file is <code>/boot/grub/grub.cfg</code>.
 
== Collapsible text ==
 
<pre><div class="toccolours mw-collapsible"> some text you might want to fold away because its a huge explanation.</div></pre><br />
 
<div class="toccolours mw-collapsible"> some text you might want to fold away because its a huge explanation.</div><br />
 
<pre><div class="toccolours mw-collapsible mw-collapsed">pre collapsed text because it is a huge explanation.</div></pre><br />
 
<div class="toccolours mw-collapsible mw-collapsed">pre collapsed text because it is a huge explanation.</div>
 
== Screencasting ==
screencasting is an easy method to explain complex tasks.  take for instance youtu.be/5KDei5mBfSg we chop off the id and insert it into the following syntax to produce a video example.<br />
tiny:
<pre>{{#widget:YouTube|id=5KDei5mBfSg|width=320|height=180}}</pre>
standard:
<pre>{{#widget:YouTube|id=5KDei5mBfSg|width=700|height=420}}</pre>
{{#widget:YouTube|id=5KDei5mBfSg|width=700|height=420}}


The basic concept is this -- some complications should simply ''be fixed in Funtoo'' rather than documented for users as ugly workarounds. So be aware
of types of issues that may fall into this category and take appropriate action such as [https://bugs.funtoo.org filing a bug]. We want the Funtoo experience to be as straightforward as possible, especially for new users. Now that that's out of the way, please browse the '''subpage links at the top of the page''' to familiarize yourself with Funtoo editing guidelines -- and have fun!
[[Category:Wiki Development]]
[[Category:Wiki Development]]
[[Category:Official Documentation]]

Latest revision as of 03:53, November 13, 2021


Thanks for your interest in contributing to the Funtoo Wiki!

Before we get started, it's a good idea to review what kinds of changes to the wiki we're looking for, and what kind of changes we're not looking for.

Most of the time it's good to document stuff. But because we want Funtoo Linux to be as seamless an experience as possible, sometimes the best approach is to use IRC or forums for support, or file a bug on our bug tracker. See the table below for the types of wiki edits we consider to be OK:

Type of EditOK?
Grammar/spelling fixesYes
New wiki contentYes
New package informationYes
Adding to existing articleYes
Adding missing/incomplete informationYes
Making correctionsYes
Adding workarounds to problems experienced, esp. install issuesMaybe not - try forums or Discord/Telegram first, and possibly open bug first on bug tracker.

The basic concept is this -- some complications should simply be fixed in Funtoo rather than documented for users as ugly workarounds. So be aware of types of issues that may fall into this category and take appropriate action such as filing a bug. We want the Funtoo experience to be as straightforward as possible, especially for new users. Now that that's out of the way, please browse the subpage links at the top of the page to familiarize yourself with Funtoo editing guidelines -- and have fun!