[Solved] ToggleConstruction.svg vs. AlterConstruction.svg

Discussions about the wiki documentation of FreeCAD and its translation.
User avatar
JoshuaCall
Posts: 44
Joined: Tue Dec 17, 2019 3:43 am

[Solved] ToggleConstruction.svg vs. AlterConstruction.svg

Postby JoshuaCall » Fri Jan 03, 2020 7:39 am

Dear all,

I noticed that Creating a simple part with PartDesign uses ToggleConstruction.svg when it should should be using AlterConstruction.svg.
ToggleConstruction.svg is included in the Artwork Sketcher page, used by a number of pages in the wiki, still available on Github, and referenced in the Sketcher.qrc file. However, I don't see where it is still being used in the FreeCAD GUI (I noticed that in the file TaskSketcherElements.cpp, only Sketcher_AlterConstruction is used as an icon string. See lines 59, 64, and 166.) If I am correct in my thinking that ToggleConstruction.svg is obsolete, then it seems that it should be removed from the wiki. This would entail removing it from the Artwork Sketcher page and then taking one of the following courses of action:

1. Updating the ToggleConstruction.svg page with a new image that is identical to the AlterConstruction image.

2. Manually changing each page that references ToggleConstruction.svg to make them reference AlterConstruction.svg instead (including for pages in languages that I don't read or write).

3. Somehow figuring out a way to automatically redirect references to ToggleConstruction.svg to the AlterConstruction.svg page.

Does anyone have an opinion on which course of action would be best?

Thank you,
Joshua
Last edited by JoshuaCall on Mon Jan 06, 2020 1:05 am, edited 1 time in total.
chrisb
Posts: 22520
Joined: Tue Mar 17, 2015 9:14 am

Re: ToggleConstruction.svg vs. AlterConstruction.svg

Postby chrisb » Fri Jan 03, 2020 10:19 am

Is it sensible to handle this together with another icon issue?
User avatar
JoshuaCall
Posts: 44
Joined: Tue Dec 17, 2019 3:43 am

Re: ToggleConstruction.svg vs. AlterConstruction.svg

Postby JoshuaCall » Fri Jan 03, 2020 10:53 am

chrisb wrote:
Fri Jan 03, 2020 10:19 am
Is it sensible to handle this together with another icon issue?
I don't have any strong feelings about changing icons in the GUI, since I'm new to using FreeCAD and the GUI icons have gone through several iterations in the past and I'm not aware of what the reasons and logic were at the time of those changes (e.g., why the change was made from the ToggleConstruction icon to the AlterConstruction icon in the GUI). I will give it some thought, though.
User avatar
JoshuaCall
Posts: 44
Joined: Tue Dec 17, 2019 3:43 am

Re: ToggleConstruction.svg vs. AlterConstruction.svg

Postby JoshuaCall » Fri Jan 03, 2020 11:57 am

I think I'm going to leave the Sketcher_ToggleConstruction.svg file as it is now and leave it in the Artwork Sketcher page (since the Artwork Sketcher page is supposed to include the icons in src/Mod/Sketcher/Gui/Resources/icons/). Then I'll just manually change all the pages to reference Sketcher_AlterConstruction.svg because that's the file that's currently being used in the GUI.
vocx
Posts: 3341
Joined: Thu Oct 18, 2018 9:18 pm

Re: ToggleConstruction.svg vs. AlterConstruction.svg

Postby vocx » Fri Jan 03, 2020 6:45 pm

JoshuaCall wrote:
Fri Jan 03, 2020 7:39 am
...
Does anyone have an opinion on which course of action would be best?

Thank you,
Joshua
The command is called Sketcher_ToggleConstruction, but the icon it is using is called Sketcher_AlterConstruction. I think it's easier to rename the current Sketcher_AlterConstruction to Sketcher_ToggleConstruction, to match its name. The current Sketcher_ToggleConstruction could be renamed in the source to Sketcher_AlterConstruction or any other name, Sketcher_ToggleConstruction_old, for example.


https://github.com/FreeCAD/FreeCAD/blob ... pp#L67-L94

Code: Select all

DEF_STD_CMD_A(CmdSketcherToggleConstruction)

CmdSketcherToggleConstruction::CmdSketcherToggleConstruction()
    :Command("Sketcher_ToggleConstruction")
{
    sAppModule      = "Sketcher";
    sGroup          = QT_TR_NOOP("Sketcher");
    sMenuText       = QT_TR_NOOP("Toggle construction geometry");
    sToolTipText    = QT_TR_NOOP("Toggles the toolbar or selected geometry to/from construction mode");
    sWhatsThis      = "Sketcher_ToggleConstruction";
    sStatusTip      = sToolTipText;
    sPixmap         = "Sketcher_AlterConstruction";
    sAccel          = "C,M";
    eType           = ForEdit;
...
}
On the wiki, the page is Sketcher_ToggleConstruction.

The name of the wiki page should match the name of the command as it appears in the sWhatsThis field, in the code above. Why? Because the documentation system of FreeCAD (Std_WhatsThis) is based on the wiki and requires these names to match in order to display the correct page when the documentation is launched.

The documentation pages in the wiki, for example, Sketcher_ToggleConstruction, have what is called a "GuiCommand" template. This template creates the floating block with information that you see on the right of the screen.

What this does is it searches the name of the page, say, Name=Sketcher_ToggleConstruction, and looks for the corresponding icon named the same. However, we can override the icon using an argument Icon=Sketcher_AlterConstruction.svg, which is exactly what is happening.

But this is convoluted. To make things easier, I prefer that online, in the wiki, the icon is always named the same as the corresponding command, then we don't have to supply the Icon= argument, or remember the actual name of the icon, we can just use the same name of the command, and add .svg.

Therefore, the solution is this.
1. In the source code, the new icon should be renamed Sketcher_ToggleConstruction.
2. In the source code, the old icon should be renamed Sketcher_ToggleConstruction_old.
3. In the wiki, the corresponding files should be updated, so that Sketcher_ToggleConstruction is the new icon, and Sketcher_ToggleConstruction_old is the old Sketcher_AlterConstruction.
4. The Artwork pages should always have all the icons as they appear in the source code, no matter if they are used or not.

By the way, this means that there are icons that have been uploaded twice or more times, once with the real name that appears in the source code, and another time with the name of the specific command in which they are used. This may sound a bit repetitive, but in reality it saves us time when writing documentation pages because we don't have to think about the name of the icon, we can just use the same name as the corresponding command. For example, the Part_SimpleCopy command uses the same Tree_Part icon that is used by a lot of Part Workbench commands, but to simplify things, we uploaded a Part_SimpleCopy icon.
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.
User avatar
JoshuaCall
Posts: 44
Joined: Tue Dec 17, 2019 3:43 am

Re: ToggleConstruction.svg vs. AlterConstruction.svg

Postby JoshuaCall » Sat Jan 04, 2020 1:33 am

vocx wrote:
Fri Jan 03, 2020 6:45 pm
1. In the source code, the new icon should be renamed Sketcher_ToggleConstruction.
2. In the source code, the old icon should be renamed Sketcher_ToggleConstruction_old.
3. In the wiki, the corresponding files should be updated, so that Sketcher_ToggleConstruction is the new icon, and Sketcher_ToggleConstruction_old is the old Sketcher_AlterConstruction.
I saved a copy of Sketcher_AlterConstruction under the new name Sketcher_ToggleConstruction. Should I completely delete the old Sketcher_AlterConstruction file from the source code, or should I leave it in? If I left it in, that would mean that we have two copies of the same image: Sketcher_ToggleConstruction and Sketcher_AlterConstruction.

And I assume that for point 3, you meant to say, "Sketcher_ToggleConstruction_old is the old Sketcher_ToggleConstruction."
vocx
Posts: 3341
Joined: Thu Oct 18, 2018 9:18 pm

Re: ToggleConstruction.svg vs. AlterConstruction.svg

Postby vocx » Sat Jan 04, 2020 7:31 pm

JoshuaCall wrote:
Sat Jan 04, 2020 1:33 am
I saved a copy of Sketcher_AlterConstruction under the new name Sketcher_ToggleConstruction. Should I completely delete the old Sketcher_AlterConstruction file from the source code, or should I leave it in? If I left it in, that would mean that we have two copies of the same image: Sketcher_ToggleConstruction and Sketcher_AlterConstruction.

And I assume that for point 3, you meant to say, "Sketcher_ToggleConstruction_old is the old Sketcher_ToggleConstruction."
Yeah... I think you are right.

In the source we don't need two files that are the same picture, you could remove AlterConstruction, and just leave ToggleConstruction and ToggleConstruction_old.

Pull request #2860.

Just make sure that every instance in the software that was using AlterConstruction is now using ToggleConstruction.

Code: Select all

cd freecad-source
git grep Sketcher_AlterConstruction
It seems you already checked this in your pull request, right? Good job.
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.
User avatar
JoshuaCall
Posts: 44
Joined: Tue Dec 17, 2019 3:43 am

Re: ToggleConstruction.svg vs. AlterConstruction.svg

Postby JoshuaCall » Sun Jan 05, 2020 12:39 am

vocx wrote:
Sat Jan 04, 2020 7:31 pm
It seems you already checked this in your pull request, right? Good job.
Yes I did; thank you. The only file still using Sketcher_AlterConstruction is the documentation binary auto-generated from the online wiki (src/Doc/freecad.qch.part03).