Merge pull request github#3043 from shati-patel/2173-tutorials

CodeQL docs migration prep: Update QL tutorials

Author: shati-patel

docs/language/learn-ql/beginner/fire-1.rst renamed to docs/language/learn-ql/beginner/catch-the-fire-starter.rst

@@ -1,5 +1,7 @@
-Catch the fire starter: Classes and predicates
-==============================================
+Catch the fire starter
+======================
+
+Learn about QL predicates and classes to solve your second mystery as a QL detective.
 
 Just as you've successfully found the thief and returned the golden crown to the castle, another terrible crime is committed. Early in the morning, a few people start a fire in a field in the north of the village and destroy all the crops!
 
@@ -103,4 +105,48 @@ You know that the fire starters live in the south *and* that they must have been
 
 ➤ `See the answer in the query console <https://lgtm.com/query/2551838470440192723/>`__
 
-Continue to the :doc:`next page <fire-2>` to gather more clues and find out which of your suspects started the fire...
+You can now continue to gather more clues and find out which of your suspects started the fire...
+
+Identify the bald bandits
+-------------------------
+
+You ask the northerners if they have any more information about the fire starters. Luckily, you have a witness! The farmer living next to the field saw two people run away just after the fire started. He only saw the tops of their heads, and noticed that they were both bald.
+
+This is a very helpful clue. Remember that you wrote a QL query to select all bald people:
+
+.. code-block:: ql
+
+   from Person p
+   where not exists (string c | p.getHairColor() = c)
+   select p
+
+To avoid having to type ``not exists (string c | p.getHairColor() = c)`` every time you want to select a bald person, you can instead define another new predicate ``isBald``.
+
+.. code-block:: ql
+
+   predicate isBald(Person p) {
+     not exists (string c | p.getHairColor() = c)
+   }
+
+The property ``isBald(p)`` holds whenever ``p`` is bald, so you can replace the previous query with:
+
+.. code-block:: ql
+
+   from Person p
+   where isBald(p)
+   select p
+
+The predicate ``isBald`` is defined to take a ``Person``, so it can also take a ``Southerner``, as ``Southerner`` is a subtype of ``Person``. It can't take an ``int`` for example—that would cause an error.
+
+You can now write a query to select the bald southerners who are allowed into the north.
+
+➤ `See the answer in the query console <https://lgtm.com/query/2572701606358725253/>`__
+
+You have found the two fire starters! They are arrested and the villagers are once again impressed with your work.
+
+What next?
+----------
+
+-  Find out who will be the new ruler of the village in the :doc:`next tutorial <crown-the-rightful-heir>`.
+-  Learn more about predicates and classes in the `QL language handbook <https://help.semmle.com/QL/ql-handbook/index.html>`__.
+-  Explore the libraries that help you get data about code in :doc:`Learning CodeQL <../../index>`.

docs/language/learn-ql/ql-etudes/river-crossing.rst renamed to docs/language/learn-ql/beginner/cross-the-river.rst

@@ -1,7 +1,10 @@
-River crossing puzzle
-#####################
+Cross the river
+===============
 
-The aim of this tutorial is to write a query that finds a solution to the following classical logic puzzle:
+Use common QL features to write a query that finds a solution to the "River crossing" logic puzzle.
+
+Introduction
+------------
 
 .. pull-quote::
 

docs/language/learn-ql/beginner/heir.rst renamed to docs/language/learn-ql/beginner/crown-the-rightful-heir.rst

@@ -1,6 +1,11 @@
 Crown the rightful heir
 =======================
 
+This is a QL detective puzzle that shows you how to use recursion in QL to write more complex queries.
+
+King Basil's heir
+-----------------
+
 Phew! No more crimes in the village—you can finally leave the village and go home.
 
 But then... During your last night in the village, the old king—the great King Basil—dies in his sleep and there is chaos everywhere!
@@ -9,9 +14,6 @@ The king never married and he had no children, so nobody knows who should inheri
 
 Eventually you decide to stay in the village to resolve the argument and find the true heir to the throne.
 
-King Basil's heir
------------------
-
 You want to find out if anyone in the village is actually related to the king. This seems like a difficult task at first, but you start work confidently. You know the villagers quite well by now, and you have a list of all the parents in the village and their children.
 
 To find out more about the king and his family, you get access to the castle and find some old family trees. You also include these relations in your database to see if anyone in the king's family is still alive.
@@ -136,7 +138,7 @@ To decide who should inherit the king's fortune, the villagers carefully read th
 
 *"The heir to the throne is the closest living relative of the king. Any person with a criminal record will not be considered. If there are multiple candidates, the oldest person is the heir."*
 
-As your final challenge, define a predicate ``hasCriminalRecord`` so that ``hasCriminalRecord(p)`` holds if ``p`` is any of the criminals you unmasked earlier (in the :doc:`Find the thief <find-thief-1>` and :doc:`Catch the fire starter <fire-1>` tutorials).
+As your final challenge, define a predicate ``hasCriminalRecord`` so that ``hasCriminalRecord(p)`` holds if ``p`` is any of the criminals you unmasked earlier (in the :doc:`Find the thief <find-the-thief>` and :doc:`Catch the fire starter <catch-the-fire-starter>` tutorials).
 
 ➤ `See the answer in the query console <https://lgtm.com/query/1820692755164273290/>`__
 
@@ -160,5 +162,5 @@ What next?
 ----------
 
 -  Learn more about recursion in the `QL language handbook <https://help.semmle.com/QL/ql-handbook/index.html>`__.
--  Put your QL skills to the test and solve the :doc:`River crossing puzzle <../ql-etudes/river-crossing>`.
+-  Put your QL skills to the test and solve the :doc:`River crossing puzzle <cross-the-river>`.
 -  Start using QL to analyze projects. See :doc:`Learning CodeQL <../../index>` for a summary of the available languages and resources.