TechDraw documentation: SeeAlso is inconsistent

Discussions about the wiki documentation of FreeCAD and its translation.
User avatar
Roy_043
Posts: 2080
Joined: Thu Dec 27, 2018 12:28 pm

TechDraw documentation: SeeAlso is inconsistent

Postby Roy_043 » Sat Nov 21, 2020 7:28 pm

Looking at the pages for the TechDraw WB I see two systems in the SeeAlso field:

1. TechDraw_LeaderLine: Menu texts (more or less) are used.

2. TechDraw_Dimension_Vertical_Extent: Command names (including the 'TechDraw' prefix) are used.

uwestoehr wrote: pinged by pinger macro
What should be used? Ideally we would all do the same thing here. But we should at least strive for consistence within the documentation of a single WB.
david69
Posts: 380
Joined: Wed Jan 01, 2014 7:48 pm

Re: TechDraw documentation: SeeAlso is inconsistent

Postby david69 » Sun Nov 22, 2020 12:33 pm

in the SeeAlso field, we have the links to other pages in relation with the given page.
they have to follow the rule [[Worbench1_page1|Worbench1 page1]], [[Worbench2_page1|Worbench2 page1]], [[Worbench2_page2|Worbench2 page2]].

the name of the page at least in English is usually short and I can tell you that, sometimes to translate, I loose some hairs.

I have modified the SeeAlso for TechDraw_LeaderLine following the above exposed rule.
in https://wiki.freecadweb.org/WikiPages#Structure, it is not clearly mentioned, IMO.

for the Workbenches field, it is only [[Name_Worbench|Name]] or [[Name_Module|Name]] and better to avoid [[Name_Worbench]] because for the translators, each one must write [[Name_Worbench/fr|Atelier Nom]].

and may be recently, you have received up-date (if you are translator) on wiki pages with the adding of _ between workbench and page wording. it's because when we translate, if there is no _, tools like google translation or deepl translate the wording. with an _, they don't. so i have added _ thinking about the next translators of other languages.
User avatar
Roy_043
Posts: 2080
Joined: Thu Dec 27, 2018 12:28 pm

Re: TechDraw documentation: SeeAlso is inconsistent

Postby Roy_043 » Sun Nov 22, 2020 2:41 pm

david69 wrote:
Sun Nov 22, 2020 12:33 pm
I have modified the SeeAlso for TechDraw_LeaderLine following the above exposed rule.
You have added 'TechDraw' to the existing text: 'Insert Rich Text Annotation'. But the existing text is a menu text, not the command name.

IMO the SeeAlso text can be:
Insert Rich Text Annotation (if we accept that a menu text is also allowed).
Or:
TechDraw RichTextAnnotation (which follows the rule you have mentioned, and I would prefer this).
Or:
RichTextAnnotation (see quote below).

https://forum.freecadweb.org/viewtopic.php?f=21&t=50389&p=433421#p432869 wrote:in the command name, I would use the WB name only if there is the possibility of misunderstanding, otherwise it is implied that it is the WB in question
david69
Posts: 380
Joined: Wed Jan 01, 2014 7:48 pm

Re: TechDraw documentation: SeeAlso is inconsistent

Postby david69 » Sun Nov 22, 2020 9:27 pm

I see two main schools:
one like Sketcher_CreateEllipseByCenter where we have [[TechDraw_RichTextAnnotation|TechDraw Rich Text Annotation]]
and the second, PartDesign_AdditiveEllipsoid, with [[PartDesign CompPrimitiveAdditive|PartDesign CompPrimitiveAdditive]]

when I translate, I usually put the shortcut following the first rule. for the non English reader, there is no more direct connection with the command itself in the code. For this reason, I prefer the first rule but for sure, I think it is important to read the workbench and the _.
we can agree on a mix of both solutions, kind of minimum of flexibilty.

oh and no icon neither in the SeeAlso. i have removed some.

I think there is mix of history and also, not all the authors are necessary aware of that kind of rules (or don't take care too much, which I can understand).