[m-dev.] declarative programming guide

[Julien Fischer]

On Tue, 21 Mar 2023, Mark Brown wrote:

> On Tue, Mar 21, 2023 at 4:05 PM Julien Fischer <jfischer at opturion.com> wrote:
>>
>>
>> Hi Mark,
>>
>> On Tue, 21 Mar 2023, Mark Brown wrote:
>>
>>> On Tue, Mar 21, 2023 at 10:28 AM Julien Fischer <jfischer at opturion.com> wrote:
>>>>
>>>> On Mon, 20 Mar 2023, Mark Brown wrote:
>>>>
>>>>> I've been collecting notes from teaching people at work about
>>>>> declarative programming, and formatting as a guide book (attached).
>>>>> Could this go on the Mercury documentation page somewhere?
>>>>
>>>> Sure. It might be worth us cleaning up the documentation page, at least
>>>> to the extent of distinguishing the official docmentation from tutorials
>>>> and alike. (The official documentation seems to be getting pushed
>>>> further and further down the page.)
>>>
>>> Agreed. If we have the canonical reference stuff at the top (Language
>>> Ref, User Guide, Library Ref) then the section beneath that should be
>>> easily spotted, and I think new users would quickly scroll down and
>>> find tutorials.
>>
>> Actually, I was thinking of adding a "Tutorials" or "Learning" entry to
>> the sidebar (just on top of "Papers") and moving all of the
>> tutorial-style documentation to a separate page.
>
> Sounds good to me.

The following diff does that; for your review.

-----------------------------------------------

Separate tutorials out into a separate subpage.

include/menubar.inc:
      Add "learning" to the side menu under "Documentation.

documentation/include/documentation.inc:
      Delete the tutorials from here.

documentation/include/learning.inc:
documentation/include/learning.php:
      Add a new subpage containing the tutorials.

diff --git a/documentation/include/documentation.inc b/documentation/include/documentation.inc
index ffd3c1a..73a5762 100644
--- a/documentation/include/documentation.inc
+++ b/documentation/include/documentation.inc
@@ -15,32 +15,6 @@ of the entire document, links to PDF versions are provided.
  </p>

  <ul class="nonindentlist2">
-        <li>
-        <h3>Mercury crash course</h3>
-        <a href="https://mercury-in.space/crash.html">
-	An introduction to Mercury through worked examples.
-        </a>
-        </li>
-
-	<li>
-	<h3>Ralph Becket Mercury tutorial</h3>
-	An introduction to Mercury.
-	This is still under development.
-	Feedback would be greatly appreciated.
-	<table class="documentation">
-	<tr><td>
-	<a href="papers/book.pdf"><button class="button">PDF</button></a>
-	</td></tr>
-	</table>
-	</li>
-
-        <li>
-        <h3>Mercury wiki tutorial</h3>
-        <a href="https://github.com/Mercury-Language/mercury/wiki/Tutorial">
-        Another introduction to Mercury.
-        </a>
-        </li>
-
  	<li>
  	<h3>Mercury Language Reference Manual</h3>
  	Information on the Mercury programming language
diff --git a/documentation/include/learning.inc b/documentation/include/learning.inc
index e69de29..877ce2d 100644
--- a/documentation/include/learning.inc
+++ b/documentation/include/learning.inc
@@ -0,0 +1,31 @@
+<h2>Documentation<span class="submenutitle">/ learning </span></h2>
+
+<p>This page contains links to resources for learning and understanding Mercury.</p>
+
+<ul class="nonindentlist2">
+        <li>
+        <h3>Mercury crash course</h3>
+        <a href="https://mercury-in.space/crash.html">
+	An introduction to Mercury through worked examples.
+        </a>
+        </li>
+
+	<li>
+	<h3>Ralph Becket Mercury tutorial</h3>
+	An introduction to Mercury.
+	This is still under development.
+	Feedback would be greatly appreciated.
+	<table class="documentation">
+	<tr><td>
+	<a href="papers/book.pdf"><button class="button">PDF</button></a>
+	</td></tr>
+	</table>
+	</li>
+
+        <li>
+        <h3>Mercury wiki tutorial</h3>
+        <a href="https://github.com/Mercury-Language/mercury/wiki/Tutorial">
+        Another introduction to Mercury.
+        </a>
+        </li>
+</ul>
diff --git a/documentation/learning.php b/documentation/learning.php
index e69de29..38d96c6 100644
--- a/documentation/learning.php
+++ b/documentation/learning.php
@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html lang="en">
+<?php
+    $menu="Documentation";
+    $title="Learning";
+    $dir="documentation";
+    $root="..";
+    $include="learning.inc";
+    include "$root/include/template.inc"
+?>
+</html>
diff --git a/include/menubar.inc b/include/menubar.inc
index 095bd1e..aea9c36 100644
--- a/include/menubar.inc
+++ b/include/menubar.inc
@@ -40,6 +40,9 @@
  	<?php
  	if($menu == "Documentation") { ?>
  	<ul class="submenu">
+        <li><a href="<?php echo $root?>/documentation/learning.html">
+        <div <?php if($include=="learning.inc"){ ?> class="submenucurrent" <?php } ?>>
+        learning</div></a></li>
  	<li><a href="<?php echo $root?>/documentation/papers.html">
  	<div <?php if($include=="papers.inc"){ ?> class="submenucurrent" <?php } ?>>
  	papers</div></a></li>

Julien.