Problem

  • String concatenation madness in hook_help():
          $output .= '<h3>' . t('Uses') . '</h3>';
          $output .= '<dl>';
          $output .= '<dt>' . t('Creating aliases') . '</dt>';
          $output .= '<dd>' . t('Users with sufficient <a href="@permissions">permissions</a> can create aliases under the <em>URL settings</em> section when they create or edit content. Some examples of aliases are: ', array('@permissions' => url('admin/people/permissions', array('fragment' => 'module-path'))));
          $output .= '<ul><li>' . t('<em>member/jane-smith</em> aliased to internal path <em>user/123</em>') . '</li>';
          $output .= '<li>' . t('<em>about-us/team</em> aliased to internal path <em>node/456</em>') . '</li>';
          $output .= '</ul></dd>';
          $output .= '<dt>' . t('Managing aliases') . '</dt>';
          $output .= '<dd>' . t('The Path module provides a way to search and view a <a href="@aliases">list of all aliases</a> that are in use on your website. Aliases can be added, edited and deleted through this list.', array('@aliases' => url('admin/config/search/path'))) . '</dd>';
          $output .= '</dl>';
    

Goal

  • Sanity?

    <h3>Uses</h3>
    
    <dl>
    <dt>Creating aliases</dt>
    <dd>Users with sufficient <a href="{{ 'admin/people/permissions#module-path'|url }}">permissions</a> can create aliases under the <em>URL settings</em> section when they create or edit content. Some examples of aliases are:
    <ul>
    <li><em>member/jane-smith</em> aliased to internal path <em>user/123</em></li>
    <li><em>about-us/team</em> aliased to internal path <em>node/456</em></li>
    </ul>
    </dd>
    <dt>Managing aliases</dt>
    <dd>The Path module provides a way to search and view a <a href="{{ 'admin/config/search/path'|url }}">list of all aliases</a> that are in use on your website. Aliases can be added, edited and deleted through this list.</dd>
    </dl>
    

    (sorry, I'm not up to speed with twig template syntax)

Details

  • Obviously, a couple of things to figure out...
    1. Extracting (static) translatable strings out of twig templates.
    2. Making that |url filter work.
    3. ...more...
Support from Acquia helps fund testing for Drupal Acquia logo

Comments

Fabianx’s picture

That is a great idea.

In general that would favor an approach like:

http://twig.sensiolabs.org/doc/extensions/i18n.html

Code: https://github.com/fabpot/Twig-extensions/blob/master/lib/Twig/Extension...

where the result is not run through gettext, but through t() instead.

Only the filtered URLs would need to be set as vars at the beginning. The rest would be quite straightforward though the question remains how to split it nicely up.

Maybe a new extension based on i18n that takes line-endings into account?

andypost’s picture

At least the results on hook_help() should have different context and I prefer to allow alterability

andypost’s picture

Issue tags: +D8MI

Tagging

Fabianx’s picture

#2: What do you mean with alterability?

andypost’s picture

Meaning that contrib should have ability to add own lines to core's help text

sun’s picture

@andypost: That's not possible right now either, and I haven't ever seen that use-case to begin with.

The proposal here just intends to change the source of the big HTML string that is generated. It's still a big HTML string though.

jhodgdon’s picture

This seems like a good proposal, as the main help page would certainly then be easier to write. But is it realistic to think we could get this done in core for D8, given that we would need it to (a) work for displaying all the existing help texts for core modules and (b) be translatable?

joelpittet’s picture

larowlan’s picture

Twig folks: Is this possible yet?

joelpittet’s picture

@larowlan I can't see why not. We have all the details in the summary figured out. We haven't used twig environment outside of hook_theme() definitions. If this *can* become a theme hook it would be fairly straight forward. If not, we need to find a place to put the template and have the twig engine just render a template... also not really too hard.

sun’s picture

Of course, I'd naturally prefer a README.md.twig as opposed to a help.html.twig file ;)

Grepping Google, I found:

https://github.com/aptoma/twig-markdown
https://github.com/KnpLabs/KnpMarkdownBundle
https://github.com/geta6/Twig-Markdown

@Crell additionally mentioned that Sculpin uses something similar:

https://sculpin.io/

The gist is that we want to pre-process or post-process the markdown formatted text, so we're able to inject {{ url() }} (or however that works) into twig-enhanced .md files.

But of course, killing hook_help() [pages] in favor of help.html.twig files would be true awesomeness as a first step already. :)

jhodgdon’s picture

Instead of actually writing the hook_help() for each module as a Twig template file, which at this point would require a lot of work in the Help module that I don't think anyone is doing, would it be possible instead to define a Twig template for help?

I am not a Twig expert but it seems like it could have input variables that would be
- about: array of paragraphs of text for the About section
- uses: array where each item is a Uses item
==> uses items each are an array with element 'title' (the title of the item) and 'text' (array of paragraphs of text)

Then you could do something like this in your hook_help():

return theme('help', array(
   'about' => array(t('about text goes here')), 
   'uses' => array(
      array(
        'title' => t('title1)', 
        'text' => array(t('first text goes here')),
      ),
    )
);

Can this be done in Twig?

jhodgdon’s picture

The problem with the ideas that were previously proposed here (original proposal, and #11 as well) is that someone would have to totally rewrite the Help module in order to use them. Instead of using hook_help(), it would need to read some other file and use that, and besides that we would need to modify localize.d.o or the code that it uses, so that it would make this new file translatable.

It is very late in the D8 cycle for this type of change to be accepted, I think? And I've seen so many proposals for redoing the help system die a horrible death.

In contrast, the idea of #12 would just require someone to write a single Help twig template that would print out help in our standard format, and then we'd need to convert the existing hook_help() text to call theme() instead of concatenating in the HTML tags as we are currently doing. This doesn't require any redo of the help system so I think it would be viable to do at this stage.

sun’s picture

@jhodgdon: That proposal is very different to the concrete proposal here, so should go into a separate issue.

The entire point of this proposal here is what you describe as "minor" but actually is a major DX clusterfuck and the primary reason for why (literally) only Drupal core cares for proper help module pages, but no one else, as outlined in the issue summary:

  $output .= '<this>';
  $output .= '<that>' . t('makes') . '</that>';
  $output .= t('no !sense at all.', array('!sense => '<sense />'));
  $output .= '</this>';
jhodgdon’s picture

Title: Use Twig templates for main help topic pages of modules » Put each module's help into a separate Twig file

OK, changing the title then -- I think several people who have commented here have missed the point partially or completely, and thought it was really about making a single Help twig template -- which you have just explained is not within the scope of this issue.

Given that, I think this issue is a non-starter at this point for Drupal 8 and should be pushed to Drupal 9. But I do not wish to start any issue wars so I am not changing the version myself. The Help module for 8 currently has no maintainer; that person or one of the branch maintainers would probably be the logical person to make that decision.

markhalliwell’s picture

Version: 8.x-dev » 9.x-dev
Priority: Major » Normal

Firstly, this is a feature request and secondly, this definitely is an API change (regardless if it's just moving it to templates). Also, degrading the priority to normal... it's just a normal request to clean up old crud (hell, could even really be a task for that matter).

FWIW though, I'd be willing to help work on this (along with anyone else willing). #1927584: Add support for the Twig {% trans %} tag extension definitely lands us the ability to translate large blocks of text inside a template. I think perhaps it would benefit us to at least look at https://drupal.org/project/advanced_help. We don't have to use anything really, just take a gander.

As far as an actual implementation though, I would strongly recommend we go for a generic auto-discovery of a README.html.twig file in the root of each project for the following reasons:

  1. Consistent name for each project: README.html.twig. People don't have to go searching for it.
  2. A lot of contrib projects already include a README or README.txt file. A simple rename, maybe add a some markdown twig tags around it to convert and voilà... easily converted help doc.
  3. Auto-discovery at root level (or even a subfolder like /help) for specific twig files could allow us to leverage structure:
    • README.html.twig
    • INSTALL.html.twig
    • CONFIGURE.html.twig
    • API.html.twig

Idk, just an idea...

jhodgdon’s picture

Just a question... Why Twig? Twig files are not all that readable until they're processed by Twig, and they're not (I think) much more writeable by non-programmers (e.g., documentation team members) than the current hook_help() template (which at least some non-programmers have managed to pick up, but not many.

I would rather close this as Won't Fix and start a new issue with a markdown or other proposal, which would have the advantage of having text that is at least readable in its unprocessed form, and easier to edit. Since we're being strict here about the issue scope, I'm assuming that anything that doesn't match the original issue here is out of scope and should be opened as a separate issue.

I just don't really see what doing this in a Twig template really buys us. Maybe we need a proper issue summary outlining what the actual problems are with the current system (not just someone's aesthetics), so we can see which ones would be solved by going to this particular system? Or we could open up one of the many many many past issues that tried to redo the help system in some more rational way... and failed to get anywhere for various reasons.

markhalliwell’s picture

Because a Twig would allow advanced maintainers the flexibility of:

<h3>Heading 3</h3>
<ol>
  <li><a href="http://google.com">Google</a></li>
  <li>Item 2</li>
  <li>Item 3</li>
</ol>
<p>Aenean eu leo quam. Pellentesque <a href="{{ 'admin'|url }}">ornare</a> sem lacinia quam venenatis vestibulum. Donec sed odio dui. Etiam porta sem malesuada magna mollis euismod. Sed posuere consectetur est at lobortis.</p>

Or the simplicity and readability of converting existing README.txt files into:

{% markdown %}
### Heading 3

1.  [Google](http://google.com)
2.  Item 2
3.  Item 3

Aenean eu leo quam. Pellentesque [ornare]({{ 'admin'|url }}) sem lacinia quam venenatis vestibulum. Donec sed odio dui. Etiam porta sem malesuada magna mollis euismod. Sed posuere consectetur est at lobortis.
{% endmarkdown %}

Quite simply, it's leveraging existing (well aside from putting in the markdown parser) template processing (twig tags, filters, functions, etc...).

No, this issue should remain open to discuss this more.

andypost’s picture

And twig should allow contrib modules to inject own lines for code templates?

joelpittet’s picture

I'd rather see the format that works best for the people usually writing these help. If markdown in a README.md is easiest to work with then cool. We can add a page for it then loading that file into the content for a routed help page. I'd rather not force people writing these help pages in twig templates when the focus is more on writing the content and not the markup.

larowlan’s picture

Can we support translation with markdown?
I don't think so but happy to be wrong.

joelpittet’s picture

Not to my knowledge:( Also would be happy to be wrong.

jhodgdon’s picture

Is everything in a Twig template automatically translated though -- I thought you had to wrap text in Twig in something to get it to be translatable? That would make writing the Twig template much more complicated than the examples shown here, thereby I think negating a lot of the supposed benefits of this approach.

joelpittet’s picture

@jhodgdon you are correct about twig + translate. And I agree with you and also curious how translation was dealt with and do we need to here too. Maybe some markdown parser changes?

jhodgdon’s picture

I'm not sure what you're asking for in #24. So far, this idea is just a conceptual idea, not code, so translation hasn't been dealt with at all.

In the existing hook_help() code, translation is dealt with by calling the t() function and passing the help text in.

joelpittet’s picture

@jhodgdon in twig you can translate things two ways, depending on how you want it to look in the markup:

With the |t filter

{{ 'Translate me'|t }}
{{ "Submitted by !author on @date"|t({ '!author': author, '@date': date }) }}

With the trans block

{% trans %}
    Some long {{ var }} Artisan post-ironic irony, direct trade slow-carb cardigan occupy chia street art ugh in narwhal shabby chic. Excepteur incididunt Tonx irony, ugh direct trade sed +1 you probably haven't heard of them kogi asymmetrical fingerstache delectus semiotics messenger bag. Before they sold out four loko ennui small batch. Tattooed veniam +1 fanny pack mumblecore laborum eiusmod non, selfies vero sed squid skateboard actually whatever.
{% endtrans %}
{% trans %}
  {{ count }} comment was deleted successfully.
{% plural count %}
  {{ count }} comments were deleted successfully.
{% endtrans %}

Partly stolen from @Mark Carver's blog post
http://getlevelten.com/blog/mark-carver/drupal-8-twig-templates-and-tran...

jhodgdon’s picture

Good information.

It would be good to see a sample of a more realistic Twig template for a module help page to see what this would look like, keeping in mind that we don't want the HTML tags to get into the translatable strings (which is why we have all the so-called "ugly concatenation" that this issue is trying to get rid of).

batigolix’s picture

Would YAML files not be more suitable for storing the help texts? They are used for Tour tips, which have an similar purpose: providing documentation for the UI
(https://drupal.org/developing/api/tour)

The HTML markup for help texts is always identical (exactly as defined inhttps://drupal.org/node/632280)

larowlan’s picture

FYI, I'm working on an example. Need to brush up on |url functionality first though

larowlan’s picture

Actually url might be blocked on #2073811: Add a url generator twig extension?

jhodgdon’s picture

RE #28 - apparently this issue has a very narrow scope and is only available for considering the specific case in the issue summary: individual Twig templates for each help file. So probably we would need to file a separate issue if we want to use YAML files.

larowlan’s picture

Status: Active » Needs review
FileSize
6.42 KB
65.83 KB
65.43 KB

So this uses url() but as #2073811: Add a url generator twig extension points out, we need a method to allow url() to use route names, but this will do for now.

So sample overview.html.twig is in attached patch.

With this approach, if hook_help returns an array with template and variables key, then that template is sought in the /help folder of the module.

This converts help_help for admin/help to use a twig template.

Screenshot before and after.
before
after

sun’s picture

Thanks for trying it out, @larowlan! Interesting start.

I wonder: What if the entire template was wrapped into {% trans %} ?

What's the realistic chance that only one original/English text fragment in a help text is changed, as opposed to the whole text? —— And, if that happens, does it make any sense in the first place to show a help page that is 95% translated, but has some English fragments in between, because those have changed?

In other words, this:

{#
/**
 * @file
 * Overview of help module displayed at admin/help.
 *
 * Available variables:
 * - has_node: TRUE if the node module is enabled.
 */
#}
{% set url_node_add = path(node.add_page) %}
{% set url_admin = path(system.admin) %}
{% set url_admin_config = path(system.admin.config) %}
{% trans %}
<h2>Getting Started.</h2>
<p>Follow these steps to set up and start using your website:</p>
<ol>
  <li><strong>Configure your website</strong> Once logged in, visit the <a href="{{url_admin}}">Administration page</a>, where you may <a href="{{url_admin_config}}">customize and configure</a> all aspects of your website.</li>
...
...
  {# Display a link to the create content page if Node module is enabled. #}
  {% if has_node %}
    <li><strong>Start posting content</strong> Finally, you may <a href="{{url_node_add}}">add new content</a> to your website.</li>
  {% endif %}
</ol>
{% endtrans %}
jhodgdon’s picture

I don't think we want the entire help, with all the tags, translated. That was the entire reason we put all the concatenation in the current hook_help. If that isn't a concern, we can just have a multi-line HTML string embedded inside the hook_help() and get rid of the Twig templates (which I think will be easier to deal with).

jibran’s picture

Really awesome work @larowlan. Let's create a meta and finish this up.

joelpittet’s picture

I'm leaning towards sun's approach with the trans around the whole thing because it will easier to read and cleaner looking and instead of translating the individual strings they could just translate the whole block of HTML, like as if they were translating the body field. The tags in the translation would be like that, would that be ok?

Also nice job @larowlan for the proof of concept. We should probably consider removing the .html.twig extention in the template definition just to be consistant with how we define templates in the theme system?

larowlan’s picture

I used single calls to t instead of trans to preserve/reuse existing translations, but I prefer the big chunk for DX too.

joelpittet’s picture

That's a good call @larowlan. Maybe Gábor Hojtsy could jump in on this or anybody on the multilingual initiative for best plan of attack?

batigolix’s picture

1) The example used in #32 and #33 is very much not representative for the help text that are currently in Drupal core. It would be better to use for example the Color module. All the hook help texts have the same structure with an About and a Uses section.

2) I still think it makes more sense to first discuss/think about what are the possibilities for this kind of documentation as mentioned in #11 and #28. Maybe that should be done in a separate issue.

3) The proposal in #32 doesnt seem a big DX gain compared to the current situation. It seems that there still is a lot of code, quotes and brackets that impede writing a bit of documentation

4) Most hook_help implementations contain texts for different paths. See for example the node module. Would these all go together in one twig file?

larowlan’s picture

1) Yes, color would be a cleaner example
2) Happy to postpone this on something else.
3) agreed, but we're kind of bound to what translation dictates
4) separate files

sun’s picture

4) separate files

This issue here is specifically about the main module help page text only. A module's "README", if you will.

All of the other hook_help() return values are beyond the scope of this issue. First and foremost, the other help texts are not BLOBs that happen to contain HTML, but instead, small fragments of help text only; most often not even involving HTML markup. In fact:

  1. For context-specific help texts, hook_help() is a weird legacy construct to begin with. The help text is attached to (A) a particular route and/or actually (B) to a block (HtmlFragment).
  2. There can be multiple help texts for the same route/block.

→ Typical use-case for plugins.

@Crell just happened to mention in IRC that all of these should simply be Tour plugins, but yeah, the use-case, processing, and output of help texts might be different, dunno.

In any case, all of that presents a crystal clear difference to the main module READMEs that are being targeted in this issue:

  1. They are big chunks of formatted text.
  2. They represent the primary/main page content. (There is no other content on these pages.)
  3. Their HTML output is composed in a manual fashion, despite the fact that there are theme functions for e.g. lists, but that is perfectly fine + makes sense for READMEs.
  4. ...

Let's proceed with experiments here. It would be awesome to see a variant of #32 that demonstrates #33 in action :)

jhodgdon’s picture

Thanks for all the enthusiasm...

Since apparently discussing the goals of this proposal and possible alternative ways to satisfy them is out of scope, can someone please open a separate issue to discuss this? I am not sure what the point of this issue is and I think we need to discuss what the goals are and the best way to satisfy them before we embark on this one specific proposal. That hasn't been done.

We also need to bring in two important stakeholders:

a) The people who actually write and review the hook_help. The way to find the people who are currently active is on the many current "update the hook_help" issues. There's a meta at: #1908570: [meta] Update or create hook_help() texts for D8 core modules

b) Translators, localize.d.o etc.

Until that discussion takes place, this whole effort is premature and I've already been shot down once on this issue for bringing it up, so we need a separate issue. Can someone who knows what the goal of this one is please file a separate issue where we can discuss other ideas? And can we postpone work on this one until that has been done please?

sun’s picture

#32 + #33 are the goal and the scope of this issue. We have Twig in core, so we should leverage it.

In essence, the architecture of our current module help pages pretty much means this in reality:

mymodule.help:
  path: '/admin/help/mymodule'
  defaults:
    # Short-circuit everything, output the theme template only.
    _template: 'readme.html.twig'
    _title: 'MyModule'
  requirements:
    _permission: 'access help pages'

Regarding A), I'm not sure why I/we do not count as "someone who actually writes and reviews hook_help()"...? — Fact is, I'm used to write polished READMEs, but every time I want or have to touch hook_help() for a module, the DX makes me cry and give up. → Whenever possible, I avoid to write or touch hook_help(). Certainly not in anyone's interest.

The overall adoption rate and quality of hook_help() in contributed modules appears to confirm that there is a problem. The only valid implementations I've ever seen are the ones in Drupal core, which alas, needs an entire armada of contributors to keep them in shape. The assumption is that hook_help() is simply too hard and unnatural to use and implement; the idea of concatenating (1) translatable strings into (2) random [HTML] markup (3) in PHP code doesn't make much sense in the first place.

Regarding B), sure, this change would certainly need an adaption for the potx extractor script (that also powers localize.d.o). — Although given that the |t and {%trans%} filters already exist in HEAD, that does not present a new or custom requirement. → Only the potential change of wrapping the whole markup (instead of text fragments) would need evaluation.

Bottom line: We can do better. This proposal is certainly not the only possible option, of course. But for the sake of focusing on the concrete experiment and proposal here, other options should be discussed in different issues. :)

The idea for this proposal was born one year ago already, around the time when Twig was originally committed to core and after the first template file conversions had happened. Given some other Twig explorations that I've recently seen and discussed with @mortendk and others at DrupalCamp Vienna, the basic idea of "Actually, let me manually produce the output for this specific page here please" appears to be (somewhat) in line with those considerations even.

Long story short: The concrete idea and proposal here is to explore whether we can replace the main help pages of modules with Twig templates (because they have little in common with hooks and even less so with PHP in general). Let's keep on experimenting to see whether we can get readme.html.twig to work in a nice way. (And if/when that works, we could proceed to explore options for the most natural way, README.md.)

jhodgdon’s picture

Wow, sorry for even asking.

Gábor Hojtsy’s picture

I'm *really* concerned on behalf of translators with this syntax proposed above by @sun:

{% trans %}
<h2>Getting Started.</h2>
<p>Follow these steps to set up and start using your website:</p>
<ol>
  <li><strong>Configure your website</strong> Once logged in, visit the <a href="{{url_admin}}">Administration page</a>, where you may <a href="{{url_admin_config}}">customize and configure</a> all aspects of your website.</li>
...
...
  {# Display a link to the create content page if Node module is enabled. #}
  {% if has_node %}
    <li><strong>Start posting content</strong> Finally, you may <a href="{{url_node_add}}">add new content</a> to your website.</li>
  {% endif %}
</ol>
{% endtrans %}

Just the immediate reasons that come to mind:

  1. Translators will need to understand twig syntax. Stuff like {# ... #} as well as whole new placeholder formts like {{url_node_add}}.
  2. Translators can easily break the twig template by accidentally doing bad things. Eg. remove the endif, forget one of two closing curly brackets, etc. What will that result in, a PHP error? A twig parsing error? I assume the site will not whitescreen but it will not be nice.
  3. Security issues may become a problem. Translations may be different filter syntax for values that would work. Unlike t() where the filters are expressed by different prefix characters, so if you use @value or %value, it would only work, if the right filtered value was provided, Twig does not work with unique identifiers for different values but instead with filters in the markup.
  4. The strings will very easily get outdated. Fix one typo in one of the sentences in a big help text. The whole translation immediately becomes outdated and translators get a *whole new string* to translate. This is obviously a limitation of how localize.drupal.org works, it should ideally propose similar string translations to get started with the translation for the *new* string. Either way, figuring out the difference and fixing it is up to the translator. Even if they use offline tools like poedit, which support fuzzy string matching for small fixes like this, they may miss the change itself and that either becomes a translation staleness issue or a security issue if a filter argument was fixed in the twig template for example.

All-in-all I think this puts too much on the translators shoulders and also opens up several possible problems that the individual strings are designed to avoid. The individual strings are designed so that if one changes, not all get outdated. They also lack structural markup, so the developer can change that + the translator cannot break it. And finally using t() placeholders the security of the string is much more ensured than what I envision happening here.

joelpittet’s picture

@Gábor Hojtsy re: #451 & 2 the hope would be that translators wouldn't touch the twig templates or need to know them. The content will be stored just like t('hello !name') etc would be stored in that proposal. {% trans %} maps to the t() function in PHP.

Gábor Hojtsy’s picture

@joelpitett: how would the grand {% trans %} block deal with the if/comment, etc. syntax in the text it contains then?!?

joelpittet’s picture

Oh didn't noticed that, I don't think that can be in there... trans I believe has a limited token set, if not enforced I'm sure we can... but same as t('tests ' . (($is_true) ? 'one may be tracked' : 'probably won't work').' more text'); currently get's handled.

joelpittet’s picture

comments are ignored. (translation happens on the generated string in the database same way t() in templates does in D7)

Gábor Hojtsy’s picture

@joelpiettet: so the generated text would be slightly different based on how the if/endif evaluated? So translators would need to translate the complete text in slightly different ways multiple times?! Still confused how this is an improvement.

jhodgdon’s picture

joelpittet: The problem is with the alternative where we would use {% trans %} for the entire text as one chunk. This would put the entire text plus markup plus some Twig {} things into one translation string.

The problem with that is that it is relatively easy for a translator to mess something up, and then the Twig template and markup and stuff wouldn't work.

Which is why we usually try to keep markup out of translation strings, in general. Given that Gabor has just confirmed this, I think we'd need to translate each line and not use the "one chunk as a big thing to translate" alternative.

Which again brings up the question of what this is really buying us, and whether this is really easier for anyone to deal with than the current method of doing hook_help().

So... Can I ask again, could we please have a discussion about the problems that are attempting to be solved here (with them being in the issue summary and not buried in the discussion), and with permission for all alternative solutions able to be discussed? If not here, in another issue?

jhodgdon’s picture

OK I've just started a separate discussion on how best to solve the problems of this issue:
#2188753: Get rid of hard-coded markup in hook_help() implementations

Feel free to continue the discussion there, propose alternatives, add to the "problems" section, etc.

lostkangaroo’s picture

Having updated a fair share of the hook_help() for D8 I can see where some of the ideas presented here could be considered improvements and I would support many of these would the time be available. However we should be focused on wrapping up the code base rather than determining something is wrong, ripping out and redoing a large portion of work that takes time due to lengthy and necessary review.

Twig files seem like the natural progression to hook_help() but we are looking at incorporating a yml for help.module to read per additional module to provide structure for the cases in the current hook_help or additional twig templates. An added benefit of this would be that help text could be available while a module is disabled. The help yml could be simply module_name.help.yml and structured

module_name_help:
  online_documentation: https://drupal.org/documentation/modules/module_name
  theme: help/module_name.help.twig
  additional_help:
    route: route_name
    theme: help/additional/route.help.twig

This way we can combine the ability to use twig templates and keep structure at the same time. It does create more files to maintain per module which actually deters DX to me personally more than the current hook_help system.

Either way this is by far a D9 issue at this point in the game.

jhodgdon’s picture

RE #53 - better to discuss on the other issue, see #52.

joelpittet’s picture

@Gábor Hojtsy it may not be the solution for this hook_help but the "improvement" is not needing to write every line as a string and instead translate the entire block of HTML(think translating a WYSIWYG body field). That may not be the best approach here but that is the purpose of {% trans %} to make t('string !var', array(...)) easier to write in HTML while still mapping directly to it. It has little in the way of magical powers that t() doesn't do because it's the same function being called when the twig file compiles to PHP.

Gábor Hojtsy’s picture

@joelpittet: trans is not news to me, I think you are missing my point. See @jhodgdon in #51 explaining some of the same things that I explained or #45 on why this is several steps back for translators. Using a big trans block is NOT an improvement for translators on *any* level.

sun’s picture

I'd like to better understand the concerns that have been raised. This is what I've heard:

  1. Actual Twig template scripting control commands cannot be part of the translated string.
  2. We don't want to include markup in translatable strings, because typos, and because we do not want translators to be able to operate on raw HTML.

Is that correct or not, or is something missing?

(1) was an error in the example snippet only; instead, I think the %trans% filter tag would end before control structures and be re-opened/re-started in the inner (and subsequent outer) body.

In case (2) is really a hard blocker (i.e., we cannot and we do not want to trust translators to produce raw but safe HTML), then we need to rethink here.

Now, if that is the case, I'd actually recommend to skip the current incarnation that involves raw HTML and directly hop to the more advanced experiment: README.md.

That is, because Markdown is (1) not raw HTML but yet (2) a clearly defined syntax and markup language.

More specifically, we do not even need Twig to resolve our two primary requirements:

  1. Links to other routes/URLs.

    Markdown:

    Dude, [Drupal](https://drupal.org/) is awesome.
    ...
    To set up your thingies, consult the [Thingie configuration](thingie.admin).
    

    → Markup Preprocessor

    A relatively simple Markdown preprocessor/filter is able to identify links that are using route names and automatically convert them into URLs, before the actual Markdown markup processing is executed.

  2. Translatable chunks of text strings (and only text strings).

    → Raw string extractor + preprocessor.

    Piggy-backing on the Markdown standard syntax: Disregarding the Markdown-Extras extension, the entire markup language of the standard Markdown syntax is based on plain-text, whereas (block) formatting is exclusively expressed via well-defined line prefixes.

    As an example:

    ## Uses
    
    * You can do this.
    * You can do that.
    

    $translatable_strings = array(
      'Uses',
      'You can do this.',
      'You can do that.',
    );
    

    Pretty simple to extract. And likewise, pretty simple to inject/rewrite.

Gábor Hojtsy’s picture

@sun: I think you missed two points from the list in #57:

1. All other pieces of text in Drupal uses HTML markup. If there is extra twig markup included, then translators need to learn that. This is also true for Markdown markup. That some source strings use HTML links while others use Markdown links sounds like a recipe for mistakes to me.

2. Long chunks of text are a problem because even small typo changes in the source invalidate all translations. This is to some degree a tooling problem, but even with tooling it is lots of work to make sure translators fix the right things and spot all changes. Shorter strings invalidated is less work to redo translations (if you have a 3 para help text and fix a typo in the source translators only need to re-translate the short snippet where the typo was fixed, not all 3 paras again).

John_B’s picture

Version: 9.x-dev » 8.0.0-rc1
Status: Needs review » Active

posted in error - sorry

John_B’s picture

Version: 8.0.0-rc1 » 9.x-dev
Status: Active » Needs review
jhodgdon’s picture

Status: Needs review » Active
joelpittet’s picture

Just a suggestion, we could maybe do something like file-name.help.twig. Where the entire document is sent for translation instead of the little bits and pieces?

andypost’s picture

Maybe better to use route_name.help.twig then?

joelpittet’s picture

*.help.twig is an file extension suggestion not a route name. We've not done that yet but just a wild thought for the problem.

Fabianx’s picture

There is the better proposal to put help into CMI, which also solves the translation bit ...

joelpittet’s picture

@fabianx cmi would make it hard to mark up help for presentation wouldn't it?

jhodgdon’s picture

I've filed a new meta issue to collect all the problems with the current help system and discuss the best route to fixing them; this issue is being added as Related there:
#2592487: [meta] Help system overhaul

One note on this one: on a different issue, it was brought up that we probably want each paragraph of help to be a separate string. See the new meta for details on this.

catch’s picture

Version: 9.x-dev » 8.1.x-dev
Status: Active » Postponed (maintainer needs more info)

Doesn't look like this is the current direction of #2592487: [meta] Help system overhaul so moving out of the active queue.

But also if we changed this, it could happen in a minor release with a bc layer for hook_help().

Version: 8.1.x-dev » 8.2.x-dev

Drupal 8.1.0-beta1 was released on March 2, 2016, which means new developments and disruptive changes should now be targeted against the 8.2.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.2.x-dev » 8.3.x-dev

Drupal 8.2.0-beta1 was released on August 3, 2016, which means new developments and disruptive changes should now be targeted against the 8.3.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

jhodgdon’s picture

Version: 8.3.x-dev » 8.4.x-dev

Drupal 8.3.0-alpha1 will be released the week of January 30, 2017, which means new developments and disruptive changes should now be targeted against the 8.4.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.4.x-dev » 8.5.x-dev

Drupal 8.4.0-alpha1 will be released the week of July 31, 2017, which means new developments and disruptive changes should now be targeted against the 8.5.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

andypost’s picture

There's 2 competing approaches but only one have patch

The main issue with help/docs stored in files is a way to pass routes & render relative links in UI
Better to start with design #2516902: Introduce a visual hierarchy to the help page.

Version: 8.5.x-dev » 8.6.x-dev

Drupal 8.5.0-alpha1 will be released the week of January 17, 2018, which means new developments and disruptive changes should now be targeted against the 8.6.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.6.x-dev » 8.7.x-dev

Drupal 8.6.0-alpha1 will be released the week of July 16, 2018, which means new developments and disruptive changes should now be targeted against the 8.7.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.7.x-dev » 8.8.x-dev

Drupal 8.7.0-alpha1 will be released the week of March 11, 2019, which means new developments and disruptive changes should now be targeted against the 8.8.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

jhodgdon’s picture

Status: Postponed (maintainer needs more info) » Closed (duplicate)
Related issues: +#3041924: [META] Convert hook_help() module overview text to topics

At this point, the planned patch for Help Topics looks a lot like this idea. So, I think we can now close this as a duplicate of #2920309: Add experimental module for Help Topics and also #3041924: [META] Convert hook_help() module overview text to topics. If not, feel free to reopen. :)