WikiPages: Difference between revisions

From FreeCAD Documentation
No edit summary
m (removed obsolete description in relation with 'next' and 'previous')
 
(304 intermediate revisions by 18 users not shown)
Line 1: Line 1:
<languages/>
<noinclude>[[Category:Wiki]]</noinclude>
{{TOCright}}
{{TOCright}}
<translate>
This page gives common guidelines on the best practices to be followed when writing or updating FreeCAD documentation.


<!--T:1-->
It also has the goal to bring together the threads that are dispersed in the forum and try to make order, being a single point of reference for FreeCAD documentation discussion and brainstorming, to better organize the wiki.
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


==Before Starting==
== Before starting == <!--T:155-->


<!--T:3-->
Editing wiki pages is easy. Before starting editing FreeCAD wiki pages, be sure to be familiar with the [[Help:Editing|Wiki editing basics]].
* 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.
* 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==
== General guidelines == <!--T:4-->


===Concise Descriptions===
=== Concise descriptions === <!--T:156-->
When describing FreeCAD functionality try to be concise and to the point. Also, please describe what FreeCAD does, '''NOT''' what FreeCAD does not do. There might be exceptions for justifying why FreeCAD does not support a certain functionality, in case for instance there is a different philosophy or way to achieve the result with respect to traditional CAD systems, but these cases must be the exception.


<!--T:5-->
===Centralized Information===
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.
Ideally, you should try to avoid duplicating the same information in different places. While it is simple to copy & paste some text, it will eventually lead to misaligned information when a page is updated and the other not. You should insert the information in one place only, and make reference to this single point.


<!--T:67-->
A possible solution for the above problem is the use of templates and transclusions (see [[Help:Editing#Templates and transcluding pages|Templates and transcluding pages]] if you are not familiar with this concept), but their usage for this goal is strongly discouraged. The reason is that in the printed manual created from the Wiki help you will have the same information printed over and over again; but even a reader using the Wiki can be confused by finding the same text in different pages.
; Bad description
In case you need the same explanations in more than one point of the documentation, please consider creating a new page topic, and make explicit references (links) to this page.
: [[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-->
===Styling===
; Good description
[[#Templates|Templates]] are heavily used, instead, for styling the text. For instance, there is a template for styling menu commands, like {{MenuCommand|File->Save}}, another template to style keys to be pressed, like {{KEY|SHIFT}}, etc.. This allows to have a consistent look and feel of the documentation, as well as to be able to update the style by simply changing the template. Please get familiar with the [[#Templates|templates]] used in FreeCAD Wiki Help documentation before writing help pages.
: [[PartDesign_Workbench|PartDesign Workbench]]: aims to provide tools for modelling complex solid parts.


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


<!--T:6-->
Working by examples will help you keep the right track, and be ahead on the learning curve. So even if reading the following sections is highly recommended, you can quickly get familiar with the structure and style of FreeCAD wiki looking at the following pages, that can be considered reference for best style practices of FreeCAD documentation.
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-->
If you are consistent with this look & feel, you won't be far from a correct FreeCAD documentation page, and your contribution will blend more easily in the wiki.
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 === <!--T:158-->
* [[Draft ShapeString]]
* [[Draft Line]]


<!--T:9-->
==Structure==
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-->
===General===
You should normally not use a '''=header=''' for a page, since the page title is automatically added.


<!--T:10-->
The User's 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. The [[Template:Docnav]], which is used to link a page with the previous and the next page of the same section (see [[#Templates]] section below for a list of all templates, including [[Template:Docnav|Docnav]]) should be aligned with the structure in the [[Online Help Toc|Table of Contents]].
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.


<!--T:11-->
===Page Names===
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.
Page names should be short, and every word should begin with a capital letter, unless they are articles, prepositions, conjunctions (e.g. 'of', 'on', 'and')


<!--T:12-->
====Bad name====
Once the work is done, please don't forget to remove the flags!
[[Working with architecture walls]]


== Examples == <!--T:13-->
====Good name====
[[Arch Wall]]


<!--T:14-->
To quickly get familiar with the structure and style of the FreeCAD wiki look at the model page: [[GuiCommand_model|GuiCommand model]].


</translate>
Workbench pages must have the format '''XYZ Workbench''', where '''XYZ''' is the name of the referred workbench.
<div class="mw-collapsible mw-collapsed toccolours">
<translate>


== Structure == <!--T:15-->
Pages describing the tools of a workbench must have the format '''XYZ MyTool''', where '''MyTool''' is the name of the specific tool.
</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-->
===Links===
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.
You should use the original link name for the links whenever possible. This clarifies the referenced chapter in printed / pdf documentation. You must anyway avoid the usage of non-meaningful words for the link.


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


<!--T:18-->
====So-so link====
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').
For more information on this topic, refer to [[Draft Workbench|drafting 2D objects]].


<!--T:20-->
====Good link====
; Bad page name:
For more information on this topic, see how to draft 2D objects in the [[Draft Workbench]].
: Construction of AeroCompany airplanes


<!--T:161-->
===Workbench pages===
; Good page name:
Every page of a workbench should start with:
: Construction of AeroCompany Airplanes
* the name of the workbench
* an image of (an example) of the look of the workbench. Not necessary to show a model (see anyway the [[#Screen capture]] section for rules), but the menu and toolbar should be visible, in their default position
* a description of what the workbench is used for


<!--T:22-->
===Command (tool) pages===
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.
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 to a minimum, and not give too many examples - tutorials is where we should go in step-by-step details.


=== Headings === <!--T:162-->
Restrictions should be documented right in the command page itself rather than elsewhere, possibly under a "restrictions" chapter.


<!--T:163-->
Please refer to the [[Gui Command]] page for specific indications on Gui Command rules (naming, documenting, etc.).
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.


===Tutorials===
=== Links === <!--T:164-->
Good tutorial examples are available at [http://freecad-tutorial.blogspot.it FreeCAD tutorial - Unofficial tutorial blog].
Though they are not styled as FreeCAD wiki pages, they are a valid example of how a written tutorial should look like.


<!--T:26-->
== Language ==
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.


<!--T:27-->
===Expressions===
; Bad link
You should avoid colloquial generic expressions as 'a couple'. Please re-phrase as 'some' if indeterminate, or with the correct cardinality.
: For more information on drafting 2D objects click [[Draft_Workbench|here]].


<!--T:29-->
===Conciseness===
; Good link
Try to avoid repetitions to keep descriptions short.
: For more information on drafting 2D objects refer to the [[Draft_Workbench|Draft Workbench]].


<!--T:39-->
====Bad description====
The preferred format for a link is:


<!--T:40-->
[[PartDesign Workbench|Part Design Workbench]]: the Part Design Workbench is a workbench for part design that aims to provide tools for modelling complex solid parts.
<code><nowiki>[[Name_of_Page|Name of Page]]</nowiki></code>


<!--T:41-->
====Good description====
Translated:


<!--T:42-->
[[PartDesign Workbench|Part Design Workbench]]: aims to provide tools for modelling complex solid parts.
<code><nowiki>[[Name_of_Page/fr|Nom de la Page]]</nowiki></code>


<!--T:43-->
==Style==
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-->
===Templates===
To link to a certain paragraph add a <code><nowiki>#</nowiki></code> sign and its headings to the page name. Example:
Styling of FreeCAD Wiki pages is mainly achieved through the usage of templates. The table here below reports the templates that should be used in FreeCAD Wiki pages. Please use the templates listed below as much as possible, since these allows to re-style the whole Wiki in one shot by updating the template, and is the preferred method in the Wiki. For special cases '''only''' you can resort to direct HTML tags.


<!--T:45-->
Remark: you can see the complete list of defined templates accessing [[Special:PrefixIndex/Template:]]. However, not all the templates defined here are used for styling the text, and others are deprecated. Please refer to the table below for the list of templates you should use when documenting FreeCAD in the Wiki.
<code><nowiki>[[WikiPages#Links|WikiPages]]</nowiki></code>


<!--T:48-->
{|{{Prettytable}}
Translated:
!Template
!Appearance
!Description
|--
|[[Template:Emphasis|Emphasis]]
|{{Emphasis|emphasis}}
|Text to emphasize
|--
|[[Template:KEY|KEY]]
|{{KEY|ALT}}
|Show a keyboard key
|--
|[[Template:FALSE|FALSE]]
|{{FALSE}}
|False value (e.g. of a [[Property editor|property]])
|--
|[[Template:TRUE|TRUE]]
|{{TRUE}}
|False value (e.g. of a [[Property editor|property]])
|--
|[[Template:MenuCommand|MenuCommand]]
|{{MenuCommand|File->Save}}
|GUI menu text
|--
|[[Template:FileName|FileName]]
|{{FileName|File name}}
|Names of files or directories
|--
|[[Template:Code|Code]]
|{{Code|import FreeCAD}}
|Style source code. Default language is Python, other languages can be specified.
|--
|[[Template:SystemInput|SystemInput]]
|{{SystemInput|Type this text}}
|User typed input text
|--
|[[Template:SystemOutput|SystemOutput]]
|{{SystemOutput|Output text}}
|Text output from the system
|--
|[[Template:Variable|Variable]]
|{{Variable|MyAttribute|TYPE}}
|Value or parameter, optionally with a type
|--
|[[Template:Optional|Optional]]
|{{Optional|InsertThis..OrNot}}
|Optional text or value
|--
|[[Template:Choice|Choice]]
|{{Choice|This|That}}
|Choice of values from which one is used
|--
|[[Template:Prettytable|Prettytable]]
|this table
|Create tables
|--
|[[Template:Clear|Clear]]
|
|Clear columns. Follow the hyperlink for a detailed explanation. Often used to stop text from flowing next to unrelated images.
|--
|[[Template:Fake heading|Fake heading]]
|{{Fake heading|Heading|2}}
|Heading that will not be included in the automatic TOC
|--
|[[Template:GuiCommand|GuiCommand]]
|See example [[GuiCommand model]]
|Main template for creating right side box for documenting GuiCommands
|--
|[[Template:Macro|Macro]]
|See example [[Macro FlattenWire]]
|Main template for creating right side box for documenting macros
|--
|[[Template:PropertyView|PropertyView]]
|{{PropertyView|Color}}
|Show a View [[Property editor|property]]
|--
|[[Template:PropertyData|PropertyData]]
|{{PropertyData|Position}}
|Show a Data [[Property editor|property]]
|--
|[[Template:Properties Title|Properties Title]] / [[Template:TitleProperty|TitleProperty]]
|{{Properties_Title|Base}}
|Title for a [[Property editor|property]] group. Will not be included in the automatic TOC.
|--
|[[Template:PropertyTasks|PropertyTasks]] / [[Template:TasksTag|TasksTag]]
|{{PropertyTasks|Tasks}}
|Argument for Tasks
|--
|[[Template:TitleTasks|TitleTasks]]
|{{TitleTasks|Tasks Title}}
|Title for Tasks
|--
|[[Template:Docnav|Docnav]]
|{{Docnav|Online Help Startpage|Feature list}}
|Used to create the 'next', 'previous' and 'index' links (usually at the bottom of a page)
|--
|[[Template:Version|Version]]
|{{Version|0.13}}
|Indicate that a feature is available only starting with a specific FreeCAD version
|--
|[[Template:VeryImportantMessage|VeryImportantMessage]]
|{{VeryImportantMessage|Important Message}}
|Used to highlight very important messages. Use sparingly.
|--
|[[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}}
|Marks work in progress on a documentation page.
|--
|[[Template:Quote|Quote]]
|{{Quote|text=Cry "Havoc" and let slip the dogs of war.|sign=[[William Shakespeare]]|source=''[[Julius Caesar (play)|Julius Caesar]]'', act III, scene I}}
|Quote for citations.
|--
|Click
|'''Deprecated'''
|Superimpose an invisible link on an image. You should use the native Wiki picture inclusion method instead.
|--
|DASH
|'''Deprecated'''
|Text box type code, colorful background. You should use the style you obtain starting the source line with a space.
|--
|Disambig
|'''Deprecated'''
|Not used.
|--
|Information
|'''Deprecated'''
|Not used. 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'''
|Obsolete with the new wiki, translations and languages are managed via a dedicated tool.
|--
|Message
|'''Deprecated'''
|For not very important messages. Not used.
|--
|Powerdocnavi, Devdocnavi, Userdocnavi
|'''Deprecated'''
|Bottom page navigation. Not to be used, redundant.
|--
|Screenshot
|'''Deprecated'''
|See [[#Screen capture]] instead.
|}


<!--T:49-->
To have a global view on the chromatic aspect, see [[WikiPagesBasicColors|Basic Graphic Template]].
<code><nowiki>[[WikiPages/fr#Liens|WikiPages]]</nowiki></code>


<!--T:50-->
===Code===
Within the same page you can omit the page name. Example:
Code must be styled using the [[Template:Code|Code]] template.


<!--T:165-->
Code description should follow the text box generated by the [[Template:Code|Code]] template, so that the description is structured according to the content. Accentuation should be strictly used ''only'' on the word or lines that must be accentuated.
<code><nowiki>[[#Links|Links]]</nowiki></code>


<!--T:33-->
====Example of bad code description====
To link to the top of the page you can use:


</translate>
{{Code|code=
<code><nowiki>&lt;/translate&gt;{{Top}}&lt;translate&gt;</nowiki></code>
makeAngularDimension (center,[angle1,angle2],p3): creates an angular Dimension from the given center,
<translate>
with the given list of angles, passing through p3. Returns the newly created object.
}}


<!--T:35-->
====Example of good code description====
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-->
{{Code|code=
; Image link
makeAngularDimension (center,[angle1,angle2],p3)
: [[Image:Draft_Wire.svg|24px|Optional text that is shown when you hover the image|link=Draft_Wire]]
}}


<!--T:227-->
* Creates an angular Dimension from the given center, with the given list of angles, passing through p3.
To use an image as a link:
* Returns the newly created object.


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


<!--T:229-->
===General===
; Image link + text link
Avoid thumbnails whenever possible. Pictures should be shown in their original size, to avoid the need for the user to continuously navigate back and forth between different pages. Most important even, in the automatically generated printed manual (e.g. pdf version), thumbnails may not be readable. Thumbnails should be used only as last resource.
: [[Image:Draft_Wire.svg|24px|link=Draft_Wire]] [[Draft_Wire|Draft Wire]]


<!--T:230-->
For the same reason, you should avoid animated pictures (i.e. gif). Animation should be reserved for tutorials not intended to be read as static content (e.g. video).
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-->
Pictures must be uploaded through the [[Special:Upload]] page.
<code><nowiki>[[Image:Draft_Wire.svg|24px|link=Draft_Wire]] [[Draft_Wire|Draft Wire]]</nowiki></code>


=== Workbench pages === <!--T:166-->
===Screen capture===
Recommended size for screen captures, to avoid any resizing when showing the picture, should be:
* native 400x200 (or width=400 and height<=200), for [[Gui Command]] 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]] 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, however use native resolution, not resizing or thumbnails, unless you have a very good reason to do so.
* Avoid larger resolutions, as they won't be much portable to any kind of display or in printed (pdf) documentation.


<!--T:52-->
If possible, you shouldn't depend too much on any OS. While of course achieving 100% independency from the underlying OS is not possible, you should use visual defaults whenever possible.
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-->
====Text====
See [[#Screen_capture|#Screen capture]] for conventions on including images.
To ease documentation translations, if you put a screenshot showing the interface, you should not show the 3D model view in the same screenshot. In this way, the translator will not have to hunt for the model used to create the screenshot, and can simply take a screenshot of the localized interface. If there are drop down menus in the taskbar, the options should be listed in the text content.


=== Command pages === <!--T:167-->
If your screen capture contains text (e.g. a menu), use the same resolution of the original interface item in FreeCAD. This avoids to have images containing very large or very small text, and keeps the same look and feel of the FreeCAD native interface.


<!--T:54-->
=====Good picture text dimension=====
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.
[[Image:partdesign_revolution_parameters.png]]


<!--T:56-->
=====Bad picture text dimension=====
Please refer to the [[GuiCommand_model|GuiCommand model]] page for more details.
[[Image:partdesign_revolution_parameters.png|190px]]


=== Tutorials === <!--T:168-->
In this picture, note that the text dimension is acceptable, but there still are visual artifacts due to rescaling (the original width is 307px, rescaled to 190px)
You should use native resolution to avoid visual artifacts due to rescaling.


<!--T:57-->
===Icons and graphics===
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.
Refer to this page for ready-to-use [[Artwork]] and Icon creation rules.


<!--T:60-->
==Models==
For examples visit the [[Tutorials|Tutorials]] page.
The following pages contain models for FreeCAD documentation.
</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">
* [[GuiCommand_model]]
<translate>
* [[Boiler_NonCommand]]


== Templates == <!--T:70-->
==Translations==
</translate>
<div class="mw-collapsible-content">
<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 per general consensus, the reference page is the English page, that should be created first. Moreover, if you want to change or add content in a page, you should do it in the the English page first, and only once the update is completed, port the modification to the translated page.
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.


=== Simple templates === <!--T:170-->
The FreeCAD wiki supports a Translation plugin which allows to manage translations between pages.


<!--T:74-->
For details on translation, see FreeCAD Wiki Translation Process under [[Localisation]].
These templates accept a simple text parameter, and format it with a particular style.
{|{{Prettytable}}
!style="width:10%;"|Template
!style="width:20%;"|Appearance
!style="width:70%;"|Description


<!--T:236-->
Other useful resources are:
|--
* Language Codes: http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
|[[Template:Top|Top]]
* Country Flags: http://en.wikipedia.org/wiki/Gallery_of_sovereign_state_flags
|
* Google Translate: http://translate.google.com/


</translate>{{Top}}<translate>
== Some tips for translators ==


<!--T:238-->
===Setting Docnav===
|Use it to add a link to the top of the page.


<!--T:171-->
See this link in the forum: http://forum.freecadweb.org/viewtopic.php?f=21&t=6716
|--
|[[Template:Emphasis|Emphasis]]
|{{Emphasis|emphasis}}
|Use it to emphasize a piece of text.


<!--T:172-->
===Using special pages===
|--
|[[Template:KEY|KEY]]
|{{KEY|Alt}}
|Use it to indicate a keyboard key that needs to be pressed.


<!--T:173-->
*[[Special:LonelyPages|Orphaned pages]] list those pages that are not linked from or transcluded into other pages in FreeCAD Documentation. These pages are not accessible via links (no one sees them). If you find in your native language, try to create the connection that exists in the English page, otherwise no one can read them.
|--
*[[Special:UncategorizedPages|Uncategorized pages]] pages without category. They do not appear when you browse the categories. Assign a category.
|[[Template:ASCII|ASCII]]
*[[Special:WantedPages|Wanted pages]] pages that are called, but that do not exist. Red link in the texts. Deprecated and very annoying.
|{{ASCII|A}}
*Others Wanted (files and templates)
|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.
*[[Special:WantedCategories|Wanted categories]] they exist always, not only has been edited text. Skip.
*[[Special:Categories|Categories]] allow you to compare the number of pages of a given type of the original version with those translated into the specified language.
*[[Special:ListRedirects|List of redirects]] allows you to control the correct redirection pages. If there are any red links, something does not work well. Investigate. Light blue links lead to pages outside the site, no problem.
*[[Special:RecentChanges|Recent changes]] track the most recent changes to the wiki.
*[[Special:LanguageStats|Language statistics]] shows translation statistics for all message groups for a 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 statistic. It also contains the link to see what has been recently translated into that language. Note: If entering code en pages appear, it is likely that the original page contains markup errors (Sidebar apart).
*[[Special:PageTranslation|Page translation]] allows you to see all the pages marked for translation, but also the updated and unmarked pages. Only administrators can mark pages for translation.
*Category:Pages to delete: list of pages to be deleted, created by mistake or unnecessary.


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


<!--T:175-->
At the page [[WikiRobots]] you can find instructions on how to set-up and use robots to automate repetitive tasks on the FreeCAD Wiki.
|--
|[[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-->
==Discussion==
|--
The Forum provides a dedicated section for discussing [http://forum.freecadweb.org/viewforum.php?f=21 documentation wiki] topics. Direct your questions there.
|[[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-->
|--
|[[Template:SpinBox|SpinBox]]
|{{SpinBox|1.50}}
|Use it to indicate a spinbox in the graphical user interface that needs to be modified.


<!--T:178-->
==Brainstorming==
|--
|[[Template:ComboBox|ComboBox]]
|{{ComboBox|Menu 1}}
|Use it to indicate a combobox in the graphical user interface that needs to be modified.


<!--T:239-->
{{VeryImportantMessage|All that follows from now on is only for open discussion. You can stop reading here if you don't intend to brainstorm modifications of the FreeCAD WikiPages style rules. You can anyway post and discuss any Wiki-related topic on the [[http://forum.freecadweb.org/viewforum.php?f=21 Forum]]. Contributions are welcome.}}
|--
|[[Template:LineEdit|LineEdit]]
|{{LineEdit|Metal Nickel (Ni)}}
|Use it to indicate a LineEdit in the graphical user interface that needs to be modified.


<!--T:179-->
===Workflow, Roadmap===
|--
|[[Template:FALSE|FALSE]], [[Template:false|false]]
|{{FALSE}}, {{false}}
|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}}


<!--T:180-->
Organize pages in the wiki
|--
|[[Template:TRUE|TRUE]], [[Template:true|true]]
|{{TRUE}}, {{true}}
|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}}


<!--T:181-->
====Content and Appearance:====
|--
** Renato: ''width of the page, now much space is unused (only for monitor 16:10)''
|[[Template:MenuCommand|MenuCommand]]
** Renato: ''white background, text more readable''
|{{MenuCommand|File → Save}}
** Renato: '' links to similar commands, similar tools, scripts, examples, discussions, insights, forum, other... On all pages or only on some pages?''
|Use it to indicate the location of a command inside a particular menu.


<!--T:182-->
====Templates====
|--
I think the things like this are also templates? <nowiki>{{PartDesign Tools}}</nowiki>
|[[Template:FileName|FileName]]
This template contains headlines, icons, short textual description, long textual description, list elements. May be easier to handle when splitted in pieces (at least: icon list, description list, "full featured": array of someWorkbenchTools[icon|description,{2-4}]...) ?
|{{FileName|File name}}
|Use it to indicate a name of a file or directory.


<!--T:183-->
* Basic Template that would be useful
|--
{|{{Prettytable}}
!Template
|[[Template:SystemInput|SystemInput]]
|{{SystemInput|Type this text}}
!Note
|Use it to indicate user typed input text.
!Note
|--
|suggestion
caution
|useful?
|as Message?
|--
|alert
|useful?
|as VeryImportantMessage?
|--
|idea
|useful?
|
|--
|shortcut
|
|as KEY?
|}


<!--T:184-->
|--
|[[Template:SystemOutput|SystemOutput]]
|{{SystemOutput|Output text}}
|Use it to indicate text output from the system.


<!--T:185-->
|--
|[[Template:Incode|Incode]]
|{{incode|import FreeCAD}}
|Use it to include in-line source code with a monospace font. It should fit in one line.


<!--T:186-->
{|{{Prettytable}}
|--
!Template
|[[Template:PropertyView|PropertyView]]
!Appearance
|{{PropertyView|Color}}
!Description
|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.
|--
|Clear
|ok
|Template for clearing columns
|--
|Click
|rarely used
|superimpose an invisible link on an image
|--
|DASH
|rarely used
|text box type code, colorful background
|--
|Disambig
|not used
|
|--
|Docnav
|ok
|
|--
|FALSE
|color or black and gray?
|<span style="color: #990000; background-color: #f1cece;">'''FALSE'''</span> <span style="color: #990000; background-color: #DDDDDD;">'''FALSE'''</span> <span style="color: #990000; background-color: #DDDDDD;">FALSE</span> <span style="color: #990000; background-color: #DDDDDD;">'''False'''</span> <span style="color: #990000; background-color: #DDDDDD;">False</span> <span style="background: #DDDDDD; border: 1px solid #888888; padding: 0px 5px 1px 5px;">False</span> <span style="background: #DDDDDD; border: 1px solid #888888; padding: 0px 5px 1px 5px;">'''False'''</span> <span style="background: #DDDDDD; border: 1px solid #888888; padding: 0px 5px 1px 5px;">'''False'''</span> <span style="background: #FFFFFF; border: 1px solid #888888; padding: 0px 5px 1px 5px;">'''False'''</span>
|--
|[[Gui Command]]
|ok
|the main anchor on documenting GuiCommands
|--
|[[MenuCommand]]
|{{MenuCommand|File->Save}}
|Text that is displayed in a GUI command menu
|--
|Information
|not used
|A standardized table providing complete information about the file, including description of what it shows and how it was made, copyright status and source.
|--
|[[KEY]]
|{{KEY|ALT}}
|Show a keyboard key
|--
|Languages
|ok
|obsolete with the new wiki
|--
|Macro
|ok, used
|the main anchor on documenting macros
|--
|Message
|rarely used
|for message not very important
|--
|VeryImportantMessage
|ok, used
|for message very important
|--
|Prettytable
|used for this table
|could have different colors
|--
|PropertyView
|background green or gray?
|<span style="background: #C2EEAA; border: 1px solid #bbbbbb; padding: 0px 5px 1px 5px;"><small>VIEW</small> '''Property'''</span> <span style="background: #DDDDDD; border: 1px solid #bbbbbb; padding: 0px 5px 1px 5px;"><small>View</small> '''Property'''</span>
|--
|Properties Title
|spelling. color or black and gray?
|{{Properties_Title|Base}}
|--
|PropertyTasks
|color or black and gray?
|{{PropertyTasks|Length}} Renato: ''serve but too many disturbing reading''
|--
|Screenshot
|link
|<small>{{{2}}} - see more [[screenshots]]</small>
|--
|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.
|--
|TasksTag
|color or black and gray?
|{{TasksTag|Text}}
|--
|TRUE
|color or black and gray?
|{{TRUE}}
|--
|UnfinishedDocu
|ok
|mark not finished documentation.
|--
|Version
|FreeCAD version, small text
|
|--
|
|
|
|}


<!--T:187-->
|--
|[[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.


<!--T:188-->
* Other Template
|--
* PartDesignTools
|[[Template:Properties Title|Properties Title]] / [[Template:TitleProperty|TitleProperty]]
* _______________
|{{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.


<!--T:189-->
===Forum===
|--
* Reflect on requests for help made ​​in the forum and use the given examples (if it is required an aid often means that the manual is not exhaustive, in the forum there are good examples, but hard to find)
|[[Template:Obsolete|Obsolete]]
** Renato: ''Insert a link on the document page or insert the example or insert nothing?''
|{{Obsolete|0.19}}
***Ralf: insert link(s) always in a field/area which is always there on every page. If there is nothing to link, there should be a text in this area as "There is currently no link to forum examples."
|Use it to indicate that a feature became obsolete in the specified FreeCAD version.
***Ralf #2 examples: no examples at pages which are describing more than exactly the use of (probably mostly) a tool. If there would be examples (at different pages) which differ in various ways and are not comparable are confusing.
*** Ralf #3 examples: But beside of existing examples: defining a "standard model" (or some of them if needed for fairly different tasks as p.e. Part-Design vs. Arch) for really every example would promise a lot of advantages. The first one: if one like to try an example the related model file is available right there with the next click. Whatever the "standard model" could be - the most important condition it have to be usable for all examples/task from to simplest up to the most complex (FEM,assembly?!)
*** May be such an ''standard model'' and his incarnations could be also a kind of a "figurehead" for FC.<br>
*** [[User:Ediloren|Ediloren]] ([[User talk:Ediloren|talk]]) 18:01, 3 September 2013 (CEST) : looks like a good idea but not too practical; I expect that the burden of adding examples for everything would be very high. I would prefer to resort on tutorials, videos, and forum unless somebody has really the time and commitment to follow this part (me not, sorry :) )
[[WikiPagesFromForum|Some useful examples taken from the forum]]


<!--T:190-->
===Documentation structure:===
|--
* Links between pages (tree and hierarchy linear, orderly, full)
|[[Template:Version|Version]]
** Renato: ''If there is an index the docnav does not serves.''
|{{Version|0.18}}
* Page titles descriptive
|Use it to indicate that a feature was introduces in the specified FreeCAD version.
** Renato: ''Translated or not translated? With the new translator seems outdated''
* Structure of the documentation (depending on the type of user and the type of documentation). ''Group some things? - If possible in any way: group everything to maximal seven (7) entrys (per group)(Ralf).'':
** Reference (needs indicate precise criteria) (Ralf: for me for advanced users/using, #3)
** How to (Ralf: additional, #4)
** Tutorial (Ralf: additional, #5)
*** External links
** Themed (Ralf: 1st thing / start point while using the documentation? - for me #1)
** examples - in relevant cases - the most basic example for using the tool / workbench /feature (is that possible with complex tools?) ; may be one "standard" example case for the most examples, if possible (so the fcstd file can be supplied and re-used for a lot of uses) for me #2 or to #1<br>
** linear (all, as now)
** structured with sub-structures (very clear if there are no more than 5..7 entrys per structure layer)
** task - specific (features is other than transform than handle mouse etc.)
** FAQ
** Books
** Plugins
** Macro


<!--T:191-->
===Documentation schemes===
|--
|[[Template:VersionMinus|VersionMinus]]
|{{VersionMinus|0.16}}
|Use it to indicate that a feature is available in the specified FreeCAD version and earlier versions.


<!--T:192-->
See [[WikiPagesDocSchemes|Documentation schemes]]
|--
|[[Template:VersionPlus|VersionPlus]]
|{{VersionPlus|0.17}}
|Use it to indicate that a feature is available in the specified FreeCAD version and later versions.


<!--T:193-->
===Repository===
|--
* fcstd file
|[[Template:ColoredText|ColoredText]]
* pics, images
|{{ColoredText|Colored Text}}
* icons (there are almost all)
|Use this template to color the background, text, or background and text. ([[Template:ColoredText|ColoredText]] page for more examples)
* "Show your FreeCAD projects here!" archives


<!--T:194-->
===Who are the users:===
|--
* New users FreeCAD:
|[[Template:ColoredParagraph|ColoredParagraph]]
** Users without CAD experience -> not the job of the FreeCAD doc to teach them CAD - the job to teach them how to use FreeCAD? ''Renato: I think that FreeCAD is currently the only free CAD program with a professional approach. Many people exactly look for this to begin.''
|{{ColoredParagraph|Colored Paragraph}}
** Users with CAD experience (2D/3D/parametric); users with 3D experience - no CAD
|Use this template to color the background, text, or background and text of an entire paragraph. [[Template:ColoredParagraph|ColoredParagraph]] page for more examples)
** Users who know how to program (version?)
|}


=== Complex templates === <!--T:195-->
* Users who know FreeCAD:
** Users
** Advanced users
** Developers


<!--T:75-->
===What the users needs:===
These templates require more input parameters, or produce a block of text with a particular format.
* According to the category of the previous point they need different things (to be determined).
* Renato: ''In my opinion the beginners to FreeCAD (or to CAD?) needs:''
** ''find the information immediately'' + Ralf: in the expected, consistent way
** ''know what are the workbenches, when and how to use them,'' + Ralf: is this one workbench all I need or do I need more than one?
** ''the commands that are available,'' + Ralf: in the workbench - for the task - all
** ''the workflow to use,'' - Ralf: workflow sounds specific - may be the most basic way to use this - may be especially for tools there could be more than page per tool (as above: basic for beginners, extended use for advanced users)
** ....


<!--T:196-->
===Translations===
{|{{Prettytable}}
!style="width:10%;"|Template
!style="width:45%;"|Appearance
!style="width:45%;"|Description


<!--T:197-->
* Consistent (the reference page is the English page, see the various discussions regarding the rules in the forum)
|--
* Updated (how?) + Ralf: 1st: Version, 2nd: frozen state of doc page - "this is the actual version of the documentation of ... for FC version xxx"; 3rd linked archiv pages of other versions (and maybe other frozen states), all with corresponding "tags" / marks
|[[Template:Prettytable|Prettytable]]
** ''Use a document type that including at least one complete section of the manual (not just one page at a time). Comparable off line with an previous version. With "Recent changes" is difficult to follow all the changes, when they are frequent.''
|This table
* FCSTD files for Documentation ''(wandererfan wrote: It would be nice to have a repository for the fcstd files +Ralf and it would be very helpful - used to generate screenshots, etc. Then the 2nd author/translator could just open the fcstd with a different locale to generate the new screenshot. This would also for standardization of background colours, font sizes, etc. )''
|Use it to format tables such as this one. Additional table properties can be added.
* Renato. My personal:
''- The wiki, is the best way to create documentation FreeCAD? Would not it be better to reserve it for some issues and create a comprehensive manual for each version?''<br>
''- About updates, this is a crucial point, I've seen that you do not like docboock, and I do not intend to return to this theme, but docboock allows translators to easily work on documents. Allows you to download the entire document and compare it with the previous one. With this way changes are made always and only in the original document. Then the translators periodically (even daily if they want) downloading the document and compares with an earlier version and update it indicating the upgrade version. I've experienced that this procedure is very good. Can I do a similar thing with the wiki? In this way there is no need to continuously monitor Recent Changes and updates are easier to control.''


<!--T:198-->
===Some notes taken from the forum===
|--
|[[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-->
yorikvanhavre wrote: ''Actually we could do a little brainstorming, see things that should be changed on the wiki...''
|--
''I already thought of a couple of things: - a new wiki homepage with a clear view of the contents - better formatting of the 3 principal sections, for user (basically the command pages), for power users (everything about python) and the higher-level stuff (compiling, etc) - more professional aspect of the wiki pages - build a better and more strict model for command pages - find a good system to handle translations''
|[[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-->
gdo wrote: ''But maybe a survey to freecad users could help to understand precisely what is the beginners needs.''
|--
|[[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-->
Ralf wrote: ''Even for the ones who are trying FreeCAD the first times, it's essential to find a consistent documentation otherwise they weren't motivated to give even some first tries.''
[[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.


<!--T:241-->
|--
|[[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-->
And many more ... dispersed and mixed in:
|--
*[http://forum.freecadweb.org/viewtopic.php?f=8&t=3167 SF hosted app retairement & call for help]
|[[Template:Codeextralink|Codeextralink]]
*[http://forum.freecadweb.org/viewtopic.php?f=10&t=3899 doc - some detail questions about changing, display, structure]: Misalignment of ToC (left menu vs. ToC and page titles), links should be called as the pages
|{{Codeextralink|https://wiki.freecad.org/Main_Page}}
*[http://forum.freecadweb.org/viewtopic.php?f=8&t=3988 wiki pages]: Best pages examples (long) discussion, propose to establish clear rules, minimize screenshots, don't use thumbnails, English pages are master, Navigation bar at the bottom like in Sketcher_Point (my view: no; use ToC), image dimensions, misalignment of ToC (Each information is linked to an index directly from the main page. The main menu expands into sub-menu. You can clearly see the hierarchy of the entire document. The documentation must be so.), how to manage docs for different FC versions, (OT: is there a timeout for editing a post? On-again some of my posts are lost in space)
|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.
* [http://forum.freecadweb.org/viewtopic.php?f=21&t=1805 Online Help (Wiki) TODO List]: Misalignment and importance of ToC (it is what gets in FreeCAD Help), grouping of workbenches (alphabetically says normandc) topic left in April 10
*[http://forum.freecadweb.org/viewtopic.php?f=21&t=3818 Wiki for New Functions?]: How to mark versions in the Wiki
*[http://forum.freecadweb.org/viewtopic.php?f=12&t=3959 Règles a suivre pour le nouveau wiki]
*[http://forum.freecadweb.org/viewtopic.php?f=13&t=4025 Tutorials auf Deutsch für FreeCAD]


<!--T:201-->
===Examples of CAD documentation===
|--
|[[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-->
http://help.solidworks.com/2013/English/SolidWorks/sldworks/c_Sketch_Fillets.htm?id=cb1f4dfbe23245aeb58d17af808ee10c#Pg0 <br>
|--
|[[Template:GuiCommand|GuiCommand]]
|See [[GuiCommand model|GuiCommand model]]
|Use it to create a box with useful information to document workbench commands (tools).


<!--T:203-->
Ralf: good: you can see where you are ; bad: a huge lot of entrys in the navigation / summary at left - the opposite of structured; sorry: pieces of the forum at the documentation page: what is the documentation page good for than? (but the link to the forum / forum search - ok.)<br>
|--
http://www.gcad3d.org/ <br>
|[[Template:TutorialInfo|TutorialInfo]]
Ralf: thumbs up. clear, well structured. sometimes long but I don't know how to avoid that at some themes. Maybe the tree structure layers could be separated in two directions at the page for more place for the content. They have "last updates" I prefer "this version of the documentation is xxx and depend the program version xxy"
|See for example [[Basic_modeling_tutorial|Basic modeling tutorial]]
|Use it to create a box with useful information to document [[Tutorials|tutorials]].


<!--T:204-->
Reported by wandererfan<br>
|--
guidelines for wiki authors:<br>
|[[Template:Macro|Macro]]
http://wiki.blender.org/index.php/Meta:Guides/Writer_Guide<br>
|See for example [[Macro_FlattenWire|Macro FlattenWire]]
http://wiki.blender.org/index.php/Meta:Guides/Style_Guide<br>
|Use it to create a box with useful information to document [[macros|macros]].
Manual TOC:<br>
http://docs.gimp.org/2.8/en/<br>
http://wiki.blender.org/index.php/Doc:2.6/Manual<br>


<!--T:205-->
Reported by Ralf:<br>
|--
http://opensourceecology.org/wiki/FreeCAD<br>
|[[Template:Docnav|Docnav]]
|{{Docnav|Online Help Startpage|Feature list}}
|Use it to create a bar with arrows and appropriate links, which is useful for putting pages in a particular sequence.


<!--T:206-->
For the Italian translation also:<br>
|--
http://tp.linux.it/
|[[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-->
===Next actions ===
|--
# gather ideas
|[[Template:Page in progress|Page in progress]]
# build Table of Contents
|{{Page in progress|Page in progress}}
# build good models (in the template created by Wandererfan)
|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.
# edit the master page in English (updated until a new FreeCAD version is released then freeze the document in pdf or doc or other)
# translate (updated until a new FreeCAD version is released then freeze)
# continue to develop the documentation for the new version of FreeCAD (repeats 4)
# continue to develop the translation for the new version of FreeCAD (repeats 5)


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


<!--T:209-->
===English===
|--
See [[Glossary]]
|[[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-->
===Other languages===
|--
*[[Italian_Translation|Italiano]]
|[[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-->
'''proposal to create the page:'''
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-->
==[[Start Workbench|Start Center]] ==
Images can be uploaded through the [[Special:Upload|Special:Upload]] page.


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


<!--T:90-->
When you start FreeCAD for the first time, you are presented with the start center:
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:
* 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 [[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.
* 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.


<!--T:92-->
[[Image:Startcenter.jpg|1024px|center]]
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.


<!--T:2-->
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-->


<!--T:93-->
The Start Center allows you to quickly jump to one of the most common workbenches, open one of the recent files, or see the latest news from the FreeCAD world. You can change the default workbench in the [[Preferences Editor|preferences]].
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.


=== Icons and graphics === <!--T:216-->
'''Use this part of [[Getting started]] then add more information'''


<!--T:98-->
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>
</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">
= Sandbox for Macro Dimensions =
<translate>


== Translations == <!--T:99-->
{{Macro|Icon=Text-x-python|Name=Dimensions|Description=Dimensioning |Author=eason}}
</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.


<!--T:100-->
==Description==
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]].
Macro for easy add dimension to Draft ... objects ...


<!--T:101-->
[[File:DM.png]]
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://translate.google.com/ Google Translate] for help with translations.
* [https://www.deepl.com/translator Deepl translator] for help with translations.


== Some tips for translators == <!--T:102-->
==How to install==
* Copy and paste the code into a macro (see [http://www.freecadweb.org/wiki/index.php?title=Macro_Install_HowTo Ho to install macro])
* Save with a meaningful name (for me "dm")


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


</translate>
<pre>
{{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]]
}}
</pre>
<translate>


<!--T:105-->
==Start==
Translated:
* In FreeCAD Python Console digit "import dm" -> Return
* In FreeCAD Python Console digit "dm.showup()" -> Return
* set path for .ttf
** in its latest tested version, the path must be defined on line 1112, replacing ''path = "/usr/share/fonts/truetype/ubuntu-font-family/Ubuntu-B.ttf" ''
* set other options


</translate>
==Use==
<pre>
* Auto: Vertical + parallel. Point1 and point2 you click decide the string, and the point3 decide direction and the position.
{{GuiCommand/fr
* 2Point: The string is the distance of the point1 and point2. Point3 decide the position of the string.
|Name=FEM EquationFlux
* Vertical: Just like auto, but the direction must be vertical.
|Name/fr=FEM Équation d'écoulement
* <del>Parallel: Just like auto, but the direction must be parallel.</del>
|MenuLocation=Solveur → Équation de flux
* Orthogonal:
|Workbenches=[[FEM_Workbench/fr|Atelier FEM]]
* Angle: To click line1 and line2. They will decide a angle. And last point decide the position of the string.
|Shortcut={{KEY|F}} {{KEY|S}}
* Custom: Mmake a String what you enter. Point1 is the start. point2 is the end.
|Version=0.17
* Del obj: It can delete the dimension you make. Just click it and what you clicked will be deleted.
|SeeAlso=[[FEM_tutorial/fr|FEM Tutoriel]]
*
}}
*
</pre>
<translate>


=== Translate navi === <!--T:107-->
==Limitations and things to improve==
* When lines are moved, the dimensions do not follow the design
* <del>parallel functions as "orthogonal" (to me)</del> ''solved, parallel has been removed''
* <del>path for .ttf is lost when exit, or Freecad is closed</del> ''solved, now the path is set in the code''
* It can not be paused, but it is always active, or exit
* It works only in the xy plane, or planes parallel to the xy
* When you break a dimension, disappear all properties


</translate>
==Script==
<pre>
* download from the forum, here it is not accepted
{{FEM_Tools_navi}}
* if it is present, remove the line 9 "import GSDraftGeomUtils"
</pre>
<translate>


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


</translate>
==Links==
<pre>
* [http://forum.freecadweb.org/viewtopic.php?f=22&t=13814 Discussion in the forum]
{{FEM_Tools_navi/fr}}
</pre>
<translate>


=== Translate link === <!--T:111-->
==Other similar instruments==


</translate>
<br /><br /><br /><br /><br />
<pre>
[[Part_Module|Part Module]]
</pre>
<translate>


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


</translate>
= Sandbox for PartDesign Fillet =
<pre>
[[Part_Module/fr|Atelier Part]]
</pre>
<translate>


=== Translate Docnav === <!--T:119-->
Some considerations about Part Design Fillet.


</translate>
Fillet is a useful tool, very agile for certain operations, but subject to certain limitations.
<pre>
{{Docnav
|[[About_FreeCAD|About FreeCAD]]
|[[Installing_on_Windows|Installing on Windows]]
}}
</pre>
<translate>


<!--T:218-->
The examples are based on a cube 10x10x20.
Translated:


</translate>
'''First case. Fillet on an edge.'''
<pre>
{{Docnav/fr
|[[About_FreeCAD/fr|À propos de FreeCAD]]
|[[Installing_on_Windows/fr|Installation sous Windows]]
}}
</pre>
<translate>


<!--T:219-->
[[File:Imm1.png]]
Example with icons:


</translate>
In appearance this tool acts on an edge, but in reality creates a curved surface that joins two other surfaces.
<pre>
Therefore it uses two faces as references, for example the side face and the upper face of a cube.
{{Docnav
At the edge that separates them can be applied a rounding with a radius equal to the limit dimension of the smaller face less a "residual safety value" of 0.0001 (according to the value of decimal set).
|[[Std_Save|Save]]
The "security value" serves to maintain existing a small surface, in this case large 0.0001.
|[[Std_SaveCopy|SaveCopy]]
|[[Std_File_Menu|Std File Menu]]
|IconL=Std_Save.svg
|IconR=Std_SaveCopy.svg
|IconC=Freecad.svg
}}
</pre>
<translate>


<!--T:220-->
[[File:Imm2.png]]
Translated:


</translate>
When one of the two surfaces that are connected disappears completing the operation fails because it lacks one of the references used by the function, and the result is unpredictable.
<pre>

{{Docnav/fr
'''Second case. Fillet applied on two opposite edges of the same face.'''
|[[Std_Save/fr|Enregistrer]]

|[[Std_SaveCopy/fr|Enregistrer une copie]]
[[File:Imm3.png]]
|[[Std_File_Menu/fr|Menu fichier]]

|IconL=Std_Save.svg
In this case, there is not a limit radius, but the limit is (R1 + R2 <thickness-0.0001).
|IconR=Std_SaveCopy.svg
The limit is valid if R1 or R2 are not superior to others thicknesses involved in the operation (eg. The height of the cube).
|IconC=Freecad.svg
The "residual safety value" is positioned at the junction of the fillets.
}}

</pre>
[[File:Imm4.png]]
[[File:Imm5.png]]


It is recommended to use this function only when modeling is ended, to eliminate "sharp corners", and instead use alternative tools to produce the model.

'''Alternative methods of rounding.'''


</div> <!-- END of Translation section collapsible element. Do not remove! -->
A simple method to create the rounded surfaces in a continuous manner, without the "surface residue" is, for example, to create a "cleaner" sketch on the front face as in this figure
</div> <!-- END of Translation section collapsible element. Do not remove! -->


<translate>
[[File:Imm6.png]]
== Create, rename and delete pages == <!--T:128-->


=== Create pages === <!--T:232-->
and then apply a Pocket -> Through all.
It returns a completely clean solid, without any interruption of the rounding surface.
Adequately shaping the sketch you can create any profile, even eccentric.


<!--T:233-->
[[File:Imm7.png]]
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-->
Even the Boolean operations allow to obtain the same result, but the dependence of the elements is different.
To create a new page do one of the following:
* 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'.
* 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 === <!--T:129-->
Since version 0.16_pre 6692 FreeCAD has been equipped with an extra check if fillet and chamfer operation returns valid shape.


<!--T:130-->
==Links==
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:
http://forum.freecadweb.org/viewtopic.php?f=21&t=15141


</translate>
<pre>
old name new name
Old_page_name_1 New_page_name_1
Old_page_name_2 New_page_name_2
...
</pre>
<translate>


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


<!--T:136-->
'''PartDesign'''
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-->
Lines created by a PartDesign Fillet can not be selected for an additional fillet or a chamfer.
For pages the procedure is the same.


== Discussion == <!--T:222-->
PartDesign Chamfer has the same behavior.


<!--T:140-->
Lines created by a Chamfer can be selected for an additional chamfer or fillet.
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.


== Terminology - naming policy == <!--T:144-->
PartDesign fillet and chamfer on tangent edges..........


=== English === <!--T:223-->
'''Part''' .......... many things are similar.


<!--T:145-->
See [[Glossary|Glossary]].


=== Other languages === <!--T:224-->


<!--T:146-->
* [[Italian_Translation|Italiano]]
* [[French_Translation|Français]]
* [[German_Translation|Deutsch]]
* [[Polish_Translation|Polish]]
* [[Spanish_Translation|Spanish]]


{{languages | {{|}} {{|}} }}


</translate>
[[Category:Documentation]]
[[Category:Documentation{{#translation:}}]]
[[Category:Wiki{{#translation:}}]]
[[Category:Wiki Documentation{{#translation:}}]]
[[Category:Administration{{#translation:}}]]

Latest revision as of 11:37, 16 April 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 arrows and 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