Difference between revisions of "Wiki Conventions"
(→OS Specifics: add preview) |
(→Parameters: add {{URL:FP}}) |
||
(13 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
− | The purpose of this page is to unify the appearance of the GnuCash wiki. | + | 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== | ==Categories== | ||
2-letter categories are reserved: | 2-letter categories are reserved: | ||
Line 18: | Line 24: | ||
==New Pages== | ==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> | ||
+ | |} | ||
− | ==Linking GnuCash Servers and List Archives== | + | Note that for all mentioned a default value is set. The empty string at FP and SF, but the english server at WP. |
− | ===Host Overview=== | + | 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: |
− | Currently there a 2 real hosts: | + | {| class="wikitable" |
− | ;www | + | |+Usage |
− | ; | + | |- |
− | :; | + | !scope="col" | Source |
− | + | !scope="col" | Result | |
− | :; | + | |-style="vertical-align:center;" |
− | + | |<nowiki>{{URL:FP|docs.}}de/latest/debugging.html</nowiki> | |
− | :;wiki. | + | |{{URL:FP|docs.}}de/latest/debugging.html |
− | Please use the respective | + | |-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 === | ===Linking Source Files === | ||
− | By default link the | + | By default link the stable branch <tt>stable</tt>. Only if you are referencing a future feature link <tt>future</tt>. |
− | :Example: | + | :;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 '' | + | 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. |
+ | |||
+ | ==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== | ==Subsections== | ||
Line 51: | Line 173: | ||
|Subchapter | |Subchapter | ||
|<pre> | |<pre> | ||
− | ==Feature X== | + | ====Feature X==== |
General text about Feature X. | General text about Feature X. | ||
− | ===Gnucash 2.7.0 and newer=== | + | =====Gnucash 2.7.0 and newer===== |
We use fee. | We use fee. | ||
− | ===Gnucash 2.6.20 and before=== | + | =====Gnucash 2.6.20 and before===== |
We use foo. | We use foo. | ||
</pre> | </pre> | ||
| | | | ||
+ | |||
==Feature X== | ==Feature X== | ||
General text about Feature X. | General text about Feature X. | ||
Line 112: | 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 | ||
− | ; | + | ;{{Mac}}: fie |
;Windows: | ;Windows: | ||
:;NT and newer: foo | :;NT and newer: foo | ||
Line 118: | 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 | ||
− | ; | + | ;{{Mac}}: fie |
;Windows: | ;Windows: | ||
:;NT and newer: foo | :;NT and newer: foo | ||
Line 125: | Line 248: | ||
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
- to unify the appearance of the GnuCash wiki.
- See also
- Wiki Tips
- 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
Contents
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
- 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.
- 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 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:
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.
|
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 XGeneral text about Feature X. Gnucash 2.7.0 and newerWe use fee. Gnucash 2.6.20 and beforeWe 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.
|
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.
|
- 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.
|
This order of OSes is both: historical and alphabetical.
Use the {{Mac}} template because Apple is changing its writing almost every season.