Merge pull request github#3225 from jf205/merge-docs-preparation-master

CodeQL docs: Merge `docs-preparation` into `master`

Author: jf205

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!
 
@@ -101,6 +103,50 @@ Now try applying ``isAllowedIn(string region)`` to a person ``p``. If ``p`` is n
 
 You know that the fire starters live in the south *and* that they must have been able to travel to the north. Write a query to find the possible suspects. You could also extend the ``select`` clause to list the age of the suspects. That way you can clearly see that all the children have been excluded from the list.
 
-➤ `See the answer in the query console <https://lgtm.com/query/2551838470440192723/>`__
+➤ `See the answer in the query console on LGTM.com <https://lgtm.com/query/2551838470440192723/>`__
+
+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 on LGTM.com <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.
+
+Further reading
+---------------
 
-Continue to the :doc:`next page <fire-2>` to gather more clues and find out which of your suspects started the fire...
+-  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 reference <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::
 
@@ -248,15 +251,15 @@ Here are some more example queries that solve the river crossing puzzle:
   #. This query uses a modified ``path`` variable to describe the resulting path in
      more detail.
 
-     ➤ `See solution in the query console <https://lgtm.com/query/659603593702729237/>`__
+     ➤ `See solution in the query console on LGTM.com <https://lgtm.com/query/659603593702729237/>`__
 
   #. This query models the man and the cargo items in a different way, using an 
      `abstract <https://help.semmle.com/QL/ql-handbook/annotations.html#abstract>`__
      class and predicate. It also displays the resulting path in a more visual way.
 
-     ➤ `See solution in the query console <https://lgtm.com/query/1025323464423811143/>`__
+     ➤ `See solution in the query console on LGTM.com <https://lgtm.com/query/1025323464423811143/>`__
 
   #. This query introduces `algebraic datatypes <https://help.semmle.com/QL/ql-handbook/types.html#algebraic-datatypes>`__
      to model the situation, instead of defining everything as a subclass of ``string``.
 
-     ➤ `See solution in the query console <https://lgtm.com/query/7260748307619718263/>`__
+     ➤ `See solution in the query console on LGTM.com <https://lgtm.com/query/7260748307619718263/>`__

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.
@@ -125,7 +127,7 @@ Here is one way to define ``relativeOf()``:
 
 Don't forget to use the predicate ``isDeceased()`` to find relatives that are still alive.
 
-➤ `See the answer in the query console <https://lgtm.com/query/6710025057257064639/>`__
+➤ `See the answer in the query console on LGTM.com <https://lgtm.com/query/6710025057257064639/>`__
 
 Select the true heir
 --------------------
@@ -136,9 +138,9 @@ 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/>`__
+➤ `See the answer in the query console on LGTM.com <https://lgtm.com/query/1820692755164273290/>`__
 
 Experimental explorations
 -------------------------
@@ -156,9 +158,9 @@ You could also try writing more of your own QL queries to find interesting facts
 -  Do all villagers live in the same region of the village as their parents?
 -  Find out whether there are any time travelers in the village! (Hint: Look for "impossible" family relations.)
 
-What next?
-----------
+Further reading
+---------------
 
--  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>`.
+-  Learn more about recursion in the `QL language reference <https://help.semmle.com/QL/ql-handbook/index.html>`__.
+-  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.