[Lowercase links] Use a lower case title for a wiki page

Discussions about the wiki documentation of FreeCAD and its translation.
Forum rules
Be nice to others! Respect the FreeCAD code of conduct!
vocx
Veteran
Posts: 5197
Joined: Thu Oct 18, 2018 9:18 pm

[Lowercase links] Use a lower case title for a wiki page

Post by vocx »

I realize many pages in the wiki have capitalization of all words in the link, such as [[User Documentation]].

This style is bad because the second word always needs to be written with a capital letter, but this looks bad when it's used in lowercase text.

There are three possibilities:
  • This tool is listed in the [[User Documentation]].
  • This tool is listed in the [[user Documentation]]
  • This tool is listed in the [[user documentation]].
The first option works, but looks ugly surrounding the lowercase text.
The second option also works; the wiki software makes the first letter a capital letter, but the second capital letter remains a capital, and again looks ugly.
The third option doesn't work; the wiki makes the first letter a capital letter, but the second word is not changed, it results in a link to [[User documentation]], which as it turns out is different from [[User Documentation]].

Links should be able to be used in regular flowing text, so that it's easy for the user to jump to those links while reading a manual or tutorial. So, I recommend more pages use lower case. Avoid creating these pages as if they were headings of a magazine, especially when the topic uses common words. It's perfectly fine to use [[Arch Wall]] because this is a specific tool of a workbench, but I don't like creating a page like [[Tutorial For Bathroom Design]], or [[Construction Of Airplanes]]. Ideally, you would include these links in some instruction:

"Please read the [[tutorial for bathroom design]], and then check the [[construction of airplanes]] tutorial."

The pages would be named with only the initial letter capitalized, [[Tutorial for bathroom design]], and [[Construction of airplanes]].

Another example in the wiki. There are two tutorials, one is [[Sketcher Tutorial]], and the other [[Sketcher tutorial]]. These are two different documents, with very similar names, which are easy to confuse. The solution is to name them [[Draft tutorial]] and [[Draft tutorial 2]].

Another thing, blank spaces are nothing but underscores _.

I've seen some links like this [[Draft_Line|Draft Line]]. The first is the name of the link, and the second is the appearance of the text. The wiki software automatically converts the space into an underscore, so the page is named [[Draft_Line]], but it can be used as [[Draft Line]] without explicitly indicating the underscore. So, in the examples above, the actual link would be [[Construction_of_airplanes]], but there is no problem if [[construction of airplanes]] is used in the text.
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.
chrisb
Veteran
Posts: 53945
Joined: Tue Mar 17, 2015 9:14 am

Re: [Lowercase links] Use a lower case title for a wiki page

Post by chrisb »

As a non native english speaker I cannot judge about how to typeset titles, but in my view they are in fact like headings in a book or journal. I have no problems reading these capitalized links; in the opposite: it suggests immediately that the link leads to a topic named as the link tells and not into the middle of some minor paragraph.
A Sketcher Lecture with in-depth information is available in English, auf Deutsch, en français, en español.
GeneFC
Veteran
Posts: 5373
Joined: Sat Mar 19, 2016 3:36 pm
Location: Punta Gorda, FL

Re: [Lowercase links] Use a lower case title for a wiki page

Post by GeneFC »

I Am Often Guilty Of "Ugly" Superfluous Capitalization, But This Is Entirely A Matter Of Taste When It Comes To Ordinary Text.

Clearly A Solution Looking For A Problem. :lol: :lol:

Gene
vocx
Veteran
Posts: 5197
Joined: Thu Oct 18, 2018 9:18 pm

Re: [Lowercase links] Use a lower case title for a wiki page

Post by vocx »

chrisb wrote: Wed Oct 31, 2018 6:40 am As a non native english speaker I cannot judge about how to typeset titles, but in my view they are in fact like headings in a book or journal.
That's the thing. A wiki is not a linear book that you read chapter by chapter, page by page. It's supposed to be a web of content that you can access from different points. Just look at the average English Wikipedia page, most links are not capitalized, only the initial word if starting a sentence, or a proper name or acronym that is typically in capital letters.

See https://en.wikipedia.org/wiki/Monte_Carlo_method Most links are in lower case, only those that include proper names, like [[cellular_Potts_model]] and [[Markov_chain_Monte_Carlo]], have capitals in them.

The Wikipedia manual of style (https://en.wikipedia.org/wiki/Wikipedia ... d_captions) mentions this as well:
Use sentence case, not title case, capitalization in all section headings. Capitalize the first letter of the first word, but leave the rest lower case except for proper names and other items that would ordinarily be capitalized in running text.

Use: Economic and demographic shifts after World War II
Avoid: Economic and Demographic Shifts After World War II

The same applies to the titles of articles, table headers and captions, the headers of infoboxes and navigation templates, and image captions and alt text. (For list items, see next section.)

Linking is easier if titles are in sentence case. It is easier for articles to be merged or split if headings resemble titles.
chrisb wrote: Wed Oct 31, 2018 6:40 am I have no problems reading these capitalized links; in the opposite: it suggests immediately that the link leads to a topic named as the link tells and not into the middle of some minor paragraph.
I'll have to take a jab at German speakers here. Ha, too many capitals!

Title case, like Wikipedia calls it, is also not consistent. There is no accepted standard; some people would capitalize every single word, including minor words like "and, of, the, a, an", etc., while other people would leave these in lowercase.
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.
vocx
Veteran
Posts: 5197
Joined: Thu Oct 18, 2018 9:18 pm

Re: [Lowercase links] Use a lower case title for a wiki page

Post by vocx »

GeneFC wrote: Wed Oct 31, 2018 1:54 pm I Am Often Guilty Of "Ugly" Superfluous Capitalization, But This Is Entirely A Matter Of Taste When It Comes To Ordinary Text.

Clearly A Solution Looking For A Problem. :lol: :lol:

Gene
The Wikipedia manual of style (https://en.wikipedia.org/wiki/Wikipedia ... d_captions) disagrees with you! You are a bad person!
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: [Lowercase links] Use a lower case title for a wiki page

Post by NormandC »

What exactly are you proposing: that we define a rule for newly created pages, or to rename all existing page titles that have uppercase on all words?
vocx
Veteran
Posts: 5197
Joined: Thu Oct 18, 2018 9:18 pm

Re: [Lowercase links] Use a lower case title for a wiki page

Post by vocx »

NormandC wrote: Thu Nov 01, 2018 4:29 am What exactly are you proposing: that we define a rule for newly created pages, or to rename all existing page titles that have uppercase on all words?
Ideally, all existing pages should be renamed to conform to this style. Since that's a very big task, and would break translations, let's not do that. But yes, I think it makes sense to use this style for new pages.
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: [Lowercase links] Use a lower case title for a wiki page

Post by NormandC »

If it's renaming pages, it should not affect translations. Actually, I just switched my wiki UI settings to English (I've got them on French), it's called "Move" rather than rename.

Anyway, when selecting the More --> Move menu, then there is a checkbox to move all subpages. The translated pages are considered subpages, it works well. Renatorivo and I have been doing this a few times now (Renato a lot more than me). But the problem is that you break links to other pages (the "What links here" menu in the sidebar shows these pages).

BTW, the forum has a custom "wiki" BBCode tag that takes a page name, and automatically fills the rest of the URL. For Draft Line I just need to type the text before, click on the wiki button which gives this in my Reply's text input area:

Code: Select all

[wiki]Draft Line[/wiki]
And the result is a link to the Draft Line wiki page.

I have been using this extensively over the years on the forum (I hope I'm not alone). So, renaming pages may potentially break links on the forum...

In any case, it seems to me that such a project should not be a priority. It's only cosmetics. Besides, if you don't want capitalized words when you place an internal link in a page, then you can change the text appearance as you've found:

vocx wrote: Wed Oct 31, 2018 3:16 am I've seen some links like this [[Draft_Line|Draft Line]].
This is called a "piped link" (see here), because there is a pipe ("|") character. In English, your use case is unnecessary, because both are rendered exactly the same. But, remember translations. In other languages, a piped link will be required - for example, in French it would have to be translated to [[Draft_Line/fr|Ligne Draft]]. I've taken the habit of adding both in English pages, I figure it might help translators.
vocx
Veteran
Posts: 5197
Joined: Thu Oct 18, 2018 9:18 pm

Re: [Lowercase links] Use a lower case title for a wiki page

Post by vocx »

NormandC wrote: Fri Nov 02, 2018 3:01 am If it's renaming pages, it should not affect translations. Actually, I just switched my wiki UI settings to English (I've got them on French), it's called "Move" rather than rename.
Yes, I noticed the Move function. It seems to work okay, but indeed some links would need to be manually adjusted.
BTW, the forum has a custom "wiki" BBCode tag ...

Code: Select all

[wiki]Draft Line[/wiki]
So, renaming pages may potentially break links on the forum...
Correct, it would break links for the forum. That's one of the disadvantages of doing drastic changes. But as you know, occasionally software projects break compatibility with older versions for the "greater good" of the project. In my opinion, the wiki should be more important than the forum, because it serves as the place to summarize the essential information of the project, including the forum.

By the way, when you use the Move command described above, the wiki automatically creates a redirect page to the older name. This takes care of links that point to the old name. I'm not sure if it would handle the links to the translations gracefully though.

For example, if [[Airplane]] is moved to [[Aeroplane]], it creates a redirection [[Airplane]] -> [[Aeroplane]].

Would it handle correctly all the instances such as this? [[Airplane/fr]] -> [[Aeroplane/fr]], [[Airplane/de]] -> [[Aeroplane/de]], etc. That's my main concern.
In any case, it seems to me that such a project should not be a priority. It's only cosmetics. Besides, if you don't want capitalized words when you place an internal link in a page, then you can change the text appearance as you've found:
vocx wrote: Wed Oct 31, 2018 3:16 am I've seen some links like this [[Draft_Line|Draft Line]].
This is called a "piped link"...

But, remember translations. In other languages, a piped link will be required - for example, in French it would have to be translated to [[Draft_Line/fr|Ligne Draft]]. I've taken the habit of adding both in English pages, I figure it might help translators.
I know what piped links are, in general they should be minimized. Ideally you should use the actual link in the flow of the text. This simplifies writing and reading the source code. (Again, Wikipedia guidelines https://en.wikipedia.org/wiki/Wikipedia:Piped_link)

The example that you give makes perfect sense for translations, because the main link will still have an English name, but you must display a translated text. However, the example I gave happens a lot on English pages, so I was principally protesting its use there.
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.
renatorivo
Veteran
Posts: 2611
Joined: Tue Feb 21, 2012 8:07 pm
Location: Torino - Italy

Re: [Lowercase links] Use a lower case title for a wiki page

Post by renatorivo »

NormandC wrote: Fri Nov 02, 2018 3:01 am This is called a "piped link" (see here), because there is a pipe ("|") character. In English, your use case is unnecessary, because both are rendered exactly the same. But, remember translations. In other languages, a piped link will be required - for example, in French it would have to be translated to [[Draft_Line/fr|Ligne Draft]]. I've taken the habit of adding both in English pages, I figure it might help translators.
+1
Piped link is really useful for translators, it simplifies their work a lot. We have always applied this method, so I ask to continue using it as much as possible.
I understand, and I'm sorry if it makes boring reading the source code, but it's a modest inconvenience compared to the advantages. I think it's the opinion of everyone working on both the code and the translations.
Post Reply