Template:GuiCommand: Difference between revisions

From FreeCAD Documentation
(Avoid duplication, and clean out template (that should explain only how to use a template, not style / structure for pages))
(30 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{|class="wikitable ct" width=100% height=100% style="float: right; width: 230px; margin-left: 1em" |
{|class="fcinfobox wikitable ct" width=100% height=100% style="float: right; width: 230px; margin-left: 1em" |
| class="ctTitle"|
| class="ctTitle" style="font-weight: bold; font-size: 125%;" |
{{#if:{{{Empty|}}}||
=== [[Image:{{{Name}}}.png|32px]] {{{Name}}} ===
{{#if:{{{Icon|}}}
|[[Image:{{{Icon}}}|32px]]<span> </span>
|{{#ifexist: Image:{{{Name}}}.svg
|[[Image:{{{Name}}}.svg|32px]]<span> </span>
|{{#ifexist: Image:{{{Name}}}.png
|[[Image:{{{Name}}}.png|32px]]<span> </span>
|[[Image:NoIconFound.png|32px|Official icon not found]]<span> </span>}}}}}}}}{{{Name}}}
|-
|-
! class="ctOdd"|Menu location
! class="ctOdd"|Menu location
Line 13: Line 20:
! class="ctOdd"|Default shortcut
! class="ctOdd"|Default shortcut
|-
|-
| class="ctEven"|{{{Shortcut|None}}}
| class="ctEven"|{{{Shortcut|''None''}}}
|-
! class="ctOdd"|Introduced in version
|-
| class="ctEven"|{{{Version|-}}}
|-
|-
! class="ctOdd"|See also
! class="ctOdd"|See also
|-
|-
| class="ctEven"|{{{SeeAlso|None}}}
| class="ctEven"|{{{SeeAlso|''None''}}}
|-
|-
| class="ctToc"|<br/>__TOC__
| class="ctToc"|<br/>__TOC__
|}
|}
[[Category:User Documentation|!]]
[[Category:User Documentation|!]]
[[Category:Command Reference]]
<noinclude><!-- Note to editors: Do Not Remove This Line. -->


==Usage==
This template is the main tool to document GuiCommands. It should be inserted as the first line in documentation pages, after the <nowiki><languages/></nowiki> and <nowiki><translate></nowiki> tags.
See a sample to the right.
{{GuiCommand
|Name=SampleCommand
|MenuLocation=Menu → Command
|Workbenches=Wb1, Wb2
|Shortcut=DefaultShortcut
|SeeAlso=OtherTopic
|Version=0.7
}}


<nowiki>{{GuiCommand
[[Category:Command Reference]]
|Name=SampleCommand
|MenuLocation=Menu → Command
|Workbenches=Wb1, Wb2
|Shortcut=DefaultShortcut
|SeeAlso=OtherTopic
|Version=0.7
}}</nowiki>


The required parameters are:
<noinclude> <!-- Note to editors: Do Not Remove This Line. -->
<nowiki>{{GuiCommand
|Name=SampleCommand
|MenuLocation=Menu → Command
|Workbenches=Wb1, Wb2
}}</nowiki>


Other parameters may be omitted or their value left empty.
==Usage==
This Template is the main anchor on documenting GuiCommands. It should be inserted as the first line in new documents.


===Required parameters===
The minimum code required for this template usage is: (sample result to right)
Parameters are specified with its value after the equals sign, <code>parameter=value</code>.
<pre>{{GuiCommand|Name=SampleCommand|MenuLocation=Sample -> Command...|Workbenches=Wb1,Wb2}}</pre>
{{GuiCommand|Name=SampleCommand|MenuLocation=Sample -> Command...|Workbenches=Wb1,Wb2|Shortcut=DefaultShortcut|SeeAlso=OtherTopic}}


Each parameter in the list is separated by a pipe symbol <code>|</code>.
===Minimum Parameters===
<nowiki>|... |Name=SampleCommand|MenuLocation=Menu → Command| ...</nowiki>
The following parameters are used in the format [parameter]=[value], with each parameter in the list separated by a pipe symbol (|):
Parameters can be placed in the same line, or each in a separate line.
;Name : The properly capitalized name of the command to be documented.
<nowiki>|...
: The name is also used to retrieve the Icon graphic in .PNG format from the WIKI repository.
|Name=SampleCommand
;MenuLocation : The location of the command in the FreeCAD menu structure.
|MenuLocation=Menu → Command
;Workbenches : One or more workbenches in FreeCAD that the command and icon can be found on.
| ...</nowiki>

The following parameters are required.

;Name
: The properly capitalized name of the command to be documented.
: The name is used to retrieve the icon graphic <code>Name.svg</code> or <code>Name.png</code> from the wiki repository. The template works properly if the icon does not exist; in this case, a generic icon [[Image:NoIconFound.png|24px]] is displayed.
;MenuLocation
: The location of the command in the FreeCAD menu structure. Please use the proper right arrow symbol (→) rather than ->.
;Workbenches
: One or more workbenches in FreeCAD that the command and icon can be found on. It should be an internal link to the workbench page, used like this:
<nowiki>[[Part Workbench|Part]]</nowiki>

The portion left of the pipe <code>|</code> is the page name, and the portion to the right is the displayed text. This example will display as [[Part Workbench|Part]].


===Optional Parameters===
===Optional Parameters===
The following parameters are optional. If they are not included in the template code, they will default to a value of "None".
The following parameters are optional. If they are not included in the template, they will default to a value of ''None'', and to a dash (-) for the <code>Version</code> parameter.
;Shortcut
;Shortcut : The default Keyboard shortcut as found in FreeCAD.
: The default keyboard shortcut to launch the command in FreeCAD, for example, <code>Shortcut=A B</code>.
;SeeAlso : Optional link to other related topics.
;SeeAlso
: Optional links to other related commands, for example, <code><nowiki>SeeAlso=[[Some Tool|Tool]]</nowiki></code>.
;Icon
: An image file different from <code>Name.svg</code> or <code>Name.png</code> to use as icon. This can be used to include a specific icon that is not named after the command, for example, <code>Icon=Some_other_name.svg</code>
;Empty
: If <code>Empty=1</code> no icon is displayed. This is done to document commands that don't have an icon, for example, commands from menus, and functions that can't be accessed from the graphical user interface.
;Version
: The FreeCAD version number in which the command was first introduced, for example, <code>Version=0.17</code>. There is no need to add the specific revision number, only the major version. Use this parameter for all new commands included in the documentation.


==Localization==
==Localization==
Line 51: Line 107:
The code required for this template is different if you are using a localized version. For more information see the [[Localisation#Translating_the_wiki|Localization]] page.
The code required for this template is different if you are using a localized version. For more information see the [[Localisation#Translating_the_wiki|Localization]] page.


* First, a localized version of this template must exist or be created.
First, a localized version of this template must exist or be created.

* The localized template must be named: <pre>Template:GuiCommand/AA</pre> where '''''/AA''''' is the 2 letter code for the desired language, for example '''''/fr''''' = French localization.
The localized template must be named:
* The method for calling the localized GuiCommand template in a GuiCommand document is: <pre>{{GuiCommand/AA|Name=SampleCommand|Name/AA=SampleCommand/AA|MenuLocation=Sample -> Commande...|Workbenches=Wb1,Wb2}}</pre> where '''''/AA''''' is the 2 letter code for the desired language, for example '''''/fr''''' = French localization.
<pre>
** In the sample code above, the ''Name'' parameter format is critical. The ''Name=SampleCommand'' allows the correct icon file to be displayed, which is not normally localized. The ''Name/AA=SampleCommand/AA'' displays the correct localized version of the GUI command documentation.
Template:GuiCommand/AA
* Make sure you add the localized version of this template to the Languages list below.
</pre>

where <code>/AA</code> is the 2 letter code for the desired language, for example <code>/fr</code> indicates French.
This are the [https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes ISO 639-1] ''language'' codes, not country codes.

The method for calling the localized GuiCommand template is:
<pre>{{GuiCommand/AA
|Name=SampleCommand
|Name/AA=SampleCommand (translated)
|MenuLocation=Menu → Commande...
|Workbenches=Wb1, Wb2
|Shortcut=DefaultShortcut
|SeeAlso=OtherTopic
|Version=0.7
}}</pre>

In the example above the <code>Name</code> parameter is critical. <code>Name=SampleCommand</code> allows the correct icon file to be displayed; <code>Name/AA=SampleCommand (translated)</code> displays the correct localized version of the command documentation.

Some templates: [[Template:GuiCommand/fr|fr]], [[Template:GuiCommand/it|it]], [[Template:GuiCommand/es|es]], [[Template:GuiCommand/pt|pt]], [[Template:GuiCommand/pt-br|pt-br]], [[Template:GuiCommand/de|de]], [[Template:GuiCommand/pl|pl]], [[Template:GuiCommand/ro|ro]], [[Template:GuiCommand/bg|bg]], [[Template:GuiCommand/cs|cs]], [[Template:GuiCommand/sk|sk]], [[Template:GuiCommand/sr|sr]], [[Template:GuiCommand/hr|hr]], [[Template:GuiCommand/ru|ru]], [[Template:GuiCommand/kk|kk]], [[Template:GuiCommand/sv|sv]], [[Template:GuiCommand/no|no]], [[Template:GuiCommand/da|da]], [[Template:GuiCommand/fi|fi]], [[Template:GuiCommand/nl|nl]], [[Template:GuiCommand/el|el]], [[Template:GuiCommand/hu|hu]], [[Template:GuiCommand/tr|tr]], [[Template:GuiCommand/uk|uk]], [[Template:GuiCommand/id|id]], [[Template:GuiCommand/ja|ja]], [[Template:GuiCommand/ko|ko]], [[Template:GuiCommand/zh|zh]], [[Template:GuiCommand/zh-cn|zh-cn]], [[Template:GuiCommand/zw-th|zw-th]]


==GuiCommand Model==
==GuiCommand model==
For a complete model of a GuiCommand, see [[GuiCommand model]].
For a complete example of how to document a GuiCommand, see [[GuiCommand model]].


[[Category:Template:Doc]]
</noinclude> <!-- Note to editors: This must be the last line of the Template. Do Not Remove This Line. -->
</noinclude> <!-- Note to editors: This must be the last line of the Template. Do Not Remove This Line. -->

Revision as of 23:18, 7 December 2018

Official icon not found {{{Name}}}

Menu location
{{{MenuLocation}}}
Workbenches
{{{Workbenches}}}
Default shortcut
None
Introduced in version
-
See also
None


Usage

This template is the main tool to document GuiCommands. It should be inserted as the first line in documentation pages, after the <languages/> and <translate> tags. See a sample to the right.

SampleCommand

Menu location
Menu → Command
Workbenches
Wb1, Wb2
Default shortcut
DefaultShortcut
Introduced in version
0.7
See also
OtherTopic


{{GuiCommand
|Name=SampleCommand
|MenuLocation=Menu → Command
|Workbenches=Wb1, Wb2
|Shortcut=DefaultShortcut
|SeeAlso=OtherTopic
|Version=0.7
}}

The required parameters are:

{{GuiCommand
|Name=SampleCommand
|MenuLocation=Menu → Command
|Workbenches=Wb1, Wb2
}}

Other parameters may be omitted or their value left empty.

Required parameters

Parameters are specified with its value after the equals sign, parameter=value.

Each parameter in the list is separated by a pipe symbol |.

|... |Name=SampleCommand|MenuLocation=Menu → Command| ...

Parameters can be placed in the same line, or each in a separate line.

|...
|Name=SampleCommand
|MenuLocation=Menu → Command
| ...

The following parameters are required.

Name
The properly capitalized name of the command to be documented.
The name is used to retrieve the icon graphic Name.svg or Name.png from the wiki repository. The template works properly if the icon does not exist; in this case, a generic icon is displayed.
MenuLocation
The location of the command in the FreeCAD menu structure. Please use the proper right arrow symbol (→) rather than ->.
Workbenches
One or more workbenches in FreeCAD that the command and icon can be found on. It should be an internal link to the workbench page, used like this:
[[Part Workbench|Part]]

The portion left of the pipe | is the page name, and the portion to the right is the displayed text. This example will display as Part.

Optional Parameters

The following parameters are optional. If they are not included in the template, they will default to a value of None, and to a dash (-) for the Version parameter.

Shortcut
The default keyboard shortcut to launch the command in FreeCAD, for example, Shortcut=A B.
SeeAlso
Optional links to other related commands, for example, SeeAlso=[[Some Tool|Tool]].
Icon
An image file different from Name.svg or Name.png to use as icon. This can be used to include a specific icon that is not named after the command, for example, Icon=Some_other_name.svg
Empty
If Empty=1 no icon is displayed. This is done to document commands that don't have an icon, for example, commands from menus, and functions that can't be accessed from the graphical user interface.
Version
The FreeCAD version number in which the command was first introduced, for example, Version=0.17. There is no need to add the specific revision number, only the major version. Use this parameter for all new commands included in the documentation.

Localization

The code required for this template is different if you are using a localized version. For more information see the Localization page.

First, a localized version of this template must exist or be created.

The localized template must be named:

Template:GuiCommand/AA

where /AA is the 2 letter code for the desired language, for example /fr indicates French. This are the ISO 639-1 language codes, not country codes.

The method for calling the localized GuiCommand template is:

{{GuiCommand/AA
|Name=SampleCommand
|Name/AA=SampleCommand (translated)
|MenuLocation=Menu → Commande...
|Workbenches=Wb1, Wb2
|Shortcut=DefaultShortcut
|SeeAlso=OtherTopic
|Version=0.7
}}

In the example above the Name parameter is critical. Name=SampleCommand allows the correct icon file to be displayed; Name/AA=SampleCommand (translated) displays the correct localized version of the command documentation.

Some templates: fr, it, es, pt, pt-br, de, pl, ro, bg, cs, sk, sr, hr, ru, kk, sv, no, da, fi, nl, el, hu, tr, uk, id, ja, ko, zh, zh-cn, zw-th

GuiCommand model

For a complete example of how to document a GuiCommand, see GuiCommand model.