WikiPages: Difference between revisions

From FreeCAD Documentation
(removed www from https://wiki.freecad.org/Main_Page. Don't know the right wording for Codeextralink.)
 
(205 intermediate revisions by 15 users not shown)
Line 1: Line 1:
<languages/>
[[Category:Documentation]]
[[Category:Wiki]]
[[Category:Wiki Documentation]]
{{TOCright}}
{{TOCright}}
<translate>
This page is an extension of the page [[Help:Editing|Help:Editing]] and gives common guidelines on the best practices to be followed when writing or updating FreeCAD documentation. It summarizes discussions and brainstorming as it relates to the FreeCAD documentation.


<!--T:1-->
==Before Starting==
This page is an extension of the [[Help:Editing|Help:Editing]] page and gives common guidelines for writing and updating the FreeCAD wiki documentation. It summarizes several discussions and brainstorming sessions
This wiki documentation is based on [https://www.mediawiki.org/wiki/MediaWiki MediaWiki], the same software that powers [https://en.wikipedia.org/wiki/Main_Page Wikipedia]. If you have contributed to Wikipedia before, editing FreeCAD wiki pages should be easy.


== Before starting == <!--T:155-->
If you have never used wiki software before, head to [[Help:Editing]] to become familiar with the markup used to edit pages.


<!--T:3-->
For advanced usage of the wiki software, see [https://www.mediawiki.org/wiki/Help:Contents MediaWiki Help:Contents]. Not all features of MediaWiki are available in this FreeCAD wiki, but many of them are.
* This wiki documentation is based on [https://www.mediawiki.org/wiki/MediaWiki MediaWiki], the same software that powers [https://en.wikipedia.org/wiki/Main_Page Wikipedia]. If you have contributed to Wikipedia, editing FreeCAD wiki pages should be easy.
We like to keep the documentation simple to read, so avoid using complex features. Keep it simple.
* Contrary to Wikipedia, the FreeCAD wiki is write-protected to avoid spam. You must request an account [http://forum.freecadweb.org/viewtopic.php?f=21&t=6830 on the forum].
* If you have never used wiki software before, please read [[Help:Editing]] to become familiar with the markup that is used.
* For advanced use of the wiki software, see [https://www.mediawiki.org/wiki/Help:Contents MediaWiki Help:Contents]. Not all features of MediaWiki are available in this FreeCAD wiki, but many are.
* We like to keep the documentation easy to read, so avoid using complex features. Keep it simple.
* Use a sandbox to test your code, for example, [[FreeCADDocu:Sandbox]] or a particular page with your name [[Sandbox:Yourname]]. Sandbox pages must be placed in the Sandbox category. This is done by adding <code><nowiki>[[Category:Sandbox]]</nowiki></code> at the bottom of the wiki code.
* Please be aware of the translations. The FreeCAD wiki uses automated translation support to provide pages in many languages. For every page multiple language versions can exist. On many pages you will see tags like <code>&lt;translate&gt;...&lt;/translate&gt;</code> and many single tags like <code>&lt;!--T:8--&gt;</code>. The latter mark so-called translation units and are created by the translation system, you should never create them manually. They link the headings and paragraphs to their translated versions. You should not change them as that would destroy those links. It is however fine to move paragraphs or change wording as long as the tags stay with them. If you remove a heading or a paragraph you should also remove the tag belonging to it. Please be aware that changes to existing headings and paragraphs affect the current translations. Your changes should be worth it. Do not worry when adding new material because the system will add new tags automatically after your edits. For more information see [[Localisation|Localisation]] and the original [https://www.mediawiki.org/wiki/Help:Extension:Translate/Page_translation_example Mediawiki:Extension:Translate page].


== General guidelines == <!--T:4-->
Use a sandbox to test your code, for example, [[FreeCADDocu:Sandbox]] or a particular page with your name [[Sandbox:Yourname]].


=== Concise descriptions === <!--T:156-->
Please be aware of the translations. The FreeCAD wiki uses automated translation support to provide pages in many languages. It is like a 3rd dimension: every page could exist in multiple language versions.<br>
On many pages you will see tags like <code><nowiki><translate>...</translate></nowiki></code> and many single tags like this <code><nowiki><!--T:8--></nowiki></code> in many sections. The former enable translation support. Do not change them. The latter are created by the system. They link the headlines/paragraphs with their translated versions. If you change the numbering obviously you will destroy those links. However, it is fine to move paragraphs or change wording as long as the tags stay with them. If you remove a paragraph you should remove the tag with it. Please be aware that changes to existing headlines and paragraphs potentially affect current translations. Your changes should be worth it. Do not worry when adding new material because the system will add new tags automatically after your edits. For more information see [[Localisation|Localisation]] and the original [https://www.mediawiki.org/wiki/Help:Extension:Translate/Page_translation_example Mediawiki:Extension:Translate page].


<!--T:5-->
==General Guidelines==
When describing FreeCAD try to be concise and to the point and avoid repetition. Describe what FreeCAD ''does'', not what FreeCAD ''does not do''. Also avoid colloquial expressions such as 'a couple'. Use 'some' when dealing with an indeterminate number, or specify the correct quantity.


<!--T:67-->
===Concise descriptions===
; Bad description
When describing FreeCAD functionality try to be concise and to the point. Describe what FreeCAD ''does'', not what FreeCAD ''does not do''. There might be exceptions for justifying why FreeCAD does not support a certain functionality, for instance, to explain how FreeCAD is different from other CAD systems.
: [[PartDesign_Workbench|PartDesign Workbench]]: the PartDesign Workbench is a workbench for part design that aims to provide tools for modelling complex solid parts.


<!--T:69-->
===Centralized information===
; Good description
: [[PartDesign_Workbench|PartDesign Workbench]]: aims to provide tools for modelling complex solid parts.

=== Centralized information === <!--T:157-->

<!--T:6-->
Avoid duplicating the same information in different places. Insert the information in a new page, and link to this page from other pages that require this information.
Avoid duplicating the same information in different places. Insert the information in a new page, and link to this page from other pages that require this information.


<!--T:7-->
Do not use transclusion of pages ([[Help:Editing#Templates and transcluding pages|Help:Editing#Templates and transcluding pages]]), as this makes the wiki difficult to translate. Use only the templates described below in [[#Templates|#Templates]].
Do not use transclusion of pages ([[Help:Editing#Templates_and_transcluding_pages|Help:Editing#Templates and transcluding pages]]), as this makes the wiki difficult to translate. Use only the templates described below in [[#Templates|#Templates]].


===Styling===
=== Styling === <!--T:158-->
Templates are used for styling the text used in the help pages.


<!--T:9-->
There is a template for styling menu commands, like {{MenuCommand|File → Save}}, another template to style keys to be pressed, like {{KEY|Shift}}, another template to show a Boolean value {{TRUE}}, etc. This allows the documentation to have a consistent look and feel, as well as being able to be translated without much effort. Please get familiar with the [[#Templates|#Templates]] section before writing help pages.
Templates are used to style the help pages. They give the documentation a consistent look and feel. There is a template for menu commands, {{MenuCommand|File → Save}}, a template to style keys to be pressed, {{KEY|Shift}}, to show a Boolean value, {{TRUE}}, etc. Please get familiar with the [[#Templates|#Templates]] section before writing help pages.


=== Temporary flags === <!--T:159-->
==Examples==


<!--T:10-->
You can quickly get familiar with the structure and style of the FreeCAD wiki by looking at the following pages, which can be considered reference pages for the rest of the FreeCAD documentation.
If you are working on a large page it is advisable to mark the page either as a work in progress or as unfinished. This assures that wiki admins don't mark your page as ready for translation while you are still changing it.
* [[Draft ShapeString]]
* [[Draft Line]]


<!--T:11-->
==Structure==
To flag a page add either <code><nowiki>{{Page in progress}}</nowiki></code> or <code><nowiki>{{UnfinishedDocu}}</nowiki></code> as the first line. With <code><nowiki>{{UnfinishedDocu}}</nowiki></code> you invite others to join you in finishing the page, while <code><nowiki>{{Page in progress}}</nowiki></code> indicates that you will do the work yourself and others should give you some time.


<!--T:12-->
===General===
Once the work is done, please don't forget to remove the flags!
You should normally not use a '''=header=''' section for a page, since the page title is automatically added.


== Examples == <!--T:13-->
The [[User hub|User hub]] provides a [[Online Help Toc|Table of Contents]]; this is used as the main reference for automatically building the offline help you can reach from FreeCAD, as well as the offline PDF documentation.


<!--T:14-->
The [[Template:Docnav]] is used to link to the page before and the page after, according to the structure of the [[Online Help Toc|Table of Contents]].
To quickly get familiar with the structure and style of the FreeCAD wiki look at the model page: [[GuiCommand_model|GuiCommand model]].
See [[#Templates|#Templates]] for a list of all templates.


</translate>
===Page names===
<div class="mw-collapsible mw-collapsed toccolours">
Page names should be short, and they should use "sentence case", as opposed to "title case". This is the [https://en.wikipedia.org/wiki/Wikipedia:Manual_of_Style/Capital_letters#Headings,_headers,_and_captions style used by Wikipedia] for their articles.
<translate>


== Structure == <!--T:15-->
Essentially, all words except the first one and proper names, should be in lowercase.
</translate>
<div class="mw-collapsible-content">
<translate>
<!--T:16-->
The [[User_hub|User hub]] provides a [[Online_Help_Toc|Table of Contents]]. This is used as the main reference for automatically building the offline help you can reach from FreeCAD, as well as the offline PDF documentation.


<!--T:17-->
:{{emphasis|Use:}} Tutorial on the construction of AeroCompany airplanes
The [[Template:Docnav]] is used to sequentially link pages, following the structure of the [[Online_Help_Toc|Table of Contents]]. See [[#Templates|#Templates]] for a list of all templates.
:{{emphasis|Avoid:}} Tutorial On The Construction Of AeroCompany Airplanes


=== Page names === <!--T:160-->
{{emphasis|Note:}} a previous convention was to use title case; every word should begin with a capital letter, unless they are articles, prepositions, conjunctions, or other grammatical particles, that is, "of, on, in, a, an, and", etc. There are many pages using this style, but this is discouraged for new pages. This is discussed in the forum thread [https://forum.freecadweb.org/viewtopic.php?p=266029#p266029 (Lowercase links) Use a lower case title for a wiki page].


<!--T:18-->
====Page names for workbench, tools, and GuiCommand help====
Page names should be short and they should use title case: every word should begin with a capital letter, unless they are articles, prepositions, conjunctions, or other grammatical particles (f.e. 'of', 'on', 'in', 'a', 'an', 'and').
The top level workbench page must have the format '''XYZ Workbench''', where '''XYZ''' is the name of the workbench.


<!--T:20-->
Pages describing the tools ([[Gui Command|Gui Command]]s) of the workbench must have the format '''XYZ Tool''', where '''Tool''' is the name of the specific tool. Every GuiCommand has to have a help page. To create your own help pages you can use the template [[GuiCommand model|GuiCommand model]].
; Bad page name:
: Construction of AeroCompany airplanes


<!--T:161-->
; Bad name
; Good page name:
*[[Working with architectural objects|Working with architectural objects]]
: Construction of AeroCompany Airplanes
*[[Working with architectural walls|Working with architectural walls]]
*[[Drafting 2D objects|Drafting 2D objects]]
*[[Tool: building a line between two points|Tool: building a line between two points]]


<!--T:22-->
; Good name
The names of top level workbench pages must have this format: <code>XYZ Workbench</code>, where <code>XYZ</code> is the name of the workbench, for example [[PartDesign_Workbench|PartDesign Workbench]]. And the names of pages describing the commands (or tools) belonging to a workbench must have this format: <code>XYZ Command</code>, for example [[PartDesign_Pad|PartDesign Pad]]. Note that you should use the command name as it occurs in the source code.
*[[Arch Workbench|Arch Workbench]]
*[[Arch Wall|Arch Wall]]


=== Headings === <!--T:162-->
*[[Draft Workbench|Draft Workbench]]
*[[Draft Line|Draft Line]]


<!--T:163-->
===Links===
Paragraph headings should be short and use sentence case: all words except the first one and proper names, should be in lowercase. You should not use <code><nowiki>H1</nowiki></code> headings (<code><nowiki>=&nbsp;Heading&nbsp;=</nowiki></code>) in your wiki markup since the page title is automatically added as the main <code><nowiki>H1</nowiki></code> heading.
You should use the original link name for the links whenever possible. This clarifies the referenced page in printed or offline documentation. You must avoid the usage of non-meaningful words for the link.


====Bad link====
=== Links === <!--T:164-->
*For more information on this topic, click [[Draft Workbench|here]].


<!--T:26-->
====So-so link====
You should use the original link name for links whenever possible. This clarifies the referenced page in printed or offline documentation. Please avoid non-meaningful words for the link.
*For more information on this topic, refer to [[Draft Workbench|drafting 2D objects]].


<!--T:27-->
====Good link====
; Bad link
*For more information on this topic, see how to draft 2D objects in the [[Draft Workbench|Draft Workbench]].
: For more information on drafting 2D objects click [[Draft_Workbench|here]].


<!--T:29-->
==== Page navigation ====
; Good link
Navigation links help the user to browse through the wealth of information in this wiki. Consider the use of to following to make browsing more fun to the reader
: For more information on drafting 2D objects refer to the [[Draft_Workbench|Draft Workbench]].
* "top" links. For long pages, you could go back to the table of contents.
* "back" links. This allows to get back to a certain issue. A back link is much ore useful than the browsers "back" button because it contains structural information. A backlink could lead you up one stage on the hierarchy of information. For example see the [[External Workbenches#General|External Workbenches]]: from whereever you arrive an a page about an external workbench you might want to see what other workbenches are available.


<!--T:39-->
See the next section on how to do these links.
The preferred format for a link is:


<!--T:40-->
[[#top|top]]
<code><nowiki>[[Name_of_Page|Name of Page]]</nowiki></code>


<!--T:41-->
===== Top Page Links =====
Translated:
Just use type the following at the place where you want the top link.


<!--T:42-->
<nowiki>[[#top|top]]</nowiki>
<code><nowiki>[[Name_of_Page/fr|Nom de la Page]]</nowiki></code>


<!--T:43-->
You could put it at the end of each chapter. Make sure to have an empty line before, so it stays free of the last paragraph.
Note that for the part before the <code><nowiki>|</nowiki></code> character, the actual link, case is relevant. If your page name is <code><nowiki>Name_of_page</nowiki></code> the link will fail if you type <code><nowiki>Name_of_Page</nowiki></code> (upper case P). Before the <code><nowiki>|</nowiki></code> character all spaces should be replaced by underscores (<code><nowiki>_</nowiki></code>). This is to assist translators using translation software, without the underscores the link would be translated by the software which is undesirable.


<!--T:44-->
:''Note 1: If you know the MediaWiki platform you might note that this works even without defining "top" as a link target using <nowiki><div></nowiki>. This only works of course if the "top" is not used for other things. ''
To link to a certain paragraph add a <code><nowiki>#</nowiki></code> sign and its headings to the page name. Example:
:''Note 2: Should you think that is useful you can just start to practice a bit by putting a "top" link at the end of every section of this really long page.''


<!--T:45-->
[[#top|top]]
<code><nowiki>[[WikiPages#Links|WikiPages]]</nowiki></code>


<!--T:48-->
===== Back Links =====
Translated:
For a back link you have 2 choices:
:* go back to the top of another page
:* go back to a certain section of another page
For the user it may be more convenient to get right to the relevant section of a page, e.g. a list of similar items.


<!--T:49-->
The general format of a link is
<code><nowiki>[[WikiPages/fr#Liens|WikiPages]]</nowiki></code>


<!--T:50-->
<nowiki>[[pagename|pagename]]</nowiki>
Within the same page you can omit the page name. Example:


<!--T:165-->
For translate this line:
<code><nowiki>[[#Links|Links]]</nowiki></code>


<!--T:33-->
<nowiki>[[pagename/fr|nom de la page]]</nowiki>
To link to the top of the page you can use:


</translate>
For this page it would be <code><nowiki>[[WikiPages|WikiPages]]</nowiki></code>. Note that the case is relevant. If your page name is "WikiPages" the link will fail if you type "Wikipages" (lower case 'p'). Best practice is to open the page in another tab and copy & paste the page name.
<code><nowiki>&lt;/translate&gt;{{Top}}&lt;translate&gt;</nowiki></code>
<translate>


<!--T:35-->
To use a certain section as link target you just add the section name (i.e. the headline text) after a '#' sign behind the page name. Example:
This template should automatically display the correct text depending on the language of the page. A link to the top of the page is especially useful for long pages as it allows the user to quickly jump back to the table of content. You can put it at the end of each paragraph. Make sure there is an empty line before and after the template.


<!--T:226-->
<nowiki>[[WikiPages#Top Page Links]]</nowiki>
; Image link
: [[Image:Draft_Wire.svg|24px|Optional text that is shown when you hover the image|link=Draft_Wire]]


<!--T:227-->
The result is a bit ugly, because of the '#' in [[WikiPages#Top Page Links]]. This can be avoided by using the '|' syntax to enter a label. See this example:
To use an image as a link:


<!--T:228-->
<nowiki>[[WikiPages#Top Page Links|WikiPages]]</nowiki>
<code><nowiki>[[Image:Draft_Wire.svg|24px|Optional text that is shown when you hover the image|link=Draft_Wire]]</nowiki></code>


<!--T:229-->
For translate this line:
; Image link + text link
: [[Image:Draft_Wire.svg|24px|link=Draft_Wire]] [[Draft_Wire|Draft Wire]]


<!--T:230-->
<nowiki>[[WikiPages/fr#Début|WikiPages début]]</nowiki>
If you leave out the optional text the link itself will be shown when the image is hovered, which is preferable, and you should also add a text link after the image link:


<!--T:231-->
Instead of "WikiPages" you can put in any text you like. The result is much better: [[WikiPages#Top Page Links|WikiPages]] or [[WikiPages#Top Page Links|WikiPages/Top Page Links]] or whatever you like. Its a bit more to type in the source but thats a small price to pay for excellent usability. Within the same page you do the same but you can omit the page name, e.g. <code><nowiki>[[#Top Page Links|Top Page Links]]</nowiki></code> gives [[#Top Page Links|Top Page Links]].
<code><nowiki>[[Image:Draft_Wire.svg|24px|link=Draft_Wire]] [[Draft_Wire|Draft Wire]]</nowiki></code>


=== Workbench pages === <!--T:166-->


<!--T:52-->
[[#top|top]]
A top level workbench page should start with:
* A description of what the workbench is used for.
* An image to illustrate the description.


<!--T:53-->
===Workbench pages===
See [[#Screen_capture|#Screen capture]] for conventions on including images.
Every page of a workbench should start with:
* the name of the workbench,
* an image of the look of the workbench (menu and toolbar in their default position), and
* a description of what the workbench is used for


=== Command pages === <!--T:167-->
See [[#Screen capture]] for conventions on including images.


<!--T:54-->
===Command (tool) pages===
The command pages describing workbench tools should not be too long, they should only explain what a command can do and what it can't, and how to use it. You should keep pictures and examples to a minimum; tutorials can expand on how to use the tool and provide step-by-step details.
Command pages describing workbench tools should not be too long, they should only explain what a command can do and what it can't, and how to use it. You should keep pictures and examples to a minimum. Tutorials can expand on how to use the tool and provide step-by-step details.


<!--T:56-->
Limitations and shortcomings should be documented right in the command page, possibly under a "restrictions" or "limitations" section.
Please refer to the [[GuiCommand_model|GuiCommand model]] page for more details.


=== Tutorials === <!--T:168-->
Please refer to the [[Gui Command|Gui Command]] page for specific indications on how these commands should be presented, and use the [[GuiCommand model|GuiCommand model]] to start filling the information where appropriate.
Use [[Boiler NonCommand|Boiler NonCommand]] to fill in information that is not related to a command.


<!--T:57-->
===Tutorials===
A well written tutorial should teach the user how to achieve certain practical results quickly.
A well written tutorial should teach how to achieve certain practical results quickly. It shouldn't be too long, but should include sufficient step-by-step instructions and images to guide the user. As FreeCAD evolves, tutorials may become obsolete, so it is important to mention the FreeCAD version used in, or required for, a tutorial.
It shouldn't be extremely long, but it should include a sufficient amount
of step-by-step instructions and pictures to guide the user on using different tools.


<!--T:60-->
A series of tutorials in which each increases in complexity could be helpful to explore basic,
For examples visit the [[Tutorials|Tutorials]] page.
intermediate, and expert tools in one or more workbenches.
</translate>
</div> <!-- End of collapsible element for Structure section. Do not remove! -->
</div> <!-- End of collapsible element for Structure section. Do not remove! -->


<div class="mw-collapsible mw-collapsed toccolours">
See the [[tutorial guidelines|tutorial guidelines]] for a basic idea on how to set up a tutorial.
<translate>


== Templates == <!--T:70-->
See some examples
</translate>
* [[Tutorials|Tutorials]], already written and accessible from the sidebar
<div class="mw-collapsible-content">
* [http://freecad-tutorial.blogspot.it FreeCAD tutorial - Unofficial tutorial blog], for other example tutorials
<translate>
<!--T:71-->
Styling of the FreeCAD wiki pages is achieved through the use of templates ([[Help:Editing#Templates_and_transcluding_pages]]). They ensure a standardized look and feel across all pages, and also make it possible to re-style the wiki. You can see the complete list of defined templates by accessing [[Special:PrefixIndex/Template:]]. But please only use the templates listed in the tables below. Only in very special cases should you use HTML tags directly.


<!--T:73-->
As FreeCAD evolves, some tutorials may become too old for modern versions of the program,
Click on the template link to see the usage instructions for a template, and to see its implementation. Templates are a powerful feature of the MediaWiki software. You should be an experienced wiki user if you wish to propose additions and modifications to existing templates. If implemented incorrectly, templates make it difficult to translate pages into other languages, so their use should be limited to text formatting, page transclusion should be avoided. See [https://www.mediawiki.org/wiki/Help:Templates MediaWiki Help:Templates] to learn more.
so it is important to mention the version or limitations of the tools used in that specific version of the tutorial.


=== Simple templates === <!--T:170-->
== Language ==


<!--T:74-->
===Expressions===
These templates accept a simple text parameter, and format it with a particular style.
You should avoid colloquial generic expressions as "a couple". Please re-phrase as "some" if an indeterminate number, or use the correct quantity.
{|{{Prettytable}}
!style="width:10%;"|Template
!style="width:20%;"|Appearance
!style="width:70%;"|Description


<!--T:236-->
===Conciseness===
|--
Try to avoid repetitions to keep descriptions short.
|[[Template:Top|Top]]
|


</translate>{{Top}}<translate>
====Bad description====


<!--T:238-->
[[PartDesign Workbench|PartDesign Workbench]]: the PartDesign Workbench is a workbench for part design that aims to provide tools for modelling complex solid parts.
|Use it to add a link to the top of the page.


<!--T:171-->
====Good description====
|--
|[[Template:Emphasis|Emphasis]]
|{{Emphasis|emphasis}}
|Use it to emphasize a piece of text.


<!--T:172-->
[[PartDesign Workbench|PartDesign Workbench]]: aims to provide tools for modelling complex solid parts.
|--
|[[Template:KEY|KEY]]
|{{KEY|Alt}}
|Use it to indicate a keyboard key that needs to be pressed.


<!--T:173-->
==Style==
|--
|[[Template:ASCII|ASCII]]
|{{ASCII|A}}
|Use it to indicate a ascii key in a image (.svg) that needs to be pressed. You must give the character desired or the number of the code ascii of the character.


<!--T:174-->
===Templates===
|--
|[[Template:Button|Button]]
|{{Button|Cancel}}
|Use it to indicate a button in the graphical user interface that needs to be pressed.


<!--T:175-->
Styling of FreeCAD wiki pages is achieved through the usage of templates ([[Help:Editing#Templates_and_transcluding_pages]]). Please only use the templates listed in the tables below; doing this will allow re-styling the entire wiki by updating the template, and help achieve a standardized look and feel across all pages. Only for special cases should you use HTML tags directly.
|--
|[[Template:RadioButton|RadioButton]]
|{{RadioButton|Option}}
|Use it to indicate a radio button in the graphical user interface that needs to be {{RadioButton|TRUE|Selected}} or {{RadioButton|FALSE|Not}}.


<!--T:176-->
You can see the complete list of defined templates by accessing [[Special:PrefixIndex/Template:]]. However, not all templates listed there are used for styling the text, and others are deprecated; please use only the ones in the tables below.
|--
|[[Template:CheckBox|CheckBox]]
|{{CheckBox|Option}}
|Use it to indicate a checkbox in the graphical user interface that needs to be {{CheckBox|TRUE|Checked}} or {{CheckBox|FALSE|Not}}.


<!--T:177-->
Click on the template link to see the usage instructions for the template, and to see its implementation. Templates are a powerful feature of the MediaWiki software; you should be an experienced wiki user if you wish to propose additions and modifications to existing templates. If implemented incorrectly, templates make it difficult to translate pages into other languages, so their use should be limited to text formatting; page transclusion should be avoided. See [https://www.mediawiki.org/wiki/Help:Templates MediaWiki Help:Templates] to learn more.
|--
|[[Template:SpinBox|SpinBox]]
|{{SpinBox|1.50}}
|Use it to indicate a spinbox in the graphical user interface that needs to be modified.


<!--T:178-->
====Simple styling templates ====
|--
These templates accept a simple text parameter, and format it with a particular style.
|[[Template:ComboBox|ComboBox]]
{|{{Prettytable}}
|{{ComboBox|Menu 1}}
!Template
|Use it to indicate a combobox in the graphical user interface that needs to be modified.
!Appearance

!Description
<!--T:239-->
|--
|--
|[[Template:Emphasis|Emphasis]]
|[[Template:LineEdit|LineEdit]]
|{{Emphasis|emphasis}}
|{{LineEdit|Metal Nickel (Ni)}}
|Use it to emphasize a piece of text.
|Use it to indicate a LineEdit in the graphical user interface that needs to be modified.
|--

|[[Template:KEY|KEY]]
<!--T:179-->
|{{KEY|Alt}}
|--
|Use it to indicate a keyboard key that needs to be pressed.
|[[Template:FALSE|FALSE]], [[Template:false|false]]
|--
|{{FALSE}}, {{false}}
|[[Template:Button|Button]]
|Use it to indicate a False Boolean value, for example, as a property in the [[Property_editor|property editor]]. This is a shortcut. Since it is a value, prefer Template [[Template:Value|Value]] {{Value|false}}
|{{Button|Cancel}}

|Use it to indicate a button in the graphical user interface that needs to be pressed.
<!--T:180-->
|--
|--
|[[Template:FALSE|FALSE]]
|[[Template:TRUE|TRUE]], [[Template:true|true]]
|{{FALSE}}
|{{TRUE}}, {{true}}
|Use it to indicate a False Boolean value, for example, as a property in the [[property editor|property editor]].
|Use it to indicate a True Boolean value, for example, as a property in the [[Property_editor|property editor]]. This is a shortcut. Since it is a value, prefer Template [[Template:Value|Value]] {{Value|true}}
|--

|[[Template:TRUE|TRUE]]
<!--T:181-->
|{{TRUE}}
|--
|Use it to indicate a True Boolean value, for example, as a property in the [[property editor|property editor]].
|[[Template:MenuCommand|MenuCommand]]
|--
|[[Template:MenuCommand|MenuCommand]]
|{{MenuCommand|File → Save}}
|Use it to indicate the location of a command inside a particular menu.
|{{MenuCommand|File → Save}}

|Use it to indicate the location of a command inside a particular menu.
<!--T:182-->
|--
|--
|[[Template:FileName|FileName]]
|{{FileName|File name}}
|[[Template:FileName|FileName]]
|{{FileName|File name}}
|Use it to indicate a name of a file or directory.
|Use it to indicate a name of a file or directory.
|--

|[[Template:SystemInput|SystemInput]]
<!--T:183-->
|{{SystemInput|Type this text}}
|--
|Use it to indicate user typed input text.
|[[Template:SystemInput|SystemInput]]
|--
|{{SystemInput|Type this text}}
|[[Template:SystemOutput|SystemOutput]]
|Use it to indicate user typed input text.
|{{SystemOutput|Output text}}

|Use it to indicate text output from the system.
<!--T:184-->
|--
|--
|[[Template:Optional|Optional]]
|[[Template:SystemOutput|SystemOutput]]
|{{Optional|Insert or not}}
|{{SystemOutput|Output text}}
|Use it in programming descriptions to indicate a text or function argument that is optional.
|Use it to indicate text output from the system.
|--

|[[Template:Choice|Choice]]
<!--T:185-->
|{{Choice|This|That}}
|--
|Use it in programming descriptions to indicate a choice between two values.
|[[Template:Incode|Incode]]
|--
|{{incode|import FreeCAD}}
|[[Template:Incode|Incode]]
|Use it to include in-line source code with a monospace font. It should fit in one line.
|{{incode|import FreeCAD}}

|Use it to include in-line source code with a monospace font. It should fit in one line.
<!--T:186-->
|--
|--
|[[Template:Variable|Variable]]
|[[Template:PropertyView|PropertyView]]
|{{Variable|MyAttribute|TYPE}}
|{{PropertyView|Color}}
|Use it in programming descriptions to indicate a value or a parameter, optionally with a type in front of it.
|Use it to indicate a View property in the [[Property_editor|property editor]]. Examples of View properties include {{emphasis|Line Color}}, {{emphasis|Line Width}}, {{emphasis|Point Color}}, {{emphasis|Point Size}}, etc.
|--

|[[Template:PropertyView|PropertyView]]
<!--T:187-->
|{{PropertyView|Color}}
|--
|Use it to indicate a View property in the [[property editor|property editor]]. View properties are like {{emphasis|Line Color}}, {{emphasis|Line Width}}, {{emphasis|Point Color}}, {{emphasis|Point Size}}, etc.
|[[Template:PropertyData|PropertyData]]
|--
|[[Template:PropertyData|PropertyData]]
|{{PropertyData|Position}}
|Use it to indicate a Data property in the [[Property_editor|property editor]]. Data properties are different for different types of objects.
|{{PropertyData|Position}}

|Use it to indicate a Data property in the [[property editor|property editor]]. Data properties are different for different types of objects.
<!--T:188-->
|--
|--
|[[Template:Properties Title|Properties Title]] / [[Template:TitleProperty|TitleProperty]]
|[[Template:Properties Title|Properties Title]] / [[Template:TitleProperty|TitleProperty]]
|{{Properties_Title|Base}}
|{{Properties_Title|Base}}
|Use it to indicate the title of a property group in the [[property editor|property editor]]. The title will not be included in the automatic table of contents.
|Use it to indicate the title of a property group in the [[Property_editor|property editor]]. The title will not be included in the automatic table of contents.
|--

|[[Template:PropertyTasks|PropertyTasks]] / [[Template:TasksTag|TasksTag]]
<!--T:189-->
|{{PropertyTasks|Tasks}}
|--
|Use it to indicate the argument for tasks.
|[[Template:Obsolete|Obsolete]]
|--
|{{Obsolete|0.19}}
|[[Template:TitleTasks|TitleTasks]]
|Use it to indicate that a feature became obsolete in the specified FreeCAD version.
|{{TitleTasks|Tasks Title}}

|Use it to indicate the title for tasks.
<!--T:190-->
|--
|--
|[[Template:Version|Version]]
|{{Version|0.18}}
|[[Template:Version|Version]]
|{{Version|0.18}}
|Use it to indicate that a particular feature is available only starting with a specific FreeCAD version.
|Use it to indicate that a feature was introduces in the specified FreeCAD version.
|--

|[[Template:Obsolete|Obsolete]]
<!--T:191-->
|{{Obsolete|0.19}}
|--
|Use it to indicate that a particular feature is obsolete starting with a specific FreeCAD version.
|[[Template:VersionMinus|VersionMinus]]
|--
|{{VersionMinus|0.16}}
|[[Template:ColoredText|ColoredText]]
|Use it to indicate that a feature is available in the specified FreeCAD version and earlier versions.
|{{ColoredText|Colored Text}}

|Use this template to colored the background, text or background and text. ([[Template:ColoredText|ColoredText]] page for more examples)
<!--T:192-->
|--
|--
|[[Template:ColoredParagraph|ColoredParagraph]]
|[[Template:VersionPlus|VersionPlus]]
|{{ColoredParagraph|Colored Paragraph}}
|{{VersionPlus|0.17}}
|Use this template to colored the background, text or background and text along the entire length of the page. ([[Template:ColoredParagraph|ColoredParagraph]] page for more examples)
|Use it to indicate that a feature is available in the specified FreeCAD version and later versions.

<!--T:193-->
|--
|[[Template:ColoredText|ColoredText]]
|{{ColoredText|Colored Text}}
|Use this template to color the background, text, or background and text. ([[Template:ColoredText|ColoredText]] page for more examples)

<!--T:194-->
|--
|[[Template:ColoredParagraph|ColoredParagraph]]
|{{ColoredParagraph|Colored Paragraph}}
|Use this template to color the background, text, or background and text of an entire paragraph. [[Template:ColoredParagraph|ColoredParagraph]] page for more examples)
|}
|}


====More complex templates ====
=== Complex templates === <!--T:195-->

<!--T:75-->
These templates require more input parameters, or produce a block of text with a particular format.
These templates require more input parameters, or produce a block of text with a particular format.
{|{{Prettytable}}
!Template
!Appearance
!Description
|--
|[[Template:Prettytable|Prettytable]]
|This table
|Use it to format tables such as this one; additional table properties can be added.
|--
|[[Template:Caption|Caption]]
|{{Caption|Some caption for an image}} {{Caption|align=center|Some caption for an image (centered)}}
|Use it to indicate an explanation text below an image in the documentation and tutorials. It can be left aligned or center aligned.
|--
|[[Template:Clear|Clear]]
|
|Use it to clear columns. Follow the definition of the template for a detailed explanation. It is often used to stop text from flowing next to unrelated images.
|--
|[[Template:Code|Code]]
|{{Code|code=import FreeCAD}}
|Source code style. Use it to include multi-line code examples with a monospace font. The default language is Python, bur other languages can be specified.
|--
|[[Template:Fake heading|Fake heading]]
|{{Fake heading|Heading|2}}
|Use it to create create a heading that will not be included automatically in the table of contents that is used for the offline documentation.
|--
|[[Template:GuiCommand|GuiCommand]]
|See [[Gui Command|Gui Command]] and [[GuiCommand model|GuiCommand model]]
|Use it to create a box with useful information to document workbench tools (GuiCommands) of FreeCAD.
|--
|[[Template:Macro|Macro]]
|See example [[Macro FlattenWire|Macro FlattenWire]]
|Use it to create a box with useful information to document [[macros|macros]].
|--
|[[Template:Docnav|Docnav]]
|{{Docnav|Online Help Startpage|Feature list}}
|Use it to create a bar with the words "next", "previous", and "index", and links to the appropriate articles, which is useful for navigating certain help pages which go in a particular sequence.
|--
|[[Template:VeryImportantMessage|VeryImportantMessage]]
|{{VeryImportantMessage|Important Message}}
|Use it to create a highlighted box with a very important message. Use sparingly, only to indicate major problems in the functionality of the software, discontinuation of tools, and similar.
|--
|[[Template:Softredirect|Softredirect]]
|
|Use it instead of the normal redirect, when you are redirecting to a special page (such as Media: or Category:), in which cases the normal redirect is disabled.
|--
|[[Template:UnfinishedDocu|UnfinishedDocu]]
|{{UnfinishedDocu}}
|Use it to create a highlighted box indicating an unfinished documentation page.
|--
|[[Template:Quote|Quote]]
|{{Quote|text=Cry "Havoc" and let slip the dogs of war.|sign=William Shakespeare|source=''Julius Caesar'', act III, scene I}}
|Use it to create a box of text with a literal quote and reference.
|--
|[[Template:Userdocnavi|Userdocnavi]], [[Template:Powerdocnavi|Powerdocnavi]], [[Template:Devdocnavi|Devdocnavi]]
|
|Use them to create navigation boxes for the user documentation, the power user documentation, and the developer documentation. This allows quickly jumping between different sections of the documentation.
They also place the corresponding page in the proper category.
{{Emphasis|(2019) Currently the Userdocnavi is the most used, while the others aren't used. It's a work in progress to design them correctly, and add them to all documentation pages.}}
|}


<!--T:196-->
===Deprecated templates===
{|{{Prettytable}}
{|{{Prettytable}}
!Template
!style="width:10%;"|Template
!Appearance
!style="width:45%;"|Appearance
!Description
!style="width:45%;"|Description
|--
|Click
|'''Deprecated'''
|Use it to superimpose an invisible link on an image. You should use the native wiki picture inclusion method instead.
|--
|DASH
|'''Deprecated'''
|Use it to show a multi-line text box for code, with colorful background. You should use the style you obtain starting the source line with a space.
|--
|Disambig
|'''Deprecated'''
|Use it a disambiguation message in a page.
|--
|Information
|'''Deprecated'''
|Use it to create a standardized table providing complete information about the file, including description of what it shows and how it was made, copyright status and source.
|--
|Languages
|'''Deprecated'''
|Use it to show available translations. It's been obsoleted with the new wiki, which handles translations and languages via a dedicated plugin.
|--
|Message
|'''Deprecated'''
|Use it show a block of text with a colorful background, to indicate a message of low importance.
|--
|Screenshot
|'''Deprecated'''
|Use it to insert screenshots of the software. See [[#Screen capture]] instead.
|}


<!--T:197-->
To have a global view on the chromatic aspect, see [[WikiPagesBasicColors|Basic Graphic Template]].
|--
|[[Template:Prettytable|Prettytable]]
|This table
|Use it to format tables such as this one. Additional table properties can be added.


<!--T:198-->
===Code===
|--
Code must be styled using the [[Template:Code|Code]] template. The description of such code should follow afterwards. Accentuation should be strictly used ''only'' on the word or lines that must be accentuated.
|[[Template:Caption|Caption]]
|<div style="width:400px;">{{Caption|Some caption for an image}}</div>
|Use it to add an explanation below an image. It can be left aligned or center aligned.


<!--T:199-->
[[Python]] code should adhere to the general recommendations established by [https://www.python.org/dev/peps/pep-0008/ PEP8: Style Guide for Python Code].
|--
In particular, parentheses should immediately follow the function name, and a space should follow a comma. This makes the code more readable.
|[[Template:Clear|Clear]]
|
|Use it to clear columns. Follow the definition of the template for a detailed explanation. It is often used to stop text from flowing next to unrelated images.


<!--T:200-->
====Example of bad code description====
|--
|[[Template:Code|Code]]
|{{Code|code=import FreeCAD}}
|Use it to include multi-line code examples with a monospace font. The default language is Python, but other languages can be specified.


<!--T:79-->
{{Code|code=
[[Python|Python]] code should adhere to the general recommendations established by [https://www.python.org/dev/peps/pep-0008/ PEP8: Style Guide for Python Code]. In particular, parentheses should immediately follow the function name, and a space should follow a comma. This makes the code more readable.
makeAngularDimension (center,[angle1,angle2],p3): creates an angular Dimension from the given center,
with the given list of angles, passing through p3. Returns the newly created object.
}}


<!--T:241-->
====Example of good code description====
|--
|[[Template:CodeDownload|CodeDownload]]
|{{CodeDownload|https://wiki.freecad.org/Main_Page|Some label}}
|Use it to create a link on a [[Macros|macro]] page.


<!--T:240-->
{{Code|code=
|--
Dimension = makeAngularDimension(center, anglelist, p3)
|[[Template:Codeextralink|Codeextralink]]
Dimension = makeAngularDimension(center, [angle1, angle2], p3)
|{{Codeextralink|https://wiki.freecad.org/Main_Page}}
}}
|Use it if the code of a [[Macros|macro]] is too large to be hosted on the Wiki. The code can then be hosted somewhere else, and the raw link to it specified with this template. The [[Std_AddonMgr|Addon Manager]] will use this link.


<!--T:201-->
* Creates an angular dimension from the given {{incode|center}} point, the {{incode|anglelist}} containing {{incode|angle1}} and {{incode|angle2}}, and passing through point {{incode|p3}}.
|--
* Returns the newly created {{incode|Dimension}} object.
|[[Template:Fake heading|Fake heading]]
|{{Fake heading|Heading|2}}
|Use it to create a heading that will not be automatically included in the table of contents.


<!--T:202-->
==Graphics==
|--
|[[Template:GuiCommand|GuiCommand]]
|See [[GuiCommand model|GuiCommand model]]
|Use it to create a box with useful information to document workbench commands (tools).


<!--T:203-->
Images and screenshots are necessary to produce a complete documentation of FreeCAD. Images are particularly useful to illustrate examples and tutorials.
|--
|[[Template:TutorialInfo|TutorialInfo]]
|See for example [[Basic_modeling_tutorial|Basic modeling tutorial]]
|Use it to create a box with useful information to document [[Tutorials|tutorials]].


<!--T:204-->
===General===
|--
Avoid thumbnails and resizing [[bitmap|bitmap]] pictures (downsizing or upscaling). Pictures should be shown in their original size, so they present sufficient detail and are readable if they include text. The exception to this are [[SVG|SVG]] images, which can be scaled to any desired size without losing detail.
|[[Template:Macro|Macro]]
|See for example [[Macro_FlattenWire|Macro FlattenWire]]
|Use it to create a box with useful information to document [[macros|macros]].


<!--T:205-->
Avoid animated pictures (GIF) in the general [[Gui Command|Gui Command]] help pages. Animations and videos should be reserved for tutorials not intended to be used as offline PDF documentation.
|--
|[[Template:Docnav|Docnav]]
|{{Docnav|Online Help Startpage|Feature list}}
|Use it to create a bar with the words 'next', 'previous', and 'index', and the appropriate links, which is useful for putting pages in a particular sequence.


<!--T:206-->
Pictures must be uploaded through the [[Special:Upload]] page.
|--
|[[Template:VeryImportantMessage|VeryImportantMessage]]
|{{VeryImportantMessage|Important Message}}
|Use it to create a highlighted box with a very important message. Use sparingly, only to indicate major problems in the functionality of the software, discontinuation of tools, and similar.


<!--T:207-->
=== Name ===
|--
Give a meaningful name to your image. If you have a picture that showcases the characteristics of a particular command, you should use the same name as the command with {{incode|_example}} at the end.
|[[Template:Page in progress|Page in progress]]
* For the command [[Draft Offset|Draft Offset]] the image should be called [[:Image:Draft Offset example.jpg|Draft Offset example.jpg]].
|{{Page in progress|Page in progress}}
* For the command [[Arch Space|Arch Space]] the image should be called [[:Image:Arch Space example.jpg|Arch Space example.jpg]].
|Use this for pages that are still in progress or that are currently being reworked. Don't forget to remove this when the page is ready.


<!--T:208-->
===Screen capture===
|--
|[[Template:UnfinishedDocu|UnfinishedDocu]]
|{{UnfinishedDocu}}
|Use it to create a highlighted box indicating an unfinished documentation page.

<!--T:209-->
|--
|[[Template:Softredirect|Softredirect]]
|
|Use it instead of the normal redirect, when you are redirecting to a special page (such as Media: or Category:), in which cases the normal redirect is disabled.

<!--T:210-->
|--
|[[Template:Quote|Quote]]
|{{Quote|text=Cry "Havoc" and let slip the dogs of war.|sign=William Shakespeare|source=''Julius Caesar'', act III, scene I}}
|Use it to create a box of text with a literal quote and reference.

<!--T:211-->
|--
|[[Template:Userdocnavi|Userdocnavi]], [[Template:Powerdocnavi|Powerdocnavi]]
|
|Use them to create navigation boxes for the user documentation, the power user documentation, and the developer documentation. This allows quickly jumping between different sections of the documentation. They also place the corresponding page in the proper category.

<!--T:235-->
|}
</translate>
</div> <!-- end of collapsible div. Do not remove! -->
</div> <!-- end of collapsible div. Do not remove! -->

<div class="mw-collapsible mw-collapsed toccolours">
<translate>

== Graphics == <!--T:86-->
</translate>
<div class="mw-collapsible-content">
<translate>
<!--T:87-->
Images and screenshots are necessary to produce a complete documentation of FreeCAD. They are particularly useful to illustrate examples and tutorials. Images should be shown in their original size, so they present sufficient detail and are readable if they include text. [[bitmap|Bitmap]] images should not be resized.

<!--T:88-->
Avoid animated pictures (GIF) in the general help pages. Animations and videos should be reserved for tutorials not intended to be used as offline PDF documentation.

<!--T:89-->
Images can be uploaded through the [[Special:Upload|Special:Upload]] page.

=== Name === <!--T:213-->

<!--T:90-->
Give meaningful names to your images. If you have an image that showcases the characteristics of a particular command, you should use the name of that command with {{incode|_example}} at the end. For example for the command [[Draft_Offset|Draft Offset]] the image should be called {{incode|Draft_Offset_example.png}}.

=== Screen capture === <!--T:214-->

<!--T:91-->
Recommended sizes for screen captures are:
Recommended sizes for screen captures are:
* Native 400x200 (or width=400 and height<=200), for [[Gui Command|Gui Command]] pages, to allow the picture to fit in the left part of the page, and for other standard snapshots.
* Native 400x200 (or width=400 and height<=200), for [[GuiCommand_model|command reference]] pages, to allow the picture to fit in the left part of the page, and for other standard snapshots.
* Native 600x400 (or width=600 and height<=400), for [[Gui Command|Gui Command]] pages, when you really need a bigger picture, and still allow the picture to fit in the left part of the page, and for other standard snapshots.
* Native 600x400 (or width=600 and height<=400), for [[GuiCommand_model|command reference]] pages, when you really need a bigger picture, and still allow the picture to fit in the left part of the page, and for other standard snapshots.
* Native 1024x768 (or width=1024 and height<=768), only for full screen images.
* Native 1024x768 (or width=1024 and height<=768), only for full screen images.
* Smaller sizes are possible when showing details, however use native resolution, not resizing or thumbnails, unless you have a very good reason to do so.
* Smaller sizes are possible when showing details.
* Avoid larger resolutions, as they won't be very portable to other kinds of display or in the printed PDF documentation.
* Avoid images with larger resolutions, as they won't be very portable to other kinds of displays or the printed PDF documentation.

You shouldn't depend on any particular configuration of your desktop or operating system when you show screenshots. You should use visual defaults of the FreeCAD interface whenever possible.


<!--T:92-->
===Text===
You shouldn't depend on a custom configuration of your desktop or operating system when you create screenshots and you should use the visual defaults of the FreeCAD interface whenever possible.
To ease documentation translations, take separate pictures of the interface and the 3D model viewport. The picture of the 3D model can be reused in every translation, while a translator can take a picture of the localized interface if necessary.


<!--T:2-->
If your screen capture contains text use the same resolution of the original interface in FreeCAD so that text is readable.
To create a screenshots you can use the options provided by your operating system, or one of these macros: [[Image:Snip.png|24px]] [[Macro_Snip|Macro Snip]] and [[Image:Macro_Screen_Wiki.png|24px]] [[Macro_Screen_Wiki|Macro Screen Wiki]].


=== Text === <!--T:215-->
====Good sizing for reading text====
[[Image:partdesign_revolution_parameters.png|PartDesign revolution parameters (original size, 307px)]]


<!--T:93-->
====Bad sizing for reading text====
To ease documentation translations, try to avoid screenshots that contain texts. If you cannot avoid this, consider taking separate screenshots of the interface and the [[3D_view|3D view]]. The image of the 3D view can be reused in every translation, while a translator can take a screenshot of the localized interface if necessary.
[[Image:partdesign_revolution_parameters.png|190px|PartDesign revolution parameters (scaled to 190px)]]


=== Icons and graphics === <!--T:216-->
In the second picture the text is less clear and there are visual artifacts due to rescaling the original width from 307px to 190px.


<!--T:98-->
===Icons and graphics===
Refer to the [[Artwork|Artwork]] page for all artwork and icons that have been created for FreeCAD, which can be immediately reused in documentation pages.
Refer to the [[Artwork|Artwork]] page for all artwork and icons that have been created for FreeCAD, and which can also be used in documentation pages. If you would like to contribute icons, please read the [[Artwork_Guidelines|Artwork Guidelines]].
</translate>
If you would like to contribute with icons, please read the [[Artwork Guidelines|Artwork Guidelines]].
</div> <!-- end of Graphics collapsible div. Do not remove! -->
</div> <!-- end of Graphics collapsible div. Do not remove! -->


<div class="mw-collapsible mw-collapsed toccolours">
==Translations==
<translate>


== Translations == <!--T:99-->
</translate>
<div class="mw-collapsible-content">
<translate>
<!--T:225-->
As per general consensus, the reference page in the wiki is the English page, which should be created first. If you want to change or add content to a page, you should do it to the English page first, and only once the update is completed, port the modification to the translated page.
As per general consensus, the reference page in the wiki is the English page, which should be created first. If you want to change or add content to a page, you should do it to the English page first, and only once the update is completed, port the modification to the translated page.


<!--T:100-->
The FreeCAD wiki supports a translation extension that allows managing translations between pages easier; for details, see [[Localisation#Translating the wiki|Localisation Translating the wiki]].
The FreeCAD wiki supports a translation extension that allows managing translations between pages easier; for details, see [[Localisation#Translating the wiki|Localisation Translating the wiki]].


<!--T:101-->
Other useful resources are:
Other useful resources are:
* [http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes ISO language codes] to identify the two-letter code for a particular language that you want to translate to
* [http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes ISO language codes] to identify the two-letter code for a particular language that you want to translate to.
* [http://translate.google.com/ Google Translate] for help with translations.
* [http://en.wikipedia.org/wiki/Gallery_of_sovereign_state_flags Country flags] to identify a country's flag for use in relevant localized pages
* [http://translate.google.com/ Google Translate] for help with translating languages
* [https://www.deepl.com/translator Deepl translator] for help with translations.


== Some tips for translators ==
== Some tips for translators == <!--T:102-->


===Setting GuiCommand===
=== Translate GuiCommand === <!--T:103-->


</translate>
{{Code|code=
<pre>
<nowiki>{{GuiCommand|Name=FEM EquationFluxsolver|Icon=Fem-equation-fluxsolver.svg|MenuLocation= Solve → Equation fluxsolver||Workbenches=[[Fem Workbench|FEM]]|Shortcut=|SeeAlso=[[FEM_tutorial|FEM tutorial]]}}
{{GuiCommand
</nowiki>
|Name=FEM EquationFlux
|MenuLocation=Solve → Flux equation
|Workbenches=[[FEM_Workbench|FEM]]
|Shortcut={{KEY|F}} {{KEY|S}}
|Version=0.17
|SeeAlso=[[FEM_tutorial|FEM tutorial]]
}}
}}
</pre>
<translate>


<!--T:105-->
translated:
Translated:


</translate>
{{Code|code=
<pre>
<nowiki>{{GuiCommand/fr|Name=FEM EquationFluxsolver|Name/fr=FEM EquationFluxsolver|Icon=Fem-equation-fluxsolver.svg|MenuLocation= Solveur → Equation fluxsolver||Workbenches=[[Fem Workbench/fr|Atelier FEM]]|Shortcut=|SeeAlso=[[FEM_tutorial/fr|FEM tutoriel]]}}
{{GuiCommand/fr
</nowiki>
|Name=FEM EquationFlux
|Name/fr=FEM Équation d'écoulement
|MenuLocation=Solveur → Équation de flux
|Workbenches=[[FEM_Workbench/fr|Atelier FEM]]
|Shortcut={{KEY|F}} {{KEY|S}}
|Version=0.17
|SeeAlso=[[FEM_tutorial/fr|FEM Tutoriel]]
}}
}}
</pre>
<translate>


=== Translate navi === <!--T:107-->
===Setting template===


</translate>
{{Code|code=
<pre>
<nowiki>{{FEM Tools navi}}</nowiki>
{{FEM_Tools_navi}}
}}
</pre>
<translate>


<!--T:109-->
translated:
Translated:


</translate>
{{Code|code=
<pre>
<nowiki>{{FEM Tools navi/fr}}</nowiki>
{{FEM_Tools_navi/fr}}
}}
</pre>
<translate>


===Setting link===
=== Translate link === <!--T:111-->


</translate>
{{Code|code=
<pre>
<nowiki>[[Part_Module]]</nowiki>
[[Part_Module|Part Module]]
}}
</pre>
<translate>


<!--T:113-->
translated:
Translated:


</translate>
{{Code|code=
<pre>
<nowiki>[[Part_Module/fr|Atelier Pièces]]</nowiki>
[[Part_Module/fr|Atelier Part]]
}}
</pre>
<translate>


=== Translate Docnav === <!--T:119-->
or:


</translate>
{{Code|code=
<pre>
<nowiki>[[Part_Module|Part Module]]</nowiki>
{{Docnav
|[[About_FreeCAD|About FreeCAD]]
|[[Installing_on_Windows|Installing on Windows]]
}}
}}
</pre>
<translate>


<!--T:218-->
translated:
Translated:


</translate>
{{Code|code=
<pre>
<nowiki>[[Part_Module/fr|Atelier Pièces]]</nowiki>
{{Docnav/fr
|[[About_FreeCAD/fr|À propos de FreeCAD]]
|[[Installing_on_Windows/fr|Installation sous Windows]]
}}
}}
</pre>
<translate>


<!--T:219-->
===Setting Docnav===
Example with icons:


</translate>
To localize the [[Template:Docnav]] navigation bar, see this thread in the forum [http://forum.freecadweb.org/viewtopic.php?f=21&t=6716 Docnav previous/next].
<pre>
{{Docnav
|[[Std_Save|Save]]
|[[Std_SaveCopy|SaveCopy]]
|[[Std_File_Menu|Std File Menu]]
|IconL=Std_Save.svg
|IconR=Std_SaveCopy.svg
|IconC=Freecad.svg
}}
</pre>
<translate>


<!--T:220-->
Essentially, a new translated template needs to be created, [[Template:Docnav/it]].
Translated:


</translate>
The translated template should include the appropriate localized links as the "previous" and "next" parameters, together with the translated text:
<pre>
<nowiki>{{docnav/it|[[Installing/it|Installazione]]|[[Mouse Model/it|Navigazione 3D - Tipo di mouse]]}}</nowiki>
{{Docnav/fr
|[[Std_Save/fr|Enregistrer]]
|[[Std_SaveCopy/fr|Enregistrer une copie]]
|[[Std_File_Menu/fr|Menu fichier]]
|IconL=Std_Save.svg
|IconR=Std_SaveCopy.svg
|IconC=Freecad.svg
}}
</pre>


</div> <!-- END of Translation section collapsible element. Do not remove! -->
The translated template should include the appropriate localized links as the "previous" and "next" parameters with icon, together with the translated text:
</div> <!-- END of Translation section collapsible element. Do not remove! -->
<nowiki>{{Docnav/it|[[Mesh Import/it|Importa Mesh]]|[[Mesh MeshFromShape/it|Crea uno Mesh da un shape]]|[[Mesh_Workbench|Mesh]]|IconL=Mesh_ImportMesh.png|IconC=Workbench_Mesh.svg|IconR=Mesh MeshFromShape.png}}</nowiki>


<translate>
Also include the appropriate language category
== Create, rename and delete pages == <!--T:128-->
<nowiki>[[Category:Template/it]]</nowiki>


=== Create pages === <!--T:232-->
If the localized category is not included in the translated template, the translated template will remain in the default English category.


<!--T:233-->
===Using special pages===
Before creating a new page you should first check if a similar page already exists. If that is the case it is usually better to edit that existing page instead. When in doubt please open a topic in the [https://forum.freecadweb.org/viewforum.php?f=21 Wiki forum] first.


<!--T:234-->
*[[Special:LonelyPages]] lists those pages that are not linked from other pages in the FreeCAD wiki, therefore nobody can access these pages. If you find any in your native language, try to create the connection that exists in the English version of the page, otherwise no one can read them.
To create a new page do one of the following:
*[[Special:UncategorizedPages]] lists pages without an assigned category, therefore they do not appear when you browse the wiki by categories. Assign a category.
* Visit the URL with the desired page name, for example: <code><nowiki>https://wiki.freecadweb.org/My_New_Page</nowiki></code>, and click on 'create this page'.
*[[Special:WantedPages]] lists pages that are called in a page, but that do not exist. These are shown as red links in the text. Deprecated and very annoying.
* Do a wiki search for the page name, and click on the red text in 'Create the page "My New Page" on this wiki!'.
*Others Wanted (files and templates)
*[[Special:WantedCategories]] lists categories that are used in a page, but that do not exist. They can be created immediately by clicking on the red link. Skip.
*[[Special:Categories]] lists all categories in the wiki. They allow you to compare the number of pages inside a translated category, which should preferably match then number of pages inside the English language category.
*[[Special:ListRedirects]] lists all redirected pages. If there is any red links, something does not work well. Investigate which link is missing. Light blue links lead to pages outside the site, no problem.
*[[Special:RecentChanges]] lists the most recent changes done to the wiki, including the pages changed, the number of changes to a particular page, whether these were additions or subtractions, and the user responsible.
*[[Special:LanguageStats]] shows translation statistics for all message groups for a single language. Shows the parts not translated in a given language, only for those pages marked for translation. To see what has not been translated, set the language code and press ''Show statistics''. It also contains the link to see what has been recently translated into that language. ''Note:'' if entering the English code ''en'' shows pages, it is likely that the original page contains markup errors, with the exception of the sidebar.
*[[Special:PageTranslation]] lists all pages marked for translation, and those unmarked but that have translation tags. Only administrators can mark pages for translation.
*[[:Category:Pages to delete]]: lists all pages that should be deleted because they were created by mistake, are obsolete, or no longer necessary.


=== Rename pages === <!--T:129-->
==Robots==


<!--T:130-->
Head to [[WikiRobots|WikiRobots]] to find instructions on how to set up and use robots to automate repetitive tasks on the FreeCAD Wiki.
Since FreeCAD is a project under permanent development, it is sometimes necessary to revise the content of the wiki. If the names of commands are changed in the source code, the wiki pages documenting them have to be renamed as well. This can only be done by wiki administrators. To inform them, open a topic in the [https://forum.freecadweb.org/viewforum.php?f=21 Wiki forum] and list the necessary renaming operation in this form:


</translate>
==Discussion==
<pre>
The [http://forum.freecadweb.org/viewforum.php?f=21 Development/Wiki subforum] in the [https://forum.freecadweb.org FreeCAD forum] provides a dedicated space
old name new name
for discussing improvements on the wiki topics and appearance. Direct your questions and suggestions there.
Old_page_name_1 New_page_name_1
Old_page_name_2 New_page_name_2
...
</pre>
<translate>


=== Delete files and pages === <!--T:135-->
==Brainstorming==


<!--T:136-->
{{VeryImportantMessage|All that follows is open to discussion. You can stop reading here if you don't intend to suggest modifications to the FreeCAD WikiPages style rules. You should discuss any wiki-related topic on the [[http://forum.freecadweb.org/viewforum.php?f=21 Development/Wiki subforum]]. Contributions are welcome.}}
In case you need to delete a file, go to its page (<code><nowiki>https://www.freecadweb.org/wiki/File:***.***</nowiki></code>) and edit it. No matter if the page is blank or not, add this as the first element: <code><nowiki>{{Delete}}</nowiki></code> and directly below it describe why the page should be deleted. Additionally, open a topic in the [https://forum.freecadweb.org/viewforum.php?f=21 Wiki forum].


<!--T:137-->
See [[Wiki brainstorming]]. The information here was moved there to avoid cluttering this page.---[[User:Vocx|Vocx]] ([[User talk:Vocx|talk]]) 00:38, 2 November 2018 (UTC)
For pages the procedure is the same.


== Discussion == <!--T:222-->
== Terminology - Naming policy==


<!--T:140-->
===English===
The [http://forum.freecadweb.org/viewforum.php?f=21 Development/Wiki subforum] in the [https://forum.freecadweb.org FreeCAD forum] provides a dedicated space for discussing wiki topics, the wiki appearance and anything else related to the wiki. Direct your questions and suggestions there.
See [[Glossary]]


== Terminology - naming policy == <!--T:144-->
===Other languages===
*[[Italian_Translation|Italiano]]
*


=== English === <!--T:223-->
==[[Start Workbench|Start Center]] ==


<!--T:145-->
'''proposal to create the page:'''
See [[Glossary|Glossary]].


=== Other languages === <!--T:224-->
See [[Sandbox:Start center]]. The information here was moved there to avoid cluttering this page.---[[User:Vocx|Vocx]] ([[User talk:Vocx|talk]]) 00:28, 2 November 2018 (UTC)


<!--T:146-->
= Sandbox for Macro Dimensions =
* [[Italian_Translation|Italiano]]
See [[Sandbox:Macro dimensions]]. The information here was moved there to avoid cluttering this page.---[[User:Vocx|Vocx]] ([[User talk:Vocx|talk]]) 23:43, 1 November 2018 (UTC)
* [[French_Translation|Français]]
* [[German_Translation|Deutsch]]
* [[Polish_Translation|Polish]]
* [[Spanish_Translation|Spanish]]


= Sandbox for PartDesign Fillet =


</translate>
See [[Sandbox:PartDesign fillet]]. The information here was moved there to avoid cluttering this page.---[[User:Vocx|Vocx]] ([[User talk:Vocx|talk]]) 23:36, 1 November 2018 (UTC)
[[Category:Documentation{{#translation:}}]]
[[Category:Wiki{{#translation:}}]]
[[Category:Wiki Documentation{{#translation:}}]]
[[Category:Administration{{#translation:}}]]

Latest revision as of 13:43, 12 January 2024

This page is an extension of the Help:Editing page and gives common guidelines for writing and updating the FreeCAD wiki documentation. It summarizes several discussions and brainstorming sessions

Before starting

  • This wiki documentation is based on MediaWiki, the same software that powers Wikipedia. If you have contributed to Wikipedia, editing FreeCAD wiki pages should be easy.
  • Contrary to Wikipedia, the FreeCAD wiki is write-protected to avoid spam. You must request an account on the forum.
  • If you have never used wiki software before, please read Help:Editing to become familiar with the markup that is used.
  • For advanced use of the wiki software, see MediaWiki Help:Contents. Not all features of MediaWiki are available in this FreeCAD wiki, but many are.
  • We like to keep the documentation easy to read, so avoid using complex features. Keep it simple.
  • Use a sandbox to test your code, for example, FreeCADDocu:Sandbox or a particular page with your name Sandbox:Yourname. Sandbox pages must be placed in the Sandbox category. This is done by adding [[Category:Sandbox]] at the bottom of the wiki code.
  • Please be aware of the translations. The FreeCAD wiki uses automated translation support to provide pages in many languages. For every page multiple language versions can exist. On many pages you will see tags like <translate>...</translate> and many single tags like <!--T:8-->. The latter mark so-called translation units and are created by the translation system, you should never create them manually. They link the headings and paragraphs to their translated versions. You should not change them as that would destroy those links. It is however fine to move paragraphs or change wording as long as the tags stay with them. If you remove a heading or a paragraph you should also remove the tag belonging to it. Please be aware that changes to existing headings and paragraphs affect the current translations. Your changes should be worth it. Do not worry when adding new material because the system will add new tags automatically after your edits. For more information see Localisation and the original Mediawiki:Extension:Translate page.

General guidelines

Concise descriptions

When describing FreeCAD try to be concise and to the point and avoid repetition. Describe what FreeCAD does, not what FreeCAD does not do. Also avoid colloquial expressions such as 'a couple'. Use 'some' when dealing with an indeterminate number, or specify the correct quantity.

Bad description
PartDesign Workbench: the PartDesign Workbench is a workbench for part design that aims to provide tools for modelling complex solid parts.
Good description
PartDesign Workbench: aims to provide tools for modelling complex solid parts.

Centralized information

Avoid duplicating the same information in different places. Insert the information in a new page, and link to this page from other pages that require this information.

Do not use transclusion of pages (Help:Editing#Templates and transcluding pages), as this makes the wiki difficult to translate. Use only the templates described below in #Templates.

Styling

Templates are used to style the help pages. They give the documentation a consistent look and feel. There is a template for menu commands, File → Save, a template to style keys to be pressed, Shift, to show a Boolean value, true, etc. Please get familiar with the #Templates section before writing help pages.

Temporary flags

If you are working on a large page it is advisable to mark the page either as a work in progress or as unfinished. This assures that wiki admins don't mark your page as ready for translation while you are still changing it.

To flag a page add either {{Page in progress}} or {{UnfinishedDocu}} as the first line. With {{UnfinishedDocu}} you invite others to join you in finishing the page, while {{Page in progress}} indicates that you will do the work yourself and others should give you some time.

Once the work is done, please don't forget to remove the flags!

Examples

To quickly get familiar with the structure and style of the FreeCAD wiki look at the model page: GuiCommand model.

Structure

The User hub provides a Table of Contents. This is used as the main reference for automatically building the offline help you can reach from FreeCAD, as well as the offline PDF documentation.

The Template:Docnav is used to sequentially link pages, following the structure of the Table of Contents. See #Templates for a list of all templates.

Page names

Page names should be short and they should use title case: every word should begin with a capital letter, unless they are articles, prepositions, conjunctions, or other grammatical particles (f.e. 'of', 'on', 'in', 'a', 'an', 'and').

Bad page name
Construction of AeroCompany airplanes
Good page name
Construction of AeroCompany Airplanes

The names of top level workbench pages must have this format: XYZ Workbench, where XYZ is the name of the workbench, for example PartDesign Workbench. And the names of pages describing the commands (or tools) belonging to a workbench must have this format: XYZ Command, for example PartDesign Pad. Note that you should use the command name as it occurs in the source code.

Headings

Paragraph headings should be short and use sentence case: all words except the first one and proper names, should be in lowercase. You should not use H1 headings (= Heading =) in your wiki markup since the page title is automatically added as the main H1 heading.

Links

You should use the original link name for links whenever possible. This clarifies the referenced page in printed or offline documentation. Please avoid non-meaningful words for the link.

Bad link
For more information on drafting 2D objects click here.
Good link
For more information on drafting 2D objects refer to the Draft Workbench.

The preferred format for a link is:

[[Name_of_Page|Name of Page]]

Translated:

[[Name_of_Page/fr|Nom de la Page]]

Note that for the part before the | character, the actual link, case is relevant. If your page name is Name_of_page the link will fail if you type Name_of_Page (upper case P). Before the | character all spaces should be replaced by underscores (_). This is to assist translators using translation software, without the underscores the link would be translated by the software which is undesirable.

To link to a certain paragraph add a # sign and its headings to the page name. Example:

[[WikiPages#Links|WikiPages]]

Translated:

[[WikiPages/fr#Liens|WikiPages]]

Within the same page you can omit the page name. Example:

[[#Links|Links]]

To link to the top of the page you can use:

</translate>{{Top}}<translate>

This template should automatically display the correct text depending on the language of the page. A link to the top of the page is especially useful for long pages as it allows the user to quickly jump back to the table of content. You can put it at the end of each paragraph. Make sure there is an empty line before and after the template.

Image link
Optional text that is shown when you hover the image

To use an image as a link:

[[Image:Draft_Wire.svg|24px|Optional text that is shown when you hover the image|link=Draft_Wire]]

Image link + text link
Draft Wire

If you leave out the optional text the link itself will be shown when the image is hovered, which is preferable, and you should also add a text link after the image link:

[[Image:Draft_Wire.svg|24px|link=Draft_Wire]] [[Draft_Wire|Draft Wire]]

Workbench pages

A top level workbench page should start with:

  • A description of what the workbench is used for.
  • An image to illustrate the description.

See #Screen capture for conventions on including images.

Command pages

Command pages describing workbench tools should not be too long, they should only explain what a command can do and what it can't, and how to use it. You should keep pictures and examples to a minimum. Tutorials can expand on how to use the tool and provide step-by-step details.

Please refer to the GuiCommand model page for more details.

Tutorials

A well written tutorial should teach how to achieve certain practical results quickly. It shouldn't be too long, but should include sufficient step-by-step instructions and images to guide the user. As FreeCAD evolves, tutorials may become obsolete, so it is important to mention the FreeCAD version used in, or required for, a tutorial.

For examples visit the Tutorials page.

Templates

Styling of the FreeCAD wiki pages is achieved through the use of templates (Help:Editing#Templates_and_transcluding_pages). They ensure a standardized look and feel across all pages, and also make it possible to re-style the wiki. You can see the complete list of defined templates by accessing Special:PrefixIndex/Template:. But please only use the templates listed in the tables below. Only in very special cases should you use HTML tags directly.

Click on the template link to see the usage instructions for a template, and to see its implementation. Templates are a powerful feature of the MediaWiki software. You should be an experienced wiki user if you wish to propose additions and modifications to existing templates. If implemented incorrectly, templates make it difficult to translate pages into other languages, so their use should be limited to text formatting, page transclusion should be avoided. See MediaWiki Help:Templates to learn more.

Simple templates

These templates accept a simple text parameter, and format it with a particular style.

Template Appearance Description
Top

Top

Use it to add a link to the top of the page.
Emphasis emphasis Use it to emphasize a piece of text.
KEY Alt Use it to indicate a keyboard key that needs to be pressed.
ASCII Use it to indicate a ascii key in a image (.svg) that needs to be pressed. You must give the character desired or the number of the code ascii of the character.
Button Cancel Use it to indicate a button in the graphical user interface that needs to be pressed.
RadioButton Option Use it to indicate a radio button in the graphical user interface that needs to be Selected or Not.
CheckBox Option Use it to indicate a checkbox in the graphical user interface that needs to be Checked or Not.
SpinBox 1.50 Use it to indicate a spinbox in the graphical user interface that needs to be modified.
ComboBox Menu 1 Use it to indicate a combobox in the graphical user interface that needs to be modified.
LineEdit Metal Nickel (Ni) Use it to indicate a LineEdit in the graphical user interface that needs to be modified.
FALSE, false false, false Use it to indicate a False Boolean value, for example, as a property in the property editor. This is a shortcut. Since it is a value, prefer Template Value false
TRUE, true true, true Use it to indicate a True Boolean value, for example, as a property in the property editor. This is a shortcut. Since it is a value, prefer Template Value true
MenuCommand File → Save Use it to indicate the location of a command inside a particular menu.
FileName File name Use it to indicate a name of a file or directory.
SystemInput Type this text Use it to indicate user typed input text.
SystemOutput Output text Use it to indicate text output from the system.
Incode import FreeCAD Use it to include in-line source code with a monospace font. It should fit in one line.
PropertyView ViewColor Use it to indicate a View property in the property editor. Examples of View properties include Line Color, Line Width, Point Color, Point Size, etc.
PropertyData DataPosition Use it to indicate a Data property in the property editor. Data properties are different for different types of objects.
Properties Title / TitleProperty Base Use it to indicate the title of a property group in the property editor. The title will not be included in the automatic table of contents.
Obsolete obsolete in version 0.19 Use it to indicate that a feature became obsolete in the specified FreeCAD version.
Version introduced in version 0.18 Use it to indicate that a feature was introduces in the specified FreeCAD version.
VersionMinus version 0.16 and below Use it to indicate that a feature is available in the specified FreeCAD version and earlier versions.
VersionPlus version 0.17 and above Use it to indicate that a feature is available in the specified FreeCAD version and later versions.
ColoredText Colored Text Use this template to color the background, text, or background and text. (ColoredText page for more examples)
ColoredParagraph
Colored Paragraph
Use this template to color the background, text, or background and text of an entire paragraph. ColoredParagraph page for more examples)

Complex templates

These templates require more input parameters, or produce a block of text with a particular format.

Template Appearance Description
Prettytable This table Use it to format tables such as this one. Additional table properties can be added.
Caption

Some caption for an image

Use it to add an explanation below an image. It can be left aligned or center aligned.
Clear Use it to clear columns. Follow the definition of the template for a detailed explanation. It is often used to stop text from flowing next to unrelated images.
Code
import FreeCAD
Use it to include multi-line code examples with a monospace font. The default language is Python, but other languages can be specified.

Python code should adhere to the general recommendations established by PEP8: Style Guide for Python Code. In particular, parentheses should immediately follow the function name, and a space should follow a comma. This makes the code more readable.

CodeDownload Use it to create a link on a macro page.
Codeextralink

Temporary code for external macro link. Do not use this code. This code is used exclusively by Addon Manager. Link for optional manual installation: Macro


# This code is copied instead of the original macro code
# to guide the user to the online download page.
# Use it if the code of the macro is larger than 64 KB and cannot be included in the wiki
# or if the RAW code URL is somewhere else in the wiki.

from PySide import QtGui, QtCore

diag = QtGui.QMessageBox(QtGui.QMessageBox.Information,
    "Information",
    "This macro must be downloaded from this link\n"
    "\n"
    "https://wiki.freecad.org/Main_Page" + "\n"
    "\n"
    "Quit this window to access the download page")

diag.setWindowFlags(QtCore.Qt.WindowStaysOnTopHint)
diag.setWindowModality(QtCore.Qt.ApplicationModal)
diag.exec_()

import webbrowser 
webbrowser.open("https://wiki.freecad.org/Main_Page")
<class="rawcodeurl"><a href="https://wiki.freecad.org/Main_Page">raw code</a>
Use it if the code of a macro is too large to be hosted on the Wiki. The code can then be hosted somewhere else, and the raw link to it specified with this template. The Addon Manager will use this link.
Fake heading
Heading
Use it to create a heading that will not be automatically included in the table of contents.
GuiCommand See GuiCommand model Use it to create a box with useful information to document workbench commands (tools).
TutorialInfo See for example Basic modeling tutorial Use it to create a box with useful information to document tutorials.
Macro See for example Macro FlattenWire Use it to create a box with useful information to document macros.
Docnav
Online Help Startpage
Feature list
Use it to create a bar with the words 'next', 'previous', and 'index', and the appropriate links, which is useful for putting pages in a particular sequence.
VeryImportantMessage
Important Message
Use it to create a highlighted box with a very important message. Use sparingly, only to indicate major problems in the functionality of the software, discontinuation of tools, and similar.
Page in progress
This documentation is a work in progress. Please don't mark it as translatable since it will change in the next hours and days.
Use this for pages that are still in progress or that are currently being reworked. Don't forget to remove this when the page is ready.
UnfinishedDocu

This documentation is not finished. Please help and contribute documentation.

GuiCommand model explains how commands should be documented. Browse Category:UnfinishedDocu to see more incomplete pages like this one. See Category:Command Reference for all commands.

See WikiPages to learn about editing the wiki pages, and go to Help FreeCAD to learn about other ways in which you can contribute.

Use it to create a highlighted box indicating an unfinished documentation page.
Softredirect Use it instead of the normal redirect, when you are redirecting to a special page (such as Media: or Category:), in which cases the normal redirect is disabled.
Quote

Cry "Havoc" and let slip the dogs of war.

—William Shakespeare, Julius Caesar, act III, scene I
Use it to create a box of text with a literal quote and reference.
Userdocnavi, Powerdocnavi Use them to create navigation boxes for the user documentation, the power user documentation, and the developer documentation. This allows quickly jumping between different sections of the documentation. They also place the corresponding page in the proper category.

Graphics

Images and screenshots are necessary to produce a complete documentation of FreeCAD. They are particularly useful to illustrate examples and tutorials. Images should be shown in their original size, so they present sufficient detail and are readable if they include text. Bitmap images should not be resized.

Avoid animated pictures (GIF) in the general help pages. Animations and videos should be reserved for tutorials not intended to be used as offline PDF documentation.

Images can be uploaded through the Special:Upload page.

Name

Give meaningful names to your images. If you have an image that showcases the characteristics of a particular command, you should use the name of that command with _example at the end. For example for the command Draft Offset the image should be called Draft_Offset_example.png.

Screen capture

Recommended sizes for screen captures are:

  • Native 400x200 (or width=400 and height<=200), for command reference pages, to allow the picture to fit in the left part of the page, and for other standard snapshots.
  • Native 600x400 (or width=600 and height<=400), for command reference pages, when you really need a bigger picture, and still allow the picture to fit in the left part of the page, and for other standard snapshots.
  • Native 1024x768 (or width=1024 and height<=768), only for full screen images.
  • Smaller sizes are possible when showing details.
  • Avoid images with larger resolutions, as they won't be very portable to other kinds of displays or the printed PDF documentation.

You shouldn't depend on a custom configuration of your desktop or operating system when you create screenshots and you should use the visual defaults of the FreeCAD interface whenever possible.

To create a screenshots you can use the options provided by your operating system, or one of these macros: Macro Snip and Macro Screen Wiki.

Text

To ease documentation translations, try to avoid screenshots that contain texts. If you cannot avoid this, consider taking separate screenshots of the interface and the 3D view. The image of the 3D view can be reused in every translation, while a translator can take a screenshot of the localized interface if necessary.

Icons and graphics

Refer to the Artwork page for all artwork and icons that have been created for FreeCAD, and which can also be used in documentation pages. If you would like to contribute icons, please read the Artwork Guidelines.

Translations

As per general consensus, the reference page in the wiki is the English page, which should be created first. If you want to change or add content to a page, you should do it to the English page first, and only once the update is completed, port the modification to the translated page.

The FreeCAD wiki supports a translation extension that allows managing translations between pages easier; for details, see Localisation Translating the wiki.

Other useful resources are:

Some tips for translators

Translate GuiCommand

{{GuiCommand
|Name=FEM EquationFlux
|MenuLocation=Solve → Flux equation
|Workbenches=[[FEM_Workbench|FEM]]
|Shortcut={{KEY|F}} {{KEY|S}}
|Version=0.17
|SeeAlso=[[FEM_tutorial|FEM tutorial]]
}}

Translated:

{{GuiCommand/fr
|Name=FEM EquationFlux
|Name/fr=FEM Équation d'écoulement
|MenuLocation=Solveur → Équation de flux
|Workbenches=[[FEM_Workbench/fr|Atelier FEM]]
|Shortcut={{KEY|F}} {{KEY|S}}
|Version=0.17
|SeeAlso=[[FEM_tutorial/fr|FEM Tutoriel]]
}}

Translate navi

{{FEM_Tools_navi}}

Translated:

{{FEM_Tools_navi/fr}}

Translate link

[[Part_Module|Part Module]]

Translated:

[[Part_Module/fr|Atelier Part]]

Translate Docnav

{{Docnav
|[[About_FreeCAD|About FreeCAD]]
|[[Installing_on_Windows|Installing on Windows]]
}}

Translated:

{{Docnav/fr
|[[About_FreeCAD/fr|À propos de FreeCAD]]
|[[Installing_on_Windows/fr|Installation sous Windows]]
}}

Example with icons:

{{Docnav
|[[Std_Save|Save]]
|[[Std_SaveCopy|SaveCopy]]
|[[Std_File_Menu|Std File Menu]]
|IconL=Std_Save.svg
|IconR=Std_SaveCopy.svg
|IconC=Freecad.svg
}}

Translated:

{{Docnav/fr
|[[Std_Save/fr|Enregistrer]]
|[[Std_SaveCopy/fr|Enregistrer une copie]]
|[[Std_File_Menu/fr|Menu fichier]]
|IconL=Std_Save.svg
|IconR=Std_SaveCopy.svg
|IconC=Freecad.svg
}}

Create, rename and delete pages

Create pages

Before creating a new page you should first check if a similar page already exists. If that is the case it is usually better to edit that existing page instead. When in doubt please open a topic in the Wiki forum first.

To create a new page do one of the following:

  • Visit the URL with the desired page name, for example: https://wiki.freecadweb.org/My_New_Page, and click on 'create this page'.
  • Do a wiki search for the page name, and click on the red text in 'Create the page "My New Page" on this wiki!'.

Rename pages

Since FreeCAD is a project under permanent development, it is sometimes necessary to revise the content of the wiki. If the names of commands are changed in the source code, the wiki pages documenting them have to be renamed as well. This can only be done by wiki administrators. To inform them, open a topic in the Wiki forum and list the necessary renaming operation in this form:

old name         new name
Old_page_name_1  New_page_name_1
Old_page_name_2  New_page_name_2
...

Delete files and pages

In case you need to delete a file, go to its page (https://www.freecadweb.org/wiki/File:***.***) and edit it. No matter if the page is blank or not, add this as the first element: {{Delete}} and directly below it describe why the page should be deleted. Additionally, open a topic in the Wiki forum.

For pages the procedure is the same.

Discussion

The Development/Wiki subforum in the FreeCAD forum provides a dedicated space for discussing wiki topics, the wiki appearance and anything else related to the wiki. Direct your questions and suggestions there.

Terminology - naming policy

English

See Glossary.

Other languages