Difference between revisions of "Wiki Conventions"

From GnuCash
Jump to: navigation, search
(→‎Keyboard Sortcuts: Wrong use of <code>)
(→‎Parameters: add {{URL:FP}})
 
(3 intermediate revisions by the same user not shown)
Line 36: Line 36:
 
==Templates==
 
==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.
 
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.
−
===Comments===
+
 
 +
===Optional Components===
 +
====Comments====
 
Templates can contain comments explaining their meaning and purpose:
 
Templates can contain comments explaining their meaning and purpose:
−
{| style="width:100%;text-align:left"
+
{| class="wikitable"
−
!scope="col" | Template content
+
!scope="col" | Template Content
−
!scope="col" | Result of the template
+
!scope="col" | Result
 
|-style="vertical-align:center;"
 
|-style="vertical-align:center;"
 
|<pre>42<noinclude>The Answer to Life, the Universe and Everything</noinclude></pre>
 
|<pre>42<noinclude>The Answer to Life, the Universe and Everything</noinclude></pre>
 
||42
 
||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
 
|}
 
|}
  
Line 64: Line 103:
 
|- style="vertical-align:top;"
 
|- style="vertical-align:top;"
 
! scope="row"|{{WebServer}}
 
! scope="row"|{{WebServer}}
−
|<nowiki>{{WebURL}}</nowiki>
+
|<nowiki>{{URL:www}}</nowiki>
−
|{{WebURL}}
+
|{{URL:www}}
 
|holding the website and the published documentation
 
|holding the website and the published documentation
  
Line 73: Line 112:
 
|has serveral aliases:
 
|has serveral aliases:
 
|- style="vertical-align:top;"
 
|- style="vertical-align:top;"
−
|<nowiki>{{BuildURL}}</nowiki>
+
|<nowiki>{{URL:Build}}</nowiki>
−
|{{BuildURL}}
+
|{{URL:Build}}
 
|authorative [[Git]] repository,
 
|authorative [[Git]] repository,
 
build server of the nightlies ([https://code.gnucash.org/builds/ program], [https://code.gnucash.org/docs/ source docs, documentation])
 
build server of the nightlies ([https://code.gnucash.org/builds/ program], [https://code.gnucash.org/docs/ source docs, documentation])
 
|- style="vertical-align:top;"
 
|- style="vertical-align:top;"
−
|<nowiki>{{BugURL}}</nowiki>
+
|<nowiki>{{URL:Bugs}}</nowiki>
−
|{{BugURL}}
+
|{{URL:Bugs}}
 
|[[Bugzilla]]
 
|[[Bugzilla]]
 
|- style="vertical-align:top;"
 
|- style="vertical-align:top;"
−
|<nowiki>{{ListURL}}</nowiki>
+
|<nowiki>{{URL:Lists}}</nowiki>
−
|{{ListURL}}
+
|{{URL:Lists}}  
 
|[[Mailing Lists]],
 
|[[Mailing Lists]],
 
[[IRC]] logs
 
[[IRC]] logs
Line 95: Line 134:
 
Please use the respective template in your links.
 
Please use the respective template in your links.
 
===Linking Source Files ===
 
===Linking Source Files ===
−
By default link the Maintainance branch <tt>maint</tt>. Only if you are referencing a future feature link <tt>master</tt>.
+
By default link the stable branch <tt>stable</tt>. Only if you are referencing a future feature link <tt>future</tt>.
−
:Example: https://github.com/Gnucash/gnucash/blob/maint/README.dependencies
+
:;Example: <nowiki>{{URL:git}}gnucash/blob/stable/README.dependencies</nowiki>:
 +
::{{URL:git}}gnucash/blob/stable/README.dependencies
 
===Linking Mails===
 
===Linking Mails===
−
Sometimes you wish to link a mail. Please use ''our own archives'' at '''{{ListServer}}''' in the form of '''<nowiki>{{ListURL}}</nowiki>''' instead of any mirror service.
+
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.
 
:;Background: There are several links to empty pages because Gmane lost many pages when it moved in 2016.
  
Line 195: Line 235:
 
|<pre>General text and [https://standards.freedesktop.org standards] like from [https://www.freedesktop.org/wiki/ freedesktop.org].
 
|<pre>General text and [https://standards.freedesktop.org standards] like from [https://www.freedesktop.org/wiki/ freedesktop.org].
 
;Linux: fee
 
;Linux: fee
−
;MacOS: fie
+
;{{Mac}}: fie
 
;Windows:
 
;Windows:
 
:;NT and newer: foo
 
:;NT and newer: foo
Line 201: Line 241:
 
|General text and [https://standards.freedesktop.org standards] like from [https://www.freedesktop.org/wiki/ freedesktop.org].
 
|General text and [https://standards.freedesktop.org standards] like from [https://www.freedesktop.org/wiki/ freedesktop.org].
 
;Linux: fee
 
;Linux: fee
−
;MacOS: fie
+
;{{Mac}}: fie
 
;Windows:
 
;Windows:
 
:;NT and newer: foo
 
:;NT and newer: foo
Line 207: Line 247:
 
|}
 
|}
 
This order of OSes is both: historical and alphabetical.
 
This order of OSes is both: historical and alphabetical.
 +
 +
Use the <nowiki>{{Mac}}</nowiki> template because Apple is changing its writing almost every season.

Latest revision as of 12:35, 29 January 2024

The purpose of this page is

  1. to unify the appearance of the GnuCash wiki.
    See also
    Wiki Tips
  2. develope a style, which can be easily converted to DocBook, to move sections into the official documenation.
    See
    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:
# Set MYPATH=<where you want to go>
cd "$MYPATH"
  • [optional text] like optional parameters e.g. gnc-fq-dump [-v] <source> <symbol>...
  • alternatives {on|off}
  • Repetition ...

New Pages

  1. Insert as first line at least one Category: [[Category:Foo]]
    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.
  2. optional the box of links to translations.
  3. Continue with usually one sentence abstract. Explain the
    context including links of important related pages,
    specific terms, and
    the planed coverage of the page.
  4. Finally the first section header starts the text body.

Templates

Use our 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:

Template Content Result 
42<noinclude>The Answer to Life, the Universe and Everything</noinclude>
 42

Parameters

Some templates use parameters like

Template Name Template Content
{{URL:FP}} https://{{{1|}}}flatpak.org/
{{URL:SF}} https://{{{1|}}}sourceforge.net
{{URL:wp}} https://{{{1|en}}}.wikipedia.org/wiki/

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:

Usage
Source Result
{{URL:FP|docs.}}de/latest/debugging.html https://docs.flatpak.org/de/latest/debugging.html
{{URL:SF|downloads.}}project/gnucash/gdb-windows/win32-gdb.zip https://downloads.sourceforge.net/project/gnucash/gdb-windows/win32-gdb.zip
{{URL:wp}}Linux_User_Group https://en.wikipedia.org/wiki/Linux_User_Group
{{URL:wp|de}}Linux_User_Group https://de.wikipedia.org/wiki/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:

Real Host Template URL Role
www.gnucash.org/ {{URL:www}} https://www.gnucash.org/ holding the website and the published documentation
code.gnucash.org has serveral aliases:
{{URL:Build}} https://code.gnucash.org/ authorative Git repository,

build server of the nightlies (program, source docs, documentation)

{{URL:Bugs}} https://bugs.gnucash.org/ Bugzilla
{{URL:Lists}} https://lists.gnucash.org/ Mailing Lists,

IRC logs

{{SERVER}} https://wiki.gnucash.org 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 Help:Variables .

Please use the respective template in your links.

Linking Source Files

By default link the stable branch stable. Only if you are referencing a future feature link future.

Example
{{URL:git}}gnucash/blob/stable/README.dependencies:
https://github.com/Gnucash/gnucash/blob/stable/README.dependencies

Linking Mails

Sometimes you wish to link a mail. Please use our own archives at lists.gnucash.org in the form of {{URL:Lists}} 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

Type You Type You Get
Simultaneous (i.e. for change app) <kbd>Alt</kbd>+<kbd>Tab</kbd> Alt+Tab
Sequential (i.e. for File->Import) <kbd>Alt</kbd>+<kbd>F</kbd>-<kbd>I</kbd> Alt+F-I
Wrong use, replace it please <code>Alt</code>+<code>Tab</code> Alt+Tab

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

Type You Type You Get
Subchapter 
====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.

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.

Bullet list 
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.

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
Definition list 
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
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:

You Type You Get 
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
 General text and standards like from freedesktop.org.
Linux
fee
macOS
fie
Windows
NT and newer
foo
XP and before
xyzzy

This order of OSes is both: historical and alphabetical.

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

Retrieved from "https://lists.gnucash.org/wiki/index.php?title=Wiki_Conventions&oldid=22005"