Add macro support in documentation

[KoBeWi]

Describe the project you are working on: I sometimes write some docs for Godot.

Describe the problem or limitation you are having in your project: Check these snippets from Godot class reference (from Control class):

Returns a color from assigned [Theme] with given [code]name[/code] and associated with [Control] of given [code]type[/code]. 

Returns a constant from assigned [Theme] with given [code]name[/code] and associated with [Control] of given [code]type[/code].

Returns a font from assigned [Theme] with given [code]name[/code] and associated with [Control] of given [code]type[/code]. 

Returns an icon from assigned [Theme] with given [code]name[/code] and associated with [Control] of given [code]type[/code]. 

As you can see, the sentences are basically repeated with some words changed. This creates more work when documenting also translators will have more work translating.

Describe the feature / enhancement and how it helps to overcome the problem or limitation: For such cases, it wold be convenient to have macros with placeholders for putting words. Then we could just do this:

<macro=get_stuff>Returns %s from assigned [Theme] with given [code]name[/code] and associated with [Control] of given [code]type[/code].</macro>

<description>
    [get_stuff]an icon[/get_stuff]
</description>

Describe how your proposal will work, with code, pseudocode, mockups, and/or diagrams: Macros would be defined at the top of documents and identified by names. When parsing document further, block tags with matching macro name would be replaced, taking the contents for placeholders (multiple words would be separated by semicolon). See above example for syntax.

If this enhancement will not be used often, can it be worked around with a few lines of script?: Well, it can be worked around with more text, but the point is to avoid this .-.

Is there a reason why this should be core and not an add-on in the asset library?: It's about Godot's documentation.

EDIT: Found another use case. RigidBody3D/Generic6DOFJoin (and probably similar nodes) have some descriptions repeated thrice, for each axis.

[Calinou]

I'm not sure if this is worth the added complexity, especially considering the class reference can be translated now. (The translation is only available for the online version currently.)

[KoBeWi]

Well, it's supposed to help the translations too. It's less text to translate if you can replace it with repetitive macros.

[YuriSizov]

I'm not sure it's going to help translators. You lose the context where the text is used, and you lock the sentence structure to what works for English. Unless you propose that translators could opt-in to use their own macros instead of the ones we would use in the source documentation, of course, but I don't think we have the technology to support that on the translation platform.

[KoBeWi]

It's possible to leave comments for translators about the context. But looking at the example I gave - it's rather clear what it's used for and the %s placeholder allows for a flexible structure.

What we have now is that when someone decides to update a text that repeats similarly multiple times, you suddenly have to re-translate X same-looking strings that differ in a single word. That's rather meh.

[YuriSizov]

It's more work, yes, but it also allows all languages to sound as natural as possible instead of building the sentence structure around the text substitution.