Detailed Preferences documentation available

Info about new community or project announcements, implemented features, classes, modules or APIs. Might get technical!
PLEASE DO NOT POST HELP REQUESTS OR OTHER DISCUSSIONS HERE!
User avatar
uwestoehr
Posts: 587
Joined: Sun Jan 27, 2019 3:21 am

Detailed Preferences documentation available

Postby uwestoehr » Sat Mar 09, 2019 12:43 am

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
Posts: 8452
Joined: Mon Dec 12, 2011 4:45 pm

Re: Detailed Preferences documentation available

Postby triplus » Sat Mar 09, 2019 1:20 am

Nice!
chrisb
Posts: 16914
Joined: Tue Mar 17, 2015 9:14 am

Re: Detailed preferences description

Postby chrisb » Sat Mar 09, 2019 8:12 am

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
Site Admin
Posts: 14456
Joined: Thu Feb 19, 2009 10:32 am

Re: Detailed Preferences documentation available

Postby wmayer » Sat Mar 09, 2019 10:49 am

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.
User avatar
Kunda1
Posts: 4812
Joined: Thu Jan 05, 2017 9:03 pm

Re: Detailed Preferences documentation available

Postby Kunda1 » Sat Mar 09, 2019 1:28 pm

uwestoehr wrote:
Sat Mar 09, 2019 12:43 am
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 ?
Want to contribute back to FC? Checkout:
#lowhangingfruit | Use the Source, Luke. | How to Help FreeCAD | How to report FC bugs and features
User avatar
uwestoehr
Posts: 587
Joined: Sun Jan 27, 2019 3:21 am

Re: Detailed Preferences documentation available

Postby uwestoehr » Sat Mar 09, 2019 3:43 pm

Kunda1 wrote:
Sat Mar 09, 2019 1:28 pm
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.
User avatar
uwestoehr
Posts: 587
Joined: Sun Jan 27, 2019 3:21 am

Re: Detailed preferences description

Postby uwestoehr » Sat Mar 09, 2019 3:46 pm

chrisb wrote:
Sat Mar 09, 2019 8:12 am
- 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.

chrisb wrote:
Sat Mar 09, 2019 8:12 am
- 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?
User avatar
uwestoehr
Posts: 587
Joined: Sun Jan 27, 2019 3:21 am

Re: Detailed Preferences documentation available

Postby uwestoehr » Sat Mar 09, 2019 4:01 pm

wmayer wrote:
Sat Mar 09, 2019 10:49 am
%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?

wmayer wrote:
Sat Mar 09, 2019 10:49 am
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

wmayer wrote:
Sat Mar 09, 2019 10:49 am
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.

wmayer wrote:
Sat Mar 09, 2019 10:49 am
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.

wmayer wrote:
Sat Mar 09, 2019 10:49 am
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.
User avatar
sgrogan
Posts: 5207
Joined: Wed Oct 22, 2014 5:02 pm

Re: Detailed Preferences documentation available

Postby sgrogan » Sat Mar 09, 2019 4:39 pm

uwestoehr wrote:
Sat Mar 09, 2019 4:01 pm
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
Site Admin
Posts: 14456
Joined: Thu Feb 19, 2009 10:32 am

Re: Detailed Preferences documentation available

Postby wmayer » Sat Mar 09, 2019 5:49 pm

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