Looking for some guidance

Discussions about the wiki documentation of FreeCAD and its translation.
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
Post Reply
garya
Posts: 424
Joined: Tue Nov 20, 2018 1:00 am
Location: Ovando, MT, USA

Looking for some guidance

Post by garya »

While re-working my way through some of the wiki I decided I should try to fix some things when I found them. I rapidly got into questionable territory, I think, so my questions:

from Kunda1:
we want said changes to be:
1. accurate
2. reflect the consensus of the community
3. mindful because many pages on the wiki are translated and so any change we make, we need to think about the translators and the work we create for them.
#3 is concerning because it hints that one might not want to correct grammar, make a sentence more concise, or rework a sentence to make it less ambiguous because of the downstream translation work. Is this what is actually happening (i.e. improvements not being made) as a result? There are numerous places where I have encountered improper English which I would normally correct and mark as a minor edit, but others where an ambiguity can be removed by rewording.

Should one make these two (improper English and ambiguity) as separate submissions, even if in the same paragraph?

#1. There are three panels not discussed -- Tree View, Property View, and Selection View. I believe all of them are initially not displayed, but the images on the page show an additional tab area beneath the Combo view, containing a tab for Selection view and Combo view. I don't remember ever seeing it. Have I screwed up my initial (default) display, or are the images from an earlier than 0.17 release and need to be updated?

BTW, is there a way to restore the default display arrangement? We should probably mention it because it's relatively easy to mess up.

While I think my rearrangement is an improvement and clarification based on my own beginner's experience, it would mean re-translating parts of that section. Is there some approved way to get a consensus on whether it should be submitted or not? I was fortunate in that I deleted translation unit 18 initially without deleting the translation marker, and I presume this is why it was not submitted (at least I think that's what happened). Or should one just think carefully before hitting "Submit".

My proposed changes (translation units 16-18 only), if anyone wants to preview them to see where I'm coming from:
=== The interface === <!--T:13-->

<!--T:14-->
Let's have a better look at the different parts of the interface:

<!--T:15-->
[[Image:Freecad-interface-04.jpg|none]]

<!--T:16-->
* '''The 3D view''' is the main component of the interface; it is where the objects you are working with are drawn and manipulated. You may have several views of the same document (or same objects), or several documents open at the same time. Each of these views may be individually undocked from the main window. You may select objects or parts of objects by clicking them, and you can pan, zoom and rotate the view with the mouse buttons. This will be explained further in the next chapter.
In addition to the 3D view panel, the following information panels are available. They may be made visible or hidden by selecting them from {{MenuCommand|View -> Panels}}. The name of the panel appears in the upper left corner of the panel when it is displayed:
* '''The combo view''' has two tabs:
** The Model tab shows you the contents and structure of your document above and the properties (or parameters) of the selected object(s) below. These properties are separated into two categories:
*** Data (properties which concern the geometry itself)
*** View (properties that affect how the geometry looks like on screen).
** The Tasks tab is where FreeCAD will prompt you for values specific to the tool you are currently using. For example, entering a 'length' value when the Line tool is being used. It will close after the OK (or Cancel) button is pressed. By double-clicking the related object in the Model tab, most tools will allow you to reopen the corresponding Task tab in order to modify the settings.
* '''The report view''' is normally hidden, but it is a good idea to leave open as it will list any information, warnings or errors to help you decipher (or debug) what you may have done wrong.
* '''The Python console''' is also hidden by default. This is where you can interact with the contents of the document using the [https://en.wikipedia.org/wiki/Python_%2 ... anguage%29 Python language]. Since every action you do on the FreeCAD interface actually executes a piece of Python code, having this open allows you to watch the code unfold in real time-allowing you a wonderful and easy way to learn a little Python on the way, almost without noticing it.
* '''The tree view''' displays only the object tree shown under the Model tab in the combo view. It is normally hidden.
* '''The property view''' displays only the object property information shown at the bottom of the combo view. It is normally hidden.
* '''The selection view''' shows the names of any objects which are currently selected. These are the objects to which a workbench operation will be applied. The selection view is normally hidden; you can usually determine the currently selected object by looking at the object tree in the Model tab of the combo view.

<!--T:17-->
[[Image:Freecad-interface-07.jpg|none]]
chrisb
Veteran
Posts: 54303
Joined: Tue Mar 17, 2015 9:14 am

Re: Looking for some guidance

Post by chrisb »

Thank you garya for helping in the wiki!

This post contains my view about a couple of your questions:
garya wrote: Sun Dec 02, 2018 4:10 am #3 ... Is this what is actually happening (i.e. improvements not being made) as a result? There are numerous places where I have encountered improper English which I would normally correct and mark as a minor edit, but others where an ambiguity can be removed by rewording.
These improvements should of course be made! Some documentation was made by non native speakers, e.g. by me, and I would be very glad if the were cleaned by someone knowing better. I think documentation in bad English is better than none, but the same in good English is even better.

Should one make these two (improper English and ambiguity) as separate submissions, even if in the same paragraph?
Not at all.
#1. ... or are the images from an earlier than 0.17
Yes.

BTW, is there a way to restore the default display arrangement? We should probably mention it because it's relatively easy to mess up.
There is a reset button in the preferences window at the bottom.
A Sketcher Lecture with in-depth information is available in English, auf Deutsch, en français, en español.
renatorivo
Veteran
Posts: 2611
Joined: Tue Feb 21, 2012 8:07 pm
Location: Torino - Italy

Re: Looking for some guidance

Post by renatorivo »

the discussion refers to https://www.freecadweb.org/wiki/Manual: ... _Interface


reset.png
reset.png (2.87 KiB) Viewed 1243 times
FreeCAD 0.16
vocx
Veteran
Posts: 5197
Joined: Thu Oct 18, 2018 9:18 pm

Re: Looking for some guidance

Post by vocx »

garya wrote: Sun Dec 02, 2018 4:10 am While re-working my way through some of the wiki
Goodness gracious, man. Please mention which part of the wiki you are talking about. There is absolutely no mention of the page you intend to edit. The wiki is not a single document, it's thousands of pages and translations.
There are numerous places where I have encountered improper English which I would normally correct and mark as a minor edit, but others where an ambiguity can be removed by rewording.
FreeCAD has been primarily developed by non-native English speakers, so the English is a bit wonky in certain parts of the documentation. You don't need to ask for permission, just edit the text to correct those errors.
#1. There are three panels not discussed -- Tree View, Property View, and Selection View. I believe all of them are initially not displayed, but the images on the page show an additional tab area beneath the Combo view, containing a tab for Selection view and Combo view. I don't remember ever seeing it. Have I screwed up my initial (default) display, or are the images from an earlier than 0.17 release and need to be updated?
The Selection View is available from the menu View -> Panels -> Selection view.

I don't think you need to update the image if the changes to the interface are minor. I mean, it's clearly ideal that all images match the most recent interface, but there are hundreds of images everywhere on the wiki, so doing this is a monumental task. Moreover, if the developers change a thing or two on the interface for the next release (0.18, 0.19, etc.), again the images will be out of sync.

So, if you have the time to change the images, then do it, but otherwise I'd rather focus on having good, descriptive text. If the image is very old, and showcases an old interface from FreeCAD 0.14 or something like that, then it really makes sense to update the image.
BTW, is there a way to restore the default display arrangement? We should probably mention it because it's relatively easy to mess up.
There is a file called user.cfg in your home directory, for example, in Linux, /home/garya/.FreeCAD/user.cfg, with the configuration. You can delete this file to remove the old configuration of your system. Next time you start FreeCAD, it will recreate this file with the default configuration.
Always add the important information to your posts if you need help. Also see Tutorials and Video tutorials.
To support the documentation effort, and code development, your donation is appreciated: liberapay.com/FreeCAD.
User avatar
NormandC
Veteran
Posts: 18589
Joined: Sat Feb 06, 2010 9:52 pm
Location: Québec, Canada

Re: Looking for some guidance

Post by NormandC »

garya wrote: Sun Dec 02, 2018 4:10 am #1. There are three panels not discussed -- Tree View, Property View, and Selection View. I believe all of them are initially not displayed, but the images on the page show an additional tab area beneath the Combo view, containing a tab for Selection view and Combo view. I don't remember ever seeing it. Have I screwed up my initial (default) display, or are the images from an earlier than 0.17 release and need to be updated?
I have never seen those tabs in 8 years (going on 9) of using FreeCAD. The Selection view isn't even visible by default. And I have no idea how Yorik (who took the screenshots) managed to combine the Combo view and the Selection view, I just tried and didn't find how.

I think it would be best to update these images; with v0.18 release almost out the door, it would make sense to make them with 0.18-dev rather than with v0.17, or they'll have to be updated again in a month or two.

If you're not familiar with MediaWiki, when clicking on an image you are brought to its page, for example:
https://www.freecadweb.org/wiki/File:Fr ... ace-04.jpg

Below, there is a link "Upload a new version of this file". I also recommend saving as PNG rather than JPEG; the latter is more suited to photographs, the former to screenshots.
User avatar
NormandC
Veteran
Posts: 18589
Joined: Sat Feb 06, 2010 9:52 pm
Location: Québec, Canada

Re: Looking for some guidance

Post by NormandC »

garya wrote: Sun Dec 02, 2018 4:10 am My proposed changes
They look fine by me. In any case, at any time we can revert changes through the View history tab. Regarding translation, a page needs to be marked for translation for changes to be "registered" or validated for the translated pages. This can only be done by admins. When we do that, we can review the changes, and there is a "do not invalidate translations" checkbox for each individual unit that we can check if the changes are only cosmetic or typos.

If I might suggest a small addition:

garya wrote: Sun Dec 02, 2018 4:10 am ** The Tasks tab is where FreeCAD will prompt you for values specific to the tool you are currently using. For example, entering a 'length' value when the Line tool is being used.
This can be confusing because there are many Line tools in FreeCAD across different workbenches, and only one behaves that way: Draft Line, so I suggest specifically mentioning the workbench in which it can be found. I don't know if it's relevant to link to its command page?
garya
Posts: 424
Joined: Tue Nov 20, 2018 1:00 am
Location: Ovando, MT, USA

Re: Looking for some guidance

Post by garya »

chrisb:
Thanks for the pointer to the reset button; I have seen it but am reluctant to use it because it is ambiguous:
If I hit reset, does it reset all settings in all categories to their defaults?
Or does it only reset settings in all tabs for the currently selected category?
Or does it only reset settings in the currently displayed tab in the current category?
Preferences_Editor does not explain, or even mention, the reset button.

vocx:
Ugh, my apologies for not including the page reference. I did originally, then did a delete all to replace the actual changes with a new version. In any case, something I overlooked.
Thanks for the pointer to user.cfg

NormandC:
Thanks for the suggestion and the clarification about there being different line tools.
** The Tasks tab is where FreeCAD will prompt you for values specific to the tool you are currently using. For example, entering a 'length' value when the Line tool is being used.
This can be confusing because there are many Line tools in FreeCAD across different workbenches, and only one behaves that way: Draft Line, so I suggest specifically mentioning the workbench in which it can be found. I don't know if it's relevant to link to its command page?
The intro to the Tasks tab where that reference occurs is verbatim from the original, but since the image below the discussion is of the Part WB and the Extrude task, it probably makes more sense to change the reference to the "Length" parameter in the Extrude task. However, it's not at all clear to me how to match that image. Since this is intro material, and since the intro tutorial starts with the Part Design and Sketcher WBs, I think it is probably better to use those in these images, with the corresponding "Pad" task, for example. It may be worth linking to the command page in any case to show what kind of detail is available for tasks in general.

I agree 0.18 images would probably be the smart thing to do. Unfortunately, I currently only have 0.17 and it's not easy for me to build 0.18; I'm running FreeBSD and porting the new stuff is somewhat of a hassle. I'll look into it but it was a bear to get the devel version of GIMP ported because of dependencies and I finally gave up.
User avatar
NormandC
Veteran
Posts: 18589
Joined: Sat Feb 06, 2010 9:52 pm
Location: Québec, Canada

Re: Looking for some guidance

Post by NormandC »

garya wrote: Mon Dec 03, 2018 4:43 am If I hit reset, does it reset all settings in all categories to their defaults?
It resets the whole FreeCAD to default. It has the same effect as deleting system.cfg and user.cfg configuration files in ~/.FreeCAD.
garya
Posts: 424
Joined: Tue Nov 20, 2018 1:00 am
Location: Ovando, MT, USA

Re: Looking for some guidance

Post by garya »

NormandC wrote: Mon Dec 03, 2018 5:20 am
garya wrote: Mon Dec 03, 2018 4:43 am If I hit reset, does it reset all settings in all categories to their defaults?
It resets the whole FreeCAD to default. It has the same effect as deleting system.cfg and user.cfg configuration files in ~/.FreeCAD.
Thanks, I've added it.
Post Reply