Changes between Version 10 and Version 11 of DevelopersGuide/HelpSystem


Ignore:
Timestamp:
2019-02-13T13:27:29+01:00 (5 years ago)
Author:
Hb---
Comment:

Third addressing method with [wikitr: inside the wiki since March 2018

Legend:

Unmodified
Added
Removed
Modified

  • DevelopersGuide/HelpSystem

    v10 v11  
    33
    44== Help content ==
    5 Help content for the JOSM help system is maintained on the [wiki:/Help JOSM wiki].
    6 
    7 === Structure of the help content ===
     5Content for the JOSM help system is maintained on the [wikitr:/Help JOSM wiki].
     6
     7=== Structure of the help content trees ===
    88The content is structured into language specific content trees.
    9  * there is a '''default content tree''' under [wiki:/Help /Help]. Content in this tree is maintained in english.
    10  * for each supported language there is a '''language specific tree''' unter {{{/Xyz:Help}}} where {{{Xyz}}} is the [wiki:/Translations/Wiki#Languagecodes ISO language code] in title case. Examples:
     9 * The '''default content tree''' is under [wiki:/Help /Help]. Content in this tree is maintained in English.
     10 * For each supported language a '''language specific tree''' unter {{{/Xyz:Help}}} where {{{Xyz}}} is the [wikitr:/Translations/Wiki#Languagecodes ISO language code] in title case. Examples:
    1111   * [wiki:/De:Help /De:Help] - help in German
    12    * [wiki:/Zh_CN:Help /Zh_CN:Help] - help in simplified variant of Chinese
     12   * [wiki:/Zh_CN:Help /Zh_CN:Help] - help in Simplified Chinese
    1313
    1414=== Help topics ===
    15 Help topics are "addresses" of individual help pages in the JOSM help content. There are two kinds of help topics:
    16   * '''absolute help topics''' - absolute help topics consist of a pointer to help content '''including''' the language specific root. Examples:
    17     * `/Help/Action/Download` - help topic for the help content about the download action, in English
    18     * `/Fr:Help/Dialog/LayerList` - help topic for the help content about the layer dialog, in French
    19 
    20   * '''relative help topics''' - relative help topics consist of a pointer to help content '''not including''' the language specific root. They are language independent references to help content used in JOSM code. Examples:
    21     * {{{/Action/Download}}} - help topic for the help content about the download action
    22     * {{{/Dialog/LayerList}}} - help topic for the help content about the layer dialog
    23 
    24 Optionally, help topics can include a fragment after a {{{#}}}. Example: {{{/ErrorMessages#BadRequest}}}. The fragment refers to a named section in the help content and the help content should either include a HTML element with an id or a name whose value is equal to the fragment. There are three approaches for creating these HTML elements:
     15Help topics are "addresses" of individual pages in the JOSM help content. Three ways of addressing help topics exist:
     16
     17  * '''relative''' - relative addressing points to content '''not including''' the language specific root. This is used in JOSM code as language independent references to wiki content. If that language specific wiki page does not exist, then JOSM calls the English page. [[BR]] Example: `/Action/Download` - topic for the download action
     18
     19  * '''absolute''' - absolute addressing consist of a pointer '''including''' the language specific root. This should only be used when the reference needs to be language specific. [[BR]] Example: `/Fr:Help/Action/Download` - topic for the download action in French
     20
     21  * '''translated''' - translated addressing is used inside the wiki. Links point always to the default content using the `[wikitr:/Help/Action/Download]` macro. If translated content is available, Trac rewrites the target URL to it. This addressing is recommend for the Wiki. It is possible since [/ticket/16101 March 2018].
     22
     23Optionally, help topics can include a fragment after a {{{#}}}. Example: {{{/ErrorMessages#BadRequest}}}. The fragment refers to a named section in the content. So the page should either include a HTML element with an id or a name equal to the fragment. Three approaches for creating these HTML elements are possible:
    2524  1.  declare the id of a wiki heading, i.e.
    2625{{{
    … …  
    2928  2.  create a <span> with an id, i.e.
    3029{{{
    31 [=#BadRequest In case of a bad request file…]
     30[=#BadRequest In case of a bad request file] a bug or try a tea…
    3231}}}
    3332  3.  include an HTML anchor, i.e.
    … …  
    4241You're encouraged to translate help content into your language. You may start with [wiki:/DevelopersGuide/HelpSystem/HelpTopicsList this list of expected help pages] and either translate already existing pages or fill in new pages with content in other languages.
    4342
    44 '''Do not''' translate the relative help topics, though. The names of relative help topics, including the optional fragments after a {{{#}}} have to be the same in all languages. The German help page for {{{/Help/Action/Upload}}} should be {{{/De:Help/Action/Upload}}}, not {{{/Help/Aktion/Hochladen}}} or even {{{/Hilfe/Aktion/Hochladen}}}.
     43'''Do not''' translate the relative help topics, though. Their names have to be the same in all languages. The help page for {{{/Help/Action/Upload}}} in German should be {{{/De:Help/Action/Upload}}} and not {{{/Help/Aktion/Hochladen}}}. And take '''care''' of the optional fragments after a {{{#}}} and their targets.
    4544
    4645=== Help content within help pages ===