Show a template's documentation and its text on its own page

README.md

@@ -66,7 +66,7 @@ An article
 - Limits, so one article cannot slow the board down: at most 500 template calls written in an article, 2000 calls and functions in all (including those inside templates), and about 500,000 characters of output. Past a limit the rest of the calls show "Too many templates" where they stand.
 - A template can include other templates, ten levels deep at most; a template that includes itself, directly or through another template, shows an error where the loop is (it cannot stop its own recursion with `{{#if:}}`, as on Wikipedia). A call to a template that does not exist is a red link to `Template:Name`.
 - The text of a template is parsed like article text, so it can use BBCode, `[[links]]`, headings and tables, and nothing an article could not.
-- **What links here** on a template page lists the articles that use it.
+- The page of a template shows its documentation (what is inside `<noinclude>`, with its calls worked out, so it can show examples), then **Template text**: the text an article gets, as it is written and not worked out, with how many articles use it. `<includeonly>` text is left off the page. **What links here** lists the articles that use the template.
 - Like headings and tables, this works in wiki articles only; in a forum post `{{Name}}` stays plain text. The first letter of a template name is not case-sensitive (`{{out of date}}` finds `Template:Out of date`).
 - **Parser functions** decide what a template shows. Only the part that is chosen is worked out, so the branch that is not taken can hold anything.
 

config/services.yml

@@ -168,6 +168,7 @@ services:
             - '@phpbbmodders.wiki.discussion'
             - '@phpbbmodders.wiki.files'
             - '@phpbbmodders.wiki.watch'
+            - '@phpbbmodders.wiki.templates'
     phpbbmodders.wiki.discussion:
         class: phpbbmodders\wiki\wiki\discussion
         arguments:

docs/TODO/todo-wiki-markup.md

@@ -163,7 +163,6 @@ out. Still to do:
   400 calls to a template took about 400 ms longer than the same table written out), one extra
   query for the template pages however many calls there are, and at most 500 calls and 2000
   functions per article. Add the cache only if articles with hundreds of calls become common.
-- Template pages show `<noinclude>` and `<includeonly>` as text; a tidier template page view.
 - A template call holds other calls in its parameters three levels deep, and a default value holds
   one level of `{{template}}`; deeper nesting stays text.
 - A list of templates and a "Template" start-point in the article picker.

language/en/link.php

@@ -44,6 +44,12 @@
 	'WIKI_LINK_NEW_ARTICLE'		=> 'This article doesn’t exist yet. Follow the link to create it.',
 	'WIKI_WHAT_LINKS_HERE'		=> 'What links here',
 	'WIKI_TEMPLATE_LOOP'		=> 'Template loop: “%s” includes itself',
+	'WIKI_TEMPLATE_TEXT'		=> 'Template text',
+	'WIKI_TEMPLATE_USED_ON'		=> array(
+		0	=> 'Not used in any article yet.',
+		1	=> 'Used in 1 article.',
+		2	=> 'Used in %d articles.',
+	),
 	'WIKI_TEMPLATE_TOO_DEEP'	=> 'Too many templates inside templates at “%s”',
 	'WIKI_TEMPLATE_UNKNOWN_FUNCTION'	=> 'Unknown function “%s”',
 	'WIKI_TIME_INVALID'			=> 'Invalid time',

styles/prosilver/template/article_body.html

@@ -48,6 +48,12 @@ <h2 itemprop="headline name">{ARTICLE_TITLE}<!-- IF ARTICLE_VERSION --> - {L_VER
 		</div>
 	</div>
 
+	<!-- IF S_TEMPLATE_PAGE -->
+		<h3>{L_WIKI_TEMPLATE_TEXT}</h3>
+		<p>{TEMPLATE_USED_ON}</p>
+		<pre class="wiki-template-source">{TEMPLATE_SOURCE}</pre>
+	<!-- ENDIF -->
+
 	<!-- IF U_SET_ACTIVE -->
 		<a href="{U_SET_ACTIVE}">{L_SET_ACTIVE}</a>
 	<!-- ENDIF -->

styles/prosilver/theme/style.css

@@ -134,3 +134,14 @@ a.wikilink-new {
 .wiki .content ul.post-buttons.wiki-buttons {
 	margin-top: 0;
 }
+
+/* The text of a template, shown as it is written on the template's page */
+pre.wiki-template-source {
+	margin: 0.5em 0;
+	padding: 0.6em 0.8em;
+	overflow: auto;
+	white-space: pre-wrap;
+	border: 1px solid #ccc;
+	background-color: rgba(128, 128, 128, 0.08);
+	font-family: monospace;
+}

tests/unit/templates_test.php

@@ -90,4 +90,13 @@ public function test_noinclude_and_includeonly_decide_what_is_included()
 
 		$this->assertSame('Body only here', templates::transclusion_text($text));
 	}
+
+	public function test_the_documentation_of_a_template_is_what_stands_in_noinclude()
+	{
+		$text = "<noinclude>First note.</noinclude>Body{{{1}}}<includeonly> hidden </includeonly><noinclude>\nSecond note.\n</noinclude>";
+
+		$this->assertSame("First note.\n\nSecond note.", templates::documentation($text));
+		$this->assertSame('', templates::documentation('Body only'));
+		$this->assertSame('Body{{{1}}} hidden ', templates::transclusion_text($text));
+	}
 }

wiki/templates.php

@@ -787,6 +787,55 @@ public static function transclusion_text($text)
 		return preg_replace('#</?includeonly>#i', '', $text);
 	}
 
+	/**
+	 * What to show on the page of a template: its documentation, which is what stands
+	 * inside <noinclude> (worked out like an article, so it can show examples), and
+	 * its text as a template, which is what an article gets, shown as it is written.
+	 *
+	 * @param string $article_text The stored text of the page
+	 * @param string $bbcode_uid The page's bbcode_uid
+	 * @return array The rendered documentation ("" when there is none) and the template text
+	 */
+	public function page_view($article_text, $bbcode_uid)
+	{
+		$edit = generate_text_for_edit($article_text, $bbcode_uid, OPTION_FLAG_BBCODE | OPTION_FLAG_SMILIES | OPTION_FLAG_LINKS);
+		$raw = htmlspecialchars_decode($edit['text'], ENT_COMPAT);
+
+		$documentation = self::documentation($raw);
+		$html = '';
+		if ($documentation !== '')
+		{
+			$uid = $bitfield = '';
+			$flags = 0;
+			$was_active = markup::is_active();
+			markup::set_active(true);
+			try
+			{
+				generate_text_for_storage($documentation, $uid, $bitfield, $flags, true, true, true);
+			}
+			finally
+			{
+				markup::set_active($was_active);
+			}
+			$html = generate_text_for_display($documentation, $uid, $bitfield, $flags);
+		}
+
+		return array($html, trim(self::transclusion_text($raw)));
+	}
+
+	/**
+	 * The text inside the <noinclude> parts of a template page.
+	 *
+	 * @param string $text The template page's text
+	 * @return string The parts one after the other, "" when there are none
+	 */
+	public static function documentation($text)
+	{
+		preg_match_all('#<noinclude>(.*?)</noinclude>#is', $text, $matches);
+
+		return trim(implode("\n\n", array_map('trim', $matches[1])));
+	}
+
 	/**
 	 * The text of the live version of a template page, as an editor would see it.
 	 *

wiki/view.php

@@ -48,6 +48,9 @@ class view extends \phpbbmodders\wiki\wiki\functions
 	/** @var \phpbbmodders\wiki\wiki\watch */
 	protected $watch;
 
+	/** @var \phpbbmodders\wiki\wiki\templates */
+	protected $templates;
+
 	/** @var string phpbb_root_path */
 	protected $phpbb_root_path;
 
@@ -74,9 +77,11 @@ class view extends \phpbbmodders\wiki\wiki\functions
 	* @param \phpbbmodders\wiki\wiki\discussion			$discussion			Start discussion object
 	* @param \phpbbmodders\wiki\wiki\files				$files				Uploaded files object
 	* @param \phpbbmodders\wiki\wiki\watch				$watch				Watched articles object
+	* @param \phpbbmodders\wiki\wiki\templates			$templates			Wiki templates object
 	*/
-	public function __construct(\phpbb\auth\auth $auth, \phpbb\db\driver\driver_interface $db, \phpbb\controller\helper $helper, \phpbb\template\template $template, \phpbb\user $user, \phpbbmodders\wiki\wiki\compare $compare, \phpbbmodders\wiki\wiki\edit $edit, $article_table, $phpbb_root_path, $php_ext, \phpbbmodders\wiki\wiki\links $links, \phpbbmodders\wiki\wiki\discussion $discussion, \phpbbmodders\wiki\wiki\files $files, \phpbbmodders\wiki\wiki\watch $watch)
+	public function __construct(\phpbb\auth\auth $auth, \phpbb\db\driver\driver_interface $db, \phpbb\controller\helper $helper, \phpbb\template\template $template, \phpbb\user $user, \phpbbmodders\wiki\wiki\compare $compare, \phpbbmodders\wiki\wiki\edit $edit, $article_table, $phpbb_root_path, $php_ext, \phpbbmodders\wiki\wiki\links $links, \phpbbmodders\wiki\wiki\discussion $discussion, \phpbbmodders\wiki\wiki\files $files, \phpbbmodders\wiki\wiki\watch $watch, \phpbbmodders\wiki\wiki\templates $templates)
 	{
+		$this->templates = $templates;
 		$this->discussion = $discussion;
 		$this->files = $files;
 		$this->watch = $watch;
@@ -196,7 +201,17 @@ public function view_article($article, $id = 0)
 			$allow_bbcode = $allow_magic_url = $allow_smilies = true;
 			// [[File:name]] in the text refers to this article's files
 			\phpbbmodders\wiki\wiki\files::set_context($this->data['article_url']);
-			$this->message_parser->format_display($allow_bbcode, $allow_magic_url, $allow_smilies);
+			$template_source = null;
+			if (strpos($this->data['article_url'], \phpbbmodders\wiki\wiki\templates::PREFIX) === 0)
+			{
+				// The page of a template shows its documentation, and its text as it is written
+				list($documentation, $template_source) = $this->templates->page_view($this->data['article_text'], $this->data['bbcode_uid']);
+				$this->message_parser->message = $documentation;
+			}
+			else
+			{
+				$this->message_parser->format_display($allow_bbcode, $allow_magic_url, $allow_smilies);
+			}
 			\phpbbmodders\wiki\wiki\files::set_context(null);
 
 			if (!empty($this->data['article_redirect']))
@@ -242,8 +257,18 @@ public function view_article($article, $id = 0)
 			$this->files->assign_to_template($this->data['article_url']);
 			$this->watch->assign_to_template($this->data['article_url']);
 
-			// Other articles whose live version links here with [[ ]].
-			foreach ($this->links->what_links_here($this->data['article_url']) as $linking)
+			$linking_articles = $this->links->what_links_here($this->data['article_url']);
+			if ($template_source !== null)
+			{
+				$this->template->assign_vars(array(
+					'S_TEMPLATE_PAGE'		=> true,
+					'TEMPLATE_SOURCE'		=> htmlspecialchars($template_source, ENT_COMPAT, 'UTF-8'),
+					'TEMPLATE_USED_ON'		=> $this->user->lang('WIKI_TEMPLATE_USED_ON', count($linking_articles)),
+				));
+			}
+
+			// Other articles whose live version links here with [[ ]], or uses it as a template
+			foreach ($linking_articles as $linking)
 			{
 				$this->template->assign_block_vars('what_links_here', array(
 					'TITLE'	=> $linking['article_title'],