View source for Wiki Conventions

The purpose of this page is
# to unify the appearance of the GnuCash wiki.
#:;See also: [[Wiki Tips]]
# develope a style, which can be easily converted to [{{URL:wp}}DocBook DocBook], to move sections into the official documenation.
#:;See: [{{URL:dbk-tdg}}docbook.html DocBook: The Definitive Guide]
#:;See also: [[Docbook Conventions]]

==Categories==
2-letter categories are reserved:
* ''Uppercase'': ISO '''region''' codes like DE (Germany), NO (Norway), ... contain region specific items like setup of tax tables.
* ''Capitalized'': ISO '''language''' codes like De page in "german|deutsch" - also readers from AT, CH, ... can use it.
:* in theory this should be lowercase, but wikimedia does not accept that.
:* at some point in time we might move them in subdomains.
==Typography==
In commands use the following Syntax:
* '''<'''replacable text'''>''' like variables for username, path, filename
: alternative in shell scripts:<Syntaxhighlight lang="sh">
# Set MYPATH=<where you want to go>
cd "$MYPATH"
</Syntaxhighlight>
* '''['''optional text''']''' like optional parameters e.g. gnc-fq-dump [-v] <source> <symbol>...
* alternatives '''{'''on'''|'''off'''}'''
* Repetition '''...'''

==New Pages==
# Insert as first line at least one '''[[#Categories|Category]]''': <nowiki>[[Category:Foo]]</nowiki>
#:[[Special:Categories|The current category list]]
#;Note: Older pages have then often at the bottom of either the abstract or the page. If you see that, move them to the header.
# optional the '''box''' of links to '''translations'''.
# Continue with usually one sentence '''abstract'''. Explain the
#: context including links of important related pages, 
#: specific terms, and
#: the planed coverage of the page.
# Finally the first '''section header''' starts the '''text body'''.

==Templates==
Use our [https://wiki.gnucash.org/wiki/index.php?title=Special%3APrefixIndex&prefix=&namespace=10 Templates] where ever possible. This will help to maintain changes of servers, protocoll etc.

===Optional Components===
====Comments====
Templates can contain comments explaining their meaning and purpose:
{| class="wikitable"
!scope="col" | Template Content
!scope="col" | Result
|-style="vertical-align:center;"
|<pre>42<noinclude>The Answer to Life, the Universe and Everything</noinclude></pre>
||42
|}

====Parameters====
Some templates use parameters like 
{| class="wikitable"
!scope="col" | Template Name
!scope="col" | Template Content
|-style="vertical-align:center;"
|<nowiki>{{URL:FP}}</nowiki>
||<nowiki>https://{{{1|}}}flatpak.org/</nowiki>
|-style="vertical-align:center;"
|<nowiki>{{URL:SF}}</nowiki>
||<nowiki>https://{{{1|}}}sourceforge.net</nowiki>
|-style="vertical-align:center;"
|<nowiki>{{URL:wp}}</nowiki>
||<nowiki>https://{{{1|en}}}.wikipedia.org/wiki/</nowiki>
|}

Note that for all mentioned a default value is set. The empty string at FP and SF, but the english server at WP.
While most things at FP and SF are on their default server, a few are on dedicated servers like our MSYS2 build of gdb. Or you want to link a german WP article:
{| class="wikitable"
|+Usage
|-
!scope="col" | Source
!scope="col" | Result
|-style="vertical-align:center;"
|<nowiki>{{URL:FP|docs.}}de/latest/debugging.html</nowiki>
|{{URL:FP|docs.}}de/latest/debugging.html
|-style="vertical-align:center;"
|<nowiki>{{URL:SF|downloads.}}project/gnucash/gdb-windows/win32-gdb.zip</nowiki>
|{{URL:SF|downloads.}}project/gnucash/gdb-windows/win32-gdb.zip
|-style="vertical-align:center;"
|<nowiki>{{URL:wp}}Linux_User_Group</nowiki>
|{{URL:wp}}Linux_User_Group
|-style="vertical-align:center;"
|<nowiki>{{URL:wp|de}}Linux_User_Group</nowiki>
|{{URL:wp|de}}Linux_User_Group
|}

===Overview===
Currently there are several groups of templates:
;syntaxhighlighted shell or console snippets: used at several places like english and german version of a page. English comments inside are OK, other language specific parts should stay outside. The template name should end in the type sh or con.
;Version: recent or required versions of GnuCash and related software (Aqbanking, F::Q, …) like
: Gnucash *Series/'''*Version'''/*Package
;Links: URLs of our and related servers.
===Linking GnuCash Servers and List Archives===
====Host Overview====
Currently there a 2 real hosts and several aliases:
{| class="wikitable"
|-
! scope="col"| Real Host
! scope="col"| Template
! scope="col"| URL
! scope="col"| Role

|- style="vertical-align:top;"
! scope="row"|{{WebServer}}
|<nowiki>{{URL:www}}</nowiki>
|{{URL:www}}
|holding the website and the published documentation

|- style="vertical-align:center;"
! scope="row" rowspan="5"|{{BuildServer}}
| colspan="2"|
|has serveral aliases:
|- style="vertical-align:top;"
|<nowiki>{{URL:Build}}</nowiki>
|{{URL:Build}}
|authorative [[Git]] repository,
build server of the nightlies ([https://code.gnucash.org/builds/ program], [https://code.gnucash.org/docs/ source docs, documentation])
|- style="vertical-align:top;"
|<nowiki>{{URL:Bugs}}</nowiki>
|{{URL:Bugs}}
|[[Bugzilla]]
|- style="vertical-align:top;"
|<nowiki>{{URL:Lists}}</nowiki>
|{{URL:Lists}} 
|[[Mailing Lists]],
[[IRC]] logs
|- style="vertical-align:top;"
|<nowiki>{{SERVER}}</nowiki>
|{{SERVER}}
|this wiki.
;Note:This is no template, but a variable which can be used in ''external'' links, but normally you will use ''internal'' links.
:See also [https://www.mediawiki.org/wiki/Help:Magic_words#Variables Help:Variables] .
|}
Please use the respective template in your links.
===Linking Source Files ===
By default link the stable branch <tt>stable</tt>. Only if you are referencing a future feature link <tt>future</tt>.
:;Example: <nowiki>{{URL:git}}gnucash/blob/stable/README.dependencies</nowiki>:
::{{URL:git}}gnucash/blob/stable/README.dependencies
===Linking Mails===
Sometimes you wish to link a mail. Please use ''our own archives'' at '''{{ListServer}}''' in the form of '''<nowiki>{{URL:Lists}}</nowiki>''' instead of any mirror service.
:;Background: There are several links to empty pages because Gmane lost many pages when it moved in 2016.

==Keyboard Sortcuts==
{| style="width:100%;text-align:left"
!scope="col" style="width:40% " | Type
!scope="col" style="width:50% " | You Type
!scope="col" style="width:10%" | You Get
|-
|Simultaneous (i.e. for change app)
|<nowiki><kbd>Alt</kbd>+<kbd>Tab</kbd></nowiki>
|<kbd>Alt</kbd>+<kbd>Tab</kbd>
|-
|Sequential (i.e. for File->Import)
|<nowiki><kbd>Alt</kbd>+<kbd>F</kbd>-<kbd>I</kbd></nowiki>
|<kbd>Alt</kbd>+<kbd>F</kbd>-<kbd>I</kbd>
|-
|'''Wrong use''', ''replace it please''
|<nowiki><code>Alt</code>+<code>Tab</code></nowiki>
|<code>Alt</code>+<code>Tab</code>
|}

==Subsections==
Use subsections for versioning and OS specifics. 

===Updating and Versioning===
While updating do not remove sections, which might for other users still relevant. Instead create subsections. Depending on the level and complexity it might be 
{| style="width:100%;text-align:left"
!scope="col" style="width:10% " | Type
!scope="col" style="width:50% " | You Type
!scope="col" style="width:40%" | You Get

|-style="vertical-align:top;"
|Subchapter
|<pre>
====Feature X====
General text about Feature X.
=====Gnucash 2.7.0 and newer=====
We use fee.
=====Gnucash 2.6.20 and before=====
We use foo.
</pre>
|

==Feature X==
General text about Feature X.
===Gnucash 2.7.0 and newer===
We use fee.
===Gnucash 2.6.20 and before===
We use foo.

|-style="vertical-align:top;"
|Bullet list
|<pre>General text about Feature X.
* Gnucash 2.7.0 and newer:
:We use fee
* Gnucash 2.4.0 to 2.6.20:
:We use fie
:... and have a 2. paragraph
* Gnucash 2.3.1 and before:
:We use foo.
</pre>
|
General text about Feature X.
* Gnucash 2.7.0 and newer:
:We use fee
* Gnucash 2.4.0 to 2.6.20:
:We use fie
:... and have a 2. paragraph
* Gnucash 2.3.1 and before:
:We use foo

|-style="vertical-align:top;"
|Definition list
|<pre>General text about Feature X.
;Gnucash 2.7.0 and newer: We use fee
;Gnucash 2.4.0 to 2.6.20: We use fie
:... and have a 2. paragraph
;Gnucash 2.3.1 and before: We use foo
</pre>
|General text about Feature X.
;Gnucash 2.7.0 and newer: We use fee
;Gnucash 2.4.0 to 2.6.20: We use fie
:... and have a 2. paragraph
;Gnucash 2.3.1 and before: We use foo
|}
;Note: Put ''newer'' versions ''before'' ''older'' versions because in the future they will become more important.

===OS Specifics===
It is almost the same:
{| 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>General text and [https://standards.freedesktop.org standards] like from [https://www.freedesktop.org/wiki/ freedesktop.org].
;Linux: fee
;{{Mac}}: fie
;Windows:
:;NT and newer: foo
:;XP and before: xyzzy</pre>
|General text and [https://standards.freedesktop.org standards] like from [https://www.freedesktop.org/wiki/ freedesktop.org].
;Linux: fee
;{{Mac}}: fie
;Windows:
:;NT and newer: foo
:;XP and before: xyzzy
|}
This order of OSes is both: historical and alphabetical.

Use the <nowiki>{{Mac}}</nowiki> template because Apple is changing its writing almost every season.