For the Configurable Help Topic system (see #2351991: Add a config entity for a configurable, topic-based help system → and my sandbox project https://www.drupal.org/sandbox/jhodgdon/2369943 → which is developing it), I need a way for a config entity to have a "Body" field containing formatted text.
The obvious way to do this is just to put the "body" into one big HTML string, but this is problematic. The main reason is that strings on config entities get translated (on localize.drupal.org if they are provided in Core), and having large translated strings with HTML tags in them poses problems:
- Translations get invalidated if any part is changed. So it is better if the strings are shorter rather than the entire text of the "body", so that if one sentence changes, only one shorter string is invalidated.
- Long strings take longer to translate and review for translators, and are harder to get right (one error in one place means it can get rejected).
- It is difficult for the translators to get all the HTML tags right. They can get corrupted or become unmatched.
So, rather than having one big string with HTML embedded in it, it is preferable to have shorter strings that are about a paragraph in length or so, and preferably without the HTML tags.
Besides config entities, it would also be desirable to use this for hook_help() implementations, which currently do things like:
$output .= '<p>' . t(something) . '</p>';
return $output;
which removes the HTML tags and shortens the strings, but is ugly. You cannot even do that that in a config entity, though -- you need some kind of a system for splitting up the string and abstracting out the HTML tags.
Related issue #2697791: Add Plugin system for abstracted HTML-formatted text → is exploring a plugin system to do this.
On this issue, the idea is to use some type of markdown format. We would need to do the following to get this done:
a) Choose a particular flavor of markdown. On #2697791-3: Add Plugin system for abstracted HTML-formatted text → , bojanz suggested Commonmark; however it currently lacks a way to do definition-style lists (DL/DT/DD in HTML terms -- which you could do by embedding the HTML tags directly, but that kind of defeats the purpose of this whole idea if you have to include HTML tags to use these lists, which are very very very common in things like hook_help() and help topics in general).
b) Add a PHP library that can parse/render this markdown flavor to the vendor area of Core (as a composer dependency).
c) Document a way to separate a long string of (text + markdown) formatting into smaller strings for translatability. The idea would be similar to what is used in #2697791: Add Plugin system for abstracted HTML-formatted text → : each "paragraph" or "section" of markdown-formatted text would be a separate string. Developers or config entity editors would choose how to split it up.
d) Figure out how to express this in a render array (define a render element etc.).
e) Figure out how to express this in a config entity schema/renderer (should be fairly simple).
a) Figure out all of the unknowns in the Proposed Resolution.
b) Convert a hook_help() implementation in Core to use this, as an illustration of how much nicer it is than returning HTML strings.
c) Make a patch.
d) Try using this for the Configurable Help config entity and verify it is workable for the UI and config schema, as a viable replacement for the "text sections" plugin system and element of #2697791: Add Plugin system for abstracted HTML-formatted text → .
e) Write a change notice for the new stuff.
f) Decide on #2697791: Add Plugin system for abstracted HTML-formatted text → vs. this issue (which one is better), and get one of them committed to Core.
None.
API addition: New markdown render element and library added to vendor area. No API changes.
No.
Closed: works as designed
11.0 🔥
render system
Enhances developer experience.
Not all content is available!
It's likely this issue predates Contrib.social: some issue and comment data are missing.
It has been quiet here for 9 years, indicating no interest in pursuing this idea. I am going to close this now.
If that is wrong and there is interest in this re-open the issue and add a comment. Or open a new issue and reference this one.