Wiki edition

The batocera wiki can be edited by multiple people, this page intends to explain how to render a page correctly.

However, you should first and foremost keep those simple rules of thumb in mind when adding/modifying informations :

  • Is the information accessible to someone with less knowledge, and if not, can other pages/sources be linked to help?
  • Is the information relevant to the current page?
  • Before making a new page, is it necessary to make a new page?
  • When making a new page, is the link concise, yet precise enough?
  • Can the page be related to something specific? for example, something purely related to an emulator or a port should have a link ending with emulators:page-name
  • Is the information somewhere else already, and if so, is it the correct place?

After answering those, we can try to learn how to edit the wiki.

When starting out, you have to first learn how to edit the wiki, that will imply practicing a bit, do not practice on this page, or any page with relevant information, use rather the PlayGround: this page is meant to be used to try things out. Now, let's start with some basics.

Headers are used to represent the basic structure of your page, you should always try to keep a clean structure in a page.

There are multiple levels of headers, from the main headers/first-level headers, the the sub-headers/second level-headers, and the third-level headers, normally, you shouldn't have to go further than that.

To create a first level header, you need to write ====== Main Header ====== (there are 6 = on the left and the right of the header, with a space between them and the header itself), for exemple, the main header of this page is written down as:

====== Wiki edition ======

The batocera wiki can be edited[…]

For a second level header, you will need to write ===== Second level header ===== (there are only 5 = this time, one less as we are one level lower), and ==== Third level header ==== for a third level header.

the following represents a valid basic structure for a wiki page

====== Playground ======
  
This page can be used as way to learn how to edit the wiki. We will first explain why there is a dedicated page for it, and then why its URL has playground:playground in the name
  
===== Goal =====
  
==== Training ====
   
As you can see, editing a wiki is not an easy task if you don't know how to do it, so this page can be used for this purpose.
   
==== Avoid unnecessary rollbacks ====
   
While this wiki system can revert changes done to a previous version, asking newcomers to edit actual pages would be risky, especially since some of them aren't that easy to read and manage in the first place.
   
===== About the page name =====
   
The page name is playground:playground because the wiki is set up in such a way that you can link pages to what is called a specific namespace, all the emulator pages are under the "emulators" namespace, so they all start with the "emulators:" name.

This wiki will automatically create a table of contents based of the headers on your page, unless you put ~~NOTOC~~ on top of your page.

You can display blocks of code either by starting a newline with two spaces, or by surrounding the code portion with the <code></code> elements, so copying and pasting the following two cases will display the same way :

  ##this is code
  #yay
<code>##this is code
#yay</code>

they will be displayed as

##this is code
#yay

Doing so will ignore any kind of formatting syntax

It is also possible to ask the wiki to not apply formatting to a specific element by suronding it by %%, or by using <nowiki></nowiki>

for exemple, writing down the following :

echo 'jambon' >> sandwich.txt

will display as

echo 'jambon' » sandwich.txt

transforming the >> into a », however writing

%%echo 'jambon' >> sandwich.txt%% or <nowiki>echo 'jambon' >> sandwich.txt</nowiki> will display it correctly.

To write down paths, or commands, it is fine to surround it with '', so ''/userdata/system/batocera.conf'' will display as /userdata/system/batocera.conf, Doing this will not skip formatting by itself however, so keep that in mind.

one easy way to display a table is to use a csv1) structure : think of it as a 2D spreadsheet, but in a pure text format where the separator of the columns is a Comma, and the separator for the lines is a newline, and the first line serves as a header.

Putting a CSV structure inside the <csv></csv> elements will display it, so for instance, if you have

Emulator name, Emulated system, Original manufacturer
Picodrive, Master system/Genesis, Sega
Genesis plus GX, Master system/Genesis, Sega

and add the <csv></csv> like this :

<csv>
Emulator name, Emulated system, Original manufacturer
Picodrive, Master system/Genesis, Sega
Genesis plus GX, Master system/Genesis, Sega
</csv>

it will then display as this

Emulator nameEmulated systemOriginal manufacturer
PicodriveMaster system/GenesisSega
Genesis plus GXMaster system/GenesisSega

Tables should be used only when they make sense

Images can be added to a page if needed, keep in mind that visuals should be an additional, not mandatory help, the syntax is the following:

{{:image-name?Size|Alternative Text}} For exemple, the “north button” image is located at https://wiki.batocera.org/_media/wiki:north.png (wiki:north.png is the name), it is the North button on a controller, which corresponds to the X Button on a SNES pad, and if we want to display this image at a 20 width pixel size, we need to put {{:wiki:north.png?nolink&20|North button (X Snes)}} and the wiki will put North button (X Snes) instead. Also if the image fails to load, or if we use the mouse cursor on it, it'll display “North button (X Snes)”, this is important for accessibility.

  • North button (X Snes) : the “X” button on a SNES layout, also referred to as the North button.
    • {{:wiki:north.png?nolink&20|North button (X Snes)}}
  • West button (Y Snes) : the “Y” button on a SNES layout, also referred to as the West button.
    • {{:wiki:west.png?nolink&20|West button (Y Snes)}}
  • South button (B Snes) : the “B” button on a SNES layout, also referred to as the South button.
    • {{:wiki:south.png?nolink&20|South button (B Snes)}}
  • East button (A Snes) : the “A” button on a SNES layout, also referred to as the East button.
    • {{:wiki:east.png?nolink&20|East button (A Snes)}}
  • On/Off Settings : the ON/OFF switch used for some options in EmulationStation
    • {{:switch-button.png?20|On/Off Settings}}
  • Slider Settings : the slider used for some options in EmulationStation
    • {{:switch-slider.png?30|Slider Settings}}

1)
Comma separated values
  • wiki/wiki-edition.txt
  • Last modified: 5 months ago
  • by fishou