Text: Update Text Representation

[kergomard]

Hi all

As promised this is a first try at updating our documentation for text representation. I tried to clarify the structure and I did not yet update the facility in Data. What it does:

• Removing the future case as there already is a basic implementation.
• Changing the emphasis in the examples: Previously the emphasis was on structure which I do not think meshes well with the definition. I think the key part of the definition is the target of the information: Does it address the user or the system. The rest, I think, are additional refinements.
• It adds the reliance on Moustache for the next level of processing. I just added it as a requirement.
• It removes the emphasis on families and replaces it by a emphasis on simplicity and reduction. If we agree on this I would actually remove the Markdown sub-shapes (and texts) to just have one markdown for everywhere.

While working on the feedback concerning the revision of the creation of questions, an additional problem surfaced: MathJax. I do not think this can (and should) be solved on the level of Markup and I do not think Moustache will solve the problem for us. My current solution would be to add a similar provision as for Moustache, but maybe somebody has a more elegant proposal.

I'm very much looking forward to your feedback.

[thibsy]

Hi @kergomard,

Thx for looking into this, much appreciated.

I agree with reducing the Markdown* texts and shapes, this underlines we have agreed on keeping the supported syntax close to the original. However, maybe we should take a clear note of this.

I was a bit confused because the section on *Text classes was reduced quite a bit. I think these classes should primarily be used by other components, and only use *Shape classes exceptionally. This change led me to believe otherwise.

In addition to my inline comments below, please

• SimpleDocumentMarkdownText: there's a reference to this class left in the mail example, which would be removed then.
• Make it clear that *Text classes are still the main entry point to the system for most of the components.
• Add something among the lines of "This is not looking to represent different markdown shapes in a granular manner" to the limitations.

P.S. regarding Latex, I think it would actually be OK to provide a *Text and *Shape class for this, since this is basically another kind of structured text, no? Whereas Mustache is something else entirely.

Kind regards,
@thibsy

[thibsy]

Maybe reference the mustache specification. Also note the typo =).

[thibsy]

Maybe we should also take note of the "set delimiter" tags, which are i.e. used to wrap latex content according to their manual. This is rather impractical for us, though – dunno if and how much we have to support or consider this.

[kergomard]

Thank you very much @thibsy for the feedback! I will give the others a little more time to react and will update everything in one fell swoop ;-) .