Detailed Preferences documentation available

[uwestoehr]

FreeCAD has tons of great feature. However, as a new user I found it quite hard to get information how they can be used. Many features are already well described in the Wiki but especially preferences settings were not.

Therefore I started a preferences documentation. Here is the result:

https://www.freecadweb.org/wiki/Preferences_Editor

This page contains now a description of every option of the general preferences of FreeCAD and of the different file formats (because they are used by several workbenches). Preference descriptions of the different workbenches have not been touched yet and will not appear in the general preferences Wiki page).

I post this here to announce it but also to invite everybody to help improving it. Because in the Wiki page you can still see some '??' which means information is missing or unclear. If you know something that is not yet documented or you have remarks, please either add this to the Wiki page or post it here.

[triplus]

Nice!

[chrisb]

Thanks for expanding the wiki, it's well presented with the expandable subsections. I have a few minor remarks. Since we had some quarrel in the past, I will not edit this page of yours.
- There are more export formats than are configurable; so the text "FreeCAD supports these file formats:" is misleading because it suggests that these are the only file formats.

- The Expand-button inside of the table header is a bit cumbersome. I would prefer something which makes it clearer what is to be expected on expand, such as a heading "Settings" or "Available Settings".

[wmayer]

Nice work!

I have some comments:
%APPDATA% is a Windows specific environment variable. So, it should be made clear that other OS don't have it defined.

Run macros in local environment -- If checked, macros are executed with the permissions of the local system user.

This has nothing to do with user permissions. When executing a macro then the function PyRun_File of the C API of Python is used. The arguments globals and locals usually are set to the dict of the __main__ module and thus variables that are used in a macro file will be added to this dict or may override existing variables.
This option is about creating a tmp. copy of this dict and passing it to PyRun_File instead to avoid to change anything in the original dict.

Using Undo/Redo on documents -- If checked, all changes in documents are stored so that the can be undone/redone

A word is missing. If checked, all changes in documents are stored so that the operation can be undone/redone

Default text color -- Selection of the default text color for document annotations. There is currently no dialog to add annotations to documents. Annotations can only be added using the Python console with this command:
obj=App.ActiveDocument.addObject("App::Annotation","Label")
This console is shown using the menu View → Panels → Python console.

The Python code is just to demonstrate that an annotation really uses the user-defined color. But IMO in the description you shouldn't give a Python code snippet as for an average user this is irrelevant.

Mesh formats (AMF and STL)

This title is a bit misleading as a user may assume that only the mesh formats AMF and STL are supported. But in fact we support: amf, stl, obj, off, ply, smf.
The first option about maximum deviation applies to all mesh formats, while the second about compression only applies to the amf format.

[Kunda1]

Therefore I started a preferences documentation.

Fantastic work on Preferences Editor
I suggest we float the screenshots to the right, make them larger, and have the descriptions on the left.
Perhaps separate each section with a horizontal rule ?

[uwestoehr]

I suggest we float the screenshots to the right...

I opened also a thread in the Wiki section of the forum because I would go the other way and remove the screenshots because they don't provide any additional info to what you already see in FC and they are not translatable. Especially for the latter I already got several complaints the last days.

[uwestoehr]

- There are more export formats than are configurable; so the text "FreeCAD supports these file formats:" is misleading because it suggests that these are the only file formats.

Thanks, this is now clarified.

- The Expand-button inside of the table header is a bit cumbersome. I would prefer something which makes it clearer what is to be expected on expand, such as a heading "Settings" or "Available Settings".

I don't know what you mean exactly. I have just taken the foldable tables as they are also used in the Wikipedia. Could you give me a syntax example of how I should format the tables or an extra header line?

[uwestoehr]

%APPDATA% is a Windows specific environment variable. So, it should be made clear that other OS don't have it defined.

I will do so. Could you please tell me how the %APPDATA% is usually named on Linux and MacOS?

This option is about creating a tmp. copy of this dict and passing it to PyRun_File instead to avoid to change anything in the original dict.

Thanks, I changed the description but I am not sure that I described this now correctly and short enough:
https://www.freecadweb.org/wiki/Prefere ... itor#Macro

A word is missing. If checked, all changes in documents are stored so that the operation can be undone/redone

The word "the" should have been "they". This is now corrected.

The Python code is just to demonstrate that an annotation really uses the user-defined color. But IMO in the description you shouldn't give a Python code snippet as for an average user this is irrelevant.

But that is why I insisted in the thread where we discussed this:
https://forum.freecadweb.org/viewtopic.php?f=3&t=34675
This preference option affects a feature that is only accessible using Python commands. Therefore I think it only raises questions to average users and I requested to either make it hidden for now or to add a GUI to annotate parts.
If it will be kept as it is I think the Preferences Wiki page must demonstrate how the setting can be used and if that is only by using a Python command then this just the current state.

This title is a bit misleading as a user may assume that only the mesh formats AMF and STL are supported. But in fact we support: amf, stl, obj, off, ply, smf.

This is now clarified. However, I cannot find any info regarding the format SMF. Looking for example here:
https://fileinfo.com/extension/smf
I get 4 different file formats but none of them is a mesh format.

[sgrogan]

I will do so. Could you please tell me how the %APPDATA% is usually named on Linux and MacOS?

For Linux it's .FreeCAD in the users home directory. It is also hidden by default.
BTW: %appdata% resolves to C:\Users\USERNAME\AppData\Roaming

[wmayer]

I will do so. Could you please tell me how the %APPDATA% is usually named on Linux and MacOS?

The directory where we put the user stuff is $HOME/.FreeCAD. But in the future this may change because in order to be XDG compliant the directory should point to $XDG_CONFIG_HOME. See also issue #2956. But this all applies to Linux only.

I don't know if $HOME also exists on macOS but it might be as it also has its roots in Unix. At least the C-API we use on Linux and macOS is basically the same. But on macOS starting this path the user stuff is then in $HOME/Library/Preferences. See https://github.com/FreeCAD/FreeCAD/blob ... .cpp#L2341

This is now clarified. However, I cannot find any info regarding the format SMF. Looking for example here:

SMF = Simple Mesh Format. The link to the specs is here: http://people.sc.fsu.edu/~jburkardt/data/smf/smf.txt