to be renamed: Std_SetColors

Discussions about the wiki documentation of FreeCAD and its translation.
User avatar
uwestoehr
Posts: 1634
Joined: Sun Jan 27, 2019 3:21 am

to be renamed: Std_SetColors

Postby uwestoehr » Sun Aug 02, 2020 5:43 pm

Can anyone please rename the page
Std_SetColors
to
Part_FaceColors

As correctly noted at the top of the page, this feature is part of the Part WB. I already updated the page accordingly but I cannot rename the page.
chrisb
Posts: 25695
Joined: Tue Mar 17, 2015 9:14 am

Re: to be renamed: Std_SetColors

Postby chrisb » Sun Aug 02, 2020 5:47 pm

User avatar
Roy_043
Posts: 1545
Joined: Thu Dec 27, 2018 12:28 pm

Re: to be renamed: Std_SetColors

Postby Roy_043 » Sun Aug 02, 2020 7:40 pm

Is it wise to invent a command name?
renatorivo
Posts: 2500
Joined: Tue Feb 21, 2012 8:07 pm
Location: Torino - Italy

Re: to be renamed: Std_SetColors

Postby renatorivo » Sun Aug 02, 2020 8:42 pm

Sorry, but this page was created in Italian, 2014, before some general rules were established. https://wiki.freecadweb.org/index.php?t ... did=102451

Since the name does not appear in the console, and the command works in all WBs, what is its correct name?
vocx
Posts: 4615
Joined: Thu Oct 18, 2018 9:18 pm

Re: to be renamed: Std_SetColors

Postby vocx » Sun Aug 02, 2020 9:24 pm

uwestoehr wrote:
Sun Aug 02, 2020 5:43 pm
Can anyone please rename the page
Std_SetColors
to
Part_FaceColors
This is an interesting question. How do we document a function that isn't defined as a Command?

https://github.com/FreeCAD/FreeCAD/blob ... ceColors.h

The code is defined in Part/Gui/TaskFaceColors.{h, cpp, ui}, but it is not a command. This task panel is launched from the viewprovider code.

https://github.com/FreeCAD/FreeCAD/blob ... #L957-L976

Code: Select all

bool ViewProviderPartExt::setEdit(int ModNum)
{
    if (ModNum == ViewProvider::Color) {
        ...

        Gui::Selection().clearSelection();
        Gui::Control().showDialog(new TaskFaceColors(this));
        return true;
    }
    ...
I think the proper way to solve this, is to convert this code to a proper Gui Command, and then launch this command so that we can document it under its command name (tentatively, Part_FaceColors).

For example:

Code: Select all

bool ViewProviderPartExt::setEdit(int ModNum)
{
    if (ModNum == ViewProvider::Color) {
        ...

        Gui::Selection().clearSelection();
        Gui::runCommand("Part_FaceColors");
        return true;
    }
    ...
Last edited by vocx on Mon Aug 03, 2020 1:25 am, edited 1 time in total.
Always add the important information to your posts if you need help.
To support the documentation effort, and code development, your donation is appreciated: paypal.
chrisb
Posts: 25695
Joined: Tue Mar 17, 2015 9:14 am

Re: to be renamed: Std_SetColors

Postby chrisb » Sun Aug 02, 2020 9:47 pm

It sure is a good idea to change the code to be clearer, more systematic or whatever. But to change the code so we can document seems rather artificial.
There is a wiki page and we just fill it with documentation how this works. It can be found by the wiki search so users can find and understand it.
No need to change the code for that.
vocx
Posts: 4615
Joined: Thu Oct 18, 2018 9:18 pm

Re: to be renamed: Std_SetColors

Postby vocx » Mon Aug 03, 2020 1:45 am

chrisb wrote:
Sun Aug 02, 2020 9:47 pm
...
There is a wiki page and we just fill it with documentation how this works. It can be found by the wiki search so users can find and understand it.
...
The issue is more about categorizing the page. Most wiki pages are in a specific category which is given by their workbench, Part, PartDesign, Sketcher, etc. These commands are registered as "Commands", so they have information like name, menu, icon, tooltip, etc. In particular, the "WhatsThis" string allows them to be automatically indexed and to be included in the automatically generated offline documentation (Std_WhatsThis). A "command", such as this one, that is not registered as an actual Command, won't benefit from this documentation mechanism.

This command is a "something", you cannot name it precisely because it doesn't have a proper "name". Should we name the wiki page "Std_SetColors", or "Part_FaceColors", or "Std_FaceColors"? You cannot say because it doesn't have a proper "name"; it obviously has a name in code, but it is essentially arbitrary how you name the wiki page after it. You can name it "Part_FaceColors", but in the code that is not its name; its name is something like "Part::Gui::TaskFaceColors", should we name the page like this? This command shows the text "Set colors" in the right-click context menu, so I think this is the reason the page is named currently as "Std_SetColors".

So, I'm not saying we absolutely must modify the code; but the proper thing to do, to bring order and consistency, is to extend the code appropriately. There are a few other functions in FreeCAD that are like this; they aren't exactly defined as commands, they just launch "free" code; for example, the Std_Transform tool could benefit from becoming an actual command and not just "code that runs when you double click".
Always add the important information to your posts if you need help.
To support the documentation effort, and code development, your donation is appreciated: paypal.
chrisb
Posts: 25695
Joined: Tue Mar 17, 2015 9:14 am

Re: to be renamed: Std_SetColors

Postby chrisb » Mon Aug 03, 2020 5:03 am

I see. To me it seems reasonable to have a category for the globally available functions, and the free floating ones could be moved there. Do other Std_xxx functions such as Std_Part have proper commands?
User avatar
Roy_043
Posts: 1545
Joined: Thu Dec 27, 2018 12:28 pm

Re: to be renamed: Std_SetColors

Postby Roy_043 » Mon Aug 03, 2020 7:10 am

The problem with inventing command names is that they can result in a mess further down the line.
Maybe we should aim for a different interim solution? Create a context menu page for each WB? Although that page may become quite long in some cases.
renatorivo
Posts: 2500
Joined: Tue Feb 21, 2012 8:07 pm
Location: Torino - Italy

Re: to be renamed: Std_SetColors

Postby renatorivo » Mon Aug 03, 2020 7:24 am

Roy_043 wrote:
Mon Aug 03, 2020 7:10 am
Maybe we should aim for a different interim solution?
An old project to organize the documentation https://wiki.freecadweb.org/ComandiPerCategorie/it