Difference between revisions of "Wiki Tips"

From GnuCash
Jump to: navigation, search
(Using Images)
 
(http->https, where applicable)
 
(14 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
Tips to edit and maintain this wiki
+
The GnuCash wiki uses the very popular and capable [https://www.mediawiki.org MediaWiki]. You can reach its detailed documentation by "Help" in the sidebar. Here we list a few tips and recommendations for the GnuCash wiki. We assume, you have already read our [[Wiki Conventions]].
 +
 
 +
==Talk Pages==
 +
MediaWiki uses "Talk pages" as a mechanism for wiki editors to communicate. Follow the recommended editing conventions over at [https://www.mediawiki.org/wiki/Help:Talk_pages MediaWiki]. Please try to be welcoming, civil and polite when communicating with fellow editors.
 +
 
 +
==Syntax Highlighting==
 +
Syntax Highlighting makes code examples so much easier to read.  It is therefore strongly preferred over <nowiki><nowiki></nowiki></nowiki>, <nowiki><pre></pre></nowiki> or indentation to mark code snippets or other formatted files.
 +
 
 +
Here are a couple of examples to illustrate this richness:
 +
{| style="width:100%;text-align:left"
 +
!scope="col" style="width:50% " | You Type
 +
!scope="col" style="width:50%" | You Get
 +
 
 +
|-style="vertical-align:top;"
 +
|<pre><syntaxhighlight lang="sh">
 +
# A hello world shell script
 +
echo "Hello, World!"
 +
</syntaxhighlight>
 +
</pre>
 +
|<syntaxhighlight lang="sh">
 +
# A hello world shell script
 +
echo "Hello, World!"
 +
</syntaxhighlight>
 +
|-style="vertical-align:top;"
 +
|<pre><syntaxhighlight lang="scheme">
 +
; A hello world program in scheme
 +
(begin
 +
  (display "Hello, World!")
 +
  (newline))
 +
</syntaxhighlight>
 +
</pre>
 +
|<syntaxhighlight lang="scheme">
 +
; A hello world program in scheme
 +
(begin
 +
  (display "Hello, World!")
 +
  (newline))
 +
</syntaxhighlight>
 +
|}
 +
 
 +
Examples with optional parameters can be found at https://www.mediawiki.org/wiki/Extension:SyntaxHighlight.
 +
 
 +
A list of supported languages is available at [https://pygments.org/languages/ Supported languages],
 +
more details at [https://pygments.org/docs/lexers/ Available lexers].
 +
 
 +
== Tables ==
 +
Tabular data loves a table.  Here's a quick example to get you started using the mediawiki syntax. To encourage consistent formatting on this wiki, we strongly prefer the use of the mediawiki table syntax with the <code>wikitable</code> <code>class</code>.
 +
 
 +
{| style="width:100%;text-align:left"
 +
!scope="col" style="width:50% " | You Type
 +
!scope="col" style="width:50%" | You Get
 +
|-style="vertical-align:top;"
 +
| <syntaxhighlight lang="php">
 +
{| class="wikitable"
 +
|-
 +
! scope="col"| Col Heading One
 +
! scope="col"| Col Heading Two
 +
! scope="col"| Col Heading Three
 +
 
 +
|- style="vertical-align:top;"
 +
| col 1, row 1
 +
| col 2, row 1
 +
| col 3, row 1
 +
 
 +
|- style="vertical-align:top;"
 +
| col 1, row 2
 +
| col 2, row 2
 +
| col 3, row 2
 +
|}
 +
</syntaxhighlight>
 +
|
 +
{| class="wikitable"
 +
|-
 +
! scope="col"| Col Heading One
 +
! scope="col"| Col Heading Two
 +
! scope="col"| Col Heading Three
 +
 
 +
|- style="vertical-align:top;"
 +
| col 1, row 1
 +
| col 2, row 1
 +
| col 3, row 1
 +
 
 +
|- style="vertical-align:top;"
 +
| col 1, row 2
 +
| col 2, row 2
 +
| col 3, row 2
 +
|}
 +
|}
 +
 
 +
Here's another example, this time with row headers:
 +
{| style="width:100%;text-align:left"
 +
!scope="col" style="width:50% " | You Type
 +
!scope="col" style="width:50%" | You Get
 +
|-style="vertical-align:top;"
 +
| <syntaxhighlight lang="php">
 +
{| class="wikitable"
 +
|-
 +
! scope="col"|
 +
! scope="col"| Col Heading One
 +
! scope="col"| Col Heading Two
 +
! scope="col"| Col Heading Three
 +
 
 +
|- style="vertical-align:top;"
 +
! scope="row"|Row Heading 1
 +
| col 1, row 1
 +
| col 2, row 1
 +
| col 3, row 1
 +
 
 +
|- style="vertical-align:top;"
 +
! scope="row"|Row Heading 2
 +
| col 1, row 2
 +
| col 2, row 2
 +
| col 3, row 2
 +
|}
 +
</syntaxhighlight>
 +
|
 +
{| class="wikitable"
 +
|-
 +
! scope="col"|
 +
! scope="col"| Col Heading One
 +
! scope="col"| Col Heading Two
 +
! scope="col"| Col Heading Three
 +
 
 +
|- style="vertical-align:top;"
 +
! scope="row"|Row Heading 1
 +
| col 1, row 1
 +
| col 2, row 1
 +
| col 3, row 1
 +
 
 +
|- style="vertical-align:top;"
 +
! scope="row"|Row Heading 2
 +
| col 1, row 2
 +
| col 2, row 2
 +
| col 3, row 2
 +
|}
 +
|}
 +
;Tip: To allow sorting by columns use <code> class="wikitable sortable"</code>.
 +
Full documentation on tables can be found [https://www.mediawiki.org/wiki/Help:Tables over at MediaWiki].
  
 
==Using Images==
 
==Using Images==
  
−
There are several ways to use images - beneath other files - in this wiki:
+
There are several ways to incorporate images into your wiki pages.
 +
 
 +
===Before you start===
 +
# Verify an upload will not violate any [https://en.wikipedia.org/wiki/Copyright copyright]s.
 +
# The preferred file format is '''.png''' because of its ''lossless compression''.
 +
# Shrink dialogs for '''screenshots''' to their minimal required size. That makes the text better readable and reduces the file size.
 +
# Run [http://optipng.sourceforge.net/ OptiPNG] over the image to reduce its size.
  
 
=== Uploading ===
 
=== Uploading ===
−
Admins and other users with uploadaccess can upload images via [[Special:Upload]].
+
Admins and other users with the uploadaccess permission can upload images via [[Special:Upload]].
−
<nowiki>[[File:filename.extension|options|caption]]</nowiki>
+
 
−
can than be used to embed them in a text.
+
These images are then referenced from a wiki page with the following syntax:
−
;Example:
+
<syntaxhighlight lang="html">
−
<nowiki>[[File:Gnucash-icon.png|100px|Click me!]]</nowiki>
+
[[File:filename.extension|options|caption]]
−
appears as
+
</syntaxhighlight>
−
:[[File:Gnucash-icon.png|100px|Click me!]]
 
  
−
This Images will have a full version history and other metadata. To see them, just click on the image.
+
{| style="width:100%;text-align:left"
 +
!scope="col" style="width:50%" | You Type
 +
!scope="col" style="width:50%" | You Get
 +
|-
 +
|<pre>[[File:Gnucash-icon.png|100px|Click me!]]</pre>
 +
|[[File:Gnucash-icon.png|100px|Click me!]]
 +
|}
 +
 
 +
Images have a full version history and other metadata. To see them, just click on the image.
  
 
With the <tt>link={target}</tt> option you can refer files from other sites with a wikimedia upload directory like commons.wikimedia.org.  
 
With the <tt>link={target}</tt> option you can refer files from other sites with a wikimedia upload directory like commons.wikimedia.org.  
  
−
=== Linking ===
+
=== Linking to External Images ===
−
Sometimes you might wish to link elsewhere existing images whithout overhead e.g. drafts of the guide might reuse the images from the nightly docs.  
+
Sometimes you might wish to link existing images without overhead, e.g. drafts of the guide might reuse the images from the nightly docs.  
−
But the URL must not match our [[MediaWiki:Spam-blacklist]] or conform our [[MediaWiki:Spam-whitelist]].
+
 
 +
The URL must not match [[MediaWiki:Spam-blacklist]] and must conform to our [[MediaWiki:Spam-whitelist]].
 +
 
 +
==== embedding external image ====
 +
Embedding an allowed image is as simple as typing its URL:
 +
<syntaxhighlight lang="html">
 +
https://url.for/some/image.png
 +
</syntaxhighlight>
 +
The URL must conform to our [[MediaWiki:External image whitelist]].
  
−
==== embedding ====
+
Example:
−
<nowiki>http://url.for/some/image.png</nowiki>
+
{| style="width:100%;text-align:left"
−
The URL must match our [[MediaWiki:External image whitelist]].
+
!scope="col" style="width:50%" | You Type
−
;Example:
+
!scope="col" style="width:50%" | You Get
−
<nowiki>http://www.gnucash.org/images/gnucash-perspective.png</nowiki>
+
|-style="vertical-align:top;"
−
appears as
+
|<pre>https://www.gnucash.org/images/gnucash-perspective.png</pre>
−
:http://www.gnucash.org/images/gnucash-perspective.png
+
|https://www.gnucash.org/images/gnucash-perspective.png
 +
|}
  
−
==== linking ====
+
==== linking to external image ====
−
<nowiki>[http://www.gnucash.org/images/banner5.png Banner]</nowiki>
+
You can also link to an external image like so.
−
This will only show up as a textual link:
+
 
−
[http://www.gnucash.org/images/banner5.png Banner]
+
{| style="width:100%;text-align:left"
−
You will have to click on it to see the image.
+
!scope="col" style="width:50%" | You Type
 +
!scope="col" style="width:50%" | You Get
 +
|-
 +
|<pre>[https://www.gnucash.org/images/banner5.png Banner]</pre>
 +
|[https://www.gnucash.org/images/banner5.png Banner]
 +
|}
 +
 +
You will have to click on the link to open the image.
  
 
;Source: https://www.mediawiki.org/wiki/Help:Images
 
;Source: https://www.mediawiki.org/wiki/Help:Images
 +
 +
== Reminders ==
 +
Some actions need some preparation to keep the wiki consistent:
 +
=== Changing Headers ===
 +
Before you change headers you should check for links on them, in the page and in whole wiki.
 +
=== Deleting Pages ===
 +
Before you delete a page you should
 +
* check for links - use the <tt>WhatLinksHere</tt> tool fom the toolbar.
 +
* check for included [[#Using Images|images]] <nowiki>[[file:...]]</nowiki> which might get orphaned.

Latest revision as of 11:17, 14 February 2021

The GnuCash wiki uses the very popular and capable MediaWiki. You can reach its detailed documentation by "Help" in the sidebar. Here we list a few tips and recommendations for the GnuCash wiki. We assume, you have already read our Wiki Conventions.

Talk Pages

MediaWiki uses "Talk pages" as a mechanism for wiki editors to communicate. Follow the recommended editing conventions over at MediaWiki. Please try to be welcoming, civil and polite when communicating with fellow editors.

Syntax Highlighting

Syntax Highlighting makes code examples so much easier to read. It is therefore strongly preferred over <nowiki></nowiki>, <pre></pre> or indentation to mark code snippets or other formatted files.

Here are a couple of examples to illustrate this richness:

You Type You Get 
<syntaxhighlight lang="sh">
# A hello world shell script
echo "Hello, World!"
</syntaxhighlight>

# A hello world shell script
echo "Hello, World!"

<syntaxhighlight lang="scheme">
; A hello world program in scheme
(begin
  (display "Hello, World!")
  (newline))
</syntaxhighlight>

; A hello world program in scheme
(begin
  (display "Hello, World!")
  (newline))

Examples with optional parameters can be found at https://www.mediawiki.org/wiki/Extension:SyntaxHighlight.

A list of supported languages is available at Supported languages, more details at Available lexers.

Tables

Tabular data loves a table. Here's a quick example to get you started using the mediawiki syntax. To encourage consistent formatting on this wiki, we strongly prefer the use of the mediawiki table syntax with the wikitable class.

You Type You Get 
{| class="wikitable"
|-
! scope="col"| Col Heading One
! scope="col"| Col Heading Two
! scope="col"| Col Heading Three

|- style="vertical-align:top;"
| col 1, row 1
| col 2, row 1
| col 3, row 1

|- style="vertical-align:top;"
| col 1, row 2
| col 2, row 2
| col 3, row 2
|}
Col Heading One Col Heading Two Col Heading Three
col 1, row 1 col 2, row 1 col 3, row 1
col 1, row 2 col 2, row 2 col 3, row 2

Here's another example, this time with row headers:

You Type You Get 
{| class="wikitable"
|-
! scope="col"|
! scope="col"| Col Heading One
! scope="col"| Col Heading Two
! scope="col"| Col Heading Three

|- style="vertical-align:top;"
! scope="row"|Row Heading 1
| col 1, row 1
| col 2, row 1
| col 3, row 1

|- style="vertical-align:top;"
! scope="row"|Row Heading 2
| col 1, row 2
| col 2, row 2
| col 3, row 2
|}
Col Heading One Col Heading Two Col Heading Three
Row Heading 1 col 1, row 1 col 2, row 1 col 3, row 1
Row Heading 2 col 1, row 2 col 2, row 2 col 3, row 2
Tip
To allow sorting by columns use class="wikitable sortable".

Full documentation on tables can be found over at MediaWiki.

Using Images

There are several ways to incorporate images into your wiki pages.

Before you start

  1. Verify an upload will not violate any copyrights.
  2. The preferred file format is .png because of its lossless compression.
  3. Shrink dialogs for screenshots to their minimal required size. That makes the text better readable and reduces the file size.
  4. Run OptiPNG over the image to reduce its size.

Uploading

Admins and other users with the uploadaccess permission can upload images via Special:Upload.

These images are then referenced from a wiki page with the following syntax: 

[[File:filename.extension|options|caption]]
You Type You Get 
[[File:Gnucash-icon.png|100px|Click me!]]
 Click me!

Images have a full version history and other metadata. To see them, just click on the image.

With the link={target} option you can refer files from other sites with a wikimedia upload directory like commons.wikimedia.org.

Linking to External Images

Sometimes you might wish to link existing images without overhead, e.g. drafts of the guide might reuse the images from the nightly docs.

The URL must not match MediaWiki:Spam-blacklist and must conform to our MediaWiki:Spam-whitelist.

embedding external image

Embedding an allowed image is as simple as typing its URL: 

https://url.for/some/image.png

The URL must conform to our MediaWiki:External image whitelist.

Example:

You Type You Get 
https://www.gnucash.org/images/gnucash-perspective.png
 gnucash-perspective.png

linking to external image

You can also link to an external image like so.

You Type You Get 
[https://www.gnucash.org/images/banner5.png Banner]
 Banner

You will have to click on the link to open the image.

Source
https://www.mediawiki.org/wiki/Help:Images

Reminders

Some actions need some preparation to keep the wiki consistent:

Changing Headers

Before you change headers you should check for links on them, in the page and in whole wiki.

Deleting Pages

Before you delete a page you should

  • check for links - use the WhatLinksHere tool fom the toolbar.
  • check for included images [[file:...]] which might get orphaned.
Retrieved from "https://wiki.gnucash.org/wiki/index.php?title=Wiki_Tips&oldid=17568"