What's the use of Template:Emphasis

[NormandC]

https://www.freecadweb.org/wiki/Template:Emphasis

This looks like a useless template to me. This can already be achieved with double apostrophes.

What's more efficient, this:

Code: Select all

{{emphasis|I want to put emphasis on this text.}}

Or this:

Code: Select all

''I want to put emphasis on this text.''

Moreover, the Edit page toolbar has an Italics button that adds the apostrophes automatically.

FC_wiki_edit_toolbar_01.png (12.28 KiB) Viewed 1215 times

Use of any inline template makes the content of an edited page harder to read and to edit. Therefore, we should use inline templates sparingly, when it's really useful - inline code is an example where it makes sense. This emphasis template doesn't, not when the same functionality is available with a more simpler formatting tool.

Just because a template is found on the wiki, it doesn't mean that we should use it - more so, if it has not been used in years. I see that the Emphasis template is listed in WikiPages. We should take a long hard look at the templates it recommends, and discuss it. IMO many of them are not worth keeping/using. As renatorivo said in another topic, we should strive for sobriety.

[yorik]

I agree we should use the default mediawiki tools whenever possible.
The utility I can see of this template would be that some people would use italic, other would use bold text to put emphasis on pieces of texts... Using a template would make it easier to unify it all at some point...

[Kunda1]

no need for this template

[vocx]

https://www.freecadweb.org/wiki/Template:Emphasis

This looks like a useless template to me. This can already be achieved with double apostrophes.
...

I assume the Emphasis template takes inspiration from a markup language like Latex. Using an emphasis command \emph{} is preferred over the simple italics command \textit{} for the reason that you don't always emphasize something with italics. You emphasize something by using "contrast". And this contrast can take different forms.

For example, if you have text in italics, if you use \emph{} the text will display upright. Like in this sentence.

Also the \emph{} command can be redefined to use bold, small caps, another font type, etc. So, in Latex, the idea is to structure your text in a logical manner and later on worry about the appearance of the text. In the wiki this is similar; as long as you use {{Emphasis}}, the template can be redefined later on to display the text in italics, bold, or with a frame, or in any other way.

I did not create the Emphasis template (Mario did?), but I've been using it because I thought it was a good idea. I completely understand if some users don't like it. It adds a bit of complexity, but at the same time it allows you to structure your text.

If you absolutely want to keep the emphasizing to italics everywhere, then yes, there is no need for the template. But if you think at some point the emphasis could be done with a different weight (bold), or something fancy like that, then it's a good idea to use it, so that changes are done quickly over all pages.

[NormandC]

I did not create the Emphasis template (Mario did?)

You just have to go to the "View history" tab at the top of the page. It was created by Ediloren back in 2013.

Anyway. To me it looks like a lot of work for not much gain.

[mario52]

hi

I did not create the Emphasis template (Mario did?), but I've been using it because I thought it was a good idea. I completely understand if some users don't like it. It adds a bit of complexity, but at the same time it allows you to structure your text.

i have modify grudgingly for normalized the wiki see <syntaxhighlight> or <pre>

What tags to use for code within the Wiki.

i agree for not create useless template

mario

[vocx]

I did not create the Emphasis template (Mario did?)

You just have to go to the "View history" tab at the top of the page. It was created by Ediloren back in 2013.

Anyway. To me it looks like a lot of work for not much gain.

As a long time Latex user, it's not a lot of work to use an emphasis command. Most of the time, you don't think about it, you just do it.

What is certain is that a wiki is not an ideal medium to build documentation. It works okay now because many users can edit it, however, maybe in the future a system like Latex or XML should be used to produce a proper PDF manual. In that case, a more complex markup language would probably be necessary. Maybe there are converters that could take the wiki pages, and automatically convert them to XML or something like that. In that case, I think the templates are useful; the converter could replace {{emphasis|something}} with <emphasis>something</emphasis>, and again, it's just a matter on how you define the format of that tag. So, using the emphasis template and similar templates is a way of future-proofing the documentation.

[NormandC]

What is certain is that a wiki is not an ideal medium to build documentation. It works okay now because many users can edit it, however, maybe in the future a system like Latex or XML should be used to produce a proper PDF manual. In that case, a more complex markup language would probably be necessary.

Personally I find PDF manuals extremely awkward and a pain to use. It's just designed to be printed on paper. An online documentation is hands down better suited for FreeCAD.

As far as markup languages go, I've never used LaTeX. It's used in academia, Its strength is in being able to format scientific formulas, we hardly need that. And is it even possible to produce an online documentation out of it?

In any case, a few FreeCAD heavyweights are pushing hard to migrate from MediaWiki to a Markdown/Git workflow at some point in the future. I think it will be inevitable.

Surely you've read that topic? https://forum.freecadweb.org/viewtopic.php?f=21&t=10079

It does have some advantages. There's a potential one I'm most interested in: at second glance, it looks like translations would be easier as they are dealt through Crowdin.net... But I'm waiting for an invite on Yorik's experiment to find out more about it.

Among shortcomings, Markdown syntax is a lot more sparse; AFAIK there is no possibility of templates/transclusion, there doesn't seem to be auto-generated TOCs for pages...

[vocx]

Personally I find PDF manuals extremely awkward and a pain to use. It's just designed to be printed on paper. An online documentation is hands down better suited for FreeCAD.

As far as markup languages go, I've never used LaTeX. It's used in academia, Its strength is in being able to format scientific formulas, we hardly need that. And is it even possible to produce an online documentation out of it?

Yes, it is possible. A markup language such as Latex or XML is first and foremost a way to structure a document. You add tags, and later on you define the appearance (bold, large font, italics) in which those tags will be displayed. So, with a system like that it is possible to take the input and produce an output in different formats, you can produce an online website, or a PDF file, or something in between.

I'm not saying it's imperative to have a PDF document, but the idea of structuring the documentation well, in logical sections, is certainly important.

In any case, a few FreeCAD heavyweights are pushing hard to migrate from MediaWiki to a Markdown/Git workflow at some point in the future. I think it will be inevitable.

Surely you've read that topic? https://forum.freecadweb.org/viewtopic.php?f=21&t=10079

It does have some advantages. There's a potential one I'm most interested in: at second glance, it looks like translations would be easier as they are dealt through Crowdin.net... But I'm waiting for an invite on Yorik's experiment to find out more about it.

Among shortcomings, Markdown syntax is a lot more sparse; AFAIK there is no possibility of templates/transclusion, there doesn't seem to be auto-generated TOCs for pages...

Yes, I saw that thread. It is certainly a possibility. And, yes, as you say, it seems that it's a simpler system. The resulting documentation is probably going to be very plain.

What I like about the wiki is that it allows you to enter the information quickly. I think if the documentation moves to a system like Git, then it becomes slightly more centralized. The same thing with Latex or XML. There would be the need to have a core documentation team tasked with maintaining the documentation. I think this is possible but only after FreeCAD has transitioned into a more stable software. There will be a time when a "FreeCAD foundation" is established, and at least a few people will be working full time on that, similar to LibreOffice or other major pieces of software.

[garya]

As a new user and new to this doc forum, feel free to take my comments lightly...

While I agree that a pdf document is not the most useful, I strongly prefer having the text properly marked up for future enhancements / migration. I'm not familiar with what the current state of indexing is, but the single most frustrating thing I encounter when using documentation is the lack of a good index. AFIK a good index can only be created with properly marked up text; I have never encountered documentation of any kind, from any organization or using any software, that was auto-generated without the help of text markup. Without text markup, indexes tend to have either a multitude of useless references, or so few they miss many important items.