Help:Wiki syntax and markup

From FedoraProject

(Difference between revisions)
Jump to: navigation, search
m (added autolang)
m (Basic Syntax: changed strikethrough to the MediaWiki tag, not the MW-supported html tag)
(4 intermediate revisions by 4 users not shown)
Line 13: Line 13:
 
|-
 
|-
 
| <pre><nowiki><code>Monospace text</code></nowiki></pre> || <code>Monospace text</code>
 
| <pre><nowiki><code>Monospace text</code></nowiki></pre> || <code>Monospace text</code>
 +
|-
 +
| <pre><nowiki><strike>Strikethrough text</strike></nowiki></pre> || <strike>Strikethrough text</strike>
 
|}
 
|}
  
Line 168: Line 170:
 
Refer to the Fedora Documentation Guide for descriptions of the types of admonition: http://docs.fedoraproject.org/documentation-guide/en_US/sn-xml-admon.html
 
Refer to the Fedora Documentation Guide for descriptions of the types of admonition: http://docs.fedoraproject.org/documentation-guide/en_US/sn-xml-admon.html
  
 +
{{Anchor|L10N_review_admonitions}}
 +
 +
=== L10N review admonitions ===
 +
 +
These are admonitions to request translation updates:
 +
 +
{|
 +
! '''What you type''' !! '''What you see'''
 +
|-
 +
|<pre><nowiki>{{Update}}</nowiki></pre>||{{Update}}
 +
|-
 +
|<pre><nowiki>{{RoughTranslation}}</nowiki> </pre>||{{RoughTranslation}}
 +
|-
 +
|<pre><nowiki>{{CleanupRemainder}}</nowiki> </pre>||{{CleanupRemainder}}
 +
|}
 +
 +
=== URLs and links inside an admonition ===
 +
 +
If you need to put a URL with form data inside an admonition, you must use the wiki parameters to set it properly:
 +
 +
{|
 +
! '''What you type''' !! '''What you see'''
 +
|-
 +
|<pre><nowiki>{{admon/note | 1=Form URLs | 2=This is a [http://example.com?foo=bar form URL].}}</nowiki></pre> || {{admon/note | 1=Form URLs | 2=This is a [http://example.com?foo=bar form URL].}}
 +
|}
  
 
{{Anchor|Writing_Example_Commands}}
 
{{Anchor|Writing_Example_Commands}}
 +
 
== Writing Example Commands ==
 
== Writing Example Commands ==
  
Line 192: Line 220:
 
Enter the <code>root</code> password when prompted.
 
Enter the <code>root</code> password when prompted.
  
{{admon/note|Command examples and root|Many commands require <code>root</code> privileges. The reader should not be logged into their system as <code>root</code>, and so you must specify either <code>su -c</code> or <code>su -</code> when explaining such commands.}}
+
{{admon/note|Command examples and root|Many commands require <code>root</code> privileges. The reader should not be logged into their system as <code>root</code>, so you must specify either <code>su -c</code> or <code>su -</code> when explaining such commands.}}
  
 
If the command requires elements to be quoted, nesting should be <code><nowiki>" ' ' "</nowiki></code>, with the single quote marks surrounded by one containing set of double quote marks.  For example:
 
If the command requires elements to be quoted, nesting should be <code><nowiki>" ' ' "</nowiki></code>, with the single quote marks surrounded by one containing set of double quote marks.  For example:

Revision as of 02:37, 14 April 2013

Note.png
If you need help with syntax that is not listed here, the Mediawiki Help should contain it. There is also a handy reference card image.

Contents

Basic Syntax

What you type What it looks like
'''bold text'''
bold text
''italics''
italics
'''''bold italics'''''
bold italics
<code>Monospace text</code>
Monospace text
<strike>Strikethrough text</strike>
Strikethrough text

Lists

What you type What it looks like
* A list item
* Another list item
** Oh joy, more list items!
  • A list item
  • Another list item
    • Oh joy, more list items!
# A numbered item
# Another numbered item
## Sub items
## More sub items
# Third numbered item
  1. A numbered item
  2. Another numbered item
    1. Sub items
    2. More sub items
  3. Third numbered item
* An unordered item...
*# With a sub-list that is ordered
*# More steps
* Back to the first list
*# Another ordered list
*#* With its own sub point
  • An unordered item...
    1. With a sub-list that is ordered
    2. More steps
  • Back to the first list
    1. Another ordered list
      • With its own sub point
Idea.png
Use HTML markup for numbered lists that include preformatted <pre> blocks
When you use preformatted text blocks, such as code or screen examples, in a numbered list using the wiki markup, it causes the numbering to restart. Instead, use the <ol> ordered list HTML markup to create the list.

Links

What you type What it looks like
Visit [[DocsProject]] to learn more about
Fedora's documentation.
Visit DocsProject to learn more about Fedora's documentation.
Our [[Websites|websites team]] offers many
individuals who can help Fedora.
Our websites team offers many individuals who can help Fedora.
See [[Artwork#Join]] on how to
join the Art Team.
See Artwork#Join on how to join the Art Team.
[[The weather in London]] is a
page that doesn't exist yet.
The weather in London is a page that doesn't exist yet.
http://fedoraproject.org/
http://fedoraproject.org/
Here are some sites:
[http://www.deviantart.com]
[http://www.flickr.com]
Here are some sites: [1] [2]
[http://fedoraproject.org Our home page]
is full of interesting information.
Our home page is full of interesting information.
Use a ':' in the link to link
to an [[:Image:Growth_wide.jpg|image]].
Use a ':' in the link to link to an image.
The [[:Category:Documentation]] lists all 
end-user documentation.
The Category:Documentation lists all end-user documentation.
The [[Category:Documentation]] link puts
this page in the listed category; the link
appears automatically on the bottom of the
page and not inline.
The [[Category:Documentation]] link puts this page in the listed category; the link appears automatically on the bottom of the page and not inline.
Note.png
There are two ways to use the Category links
Be sure to use the ':' before the word Category when you intend to link to a category page. Omit the ':' when the page is supposed to be in that category. Refer to the examples above.

Tables

Tables should be used sparingly and only when necessary.

For more advanced table usage, read up on Mediawiki.org's page on tables.

What you want How to get it
Start a table
{|
Table header
! Column 1 !! Column 2 !! Column 3
Table row
|-
Table data
| Cell 1 || Cell 2 || Cell 3
End a table
|}

IRC Logs

IRC logs can either be surrounded in <pre> tags, or converted into MediaWiki pipe-tables with irclog2html and Ian's MediaWiki patch for irclog2html.

Notes, Tips, and Other Admonitions

These are collectively known as admonitions, and are used in DocBook. To make a paragraph into an admonition, use the special admonition template. A short title and a longer descriptive paragraph are recommended.

What you type What you see
{{admon/note|A title|Here is more information about
this tip, with information that provides more insight
into the informative title of the initial paragraph.}}
Note.png
A title
Here is more information about this tip, with information that provides more insight into the informative title of the initial paragraph.

Indent the initial and second paragraph by one space, to ensure that the box aligns correctly.

These are the standard types of admonition:

What you type What you see
{{admon/note|This is a note|Informational paragraph
that tells more about what is going on.}}
Note.png
This is a note
Informational paragraph that tells more about what is going on.
{{admon/tip|This is a tip|Informational paragraph
that tells more about what is going on.}}
Idea.png
This is a tip
Informational paragraph that tells more about what is going on.
{{admon/important|This is important|Informational paragraph
that tells more about what is going on.}}
Important.png
This is important
Informational paragraph that tells more about what is going on.
{{admon/caution|This is a caution|Informational paragraph
that tells more about what is going on.}}
Stop (medium size).png
This is a caution
Informational paragraph that tells more about what is going on.
{{admon/warning|This is a warning|Informational paragraph
that tells more about what is going on.}}
Warning (medium size).png
This is a warning
Informational paragraph that tells more about what is going on.

Admonition examples

Examples showing context for using these admonitions:

Note.png
Cliffs can be very high
Wikipedia can vouch for this.
Idea.png
Standing away from cliff edges is a way to stay safe
For more information, read the cliffs(1) man page.
Important.png
Keep your children away from the cliff edge to your right
Children move around quite a bit and can easily fall off. You should hold their hand.
Stop (medium size).png
You are getting near the cliff edge
As mentioned earlier, cliffs can be very high, and it would be bad to fall.
Warning (medium size).png
You are about to fall off the cliff
Move away as quickly as possible to avert falling.

Refer to the Fedora Documentation Guide for descriptions of the types of admonition: http://docs.fedoraproject.org/documentation-guide/en_US/sn-xml-admon.html

L10N review admonitions

These are admonitions to request translation updates:

What you type What you see
{{Update}}
Outdated.png
This wiki page is outdated
Please update this wiki page to reflect recent events or newly available information.
{{RoughTranslation}} 
Translation.png
This article is a rough translation
It may have been generated by a computer or by a translator without dual proficiency.
Please help to enhance the translation.
{{CleanupRemainder}} 
Clear.png
The content appearing below may require cleanup
Please improve this article if you can, and move or remove this notice if appropriate.

URLs and links inside an admonition

If you need to put a URL with form data inside an admonition, you must use the wiki parameters to set it properly:

What you type What you see
{{admon/note | 1=Form URLs | 2=This is a [http://example.com?foo=bar form URL].}}
Note.png
Form URLs
This is a form URL.

Writing Example Commands

Example commands are one or more commands set apart from the body of the explanation. Do not use prompt symbols or any other content that shows machine name, user, directory, etc. (which are details set in the $PS1 environment variable.)

Enclose any example command in <pre></pre> tags:

<pre>
su -c "yum install awesome-application"
</pre>

Enter the <code>root</code> password when prompted.

Which produces:

su -c "yum install awesome-application"

Enter the root password when prompted.

Note.png
Command examples and root
Many commands require root privileges. The reader should not be logged into their system as root, so you must specify either su -c or su - when explaining such commands.

If the command requires elements to be quoted, nesting should be " ' ' ", with the single quote marks surrounded by one containing set of double quote marks. For example:

su -c "command -o 'Some Text' -file 'More text' foo/bar"

If you need to have a series of commands or su -c is not responding as expected, have the user switch to root and warn the user to return to a normal user shell afterward.

su -
Password:
service food stop
cp /etc/foo.d/foo.conf /etc/foo.d/foo.conf.backup
vi /etc/foo.d/foo.conf
food --test-config
...
service food start
exit

Example command output

When the example shows a command as part of showing the output to the screen, you may use a command prompt to clarify commands and output.

$ su -c "ls -l /root"
Password: 
total 148
-rw------- 1 root root  1961 2007-09-21 02:46 anaconda-ks.cfg
-rw-r--r-- 1 root root 46725 2007-09-21 02:46 install.log
-rw-r--r-- 1 root root  6079 2007-09-21 02:42 install.log.syslog
-rw-r--r-- 1 root root  3699 2008-07-28 17:24 scsrun.log
-rw-r--r-- 1 root root 45038 2008-01-10 10:21 upgrade.log
-rw-r--r-- 1 root root  1317 2008-01-10 10:20 upgrade.log.syslog

Quick Tips

Note.png
For more information
on drafting documentation on the Wiki, refer to Writing Wiki Documentation.

Structure of a Wiki Page

This section describes the common structure of a wiki page. Follow these guidelines for every wiki page. There are additional rules used for formal Fedora documentation, covered in Writing for DocBook using the wiki ; those rules are only required for content written to follow the procedures of the Fedora Documentation Project. Pages that are templates of standard content that are drawn into other pages may have a different structure.

Note.png
Header 1 (h1) deprecated for use in markup
The header 1 is defined by the page title. When making new or migrating pages, either re-nest or re-structure the page to have only header 2 and below.
  • The title of the page is a first-level header. It is created automatically from the page title.
  • Sections are created using the equals symbols in pairs:
    == Header 2 ==
    === Header 3 ===
    ==== Header 4 ====
    ===== Don't do this, 5 levels of nesting means you need a new page or three =====
    
  • The table of contents is automatically created and populated when the page grows big enough.
  • Anchors to sections are automatically created, with specific symbols used in place of punctuation and spaces:
    This page ==> This_page
    This, that, and the other page ==> This%2C_that%2C_and_the_other_page
    
Idea.png
You can use .2C instead of %2C for anchors
The substitute of '.' for '%' works for anchors against a specific section.

Learn by Example

Among the better ways to learn how to edit the wiki is reviewing the code of existing pages. This is very easy to do:

  1. Find a page whose source you would like to view.
  2. Click on either the edit or view source tab at the top of the page.

The wiki will display the plaintext form of that page. This is particularly valuable for learning some of the clever tricks used by wiki editors ahead of you. Those 'clever tricks' are valuable, as they allow you to do unique, interesting, and powerful things you might not have thought were possible. You might try this on pages like Main Page (but please don't make drastic or unwanted edits to this page!).


Marking Technical Terms

Use the code markup (<code></code>) to mark the names of applications, files, directories, software packages, user accounts, and other words that have a specific technical meaning. This displays the marked words as monospace.

Use two single-quotes (''[name of menu]'') to mark the names of menu items and other elements of the graphical interface. This displays the marked words in italic.


Term Mark Up Formatted example
Names of GUI applications
 '''boldface''' 
Firefox
Files, directories
 <code>inline code tags</code> 
/usr/bin/firefox
Software packages
 <code>package name</code> 
firefox-1.2.3
User accounts
 <code>username</code> 
username
Other words that have a specific technical meaning
 <code>technical term</code> 
... the class org.fedora.someJava.classname ...
Graphical menus and menu items
 ''Menu name'' 
Applications > Internet > Firefox Web Browser
Other GUI or WebUI interface element
 ''two single-ticks'' 
... click the Submit button ...
Inline command and daemons
 <code>command -option</code> <code>daemon</code>
grep httpd to find the PIDs of the running httpd processes.
Blocks of code, configuration files, etc.
 <pre>whitespace preserved< /pre> 
whitespace
    is preservered
  here
Inline pieces of code, configuration files, etc.
 <code>inline whitespace not preserved</code> 
... Next, modify the variables for set() in /path/to/org/dev108/classname ...
First term, glossary term
 ''term'' 
... Firefox is an example of a graphical user interface or GUI.
Keystrokes
 '''[Key]''' 
Press the [Enter] key ...

For example:

The <code>thunderbird</code> package installs the '''Mozilla Thunderbird'''
e-mail application. To start '''Thunderbird''', select:
  ''Applications > Internet > Thunderbird Email''.

Which produces:

The thunderbird package installs the Mozilla Thunderbird e-mail application. To start Thunderbird, select: Applications > Internet > Thunderbird Email.