GuiCommand model Wiki page

[Roy_043]

I've thought i've read this information but i am not capable to proove it with a page. may be an issue with my memory.
when i've reworked the docnav and guicommand, very seldomely i've seen links to other thing than page of tools.

In the section you have linked to: |SeeAlso=[[FEM_tutorial/fr|FEM tutoriel]]

about the docnav, it is already well defined

We are discussing the GuiCommand model here and the Docnav is part of that page. I gather that you do not like the Docnav on GuiCommand_model page?

[Roy_043]

a detail but it helps translators, [[workbench_tool|workbench tool]] or [[the_link_to_the_page|the link to the page]]. when we use automatic translators on line, the the_link_to_the_page is not translated while "the link to the page" can be.

Note that for the section before the '|' character, the actual link, case is relevant. If your page name is 'Name_of_page' the link will fail if you type 'Name_of_Page' (upper case 'P'). Before the '|' character all spaces should be replaced by underscores ('_'). This is to assist translators using translation software, without the underscores the link would be translated by the software which is undesirable.

[hmk]

Can the GuiCommand show how to properly describe "Esc to abort"? As usual, there are various ways of formatting floating around.

Especially, I have seen it as the last point in numbered lists (eg Sketcher_Trimming):
4. Pressing Esc or pressing the right mouse button will terminate the function.
This seem a bit odd, but I have no problem follow this style...

nb. Depending on how the tool works, there may be no one style of formatting that fits for everything!?

[Roy_043]

This seem a bit odd

What alternative are you thinking of?

[hmk]

This seem a bit odd

What alternative are you thinking of?

Having it after or before the numbering (without special formatting). Having it before may seem a bit strange, but then you know beforehand that you can bail out any time when following the steps.

Screenshot_2021-02-01 Editing Sketcher Trimming (section) - FreeCAD Documentation.png (24.77 KiB) Viewed 2455 times

Addendum: Or, if applicable, this seems also a good solution to me:

Screenshot_2021-02-01 Draft Snap Center - FreeCAD Documentation.png (28.99 KiB) Viewed 2446 times

I don't have a strong opinion (part of the numbering, before, or after), just would like some rule to follow.

[Roy_043]

Another solution:

[hmk]

Another solution:

So many wonderful options to choose from... Actually, to me this feels the most generic and it is nicely isolated from the "successful usage" of a command, so I personally like this as the default suggestion best.

[david69]

Code: Select all

{{Docnav
|[[Base_PreviousCommand|PreviousCommand]]
|[[Base_NextCommand|NextCommand]]
|[[Workbench_Name|Workbench]]
|IconL= <!--filename of icon with extension (e.g. svg, png)-->
|IconR= <!--filename of icon with extension (e.g. svg, png)-->
|IconC= <!--filename of icon with extension (e.g. svg, png)-->
}}

is perfect like that. Roy, you were the one whom suggested this way to organize it and i'm pleased.
with recent icons in svg, it's easy to see if the name of the previous/next/name are matching with the icons.

Code: Select all

{{Docnav
|[[Base_PreviousCommand|PreviousCommand]]
|[[Base_NextCommand|NextCommand]]
|[[Workbench_Name|Workbench]]
|IconL= Base_PreviousCommand.svg
|IconR= Base_NextCommand.svg
|IconC= Workbench_Name.svg
}}

Another solution:

+1

i would be curious to have Kaktus' feedback and others of course.

[Roy_043]

Some additional issues we may want to address:

1.
Is it a tool, a command or a function?
What are we talking about on the pages of the Command reference? I would say (obviously) 'commands', but many editors seem to prefer 'tools' or (rarer) 'functions'.

2.
CSS: Vertical spacing around images and bottom Docnav.
The vertical spacing around images is not optimal IMO. If a caption is added there is too much space below the image. This can be improved by deleting the blank line below the caption in the wiki code. But ideally this should be handled better by the CSS.
I have acquired the habit of adding an additional blank line above the bottom Docnav. With this blank line the page looks better. Again this is something that should be handled by the CSS IMO.

3.
Move the 'main' image below the Usage paragraph.
In a discussion about images and their usefulness, it was mentioned that users can browse the wiki from a (2nd) low-res device. If there is an image above the 'Usage' paragraph these users have to scroll to get to that paragraph. This can be improved by moving the 'main' image below the 'Usage' paragraph.

4.
CSS: Layout of lists when the list flows around an image.
See Std SetAppearance for an example where this goes wrong. This is perhaps an issue related to the CSS or the wiki software?

5.
How detailed/specific should we be?
On some recently modified pages I see this as the first instruction:
'Switch to the XYZ workbench'
And sometimes also:
'Press the ABC button in/on the toolbar'
This raises the question: How specific should we get? IMO specifying the workbench is superfluous. we are already leaving out the workbench prefix in the Docnav. And if we are going to specify 'toolbar' shouldn't we then also specify its name?

6.
Wrong use of the KEY and Button templates.
Many editors seem to want to add a 'box' around certain words. In the past the KEY template was (ab)used for this. Currently the Button template seems to be favored.
How should we deal with this? In some cases applying these templates throughout can make the text harder to read. See f.e. Std_LinkMake.

[Roy_043]

Ad. 2.
A very small change to https://wiki.freecadweb.org/Template:Caption has fixed the extra space that would appear below the caption.