Issue #2832269 by gisle: Added display of README along with HTML

ASSETS.yml

----
-# Define an alias for screendumps.
-aliases:
-  hide: TRUE
-  title: ALIASES
-  block:
-  - &screendumps
-    type: asset
-    approved: allowed license
-    license: CC0
-    rights: https://creativecommons.org/publicdomain/zero/1.0/
-    source: Gisle Hannemyr
-
-help.png:
-  title: help.png
-  type: asset
-  approved: allowed license
-  license: CC0
-  rights: https://creativecommons.org/publicdomain/zero/1.0/
-  source: unknown origin
-  hide: TRUE
-
-help/ahelp_tab.png:
-  title: ahelp_tab.png
-  hide: TRUE
-  a: *screendumps
-
-help/click_icon.png:
-  title: click_icon.png
-  hide: TRUE
-  a: *screendumps
-

README.txt

@@ -6,6 +6,7 @@ CONTENTS OF THIS FILE
 * Recommended modules
 * Installation
 * Configuration
+* Support status
 * Maintainers
 
 
@@ -31,8 +32,7 @@ Advanced help hint:
   https://www.drupal.org/project/advanced_help_hint
   If Advanced help is not enabled, this module will generate a hint
   string that can be used in the project's hook_help to hint that
-  Advanced help should be
-  enabled.
+  Advanced help should be enabled.
 
 
 Installation
@@ -47,11 +47,31 @@ further information.
 Configuration
 -------------
 
-By itself, this module doesn't do much. The Advanced help assists
-other modules and themes in showing help texts. Nothing will show up
-until you enable at least one other module that makes use of the
-Advanced help framework or comes with a file named README.md or
-README.txt.
+There is no configuration.
+
+When you enable the module, you will have access to on-screen help,
+including README-files, created to tie in with the **Advanced help**
+framework.
+
+
+Support status
+--------------
+
+Reported bugs for the Drupal 7 branch will be fixed in a timely
+manner.  Older versions are no longer supported.
+
+Community support in the form of patches are very welcome for both
+Drupal 7 and Drupal 8 versions. For QA, the project needs community
+support in the form of reviews of patches, development versions and
+releases.
+
+The primary goal of the module is to remain light-weight and simple.
+This means that not all feature requests will be implemented, even if
+they are a good idea.  Feature requests accompanied by patches are
+more likely to make it into a release.
+
+The maintainer hopes that the community is willing to help out by
+answering & closing support requests.
 
 
 Maintainers
@@ -64,4 +84,4 @@ amitgoyal  (5 commits)
 gisle (current maintainer, D7)
 gnuget (current maintainer, D8)
 
-This project has been sponsored by:Hannemyr Nye Medier AS
+This project has been sponsored by: Hannemyr Nye Medier AS

advanced_help.module

@@ -32,10 +32,27 @@
  * links.)
  */
 
+/**
+ * Implements hook_help().
+ */
+function advanced_help_help($path, $arg) {
+  if ($path == 'admin/help#advanced_help') {
+    $output = '<p>' . t('This module provides extended help and documentation.') . '</p>';
+    if (function_exists('advanced_help_hint_docs')) {
+      $output .= '<p>' . advanced_help_hint_docs('advanced_help', 'https://www.drupal.org/docs/7/modules/advanced-help', TRUE) . '</p>';
+    }
+    else {
+      $output .= t('If you install and enable the module <strong>!url</strong>, you will get more help for <strong>Advanced help</strong>.',
+        array('!url' => l('Advanced help hint', 'https://www.drupal.org/project/advanced_help_hint')));
+    }
+    return $output;
+  }
+}
+
 /**
  * Implements hook_menu().
  *
- * Strings in hook_help() should not be run through t().
+ * Strings in hook_menu() should not be run through t().
  */
 function advanced_help_menu() {
   $help_exists = module_exists('help') ? TRUE : FALSE;
@@ -590,7 +607,7 @@ function theme_advanced_help_topic($variables) {
 function advanced_help_get_topic_filename($module, $topic) {
   $info = advanced_help_get_topic_file_info($module, $topic);
   if ($info) {
-    return "./$info[path]/$info[file]";
+    return "$info[path]/$info[file]";
   }
 }
 
@@ -605,6 +622,9 @@ function _advanced_help_get_module_type($module) {
 
 /**
  * Load and render a help topic.
+ *
+ * The strategy is first to see if a translated file for the current
+ * active language exists.  If not found, look for the default.
  */
 function advanced_help_get_topic_file_info($module, $topic) {
   global $language;
@@ -617,16 +637,14 @@ function advanced_help_get_topic_file_info($module, $topic) {
   // Search paths:
   $module_type = _advanced_help_get_module_type($module);
   $paths = array(
-    // Allow theme override.
-    path_to_theme() . '/help',
-    // Translations.
+    // First see if a translation exists.
     drupal_get_path($module_type, $module) . "/translations/help/$language->language",
     // In same directory as .inc file.
     $info['path'],
   );
 
   foreach ($paths as $path) {
-    if (file_exists("./$path/$info[file]")) {
+    if (file_exists("$path/$info[file]")) {
       return array('path' => $path, 'file' => $info['file']);
     }
   }
@@ -824,36 +842,43 @@ function advanced_help_get_settings() {
 function _advanced_help_parse_ini() {
   global $language;
   static $ini = NULL;
-
   if (!isset($ini)) {
     $cache = cache_get('advanced_help_ini:' . $language->language);
     if ($cache) {
       $ini = $cache->data;
     }
   }
-
   if (!isset($ini)) {
+    // No cached list of topics - create it.
     $ini = array('topics' => array(), 'settings' => array());
 
     foreach (array_merge(module_list(), list_themes()) as $plugin) {
       $module = is_string($plugin) ? $plugin : $plugin->name;
       $module_path = drupal_get_path(is_string($plugin) ? 'module' : 'theme', $module);
-      $info = array();
+
+      // Parse ini-file if it exists
       if (file_exists("$module_path/help/$module.help.ini")) {
-        $path = "$module_path/help";
+        $path_html = "$module_path/help";
         $info = parse_ini_file("./$module_path/help/$module.help.ini", TRUE);
+        if (!$info) {
+          drupal_set_message(t('There is a syntax error in the default .ini-file.  Unable to display topics.'), 'error');
+        }
+      }
+      else {
+        $info = array();
       }
-      elseif (!file_exists("$module_path/help")) {
+      if (empty($info) || !empty($info['advanced help settings']['show readme'])) {
         // Look for one or more README files.
         $files = file_scan_directory("./$module_path",
           '/^(readme).*\.(txt|md)$/i', array('recurse' => FALSE));
-        $path = "./$module_path";
+        $path_readme = "$module_path";
         foreach ($files as $name => $fileinfo) {
           $info[$fileinfo->filename] = array(
             'line break' => TRUE,
             'readme file' => TRUE,
             'file' => $fileinfo->filename,
             'title' => $fileinfo->name,
+            'weight' => -99,
           );
         }
       }
@@ -863,6 +888,9 @@ function _advanced_help_parse_ini() {
         $translation = array();
         if (file_exists("$module_path/translations/help/$language->language/$module.help.ini")) {
           $translation = parse_ini_file("$module_path/translations/help/$language->language/$module.help.ini", TRUE);
+          if (!$translation) {
+            drupal_set_message(t('There is a syntax error in the translated .ini-file.'), 'error');
+          }
         }
 
         $ini['settings'][$module] = array();
@@ -895,9 +923,10 @@ function _advanced_help_parse_ini() {
             // Require extension.
             'file' => isset($topic['readme file']) ? $file : $file . '.html',
             // Not in .ini file.
-            'path' => $path,
+            'path' => isset($topic['readme file']) ? $path_readme : $path_html,
             'line break' => isset($topic['line break']) ? $topic['line break'] : (isset($ini['settings'][$module]['line break']) ? $ini['settings'][$module]['line break'] : FALSE),
             'navigation' => isset($topic['navigation']) ? $topic['navigation'] : (isset($ini['settings'][$module]['navigation']) ? $ini['settings'][$module]['navigation'] : TRUE),
+            'show readme' => isset($topic['show readme']) ? $topic['show readme'] : (isset($ini['settings'][$module]['show readme']) ? $ini['settings'][$module]['show readme'] : FALSE),
             'css' => isset($topic['css']) ? $topic['css'] : (isset($ini['settings'][$module]['css']) ? $ini['settings'][$module]['css'] : NULL),
             'readme file' => isset($topic['readme file']) ? $topic['readme file'] : FALSE,
           );

help/advanced_help.help.ini

-[readme]
-title = README
+[advanced help settings]
+show readme = TRUE
+
+[introduction]
+title = Introduction
 weight = -11
 
 [using-advanced-help]

help/ini-file.html

@@ -35,19 +35,26 @@ use a more friendly name than appears in the project's .info file.</dd>
 module/theme index. It overrides the <code>name</code> setting above,
 as well as the project's name in its .info file.</dd>
 
+<dt><code>show readme</code> (FALSE)</dt>
+<dd>For projects that comes with a set of HTML-files, the default is
+to hide the project's <code>README</code>-file. Setting this TRUE will
+show the README along with the HTML-files.</dd>
+
 <dt><code>hide</code> (FALSE)</dt>
 <dd>This may be used to hide a module or theme in the module/theme
 index. This is particularly useful for modules who insert their help
-files into the hierarchy of another module or theme, as might be done
-by modules that extend <strong>Views</strong> or derived themes that
-extend base themes like <strong>Zen</strong>. By setting this to TRUE
-the project will not appear as its own entry.</dd>
+files into the hierarchy of another module or theme. By setting this
+to TRUE the project will not appear as its own entry.</dd>
+
 </dl>
 
 <p>Each section after that will correspond to a single help file for a
-single topic.  It starts with the topic name in square brackets
-(e.g. <code>[ini-file]</code>).  The following settings may be set for
-each file/topic, with the default value (if any) in brackets.</p>
+single topic.  It starts with the topic machine name in square
+brackets (e.g. <code>[introduction]</code>).  The file containing the
+documentation for that topic will have the same machine name with the
+extension <code>html</code> (e.g. <code>introduction.html</code>) The
+following settings may be set for each file/topic, with the default
+value (if any) in brackets.</p>
 
 <dl>
 <dt><code>title</code></dt>
@@ -68,8 +75,8 @@ are sorted alphabetically.</dd>
 <dt><code>parent</code></dt>
 <dd>The topic ID to use in a hierarchy; children will be listed
 beneath parents in the topic list, and will have the parent in their
-breadcrumb trail. You may parent this topic to a topic in another
-module or theme by using <code>module%topic</code>
+breadcrumb trail. You may parent this topic to a topic
+in <em>another</em> module or theme by using <code>module%topic</code>
 or <code>theme%topic</code> as the identifier,
 where <code>module</code> or <code>theme</code> is the project's short
 name. For example if parent is set to, '<code>views%display</code>',
@@ -93,25 +100,5 @@ will override any .css file added by the global settings.</dd>
 <dd>The height in pixels of the popup window.</dd>
 </dl>
 
-<p>For example, here is a version of the <code>advanced_help.help.ini</code> file:</p>
-
-<pre>
-[readme]
-title = README
-weight = -11
-
-[using-advanced-help]
-title = Using advanced help
-weight = -10
-
-[translation]
-title = Translating advanced help
-
-[ini-file]
-title = Help .ini file format
-line break = FALSE
-
-[why-advanced-help]
-title = Why advanced help?
-line break = TRUE
-</pre>
+<p>Take a look at the .ini-file for this project to see an
+example.</p>

help/introduction.html

+<p>The <strong>Advanced help</strong> module provides a framework that
+allows help texts to be viewed as integrated into a Drupal
+website.</p>
+
+<p>These help texts are stored in ordinary <code>.html</code>-files
+that lives in the file system (as opposed to the database).  These
+files are distributed from the project Drupal.org repo in the same
+package as the module or theme, and placed in a subdirectory named
+<code>help</code> in the project or theme directory.</p>
+  
+<p>The help texts can be marked up with standard HTML. They will be
+rendered using your site's theme, but you may provide custom css.  If
+there is a <code>README.md</code> or <code>README.txt</code> in the
+package, the content of that file may be shown as well.</p>
+  
+<p>The help texts can be placed in an hierarchical book, allowing for
+top-down navigation, or placed in popups that can be added to a page
+with plain text links or themed icon links.</p>
+
+<p>Cross-linking book-sections,using fragment identifiers, works as
+one would expect.</p>
+
+<p>The help texts may be made searchable, but are not so by default (see
+“<a href="&topic:advanced_help/using-advanced-help#search&">Using advanced help</a>”
+for details).  If search is enabled, all help texts are fully
+indexed. This means that the entire contents of the advanced help set
+of pages can be searched for keywords.</p>
+
+<p>Modules and themes can even insert help texts into another
+project's hierarchy.</p>
+
+<p>May be integrated into <code>hook_help()</code> using companion
+module
+<a href="https://www.drupal.org/project/advanced_help_hint"><strong>Advanced help hint</strong></a>.</p>
+
+
+<h2 id="demo">Demonstrations</h2>
+
+<p>The project comes with a small demo module named
+<strong>Advanced help example</strong> to demonstrate how it works.
+For an example of a project that makes extensive use of the advanced
+help features, see the <strong>Views</strong> project.</p>
+
+<p>For an example of translation of help text, see the
+directory <code>translations/help/nb</code> in the <strong>Advanced
+help example</strong> submodule. For translation instructions, see the
+section named “<a href="&topic:advanced_help/translation&">Translating
+    advanced help</a>”.</p>

help/readme.html

-<h2 id="project-description">Synopsis</h2>
-
-<p>The <strong>Advanced help</strong> module provides a framework that allows
-module and theme developers integrate help texts in a Drupal site.</p>
-
-<p>These help texts are stored in ordinary <code>.html</code>-files
-that lives in the file system (as opposed to the database).  These
-files are distributed from the project Drupal.org repo in the same
-package as the module or theme, and placed in a subdirectory named
-<code>help</code> in the project or theme directory.  This means that
-the help texts can be easily kept in sync with the project they
-provide help texts for, but also that read access to these files
-are not managed by any content access restrictions imposed by Drupal.</p>
-  
-<p>The help texts can be marked up with standard HTML. They will be
-rendered using your site's theme.</p>
-
-<p>If the module or theme author does not make use of the
-<em>Advanced help</em> HTML-framework, but if there is a
-<code>README.md</code> or <code>README.txt</code> in the package,
-the content of that file will be shown instead.</p>
-  
-<p>The help texts may appear in a popup or not as the project prefers.
-By taking away access to view the popups, a site can hide popups from
-users.</p>
-
-<p>The help texts can be placed in a hierarchy, allowing for top down
-navigation of help.</p>
-
-<p>The help texts may be made searchable. If advanced help search is
-enabled, all help texts are fully indexed. This means that the entire
-contents of the advanced help set of pages can be searched for
-keywords.</p>
-
-<h2 id="use">Using the module</h2>
-
-<p>When you enable the module, a new tab with the legend “Advanced
-help” will show up under “Help”:
-
-<div class="ta-center">
-<img class="help-img-center" alt="ahelp_tab.png" src="&path&ahelp_tab.png" width="661" height="225" border="1" />
-</div>
-
-<p>By itself, this module doesn't do much.  The <strong>Advanced
-help</strong> assists other modules and themes in showing help texts.
-Nothing will show up until you enable at least one other module that
-makes use of the advanced help framework or comes with a file
-named <code>README.md</code> or <code>README.txt</code>.  However, it
-comes with a small companion demo module named
-<strong>Advanced help example</strong> to demonstrate how it works.
-For more extensive example of use of the advanced help features, see
-the <strong>Views</strong> project.</p>
-
-<!--
-<h2 id="project-recommended">Recommended modules</h2>
-
-<ul>
-<li><a href="https://www.drupal.org/project/markdown">Markdown filter</a>:<br>
-When this module is enabled, display of any <code>README.md</code> the
-module shows will be rendered with markdown.</li>
-<li><a href="https://www.drupal.org/project/attributions">Attributions</a>:<br>
-When this module is enabled, attributions of third party content used
-by the project (i.e. some text from Wikipedia) will be available in an
-attribution block and on an attribution page.</li>
-</ul>
--->
-
-<h2 id="support-status">Support status</h2>
-
-<p>Reported bugs for the Drupal 7 branch will be fixed in a timely
-manner.  Bugs in the issue queue for the Drupal 6 branch will only be
-fixed if accompanied with a patch, after the patch has been reviewed
-and tested by the community.  No Drupal 8 version is currently under
-development.  Post a message in
-the <a href="https://www.drupal.org/node/1928218">issue queue</a> if
-you're interested in managing a port of the project to to Drupal
-8. Older versions are no longer supported.</p>
-
-<p>Community support in the form of patches are very welcome for both
-Drupal 6 and Drupal 7 versions, and will be given priority. For QA,
-the project needs community support in the form of reviews of patches,
-development versions and releases.</p>
-
-<p>The primary goal of the module is to remain <strong>light-weight
-and simple</strong>.  This means that not all feature requests will be
-implemented, even if they are a good idea.  Feature requests
-accompanied by patches are more likely to make it into a release.</p>
-
-<p>The maintainer hopes that the community is willing to help out by
-answering &amp; closing support requests.</p>
-
-<!--
-<h2 id="project-problems">Known problems</h2>
--->
-
-
-
-<h2 id="project-maintainers">Credits</h2>
-
-<ul>
-<li><a href="https://www.drupal.org/u/merlinofchaos">merlinofchaos</a> (52 commits, original creator)</li>
-<li><a href="https://www.drupal.org/u/redndahead">redndahead</a> (8 commits)</li>
-<li><a href="https://www.drupal.org/u/dmitrig01">dmitrig01</a> (3 commits)</li>
-<li><a href="https://www.drupal.org/u/amitgoyal">amitgoyal </a> (5 commits)</li>
-<li><a href="https://www.drupal.org/u/gisle">gisle</a> (current maintainer, D7)</li>
-<li><a href="https://www.drupal.org/u/gnuget">gnuget</a> (current maintainer, D8)</li>
-</ul>

help/using-advanced-help.html

 <p>The <strong>Advanced help</strong> module provides a framework that
 allows module and theme developers integrate help texts in a Drupal
-site.  Although the <strong>Advanced help</strong> does not provide
-general help by itself, it provides a powerful and easy framework that
-modules and themes may use to provide their own help.</p>
+site.</p>
+
+<p>It provides a framework for creating and maintaing HTML help texts.
+It may also be used to display a module's or
+theme's <code>README</code>-file on the screen.</p>
+
+<h2 id="ah_enable">Enabling the module</h2>
+
+<p>When you enable the module, a new tab with the legend “Advanced
+help” will show up under “Help”:
+
+<div class="ta-center">
+<img class="help-img-center" alt="ahelp_tab.png" src="&path&ahelp_tab.png" width="661" height="225" border="1" />
+</div>
+
+<p>Links to the help texts are under this tab.</p>
+
+<h2 id="ah_crehlp">Creating help</h2>
 
 <p>Modules and themes utilizing <strong>Advanced help</strong> should
 create a subdirectory named <code>help</code> inside their own main
@@ -11,62 +26,78 @@ directory. Place the file
 formatted similar to the following example:</p>
 
 <pre>
-[about-php]
-title = About PHP
-file = about-php
-weight = -10
+[advanced help settings]
+navigation = FALSE
+show readme = FALSE
 
-[history]
-title = History of PHP
-parent = about-php
+[about-example]
+title = About the help example
+weight = -11
 
-[usage]
-title = Usage of PHP
-weight = 1
-
-[security] 
-title = Security of PHP
-weight = 2
+[lorem]
+title = Lorem ipsum
+weight = -10
 
-[syntax]
-title = PHP syntax
-parent = usage
+[etiam]
+title = Etiam ultricies
+parent = lorem