From 6ed290f2bdaefaf1856193b34a9cdff9cee6afe9 Mon Sep 17 00:00:00 2001
From: james <james@semmle.com>
Date: Thu, 5 Nov 2020 09:43:40 +0000
Subject: [PATCH 1/5] rename rst files

---
 .../{intro-to-data-flow.rst => about-data-flow-analysis.rst}      | 0
 .../learn-ql/cpp/{dataflow.rst => analyzing-data-flow-in-cpp.rst} | 0
 .../cpp/{basic-query-cpp.rst => basic-query-for-cpp-code.rst}     | 0
 docs/language/learn-ql/cpp/{ql-for-cpp.rst => codeql-for-cpp.rst} | 0
 .../{introduce-libraries-cpp.rst => codeql-library-for-cpp.rst}   | 0
 ...conversions-classes.rst => conversions-and-classes-in-cpp.rst} | 0
 ...e-terminator.rst => detecting-a-potential-buffer-overflow.rst} | 0
 ...ions-types.rst => expressions-types-and-statements-in-cpp.rst} | 0
 .../learn-ql/cpp/{function-classes.rst => functions-in-cpp.rst}   | 0
 ...mbering-hash-cons.rst => hash-consing-and-value-numbering.rst} | 0
 ...ization.rst => refining-a-query-to-account-for-edge-cases.rst} | 0
 .../cpp/{range-analysis.rst => using-range-analsis-in-cpp.rst}    | 0
 .../cpp/{guards.rst => using-the-guards-library-in-cpp.rst}       | 0
 .../csharp/{dataflow.rst => analyzing-data-flow-in-csharp.rst}    | 0
 .../{basic-query-csharp.rst => basic-query-for-csharp-code.rst}   | 0
 .../learn-ql/csharp/{ql-for-csharp.rst => codeql-for-csharp.rst}  | 0
 ...troduce-libraries-csharp.rst => codeql-library-for-csharp.rst} | 0
 ...abstract-syntax-tree-classes-for-working-with-go-programs.rst} | 0
 .../go/{basic-query-go.rst => basic-query-for-go-code.rst}        | 0
 docs/language/learn-ql/go/{ql-for-go.rst => codeql-for-go.rst}    | 0
 .../go/{introduce-libraries-go.rst => codeql-library-for-go.rst}  | 0
 ...ary-modeling-go.rst => modeling-data-flow-in-go-libraries.rst} | 0
 ...abstract-syntax-tree-classes-for-working-with-go-programs.rst} | 0
 .../java/{dataflow.rst => analyzing-data-flow-in-java.rst}        | 0
 .../learn-ql/java/{annotations.rst => annotations-in-java.rst}    | 0
 .../java/{basic-query-java.rst => basic-query-for-java-code.rst}  | 0
 .../learn-ql/java/{ql-for-java.rst => codeql-for-java.rst}        | 0
 .../{introduce-libraries-java.rst => codeql-library-for-java.rst} | 0
 .../java/{call-graph.rst => navigating-the-call-graph.rst}        | 0
 ...ions-statements.rst => overflow-prone-comparisons-in-java.rst} | 0
 .../java/{types-class-hierarchy.rst => types-in-java.rst}         | 0
 .../{source-locations.rst => working-with-source-locations.rst}   | 0
 ...abstract-syntax-tree-classes-for-working-with-go-programs.rst} | 0
 .../{dataflow.rst => analyzing-data-flow-in-javascript.rst}       | 0
 ...c-query-javascript.rst => basic-query-for-javascript-code.rst} | 0
 .../{ql-for-javascript.rst => codeql-for-javascript.rst}          | 0
 ...troduce-libraries-js.rst => codeql-library-for-javascript.rst} | 0
 ...troduce-libraries-ts.rst => codeql-library-for-typescript.rst} | 0
 ...w-cheat-sheet.rst => data-flow-cheat-sheet-for-javascript.rst} | 0
 ...s.rst => using-flow-labels-for-precise-data-flow-analysis.rst} | 0
 ...type-tracking.rst => using-type-tracking-for-api-modeling.rst} | 0
 .../{locations.rst => providing-locations-in-codeql-queries.rst}  | 0
 .../{control-flow.rst => analyzing-control-flow-in-python.rst}    | 0
 ...> analyzing-data-flow-and-tracking-tainted-data-in-python.rst} | 0
 .../{basic-query-python.rst => basic-query-for-python-code.rst}   | 0
 .../learn-ql/python/{ql-for-python.rst => codeql-for-python.rst}  | 0
 ...troduce-libraries-python.rst => codeql-library-for-python.rst} | 0
 ...s-expressions.rst => expressions-and-statements-in-python.rst} | 0
 .../learn-ql/python/{functions.rst => functions-in-python.rst}    | 0
 ...nfer.rst => pointer-analysis-and-type-inference-in-python.rst} | 0
 .../{introduction-to-queries.rst => about-codeql-queries.rst}     | 0
 .../writing-queries/{writing-queries.rst => codeql-queries.rst}   | 0
 .../{path-queries.rst => creating-path-queries.rst}               | 0
 .../{select-statement.rst => defining-the-results-of-a-query.rst} | 0
 .../{query-metadata.rst => metadata-for-codeql-queries.rst}       | 0
 .../writing-queries/{query-help.rst => query-help-files.rst}      | 0
 ...ebugging-queries.rst => troubleshooting-query-performance.rst} | 0
 .../{evaluation.rst => evaluations-of-ql-programs.rst}            | 0
 .../ql-handbook/{language.rst => ql-language-specification.rst}   | 0
 .../ql-handbook/{qldoc.rst => qldoc-comment-specification.rst}    | 0
 60 files changed, 0 insertions(+), 0 deletions(-)
 rename docs/language/learn-ql/{intro-to-data-flow.rst => about-data-flow-analysis.rst} (100%)
 rename docs/language/learn-ql/cpp/{dataflow.rst => analyzing-data-flow-in-cpp.rst} (100%)
 rename docs/language/learn-ql/cpp/{basic-query-cpp.rst => basic-query-for-cpp-code.rst} (100%)
 rename docs/language/learn-ql/cpp/{ql-for-cpp.rst => codeql-for-cpp.rst} (100%)
 rename docs/language/learn-ql/cpp/{introduce-libraries-cpp.rst => codeql-library-for-cpp.rst} (100%)
 rename docs/language/learn-ql/cpp/{conversions-classes.rst => conversions-and-classes-in-cpp.rst} (100%)
 rename docs/language/learn-ql/cpp/{zero-space-terminator.rst => detecting-a-potential-buffer-overflow.rst} (100%)
 rename docs/language/learn-ql/cpp/{expressions-types.rst => expressions-types-and-statements-in-cpp.rst} (100%)
 rename docs/language/learn-ql/cpp/{function-classes.rst => functions-in-cpp.rst} (100%)
 rename docs/language/learn-ql/cpp/{value-numbering-hash-cons.rst => hash-consing-and-value-numbering.rst} (100%)
 rename docs/language/learn-ql/cpp/{private-field-initialization.rst => refining-a-query-to-account-for-edge-cases.rst} (100%)
 rename docs/language/learn-ql/cpp/{range-analysis.rst => using-range-analsis-in-cpp.rst} (100%)
 rename docs/language/learn-ql/cpp/{guards.rst => using-the-guards-library-in-cpp.rst} (100%)
 rename docs/language/learn-ql/csharp/{dataflow.rst => analyzing-data-flow-in-csharp.rst} (100%)
 rename docs/language/learn-ql/csharp/{basic-query-csharp.rst => basic-query-for-csharp-code.rst} (100%)
 rename docs/language/learn-ql/csharp/{ql-for-csharp.rst => codeql-for-csharp.rst} (100%)
 rename docs/language/learn-ql/csharp/{introduce-libraries-csharp.rst => codeql-library-for-csharp.rst} (100%)
 rename docs/language/learn-ql/go/{ast-class-reference.rst => abstract-syntax-tree-classes-for-working-with-go-programs.rst} (100%)
 rename docs/language/learn-ql/go/{basic-query-go.rst => basic-query-for-go-code.rst} (100%)
 rename docs/language/learn-ql/go/{ql-for-go.rst => codeql-for-go.rst} (100%)
 rename docs/language/learn-ql/go/{introduce-libraries-go.rst => codeql-library-for-go.rst} (100%)
 rename docs/language/learn-ql/go/{library-modeling-go.rst => modeling-data-flow-in-go-libraries.rst} (100%)
 rename docs/language/learn-ql/java/{ast-class-reference.rst => abstract-syntax-tree-classes-for-working-with-go-programs.rst} (100%)
 rename docs/language/learn-ql/java/{dataflow.rst => analyzing-data-flow-in-java.rst} (100%)
 rename docs/language/learn-ql/java/{annotations.rst => annotations-in-java.rst} (100%)
 rename docs/language/learn-ql/java/{basic-query-java.rst => basic-query-for-java-code.rst} (100%)
 rename docs/language/learn-ql/java/{ql-for-java.rst => codeql-for-java.rst} (100%)
 rename docs/language/learn-ql/java/{introduce-libraries-java.rst => codeql-library-for-java.rst} (100%)
 rename docs/language/learn-ql/java/{call-graph.rst => navigating-the-call-graph.rst} (100%)
 rename docs/language/learn-ql/java/{expressions-statements.rst => overflow-prone-comparisons-in-java.rst} (100%)
 rename docs/language/learn-ql/java/{types-class-hierarchy.rst => types-in-java.rst} (100%)
 rename docs/language/learn-ql/java/{source-locations.rst => working-with-source-locations.rst} (100%)
 rename docs/language/learn-ql/javascript/{ast-class-reference.rst => abstract-syntax-tree-classes-for-working-with-go-programs.rst} (100%)
 rename docs/language/learn-ql/javascript/{dataflow.rst => analyzing-data-flow-in-javascript.rst} (100%)
 rename docs/language/learn-ql/javascript/{basic-query-javascript.rst => basic-query-for-javascript-code.rst} (100%)
 rename docs/language/learn-ql/javascript/{ql-for-javascript.rst => codeql-for-javascript.rst} (100%)
 rename docs/language/learn-ql/javascript/{introduce-libraries-js.rst => codeql-library-for-javascript.rst} (100%)
 rename docs/language/learn-ql/javascript/{introduce-libraries-ts.rst => codeql-library-for-typescript.rst} (100%)
 rename docs/language/learn-ql/javascript/{dataflow-cheat-sheet.rst => data-flow-cheat-sheet-for-javascript.rst} (100%)
 rename docs/language/learn-ql/javascript/{flow-labels.rst => using-flow-labels-for-precise-data-flow-analysis.rst} (100%)
 rename docs/language/learn-ql/javascript/{type-tracking.rst => using-type-tracking-for-api-modeling.rst} (100%)
 rename docs/language/learn-ql/{locations.rst => providing-locations-in-codeql-queries.rst} (100%)
 rename docs/language/learn-ql/python/{control-flow.rst => analyzing-control-flow-in-python.rst} (100%)
 rename docs/language/learn-ql/python/{taint-tracking.rst => analyzing-data-flow-and-tracking-tainted-data-in-python.rst} (100%)
 rename docs/language/learn-ql/python/{basic-query-python.rst => basic-query-for-python-code.rst} (100%)
 rename docs/language/learn-ql/python/{ql-for-python.rst => codeql-for-python.rst} (100%)
 rename docs/language/learn-ql/python/{introduce-libraries-python.rst => codeql-library-for-python.rst} (100%)
 rename docs/language/learn-ql/python/{statements-expressions.rst => expressions-and-statements-in-python.rst} (100%)
 rename docs/language/learn-ql/python/{functions.rst => functions-in-python.rst} (100%)
 rename docs/language/learn-ql/python/{pointsto-type-infer.rst => pointer-analysis-and-type-inference-in-python.rst} (100%)
 rename docs/language/learn-ql/writing-queries/{introduction-to-queries.rst => about-codeql-queries.rst} (100%)
 rename docs/language/learn-ql/writing-queries/{writing-queries.rst => codeql-queries.rst} (100%)
 rename docs/language/learn-ql/writing-queries/{path-queries.rst => creating-path-queries.rst} (100%)
 rename docs/language/learn-ql/writing-queries/{select-statement.rst => defining-the-results-of-a-query.rst} (100%)
 rename docs/language/learn-ql/writing-queries/{query-metadata.rst => metadata-for-codeql-queries.rst} (100%)
 rename docs/language/learn-ql/writing-queries/{query-help.rst => query-help-files.rst} (100%)
 rename docs/language/learn-ql/writing-queries/{debugging-queries.rst => troubleshooting-query-performance.rst} (100%)
 rename docs/language/ql-handbook/{evaluation.rst => evaluations-of-ql-programs.rst} (100%)
 rename docs/language/ql-handbook/{language.rst => ql-language-specification.rst} (100%)
 rename docs/language/ql-handbook/{qldoc.rst => qldoc-comment-specification.rst} (100%)

diff --git a/docs/language/learn-ql/intro-to-data-flow.rst b/docs/language/learn-ql/about-data-flow-analysis.rst
similarity index 100%
rename from docs/language/learn-ql/intro-to-data-flow.rst
rename to docs/language/learn-ql/about-data-flow-analysis.rst
diff --git a/docs/language/learn-ql/cpp/dataflow.rst b/docs/language/learn-ql/cpp/analyzing-data-flow-in-cpp.rst
similarity index 100%
rename from docs/language/learn-ql/cpp/dataflow.rst
rename to docs/language/learn-ql/cpp/analyzing-data-flow-in-cpp.rst
diff --git a/docs/language/learn-ql/cpp/basic-query-cpp.rst b/docs/language/learn-ql/cpp/basic-query-for-cpp-code.rst
similarity index 100%
rename from docs/language/learn-ql/cpp/basic-query-cpp.rst
rename to docs/language/learn-ql/cpp/basic-query-for-cpp-code.rst
diff --git a/docs/language/learn-ql/cpp/ql-for-cpp.rst b/docs/language/learn-ql/cpp/codeql-for-cpp.rst
similarity index 100%
rename from docs/language/learn-ql/cpp/ql-for-cpp.rst
rename to docs/language/learn-ql/cpp/codeql-for-cpp.rst
diff --git a/docs/language/learn-ql/cpp/introduce-libraries-cpp.rst b/docs/language/learn-ql/cpp/codeql-library-for-cpp.rst
similarity index 100%
rename from docs/language/learn-ql/cpp/introduce-libraries-cpp.rst
rename to docs/language/learn-ql/cpp/codeql-library-for-cpp.rst
diff --git a/docs/language/learn-ql/cpp/conversions-classes.rst b/docs/language/learn-ql/cpp/conversions-and-classes-in-cpp.rst
similarity index 100%
rename from docs/language/learn-ql/cpp/conversions-classes.rst
rename to docs/language/learn-ql/cpp/conversions-and-classes-in-cpp.rst
diff --git a/docs/language/learn-ql/cpp/zero-space-terminator.rst b/docs/language/learn-ql/cpp/detecting-a-potential-buffer-overflow.rst
similarity index 100%
rename from docs/language/learn-ql/cpp/zero-space-terminator.rst
rename to docs/language/learn-ql/cpp/detecting-a-potential-buffer-overflow.rst
diff --git a/docs/language/learn-ql/cpp/expressions-types.rst b/docs/language/learn-ql/cpp/expressions-types-and-statements-in-cpp.rst
similarity index 100%
rename from docs/language/learn-ql/cpp/expressions-types.rst
rename to docs/language/learn-ql/cpp/expressions-types-and-statements-in-cpp.rst
diff --git a/docs/language/learn-ql/cpp/function-classes.rst b/docs/language/learn-ql/cpp/functions-in-cpp.rst
similarity index 100%
rename from docs/language/learn-ql/cpp/function-classes.rst
rename to docs/language/learn-ql/cpp/functions-in-cpp.rst
diff --git a/docs/language/learn-ql/cpp/value-numbering-hash-cons.rst b/docs/language/learn-ql/cpp/hash-consing-and-value-numbering.rst
similarity index 100%
rename from docs/language/learn-ql/cpp/value-numbering-hash-cons.rst
rename to docs/language/learn-ql/cpp/hash-consing-and-value-numbering.rst
diff --git a/docs/language/learn-ql/cpp/private-field-initialization.rst b/docs/language/learn-ql/cpp/refining-a-query-to-account-for-edge-cases.rst
similarity index 100%
rename from docs/language/learn-ql/cpp/private-field-initialization.rst
rename to docs/language/learn-ql/cpp/refining-a-query-to-account-for-edge-cases.rst
diff --git a/docs/language/learn-ql/cpp/range-analysis.rst b/docs/language/learn-ql/cpp/using-range-analsis-in-cpp.rst
similarity index 100%
rename from docs/language/learn-ql/cpp/range-analysis.rst
rename to docs/language/learn-ql/cpp/using-range-analsis-in-cpp.rst
diff --git a/docs/language/learn-ql/cpp/guards.rst b/docs/language/learn-ql/cpp/using-the-guards-library-in-cpp.rst
similarity index 100%
rename from docs/language/learn-ql/cpp/guards.rst
rename to docs/language/learn-ql/cpp/using-the-guards-library-in-cpp.rst
diff --git a/docs/language/learn-ql/csharp/dataflow.rst b/docs/language/learn-ql/csharp/analyzing-data-flow-in-csharp.rst
similarity index 100%
rename from docs/language/learn-ql/csharp/dataflow.rst
rename to docs/language/learn-ql/csharp/analyzing-data-flow-in-csharp.rst
diff --git a/docs/language/learn-ql/csharp/basic-query-csharp.rst b/docs/language/learn-ql/csharp/basic-query-for-csharp-code.rst
similarity index 100%
rename from docs/language/learn-ql/csharp/basic-query-csharp.rst
rename to docs/language/learn-ql/csharp/basic-query-for-csharp-code.rst
diff --git a/docs/language/learn-ql/csharp/ql-for-csharp.rst b/docs/language/learn-ql/csharp/codeql-for-csharp.rst
similarity index 100%
rename from docs/language/learn-ql/csharp/ql-for-csharp.rst
rename to docs/language/learn-ql/csharp/codeql-for-csharp.rst
diff --git a/docs/language/learn-ql/csharp/introduce-libraries-csharp.rst b/docs/language/learn-ql/csharp/codeql-library-for-csharp.rst
similarity index 100%
rename from docs/language/learn-ql/csharp/introduce-libraries-csharp.rst
rename to docs/language/learn-ql/csharp/codeql-library-for-csharp.rst
diff --git a/docs/language/learn-ql/go/ast-class-reference.rst b/docs/language/learn-ql/go/abstract-syntax-tree-classes-for-working-with-go-programs.rst
similarity index 100%
rename from docs/language/learn-ql/go/ast-class-reference.rst
rename to docs/language/learn-ql/go/abstract-syntax-tree-classes-for-working-with-go-programs.rst
diff --git a/docs/language/learn-ql/go/basic-query-go.rst b/docs/language/learn-ql/go/basic-query-for-go-code.rst
similarity index 100%
rename from docs/language/learn-ql/go/basic-query-go.rst
rename to docs/language/learn-ql/go/basic-query-for-go-code.rst
diff --git a/docs/language/learn-ql/go/ql-for-go.rst b/docs/language/learn-ql/go/codeql-for-go.rst
similarity index 100%
rename from docs/language/learn-ql/go/ql-for-go.rst
rename to docs/language/learn-ql/go/codeql-for-go.rst
diff --git a/docs/language/learn-ql/go/introduce-libraries-go.rst b/docs/language/learn-ql/go/codeql-library-for-go.rst
similarity index 100%
rename from docs/language/learn-ql/go/introduce-libraries-go.rst
rename to docs/language/learn-ql/go/codeql-library-for-go.rst
diff --git a/docs/language/learn-ql/go/library-modeling-go.rst b/docs/language/learn-ql/go/modeling-data-flow-in-go-libraries.rst
similarity index 100%
rename from docs/language/learn-ql/go/library-modeling-go.rst
rename to docs/language/learn-ql/go/modeling-data-flow-in-go-libraries.rst
diff --git a/docs/language/learn-ql/java/ast-class-reference.rst b/docs/language/learn-ql/java/abstract-syntax-tree-classes-for-working-with-go-programs.rst
similarity index 100%
rename from docs/language/learn-ql/java/ast-class-reference.rst
rename to docs/language/learn-ql/java/abstract-syntax-tree-classes-for-working-with-go-programs.rst
diff --git a/docs/language/learn-ql/java/dataflow.rst b/docs/language/learn-ql/java/analyzing-data-flow-in-java.rst
similarity index 100%
rename from docs/language/learn-ql/java/dataflow.rst
rename to docs/language/learn-ql/java/analyzing-data-flow-in-java.rst
diff --git a/docs/language/learn-ql/java/annotations.rst b/docs/language/learn-ql/java/annotations-in-java.rst
similarity index 100%
rename from docs/language/learn-ql/java/annotations.rst
rename to docs/language/learn-ql/java/annotations-in-java.rst
diff --git a/docs/language/learn-ql/java/basic-query-java.rst b/docs/language/learn-ql/java/basic-query-for-java-code.rst
similarity index 100%
rename from docs/language/learn-ql/java/basic-query-java.rst
rename to docs/language/learn-ql/java/basic-query-for-java-code.rst
diff --git a/docs/language/learn-ql/java/ql-for-java.rst b/docs/language/learn-ql/java/codeql-for-java.rst
similarity index 100%
rename from docs/language/learn-ql/java/ql-for-java.rst
rename to docs/language/learn-ql/java/codeql-for-java.rst
diff --git a/docs/language/learn-ql/java/introduce-libraries-java.rst b/docs/language/learn-ql/java/codeql-library-for-java.rst
similarity index 100%
rename from docs/language/learn-ql/java/introduce-libraries-java.rst
rename to docs/language/learn-ql/java/codeql-library-for-java.rst
diff --git a/docs/language/learn-ql/java/call-graph.rst b/docs/language/learn-ql/java/navigating-the-call-graph.rst
similarity index 100%
rename from docs/language/learn-ql/java/call-graph.rst
rename to docs/language/learn-ql/java/navigating-the-call-graph.rst
diff --git a/docs/language/learn-ql/java/expressions-statements.rst b/docs/language/learn-ql/java/overflow-prone-comparisons-in-java.rst
similarity index 100%
rename from docs/language/learn-ql/java/expressions-statements.rst
rename to docs/language/learn-ql/java/overflow-prone-comparisons-in-java.rst
diff --git a/docs/language/learn-ql/java/types-class-hierarchy.rst b/docs/language/learn-ql/java/types-in-java.rst
similarity index 100%
rename from docs/language/learn-ql/java/types-class-hierarchy.rst
rename to docs/language/learn-ql/java/types-in-java.rst
diff --git a/docs/language/learn-ql/java/source-locations.rst b/docs/language/learn-ql/java/working-with-source-locations.rst
similarity index 100%
rename from docs/language/learn-ql/java/source-locations.rst
rename to docs/language/learn-ql/java/working-with-source-locations.rst
diff --git a/docs/language/learn-ql/javascript/ast-class-reference.rst b/docs/language/learn-ql/javascript/abstract-syntax-tree-classes-for-working-with-go-programs.rst
similarity index 100%
rename from docs/language/learn-ql/javascript/ast-class-reference.rst
rename to docs/language/learn-ql/javascript/abstract-syntax-tree-classes-for-working-with-go-programs.rst
diff --git a/docs/language/learn-ql/javascript/dataflow.rst b/docs/language/learn-ql/javascript/analyzing-data-flow-in-javascript.rst
similarity index 100%
rename from docs/language/learn-ql/javascript/dataflow.rst
rename to docs/language/learn-ql/javascript/analyzing-data-flow-in-javascript.rst
diff --git a/docs/language/learn-ql/javascript/basic-query-javascript.rst b/docs/language/learn-ql/javascript/basic-query-for-javascript-code.rst
similarity index 100%
rename from docs/language/learn-ql/javascript/basic-query-javascript.rst
rename to docs/language/learn-ql/javascript/basic-query-for-javascript-code.rst
diff --git a/docs/language/learn-ql/javascript/ql-for-javascript.rst b/docs/language/learn-ql/javascript/codeql-for-javascript.rst
similarity index 100%
rename from docs/language/learn-ql/javascript/ql-for-javascript.rst
rename to docs/language/learn-ql/javascript/codeql-for-javascript.rst
diff --git a/docs/language/learn-ql/javascript/introduce-libraries-js.rst b/docs/language/learn-ql/javascript/codeql-library-for-javascript.rst
similarity index 100%
rename from docs/language/learn-ql/javascript/introduce-libraries-js.rst
rename to docs/language/learn-ql/javascript/codeql-library-for-javascript.rst
diff --git a/docs/language/learn-ql/javascript/introduce-libraries-ts.rst b/docs/language/learn-ql/javascript/codeql-library-for-typescript.rst
similarity index 100%
rename from docs/language/learn-ql/javascript/introduce-libraries-ts.rst
rename to docs/language/learn-ql/javascript/codeql-library-for-typescript.rst
diff --git a/docs/language/learn-ql/javascript/dataflow-cheat-sheet.rst b/docs/language/learn-ql/javascript/data-flow-cheat-sheet-for-javascript.rst
similarity index 100%
rename from docs/language/learn-ql/javascript/dataflow-cheat-sheet.rst
rename to docs/language/learn-ql/javascript/data-flow-cheat-sheet-for-javascript.rst
diff --git a/docs/language/learn-ql/javascript/flow-labels.rst b/docs/language/learn-ql/javascript/using-flow-labels-for-precise-data-flow-analysis.rst
similarity index 100%
rename from docs/language/learn-ql/javascript/flow-labels.rst
rename to docs/language/learn-ql/javascript/using-flow-labels-for-precise-data-flow-analysis.rst
diff --git a/docs/language/learn-ql/javascript/type-tracking.rst b/docs/language/learn-ql/javascript/using-type-tracking-for-api-modeling.rst
similarity index 100%
rename from docs/language/learn-ql/javascript/type-tracking.rst
rename to docs/language/learn-ql/javascript/using-type-tracking-for-api-modeling.rst
diff --git a/docs/language/learn-ql/locations.rst b/docs/language/learn-ql/providing-locations-in-codeql-queries.rst
similarity index 100%
rename from docs/language/learn-ql/locations.rst
rename to docs/language/learn-ql/providing-locations-in-codeql-queries.rst
diff --git a/docs/language/learn-ql/python/control-flow.rst b/docs/language/learn-ql/python/analyzing-control-flow-in-python.rst
similarity index 100%
rename from docs/language/learn-ql/python/control-flow.rst
rename to docs/language/learn-ql/python/analyzing-control-flow-in-python.rst
diff --git a/docs/language/learn-ql/python/taint-tracking.rst b/docs/language/learn-ql/python/analyzing-data-flow-and-tracking-tainted-data-in-python.rst
similarity index 100%
rename from docs/language/learn-ql/python/taint-tracking.rst
rename to docs/language/learn-ql/python/analyzing-data-flow-and-tracking-tainted-data-in-python.rst
diff --git a/docs/language/learn-ql/python/basic-query-python.rst b/docs/language/learn-ql/python/basic-query-for-python-code.rst
similarity index 100%
rename from docs/language/learn-ql/python/basic-query-python.rst
rename to docs/language/learn-ql/python/basic-query-for-python-code.rst
diff --git a/docs/language/learn-ql/python/ql-for-python.rst b/docs/language/learn-ql/python/codeql-for-python.rst
similarity index 100%
rename from docs/language/learn-ql/python/ql-for-python.rst
rename to docs/language/learn-ql/python/codeql-for-python.rst
diff --git a/docs/language/learn-ql/python/introduce-libraries-python.rst b/docs/language/learn-ql/python/codeql-library-for-python.rst
similarity index 100%
rename from docs/language/learn-ql/python/introduce-libraries-python.rst
rename to docs/language/learn-ql/python/codeql-library-for-python.rst
diff --git a/docs/language/learn-ql/python/statements-expressions.rst b/docs/language/learn-ql/python/expressions-and-statements-in-python.rst
similarity index 100%
rename from docs/language/learn-ql/python/statements-expressions.rst
rename to docs/language/learn-ql/python/expressions-and-statements-in-python.rst
diff --git a/docs/language/learn-ql/python/functions.rst b/docs/language/learn-ql/python/functions-in-python.rst
similarity index 100%
rename from docs/language/learn-ql/python/functions.rst
rename to docs/language/learn-ql/python/functions-in-python.rst
diff --git a/docs/language/learn-ql/python/pointsto-type-infer.rst b/docs/language/learn-ql/python/pointer-analysis-and-type-inference-in-python.rst
similarity index 100%
rename from docs/language/learn-ql/python/pointsto-type-infer.rst
rename to docs/language/learn-ql/python/pointer-analysis-and-type-inference-in-python.rst
diff --git a/docs/language/learn-ql/writing-queries/introduction-to-queries.rst b/docs/language/learn-ql/writing-queries/about-codeql-queries.rst
similarity index 100%
rename from docs/language/learn-ql/writing-queries/introduction-to-queries.rst
rename to docs/language/learn-ql/writing-queries/about-codeql-queries.rst
diff --git a/docs/language/learn-ql/writing-queries/writing-queries.rst b/docs/language/learn-ql/writing-queries/codeql-queries.rst
similarity index 100%
rename from docs/language/learn-ql/writing-queries/writing-queries.rst
rename to docs/language/learn-ql/writing-queries/codeql-queries.rst
diff --git a/docs/language/learn-ql/writing-queries/path-queries.rst b/docs/language/learn-ql/writing-queries/creating-path-queries.rst
similarity index 100%
rename from docs/language/learn-ql/writing-queries/path-queries.rst
rename to docs/language/learn-ql/writing-queries/creating-path-queries.rst
diff --git a/docs/language/learn-ql/writing-queries/select-statement.rst b/docs/language/learn-ql/writing-queries/defining-the-results-of-a-query.rst
similarity index 100%
rename from docs/language/learn-ql/writing-queries/select-statement.rst
rename to docs/language/learn-ql/writing-queries/defining-the-results-of-a-query.rst
diff --git a/docs/language/learn-ql/writing-queries/query-metadata.rst b/docs/language/learn-ql/writing-queries/metadata-for-codeql-queries.rst
similarity index 100%
rename from docs/language/learn-ql/writing-queries/query-metadata.rst
rename to docs/language/learn-ql/writing-queries/metadata-for-codeql-queries.rst
diff --git a/docs/language/learn-ql/writing-queries/query-help.rst b/docs/language/learn-ql/writing-queries/query-help-files.rst
similarity index 100%
rename from docs/language/learn-ql/writing-queries/query-help.rst
rename to docs/language/learn-ql/writing-queries/query-help-files.rst
diff --git a/docs/language/learn-ql/writing-queries/debugging-queries.rst b/docs/language/learn-ql/writing-queries/troubleshooting-query-performance.rst
similarity index 100%
rename from docs/language/learn-ql/writing-queries/debugging-queries.rst
rename to docs/language/learn-ql/writing-queries/troubleshooting-query-performance.rst
diff --git a/docs/language/ql-handbook/evaluation.rst b/docs/language/ql-handbook/evaluations-of-ql-programs.rst
similarity index 100%
rename from docs/language/ql-handbook/evaluation.rst
rename to docs/language/ql-handbook/evaluations-of-ql-programs.rst
diff --git a/docs/language/ql-handbook/language.rst b/docs/language/ql-handbook/ql-language-specification.rst
similarity index 100%
rename from docs/language/ql-handbook/language.rst
rename to docs/language/ql-handbook/ql-language-specification.rst
diff --git a/docs/language/ql-handbook/qldoc.rst b/docs/language/ql-handbook/qldoc-comment-specification.rst
similarity index 100%
rename from docs/language/ql-handbook/qldoc.rst
rename to docs/language/ql-handbook/qldoc-comment-specification.rst

From 21cdf896bb1be41b41a8b4b68bed4c923b3d4bdb Mon Sep 17 00:00:00 2001
From: james <james@semmle.com>
Date: Thu, 5 Nov 2020 14:36:35 +0000
Subject: [PATCH 2/5] first pass through files and links

---
 .../learn-ql/about-data-flow-analysis.rst     | 14 ++---
 .../learn-ql/beginner/find-the-thief.rst      |  2 +-
 .../cpp/analyzing-data-flow-in-cpp.rst        |  4 +-
 docs/language/learn-ql/cpp/codeql-for-cpp.rst | 44 +++++++-------
 .../learn-ql/cpp/functions-in-cpp.rst         |  4 +-
 ...ning-a-query-to-account-for-edge-cases.rst |  2 +-
 .../csharp/analyzing-data-flow-in-csharp.rst  |  4 +-
 .../learn-ql/csharp/codeql-for-csharp.rst     | 12 ++--
 .../csharp/codeql-library-for-csharp.rst      |  2 +-
 docs/language/learn-ql/go/codeql-for-go.rst   | 16 ++---
 .../learn-ql/go/codeql-library-for-go.rst     |  4 +-
 docs/language/learn-ql/index.rst              | 14 ++---
 docs/language/learn-ql/introduction-to-ql.rst |  6 +-
 .../java/analyzing-data-flow-in-java.rst      |  4 +-
 .../learn-ql/java/annotations-in-java.rst     |  2 +-
 .../learn-ql/java/codeql-for-java.rst         | 36 ++++++------
 .../learn-ql/java/codeql-library-for-java.rst | 12 ++--
 .../overflow-prone-comparisons-in-java.rst    |  2 +-
 ...th-javascript-and-typescript-programs.rst} |  0
 .../analyzing-data-flow-in-javascript.rst     |  4 +-
 .../javascript/codeql-for-javascript.rst      | 32 +++++-----
 .../codeql-library-for-typescript.rst         |  2 +-
 .../data-flow-cheat-sheet-for-javascript.rst  | 10 ++--
 ...-labels-for-precise-data-flow-analysis.rst |  6 +-
 .../using-type-tracking-for-api-modeling.rst  |  8 +--
 .../analyzing-control-flow-in-python.rst      |  2 +-
 ...ow-and-tracking-tainted-data-in-python.rst |  6 +-
 .../learn-ql/python/codeql-for-python.rst     | 28 ++++-----
 .../python/codeql-library-for-python.rst      |  4 +-
 .../expressions-and-statements-in-python.rst  |  2 +-
 .../learn-ql/python/functions-in-python.rst   |  4 +-
 ...-analysis-and-type-inference-in-python.rst |  2 +-
 docs/language/learn-ql/ql-training.rst        |  2 +-
 .../writing-queries/about-codeql-queries.rst  | 20 +++----
 .../writing-queries/codeql-queries.rst        | 32 +++++-----
 .../writing-queries/creating-path-queries.rst | 28 ++++-----
 .../defining-the-results-of-a-query.rst       |  6 +-
 .../metadata-for-codeql-queries.rst           | 58 +++++++++----------
 .../troubleshooting-query-performance.rst     |  2 +-
 .../ql-handbook/about-the-ql-language.rst     |  2 +-
 docs/language/ql-handbook/annotations.rst     |  2 +-
 ...rams.rst => evaluation-of-ql-programs.rst} |  2 +-
 docs/language/ql-handbook/index.rst           |  6 +-
 docs/language/ql-handbook/lexical-syntax.rst  |  2 +-
 44 files changed, 228 insertions(+), 228 deletions(-)
 rename docs/language/learn-ql/javascript/{abstract-syntax-tree-classes-for-working-with-go-programs.rst => abstract-syntax-tree-classes-for-working-with-javascript-and-typescript-programs.rst} (100%)
 rename docs/language/ql-handbook/{evaluations-of-ql-programs.rst => evaluation-of-ql-programs.rst} (98%)

diff --git a/docs/language/learn-ql/about-data-flow-analysis.rst b/docs/language/learn-ql/about-data-flow-analysis.rst
index bba1ca60807..edb4689fec1 100644
--- a/docs/language/learn-ql/about-data-flow-analysis.rst
+++ b/docs/language/learn-ql/about-data-flow-analysis.rst
@@ -14,17 +14,17 @@ The following sections provide a brief introduction to data flow analysis with C
 
 See the following tutorials for more information about analyzing data flow in specific languages:
 
-- ":doc:`Analyzing data flow in C/C++ <cpp/dataflow>`"
-- ":doc:`Analyzing data flow in C# <csharp/dataflow>`"
-- ":doc:`Analyzing data flow in Java <java/dataflow>`"
-- ":doc:`Analyzing data flow in JavaScript/TypeScript <javascript/dataflow>`"
-- ":doc:`Analyzing data flow and tracking tainted data in Python <python/taint-tracking>`"
+- ":doc:`Analyzing data flow in C/C++ <cpp/analyzing-data-flow-in-cpp>`"
+- ":doc:`Analyzing data flow in C# <csharp/analyzing-data-flow-in-csharp>`"
+- ":doc:`Analyzing data flow in Java <java/analyzing-data-flow-in-java>`"
+- ":doc:`Analyzing data flow in JavaScript/TypeScript <javascript/analyzing-data-flow-in-javascript>`"
+- ":doc:`Analyzing data flow and tracking tainted data in Python <python/analyzing-data-flow-and-tracking-tainted-data-in-python>`"
 
 .. pull-quote::
 
     Note
 
-    Data flow analysis is used extensively in path queries. To learn more about path queries, see ":doc:`Creating path queries <writing-queries/path-queries>`."  
+    Data flow analysis is used extensively in path queries. To learn more about path queries, see ":doc:`Creating path queries <writing-queries/creating-path-queries>`."  
 
 .. _data-flow-graph:
 
@@ -82,5 +82,5 @@ These flow steps are modeled in the taint-tracking library using predicates that
 Further reading
 ***************
 
-- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-paths.html>`__"
+- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-data-flow-with-path-queries.html>`__"
 
diff --git a/docs/language/learn-ql/beginner/find-the-thief.rst b/docs/language/learn-ql/beginner/find-the-thief.rst
index 6111590d603..2109e5d17d4 100644
--- a/docs/language/learn-ql/beginner/find-the-thief.rst
+++ b/docs/language/learn-ql/beginner/find-the-thief.rst
@@ -48,7 +48,7 @@ There is too much information to search through by hand, so you decide to use yo
 
 #. Open the `query console on LGTM.com <https://lgtm.com/query>`__ to get started.
 #. Select a language and a demo project. For this tutorial, any language and project will do.
-#. Delete the default code ``import <language> select "hello world"``.
+#. Delete the default code ``import <ql-language-specification> select "hello world"``.
 
 QL libraries
 ------------
diff --git a/docs/language/learn-ql/cpp/analyzing-data-flow-in-cpp.rst b/docs/language/learn-ql/cpp/analyzing-data-flow-in-cpp.rst
index bcf096aa857..8334b5b6767 100644
--- a/docs/language/learn-ql/cpp/analyzing-data-flow-in-cpp.rst
+++ b/docs/language/learn-ql/cpp/analyzing-data-flow-in-cpp.rst
@@ -6,7 +6,7 @@ You can use data flow analysis to track the flow of potentially malicious or ins
 About data flow
 ---------------
 
-Data flow analysis computes the possible values that a variable can hold at various points in a program, determining how those values propagate through the program, and where they are used. In CodeQL, you can model both local data flow and global data flow. For a more general introduction to modeling data flow, see ":doc:`About data flow analysis <../intro-to-data-flow>`."
+Data flow analysis computes the possible values that a variable can hold at various points in a program, determining how those values propagate through the program, and where they are used. In CodeQL, you can model both local data flow and global data flow. For a more general introduction to modeling data flow, see ":doc:`About data flow analysis <../about-data-flow-analysis>`."
 
 Local data flow
 ---------------
@@ -390,7 +390,7 @@ Exercise 4
 Further reading
 ---------------
 
-- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-paths.html>`__"
+- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-data-flow-with-path-queries.html>`__"
 
 
 .. include:: ../../reusables/cpp-further-reading.rst
diff --git a/docs/language/learn-ql/cpp/codeql-for-cpp.rst b/docs/language/learn-ql/cpp/codeql-for-cpp.rst
index 19b9ab1e490..021ed5270e6 100644
--- a/docs/language/learn-ql/cpp/codeql-for-cpp.rst
+++ b/docs/language/learn-ql/cpp/codeql-for-cpp.rst
@@ -6,37 +6,37 @@ Experiment and learn how to write effective and efficient queries for CodeQL dat
 .. toctree::
    :hidden:
 
-   basic-query-cpp
-   introduce-libraries-cpp
-   function-classes
-   expressions-types
-   conversions-classes
-   dataflow
-   private-field-initialization
-   zero-space-terminator
-   guards
-   range-analysis
-   value-numbering-hash-cons
+   basic-query-for-cpp-code
+   codeql-library-for-cpp
+   functions-in-cpp
+   expressions-types-and-statements-in-cpp
+   conversions-and-classes-in-cpp
+   analyzing-data-flow-in-cpp
+   refining-a-query-to-account-for-edge-cases
+   detecting-a-potential-buffer-overflow
+   using-the-guards-library-in-cpp
+   using-range-analsis-in-cpp
+   hash-consing-and-value-numbering
 
 
--  :doc:`Basic query for C and C++ code <basic-query-cpp>`: Learn to write and run a simple CodeQL query using LGTM.
+-  :doc:`Basic query for C and C++ code <basic-query-for-cpp-code>`: Learn to write and run a simple CodeQL query using LGTM.
 
--  :doc:`CodeQL library for C and C++ <introduce-libraries-cpp>`: When analyzing C or C++ code, you can use the large collection of classes in the CodeQL library for C and C++.
+-  :doc:`CodeQL library for C and C++ <codeql-library-for-cpp>`: When analyzing C or C++ code, you can use the large collection of classes in the CodeQL library for C and C++.
 
--  :doc:`Functions in C and C++ <function-classes>`: You can use CodeQL to explore functions in C and C++ code.
+-  :doc:`Functions in C and C++ <functions-in-cpp>`: You can use CodeQL to explore functions in C and C++ code.
 
--  :doc:`Expressions, types, and statements in C and C++ <expressions-types>`: You can use CodeQL to explore expressions, types, and statements in C and C++ code to find, for example, incorrect assignments.
+-  :doc:`Expressions, types, and statements in C and C++ <expressions-types-and-statements-in-cpp>`: You can use CodeQL to explore expressions, types, and statements in C and C++ code to find, for example, incorrect assignments.
 
--  :doc:`Conversions and classes in C and C++ <conversions-classes>`: You can use the standard CodeQL libraries for C and C++ to detect when the type of an expression is changed.
+-  :doc:`Conversions and classes in C and C++ <conversions-and-classes-in-cpp>`: You can use the standard CodeQL libraries for C and C++ to detect when the type of an expression is changed.
 
--  :doc:`Analyzing data flow in C and C++ <dataflow>`: You can use data flow analysis to track the flow of potentially malicious or insecure data that can cause vulnerabilities in your codebase.
+-  :doc:`Analyzing data flow in C and C++ <analyzing-data-flow-in-cpp>`: You can use data flow analysis to track the flow of potentially malicious or insecure data that can cause vulnerabilities in your codebase.
 
--  :doc:`Refining a query to account for edge cases <private-field-initialization>`: You can improve the results generated by a CodeQL query by adding conditions to remove false positive results caused by common edge cases.
+-  :doc:`Refining a query to account for edge cases <refining-a-query-to-account-for-edge-cases>`: You can improve the results generated by a CodeQL query by adding conditions to remove false positive results caused by common edge cases.
 
--  :doc:`Detecting a potential buffer overflow <zero-space-terminator>`: You can use CodeQL to detect potential buffer overflows by checking for allocations equal to ``strlen`` in C and C++.
+-  :doc:`Detecting a potential buffer overflow <detecting-a-potential-buffer-overflow>`: You can use CodeQL to detect potential buffer overflows by checking for allocations equal to ``strlen`` in C and C++.
 
--  :doc:`Using the guards library in C and C++ <guards>`: You can use the CodeQL guards library to identify conditional expressions that control the execution of other parts of a program in C and C++ codebases. 
+-  :doc:`Using the guards library in C and C++ <using-the-guards-library-in-cpp>`: You can use the CodeQL guards library to identify conditional expressions that control the execution of other parts of a program in C and C++ codebases. 
 
--  :doc:`Using range analysis for C and C++ <range-analysis>`: You can use range analysis to determine the upper or lower bounds on an expression, or whether an expression could potentially over or underflow.
+-  :doc:`Using range analysis for C and C++ <using-range-analsis-in-cpp>`: You can use range analysis to determine the upper or lower bounds on an expression, or whether an expression could potentially over or underflow.
 
--  :doc:`Hash consing and value numbering <value-numbering-hash-cons>`: You can use specialized CodeQL libraries to recognize expressions that are syntactically identical or compute the same value at runtime in C and C++ codebases.
+-  :doc:`Hash consing and value numbering <hash-consing-and-value-numbering>`: You can use specialized CodeQL libraries to recognize expressions that are syntactically identical or compute the same value at runtime in C and C++ codebases.
diff --git a/docs/language/learn-ql/cpp/functions-in-cpp.rst b/docs/language/learn-ql/cpp/functions-in-cpp.rst
index 38f53f2354b..66b9fc50d7c 100644
--- a/docs/language/learn-ql/cpp/functions-in-cpp.rst
+++ b/docs/language/learn-ql/cpp/functions-in-cpp.rst
@@ -6,7 +6,7 @@ You can use CodeQL to explore functions in C and C++ code.
 Overview
 --------
 
-The standard CodeQL library for C and C++ represents functions using the ``Function`` class (see :doc:`CodeQL libraries for C and C++ <introduce-libraries-cpp>`).
+The standard CodeQL library for C and C++ represents functions using the ``Function`` class (see :doc:`CodeQL libraries for C and C++ <codeql-library-for-cpp>`).
 
 The example queries in this topic explore some of the most useful library predicates for querying functions.
 
@@ -28,7 +28,7 @@ This query is very general, so there are probably too many results to be interes
 Finding functions that are not called
 -------------------------------------
 
-It might be more interesting to find functions that are not called, using the standard CodeQL ``FunctionCall`` class from the **abstract syntax tree** category (see :doc:`CodeQL libraries for C and C++ <introduce-libraries-cpp>`). The ``FunctionCall`` class can be used to identify places where a function is actually used, and it is related to ``Function`` through the ``FunctionCall.getTarget()`` predicate.
+It might be more interesting to find functions that are not called, using the standard CodeQL ``FunctionCall`` class from the **abstract syntax tree** category (see :doc:`CodeQL libraries for C and C++ <codeql-library-for-cpp>`). The ``FunctionCall`` class can be used to identify places where a function is actually used, and it is related to ``Function`` through the ``FunctionCall.getTarget()`` predicate.
 
 .. code-block:: ql
 
diff --git a/docs/language/learn-ql/cpp/refining-a-query-to-account-for-edge-cases.rst b/docs/language/learn-ql/cpp/refining-a-query-to-account-for-edge-cases.rst
index 5f26cebd4eb..28651a32f68 100644
--- a/docs/language/learn-ql/cpp/refining-a-query-to-account-for-edge-cases.rst
+++ b/docs/language/learn-ql/cpp/refining-a-query-to-account-for-edge-cases.rst
@@ -6,7 +6,7 @@ You can improve the results generated by a CodeQL query by adding conditions to
 Overview
 --------
 
-This topic describes how a C++ query was developed. The example introduces recursive predicates and demonstrates the typical workflow used to refine a query. For a full overview of the topics available for learning to write queries for C/C++ code, see ":doc:`CodeQL for C and C++ <ql-for-cpp>`."
+This topic describes how a C++ query was developed. The example introduces recursive predicates and demonstrates the typical workflow used to refine a query. For a full overview of the topics available for learning to write queries for C/C++ code, see ":doc:`CodeQL for C and C++ <codeql-for-cpp>`."
 
 Finding every private field and checking for initialization
 -----------------------------------------------------------
diff --git a/docs/language/learn-ql/csharp/analyzing-data-flow-in-csharp.rst b/docs/language/learn-ql/csharp/analyzing-data-flow-in-csharp.rst
index ac1772ba96a..836e3e99346 100644
--- a/docs/language/learn-ql/csharp/analyzing-data-flow-in-csharp.rst
+++ b/docs/language/learn-ql/csharp/analyzing-data-flow-in-csharp.rst
@@ -8,7 +8,7 @@ About this article
 
 This article describes how data flow analysis is implemented in the CodeQL libraries for C# and includes examples to help you write your own data flow queries.
 The following sections describe how to use the libraries for local data flow, global data flow, and taint tracking.
-For a more general introduction to modeling data flow, see ":doc:`About data flow analysis <../intro-to-data-flow>`."
+For a more general introduction to modeling data flow, see ":doc:`About data flow analysis <../about-data-flow-analysis>`."
 
 Local data flow
 ---------------
@@ -553,7 +553,7 @@ This can be adapted from the ``SystemUriFlow`` class:
 Further reading
 ---------------
 
-- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-paths.html>`__"
+- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-data-flow-with-path-queries.html>`__"
 
 
 .. include:: ../../reusables/csharp-further-reading.rst
diff --git a/docs/language/learn-ql/csharp/codeql-for-csharp.rst b/docs/language/learn-ql/csharp/codeql-for-csharp.rst
index 87153eabb5d..5a780862da2 100644
--- a/docs/language/learn-ql/csharp/codeql-for-csharp.rst
+++ b/docs/language/learn-ql/csharp/codeql-for-csharp.rst
@@ -6,14 +6,14 @@ Experiment and learn how to write effective and efficient queries for CodeQL dat
 .. toctree::
    :hidden:
 
-   basic-query-csharp
-   introduce-libraries-csharp
-   dataflow
+   basic-query-for-csharp-code
+   codeql-library-for-csharp
+   analyzing-data-flow-in-csharp
 
--  :doc:`Basic query for C# code <basic-query-csharp>`: Learn to write and run a simple CodeQL query using LGTM.
+-  :doc:`Basic query for C# code <basic-query-for-csharp-code>`: Learn to write and run a simple CodeQL query using LGTM.
 
--  :doc:`CodeQL library for C# <introduce-libraries-csharp>`: When you're analyzing a C# program, you can make use of the large collection of classes in the CodeQL library for C#.
+-  :doc:`CodeQL library for C# <codeql-library-for-csharp>`: When you're analyzing a C# program, you can make use of the large collection of classes in the CodeQL library for C#.
 
--  :doc:`Analyzing data flow in C# <dataflow>`: You can use CodeQL to track the flow of data through a C# program to its use.
+-  :doc:`Analyzing data flow in C# <analyzing-data-flow-in-csharp>`: You can use CodeQL to track the flow of data through a C# program to its use.
 
 
diff --git a/docs/language/learn-ql/csharp/codeql-library-for-csharp.rst b/docs/language/learn-ql/csharp/codeql-library-for-csharp.rst
index 85e0c6a0e3e..b8c50a0aa8d 100644
--- a/docs/language/learn-ql/csharp/codeql-library-for-csharp.rst
+++ b/docs/language/learn-ql/csharp/codeql-library-for-csharp.rst
@@ -14,7 +14,7 @@ There is an extensive core library for analyzing CodeQL databases extracted from
 
 Since this is required for all C# queries, it's omitted from code snippets below.
 
-The core library contains all the program elements, including `files <#files>`__, `types <#types>`__, methods, `variables <#variables>`__, `statements <#statements>`__, and `expressions <#expressions>`__. This is sufficient for most queries, however additional libraries can be imported for bespoke functionality such as control flow and data flow. For information about these additional libraries, see ":doc:`CodeQL for C# <ql-for-csharp>`." 
+The core library contains all the program elements, including `files <#files>`__, `types <#types>`__, methods, `variables <#variables>`__, `statements <#statements>`__, and `expressions <#expressions>`__. This is sufficient for most queries, however additional libraries can be imported for bespoke functionality such as control flow and data flow. For information about these additional libraries, see ":doc:`CodeQL for C# <codeql-for-csharp>`." 
 
 Class hierarchies
 ~~~~~~~~~~~~~~~~~
diff --git a/docs/language/learn-ql/go/codeql-for-go.rst b/docs/language/learn-ql/go/codeql-for-go.rst
index 3b7ae27bce1..1a0a42c142b 100644
--- a/docs/language/learn-ql/go/codeql-for-go.rst
+++ b/docs/language/learn-ql/go/codeql-for-go.rst
@@ -6,16 +6,16 @@ Experiment and learn how to write effective and efficient queries for CodeQL dat
 .. toctree::
    :hidden:
 
-   basic-query-go
-   introduce-libraries-go
-   ast-class-reference
-   library-modeling-go
+   basic-query-for-go-code
+   codeql-library-for-go
+   abstract-syntax-tree-classes-for-working-with-go-programs
+   modeling-data-flow-in-go-libraries
 
--  :doc:`Basic query for Go code <basic-query-go>`: Learn to write and run a simple CodeQL query using LGTM.
+-  :doc:`Basic query for Go code <basic-query-for-go-code>`: Learn to write and run a simple CodeQL query using LGTM.
 
--  :doc:`CodeQL library for Go <introduce-libraries-go>`: When you're analyzing a Go program, you can make use of the large collection of classes in the CodeQL library for Go.
+-  :doc:`CodeQL library for Go <codeql-library-for-go>`: When you're analyzing a Go program, you can make use of the large collection of classes in the CodeQL library for Go.
 
--  :doc:`Abstract syntax tree classes for working with Go programs <ast-class-reference>`: CodeQL has a large selection of classes for representing the abstract syntax tree of Go programs.
+-  :doc:`Abstract syntax tree classes for working with Go programs <abstract-syntax-tree-classes-for-working-with-go-programs>`: CodeQL has a large selection of classes for representing the abstract syntax tree of Go programs.
 
--  :doc:`Modeling data flow in Go libraries <library-modeling-go>`: When analyzing a Go program, CodeQL does not examine the source code for external packages. 
+-  :doc:`Modeling data flow in Go libraries <modeling-data-flow-in-go-libraries>`: When analyzing a Go program, CodeQL does not examine the source code for external packages. 
    To track the flow of untrusted data through a library, you can create a model of the library.
diff --git a/docs/language/learn-ql/go/codeql-library-for-go.rst b/docs/language/learn-ql/go/codeql-library-for-go.rst
index 0264ca5973c..343def3bd30 100644
--- a/docs/language/learn-ql/go/codeql-library-for-go.rst
+++ b/docs/language/learn-ql/go/codeql-library-for-go.rst
@@ -100,7 +100,7 @@ statements and expressions, respectively. This section briefly discusses some of
 important subclasses and predicates. For a full reference of all the subclasses of `Stmt
 <https://help.semmle.com/qldoc/go/semmle/go/Stmt.qll/type.Stmt$Stmt.html>`__ and `Expr
 <https://help.semmle.com/qldoc/go/semmle/go/Expr.qll/type.Expr$Expr.html>`__, see
-:doc:`Abstract syntax tree classes for Go <ast-class-reference>`.
+:doc:`Abstract syntax tree classes for Go <abstract-syntax-tree-classes-for-working-with-go-programs>`.
 
 Statements
 ~~~~~~~~~~
@@ -502,7 +502,7 @@ taint, you can define a subclass of ``TaintTracking::Configuration``, which work
 data-flow configurations.
 
 A detailed exposition of global data flow and taint tracking is out of scope for this brief
-introduction. For a general overview of data flow and taint tracking, see "`About data flow analysis <https://help.semmle.com/QL/learn-ql/intro-to-data-flow.html>`__."
+introduction. For a general overview of data flow and taint tracking, see "`About data flow analysis <https://help.semmle.com/QL/learn-ql/about-data-flow-analysis.html>`__."
 
 Advanced libraries
 ------------------
diff --git a/docs/language/learn-ql/index.rst b/docs/language/learn-ql/index.rst
index 9f10b0d9c57..0284075f3c1 100644
--- a/docs/language/learn-ql/index.rst
+++ b/docs/language/learn-ql/index.rst
@@ -19,13 +19,13 @@ CodeQL is based on a powerful query language called QL. The following topics hel
    :maxdepth: 1
 
    beginner/ql-tutorials
-   writing-queries/writing-queries
-   cpp/ql-for-cpp
-   csharp/ql-for-csharp
-   go/ql-for-go
-   java/ql-for-java
-   javascript/ql-for-javascript
-   python/ql-for-python
+   writing-queries/codeql-queries
+   cpp/codeql-for-cpp
+   csharp/codeql-for-csharp
+   go/codeql-for-go
+   java/codeql-for-java
+   javascript/codeql-for-javascript
+   python/codeql-for-python
    ql-training
 
 .. toctree::
diff --git a/docs/language/learn-ql/introduction-to-ql.rst b/docs/language/learn-ql/introduction-to-ql.rst
index a208d4f38be..9305f3e404f 100644
--- a/docs/language/learn-ql/introduction-to-ql.rst
+++ b/docs/language/learn-ql/introduction-to-ql.rst
@@ -15,13 +15,13 @@ QL also supports recursion and aggregates. This allows you to write complex recu
 Running a query
 ---------------
 
-You can try out the following examples and exercises using `CodeQL for VS Code <https://help.semmle.com/codeql/codeql-for-vscode.html>`__, or you can run them in the `query console on LGTM.com <https://lgtm.com/query>`__. Before you can run a query on LGTM.com, you need to select a language and project to query (for these logic examples, any language and project will do).
+You can try out the following examples and exercises using `CodeQL for VS Code <https://help.semmle.com/codeql/codeql-for-visual-studio-code.html>`__, or you can run them in the `query console on LGTM.com <https://lgtm.com/query>`__. Before you can run a query on LGTM.com, you need to select a language and project to query (for these logic examples, any language and project will do).
 
 Once you have selected a language, the query console is populated with the query:
 
 .. code-block:: ql
 
-   import <language>
+   import <ql-language-specification>
 
    select "hello world"
 
@@ -122,7 +122,7 @@ The following example queries *do* use these databases and give you an idea of h
 Queries using the CodeQL libraries can find errors and uncover variants of important security vulnerabilities in codebases.
 Visit `GitHub Security Lab <https://securitylab.github.com/>`__ to read about examples of vulnerabilities that we have recently found in open source projects.
 
-To import the CodeQL library for a specific programming language, type ``import <language>`` at the start of the query.
+To import the CodeQL library for a specific programming language, type ``import <ql-language-specification>`` at the start of the query.
 
 .. code-block:: ql
 
diff --git a/docs/language/learn-ql/java/analyzing-data-flow-in-java.rst b/docs/language/learn-ql/java/analyzing-data-flow-in-java.rst
index 03c73fb3c73..446c904d630 100644
--- a/docs/language/learn-ql/java/analyzing-data-flow-in-java.rst
+++ b/docs/language/learn-ql/java/analyzing-data-flow-in-java.rst
@@ -9,7 +9,7 @@ About this article
 This article describes how data flow analysis is implemented in the CodeQL libraries for Java and includes examples to help you write your own data flow queries.
 The following sections describe how to use the libraries for local data flow, global data flow, and taint tracking.
 
-For a more general introduction to modeling data flow, see ":doc:`About data flow analysis <../intro-to-data-flow>`."
+For a more general introduction to modeling data flow, see ":doc:`About data flow analysis <../about-data-flow-analysis>`."
 
 Local data flow
 ---------------
@@ -358,7 +358,7 @@ Exercise 4
 Further reading
 ---------------
 
-- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-paths.html>`__"
+- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-data-flow-with-path-queries.html>`__"
 
 
 .. include:: ../../reusables/java-further-reading.rst
diff --git a/docs/language/learn-ql/java/annotations-in-java.rst b/docs/language/learn-ql/java/annotations-in-java.rst
index 0be55d920fd..e64bdce81dc 100644
--- a/docs/language/learn-ql/java/annotations-in-java.rst
+++ b/docs/language/learn-ql/java/annotations-in-java.rst
@@ -180,7 +180,7 @@ Finally, we use these classes to find calls to deprecated methods, excluding cal
 
 In our example, this query flags the call to ``A.m`` in ``A.r``, but not the one in ``A.n``.
 
-For more information about the class ``Call``, see ":doc:`Navigating the call graph <call-graph>`."
+For more information about the class ``Call``, see ":doc:`Navigating the call graph <navigating-the-call-graph>`."
 
 Improvements
 ~~~~~~~~~~~~
diff --git a/docs/language/learn-ql/java/codeql-for-java.rst b/docs/language/learn-ql/java/codeql-for-java.rst
index 30d1ec9c1c9..d94433b729e 100644
--- a/docs/language/learn-ql/java/codeql-for-java.rst
+++ b/docs/language/learn-ql/java/codeql-for-java.rst
@@ -6,34 +6,34 @@ Experiment and learn how to write effective and efficient queries for CodeQL dat
 .. toctree::
    :hidden:
 
-   basic-query-java
-   introduce-libraries-java
-   dataflow
-   types-class-hierarchy
-   expressions-statements
-   call-graph
-   annotations
+   basic-query-for-java-code
+   codeql-library-for-java
+   analyzing-data-flow-in-java
+   types-in-java
+   overflow-prone-comparisons-in-java
+   navigating-the-call-graph
+   annotations-in-java
    javadoc
-   source-locations
-   ast-class-reference
+   working-with-source-locations
+   abstract-syntax-tree-classes-for-working-with-go-programs
 
--  :doc:`Basic query for Java code <basic-query-java>`: Learn to write and run a simple CodeQL query using LGTM.
+-  :doc:`Basic query for Java code <basic-query-for-java-code>`: Learn to write and run a simple CodeQL query using LGTM.
 
--  :doc:`CodeQL library for Java <introduce-libraries-java>`: When analyzing Java code, you can use the large collection of classes in the CodeQL library for Java.
+-  :doc:`CodeQL library for Java <codeql-library-for-java>`: When analyzing Java code, you can use the large collection of classes in the CodeQL library for Java.
 
--  :doc:`Analyzing data flow in Java <dataflow>`: You can use CodeQL to track the flow of data through a Java program to its use. 
+-  :doc:`Analyzing data flow in Java <analyzing-data-flow-in-java>`: You can use CodeQL to track the flow of data through a Java program to its use. 
 
--  :doc:`Java types <types-class-hierarchy>`: You can use CodeQL to find out information about data types used in Java code. This allows you to write queries to identify specific type-related issues.
+-  :doc:`Java types <types-in-java>`: You can use CodeQL to find out information about data types used in Java code. This allows you to write queries to identify specific type-related issues.
 
--  :doc:`Overflow-prone comparisons in Java <expressions-statements>`: You can use CodeQL to check for comparisons in Java code where one side of the comparison is prone to overflow.
+-  :doc:`Overflow-prone comparisons in Java <overflow-prone-comparisons-in-java>`: You can use CodeQL to check for comparisons in Java code where one side of the comparison is prone to overflow.
 
--  :doc:`Navigating the call graph <call-graph>`: CodeQL has classes for identifying code that calls other code, and code that can be called from elsewhere. This allows you to find, for example, methods that are never used.
+-  :doc:`Navigating the call graph <navigating-the-call-graph>`: CodeQL has classes for identifying code that calls other code, and code that can be called from elsewhere. This allows you to find, for example, methods that are never used.
 
--  :doc:`Annotations in Java <annotations>`: CodeQL databases of Java projects contain information about all annotations attached to program elements.
+-  :doc:`Annotations in Java <annotations-in-java>`: CodeQL databases of Java projects contain information about all annotations attached to program elements.
 
 -  :doc:`Javadoc <javadoc>`: You can use CodeQL to find errors in Javadoc comments in Java code.
 
--  :doc:`Working with source locations <source-locations>`: You can use the location of entities within Java code to look for potential errors. Locations allow you to deduce the presence, or absence, of white space which, in some cases, may indicate a problem.
+-  :doc:`Working with source locations <working-with-source-locations>`: You can use the location of entities within Java code to look for potential errors. Locations allow you to deduce the presence, or absence, of white space which, in some cases, may indicate a problem.
 
--  :doc:`Abstract syntax tree classes for working with Java programs <ast-class-reference>`: CodeQL has a large selection of classes for representing the abstract syntax tree of Java programs.
+-  :doc:`Abstract syntax tree classes for working with Java programs <abstract-syntax-tree-classes-for-working-with-go-programs>`: CodeQL has a large selection of classes for representing the abstract syntax tree of Java programs.
 
diff --git a/docs/language/learn-ql/java/codeql-library-for-java.rst b/docs/language/learn-ql/java/codeql-library-for-java.rst
index 35004241657..7d8055547d0 100644
--- a/docs/language/learn-ql/java/codeql-library-for-java.rst
+++ b/docs/language/learn-ql/java/codeql-library-for-java.rst
@@ -196,7 +196,7 @@ The wildcards ``? extends Number`` and ``? super Float`` are represented by clas
 
 For dealing with generic methods, there are classes ``GenericMethod``, ``ParameterizedMethod`` and ``RawMethod``, which are entirely analogous to the like-named classes for representing generic types.
 
-For more information on working with types, see the :doc:`article on Java types <types-class-hierarchy>`.
+For more information on working with types, see the :doc:`article on Java types <types-in-java>`.
 
 Variables
 ~~~~~~~~~
@@ -210,7 +210,7 @@ Class ``Variable`` represents a variable `in the Java sense <https://docs.oracle
 Abstract syntax tree
 --------------------
 
-Classes in this category represent abstract syntax tree (AST) nodes, that is, statements (class ``Stmt``) and expressions (class ``Expr``). For a full list of expression and statement types available in the standard QL library, see ":doc:`Abstract syntax tree classes for working with Java programs <ast-class-reference>`."
+Classes in this category represent abstract syntax tree (AST) nodes, that is, statements (class ``Stmt``) and expressions (class ``Expr``). For a full list of expression and statement types available in the standard QL library, see ":doc:`Abstract syntax tree classes for working with Java programs <abstract-syntax-tree-classes-for-working-with-go-programs>`."
 
 Both ``Expr`` and ``Stmt`` provide member predicates for exploring the abstract syntax tree of a program:
 
@@ -260,7 +260,7 @@ Finally, here is a query that finds method bodies:
 
 As these examples show, the parent node of an expression is not always an expression: it may also be a statement, for example, an ``IfStmt``. Similarly, the parent node of a statement is not always a statement: it may also be a method or a constructor. To capture this, the QL Java library provides two abstract class ``ExprParent`` and ``StmtParent``, the former representing any node that may be the parent node of an expression, and the latter any node that may be the parent node of a statement.
 
-For more information on working with AST classes, see the :doc:`article on overflow-prone comparisons in Java <expressions-statements>`.
+For more information on working with AST classes, see the :doc:`article on overflow-prone comparisons in Java <overflow-prone-comparisons-in-java>`.
 
 Metadata
 --------
@@ -292,7 +292,7 @@ These annotations are represented by class ``Annotation``. An annotation is simp
 
 ➤ `See this in the query console on LGTM.com <https://lgtm.com/query/5393027107459215059/>`__. Only constructors with the ``@Deprecated`` annotation are reported this time.
 
-For more information on working with annotations, see the :doc:`article on annotations <annotations>`.
+For more information on working with annotations, see the :doc:`article on annotations <annotations-in-java>`.
 
 For Javadoc, class ``Element`` has a member predicate ``getDoc`` that returns a delegate ``Documentable`` object, which can then be queried for its attached Javadoc comments. For example, the following query finds Javadoc comments on private fields:
 
@@ -379,9 +379,9 @@ Conversely, ``Callable.getAReference`` returns a ``Call`` that refers to it. So
    where not exists(c.getAReference())
    select c
 
-➤ `See this in the query console on LGTM.com <https://lgtm.com/query/7261739919657747703/>`__. The LGTM.com demo projects all appear to have many methods that are not called directly, but this is unlikely to be the whole story. To explore this area further, see ":doc:`Navigating the call graph <call-graph>`."
+➤ `See this in the query console on LGTM.com <https://lgtm.com/query/7261739919657747703/>`__. The LGTM.com demo projects all appear to have many methods that are not called directly, but this is unlikely to be the whole story. To explore this area further, see ":doc:`Navigating the call graph <navigating-the-call-graph>`."
 
-For more information about callables and calls, see the :doc:`article on the call graph <call-graph>`.
+For more information about callables and calls, see the :doc:`article on the call graph <navigating-the-call-graph>`.
 
 Further reading
 ---------------
diff --git a/docs/language/learn-ql/java/overflow-prone-comparisons-in-java.rst b/docs/language/learn-ql/java/overflow-prone-comparisons-in-java.rst
index 5e8bfbf8b5e..d25892c0a57 100644
--- a/docs/language/learn-ql/java/overflow-prone-comparisons-in-java.rst
+++ b/docs/language/learn-ql/java/overflow-prone-comparisons-in-java.rst
@@ -26,7 +26,7 @@ If ``l`` is bigger than 2\ :sup:`31`\ - 1 (the largest positive value of type ``
 
    All primitive numeric types have a maximum value, beyond which they will wrap around to their lowest possible value (called an "overflow"). For ``int``, this maximum value is 2\ :sup:`31`\ - 1. Type ``long`` can accommodate larger values up to a maximum of 2\ :sup:`63`\ - 1. In this example, this means that ``l`` can take on a value that is higher than the maximum for type ``int``; ``i`` will never be able to reach this value, instead overflowing and returning to a low value.
 
-We're going to develop a query that finds code that looks like it might exhibit this kind of behavior. We'll be using several of the standard library classes for representing statements and functions. For a full list, see ":doc:`Abstract syntax tree classes for working with Java programs <ast-class-reference>`."
+We're going to develop a query that finds code that looks like it might exhibit this kind of behavior. We'll be using several of the standard library classes for representing statements and functions. For a full list, see ":doc:`Abstract syntax tree classes for working with Java programs <abstract-syntax-tree-classes-for-working-with-go-programs>`."
 
 Initial query
 -------------
diff --git a/docs/language/learn-ql/javascript/abstract-syntax-tree-classes-for-working-with-go-programs.rst b/docs/language/learn-ql/javascript/abstract-syntax-tree-classes-for-working-with-javascript-and-typescript-programs.rst
similarity index 100%
rename from docs/language/learn-ql/javascript/abstract-syntax-tree-classes-for-working-with-go-programs.rst
rename to docs/language/learn-ql/javascript/abstract-syntax-tree-classes-for-working-with-javascript-and-typescript-programs.rst
diff --git a/docs/language/learn-ql/javascript/analyzing-data-flow-in-javascript.rst b/docs/language/learn-ql/javascript/analyzing-data-flow-in-javascript.rst
index 4929111b4cd..1d4bc49a24a 100644
--- a/docs/language/learn-ql/javascript/analyzing-data-flow-in-javascript.rst
+++ b/docs/language/learn-ql/javascript/analyzing-data-flow-in-javascript.rst
@@ -9,7 +9,7 @@ The various sections in this article describe how to utilize the libraries for l
 As our running example, we will develop a query that identifies command-line arguments that are passed as a file path to the standard Node.js ``readFile`` function.
 While this is not a problematic pattern as such, it is typical of the kind of reasoning that is frequently used in security queries.
 
-For a more general introduction to modeling data flow, see ":doc:`About data flow analysis <../intro-to-data-flow>`."
+For a more general introduction to modeling data flow, see ":doc:`About data flow analysis <../about-data-flow-analysis>`."
 
 Data flow nodes
 ---------------
@@ -554,7 +554,7 @@ Exercise 4
 Further reading
 ---------------
 
-- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-paths.html>`__"
+- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-data-flow-with-path-queries.html>`__"
 
 
 .. include:: ../../reusables/java-further-reading.rst
diff --git a/docs/language/learn-ql/javascript/codeql-for-javascript.rst b/docs/language/learn-ql/javascript/codeql-for-javascript.rst
index 874ae9798f8..d0656da685a 100644
--- a/docs/language/learn-ql/javascript/codeql-for-javascript.rst
+++ b/docs/language/learn-ql/javascript/codeql-for-javascript.rst
@@ -6,27 +6,27 @@ Experiment and learn how to write effective and efficient queries for CodeQL dat
 .. toctree::
    :hidden:
 
-   basic-query-javascript
-   introduce-libraries-js
-   introduce-libraries-ts
-   dataflow
-   flow-labels
-   type-tracking
-   ast-class-reference
-   dataflow-cheat-sheet
+   basic-query-for-javascript-code
+   codeql-library-for-javascript
+   codeql-library-for-typescript
+   analyzing-data-flow-in-javascript
+   using-flow-labels-for-precise-data-flow-analysis
+   using-type-tracking-for-api-modeling
+   abstract-syntax-tree-classes-for-working-with-javascript-and-typescript-programs
+   data-flow-cheat-sheet-for-javascript
 
--  :doc:`Basic query for JavaScript code <basic-query-javascript>`: Learn to write and run a simple CodeQL query using LGTM.
+-  :doc:`Basic query for JavaScript code <basic-query-for-javascript-code>`: Learn to write and run a simple CodeQL query using LGTM.
 
--  :doc:`CodeQL library for JavaScript <introduce-libraries-js>`: When you're analyzing a JavaScript program, you can make use of the large collection of classes in the CodeQL library for JavaScript.
+-  :doc:`CodeQL library for JavaScript <codeql-library-for-javascript>`: When you're analyzing a JavaScript program, you can make use of the large collection of classes in the CodeQL library for JavaScript.
 
--  :doc:`CodeQL library for TypeScript <introduce-libraries-ts>`: When you're analyzing a TypeScript program, you can make use of the large collection of classes in the CodeQL library for TypeScript.
+-  :doc:`CodeQL library for TypeScript <codeql-library-for-typescript>`: When you're analyzing a TypeScript program, you can make use of the large collection of classes in the CodeQL library for TypeScript.
 
--  :doc:`Analyzing data flow in JavaScript and TypeScript <dataflow>`: This topic describes how data flow analysis is implemented in the CodeQL libraries for JavaScript/TypeScript and includes examples to help you write your own data flow queries.
+-  :doc:`Analyzing data flow in JavaScript and TypeScript <analyzing-data-flow-in-javascript>`: This topic describes how data flow analysis is implemented in the CodeQL libraries for JavaScript/TypeScript and includes examples to help you write your own data flow queries.
 
--  :doc:`Using flow labels for precise data flow analysis <flow-labels>`: You can associate flow labels with each value tracked by the flow analysis to determine whether the flow contains potential vulnerabilities.
+-  :doc:`Using flow labels for precise data flow analysis <using-flow-labels-for-precise-data-flow-analysis>`: You can associate flow labels with each value tracked by the flow analysis to determine whether the flow contains potential vulnerabilities.
 
--  :doc:`Using type tracking for API modeling <type-tracking>`: You can track data through an API by creating a model using the CodeQL type-tracking library for JavaScript.
+-  :doc:`Using type tracking for API modeling <using-type-tracking-for-api-modeling>`: You can track data through an API by creating a model using the CodeQL type-tracking library for JavaScript.
 
--  :doc:`Abstract syntax tree classes for working with JavaScript and TypeScript programs <ast-class-reference>`: CodeQL has a large selection of classes for representing the abstract syntax tree of JavaScript and TypeScript programs.
+-  :doc:`Abstract syntax tree classes for working with JavaScript and TypeScript programs <abstract-syntax-tree-classes-for-working-with-javascript-and-typescript-programs>`: CodeQL has a large selection of classes for representing the abstract syntax tree of JavaScript and TypeScript programs.
 
--  :doc:`Data flow cheat sheet for JavaScript <dataflow-cheat-sheet>`: This article describes parts of the JavaScript libraries commonly used for variant analysis and in data flow queries.
+-  :doc:`Data flow cheat sheet for JavaScript <data-flow-cheat-sheet-for-javascript>`: This article describes parts of the JavaScript libraries commonly used for variant analysis and in data flow queries.
diff --git a/docs/language/learn-ql/javascript/codeql-library-for-typescript.rst b/docs/language/learn-ql/javascript/codeql-library-for-typescript.rst
index 614b9fee68e..67a5adfd774 100644
--- a/docs/language/learn-ql/javascript/codeql-library-for-typescript.rst
+++ b/docs/language/learn-ql/javascript/codeql-library-for-typescript.rst
@@ -12,7 +12,7 @@ Support for analyzing TypeScript code is bundled with the CodeQL libraries for J
 
    import javascript
 
-:doc:`CodeQL libraries for JavaScript <introduce-libraries-js>` covers most of this library, and is also relevant for TypeScript analysis. This document supplements the JavaScript documentation with the TypeScript-specific classes and predicates.
+:doc:`CodeQL libraries for JavaScript <codeql-library-for-javascript>` covers most of this library, and is also relevant for TypeScript analysis. This document supplements the JavaScript documentation with the TypeScript-specific classes and predicates.
 
 Syntax
 ------
diff --git a/docs/language/learn-ql/javascript/data-flow-cheat-sheet-for-javascript.rst b/docs/language/learn-ql/javascript/data-flow-cheat-sheet-for-javascript.rst
index c26b4222741..4ac5ec89957 100644
--- a/docs/language/learn-ql/javascript/data-flow-cheat-sheet-for-javascript.rst
+++ b/docs/language/learn-ql/javascript/data-flow-cheat-sheet-for-javascript.rst
@@ -34,12 +34,12 @@ This query reports flow paths which:
 - Step through variables, function calls, properties, strings, arrays, promises, exceptions, and steps added by `isAdditionalTaintStep <https://help.semmle.com/qldoc/javascript/semmle/javascript/dataflow/TaintTracking.qll/predicate.TaintTracking$TaintTracking$Configuration$isAdditionalTaintStep.2.html>`__.
 - End at a node matched by `isSink <https://help.semmle.com/qldoc/javascript/semmle/javascript/dataflow/Configuration.qll/predicate.Configuration$Configuration$isSink.1.html>`__.
 
-See also: "`Global data flow <https://help.semmle.com/QL/learn-ql/javascript/dataflow.html#global-data-flow>`__" and ":doc:`Creating path queries <../writing-queries/path-queries>`."
+See also: "`Global data flow <https://help.semmle.com/QL/learn-ql/javascript/dataflow.html#global-data-flow>`__" and ":doc:`Creating path queries <../writing-queries/creating-path-queries>`."
 
 DataFlow module
 ---------------
 
-Use data flow nodes to match program elements independently of syntax. See also: ":doc:`Analyzing data flow in JavaScript and TypeScript <dataflow>`."
+Use data flow nodes to match program elements independently of syntax. See also: ":doc:`Analyzing data flow in JavaScript and TypeScript <analyzing-data-flow-in-javascript>`."
 
 Predicates in the ``DataFlow::`` module:
 
@@ -142,7 +142,7 @@ Files
 AST nodes
 ---------
 
-See also: ":doc:`Abstract syntax tree classes for working with JavaScript and TypeScript programs <ast-class-reference>`."
+See also: ":doc:`Abstract syntax tree classes for working with JavaScript and TypeScript programs <abstract-syntax-tree-classes-for-working-with-javascript-and-typescript-programs>`."
 
 Conversion between DataFlow and AST nodes:
 
@@ -163,7 +163,7 @@ String matching
 Type tracking
 -------------
 
-See also: ":doc:`Using type tracking for API modeling <type-tracking>`."
+See also: ":doc:`Using type tracking for API modeling <using-type-tracking-for-api-modeling>`."
 
 Use the following template to define forward type tracking predicates:
 
@@ -220,7 +220,7 @@ Troubleshooting
 Further reading
 ---------------
 
-- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-paths.html>`__"
+- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-data-flow-with-path-queries.html>`__"
 
 
 .. include:: ../../reusables/javascript-further-reading.rst
diff --git a/docs/language/learn-ql/javascript/using-flow-labels-for-precise-data-flow-analysis.rst b/docs/language/learn-ql/javascript/using-flow-labels-for-precise-data-flow-analysis.rst
index ffd4d9cf34c..45b17c666be 100644
--- a/docs/language/learn-ql/javascript/using-flow-labels-for-precise-data-flow-analysis.rst
+++ b/docs/language/learn-ql/javascript/using-flow-labels-for-precise-data-flow-analysis.rst
@@ -7,7 +7,7 @@ Overview
 --------
 
 You can use basic inter-procedural data-flow analysis and taint tracking as described in
-":doc:`Analyzing data flow in JavaScript and TypeScript <dataflow>`" to check whether there is a path in
+":doc:`Analyzing data flow in JavaScript and TypeScript <analyzing-data-flow-in-javascript>`" to check whether there is a path in
 the data-flow graph from some source node to a sink node that does not pass through any sanitizer
 nodes. Another way of thinking about this is that it statically models the flow of data through the
 program, and associates a flag with every data value telling us whether it might have come from a
@@ -267,7 +267,7 @@ sanitized value:
     }
   }
 
-Here is the final query, expressed as a :doc:`path query <../writing-queries/path-queries>` so we can examine paths from sources to sinks
+Here is the final query, expressed as a :doc:`path query <../writing-queries/creating-path-queries>` so we can examine paths from sources to sinks
 step by step in the UI:
 
 .. code-block:: ql
@@ -398,7 +398,7 @@ string may be an absolute path and whether it may contain ``..`` components.
 Further reading
 ---------------
 
-- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-paths.html>`__"
+- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-data-flow-with-path-queries.html>`__"
 
 
 .. include:: ../../reusables/javascript-further-reading.rst
diff --git a/docs/language/learn-ql/javascript/using-type-tracking-for-api-modeling.rst b/docs/language/learn-ql/javascript/using-type-tracking-for-api-modeling.rst
index f2f6cca0594..b3c90c6206e 100644
--- a/docs/language/learn-ql/javascript/using-type-tracking-for-api-modeling.rst
+++ b/docs/language/learn-ql/javascript/using-type-tracking-for-api-modeling.rst
@@ -10,7 +10,7 @@ usually to recognize method calls and properties accessed on a specific type of
 
 This is an advanced topic and is intended for readers already familiar with the
 `SourceNode <https://help.semmle.com/QL/learn-ql/javascript/dataflow.html#source-nodes>`__ class as well as
-`taint tracking <https://help.semmle.com/QL/learn-ql/javascript/dataflow.html#using-global-taint-tracking>`__.
+`taint tracking <https://help.semmle.com/QL/learn-ql/javascript/dataflow.html#using-global-analyzing-data-flow-and-tracking-tainted-data-in-python>`__.
 For TypeScript analysis also consider reading about `static type information <https://help.semmle.com/QL/learn-ql/javascript/introduce-libraries-ts.html#static-type-information>`__ first.
 
 
@@ -489,11 +489,11 @@ Prefer type tracking when:
 
 Prefer data-flow configurations when:
 
-- Tracking user-controlled data -- use `taint tracking <https://help.semmle.com/QL/learn-ql/javascript/dataflow.html#using-global-taint-tracking>`__.
-- Differentiating between different kinds of user-controlled data -- see ":doc:`Using flow labels for precise data flow analysis <flow-labels>`."
+- Tracking user-controlled data -- use `taint tracking <https://help.semmle.com/QL/learn-ql/javascript/dataflow.html#using-global-analyzing-data-flow-and-tracking-tainted-data-in-python>`__.
+- Differentiating between different kinds of user-controlled data -- see ":doc:`Using flow labels for precise data flow analysis <using-flow-labels-for-precise-data-flow-analysis>`."
 - Tracking transformations of a value through generic utility functions.
 - Tracking values through string manipulation.
-- Generating a path from source to sink -- see ":doc:`Creating path queries <../writing-queries/path-queries>`."
+- Generating a path from source to sink -- see ":doc:`Creating path queries <../writing-queries/creating-path-queries>`."
 
 Lastly, depending on the code base being analyzed, some alternatives to consider are:
 
diff --git a/docs/language/learn-ql/python/analyzing-control-flow-in-python.rst b/docs/language/learn-ql/python/analyzing-control-flow-in-python.rst
index f4736f0011d..86cb7248ba2 100644
--- a/docs/language/learn-ql/python/analyzing-control-flow-in-python.rst
+++ b/docs/language/learn-ql/python/analyzing-control-flow-in-python.rst
@@ -112,7 +112,7 @@ Example finding mutually exclusive blocks within the same function
    )
    select b1, b2
 
-➤ `See this in the query console on LGTM.com <https://lgtm.com/query/671000028/>`__. This typically gives a very large number of results, because it is a common occurrence in normal control flow. It is, however, an example of the sort of control-flow analysis that is possible. Control-flow analyses such as this are an important aid to data flow analysis. For more information, see ":doc:`Analyzing data flow and tracking tainted data in Python <taint-tracking>`."
+➤ `See this in the query console on LGTM.com <https://lgtm.com/query/671000028/>`__. This typically gives a very large number of results, because it is a common occurrence in normal control flow. It is, however, an example of the sort of control-flow analysis that is possible. Control-flow analyses such as this are an important aid to data flow analysis. For more information, see ":doc:`Analyzing data flow and tracking tainted data in Python <analyzing-data-flow-and-tracking-tainted-data-in-python>`."
 
 Further reading
 ---------------
diff --git a/docs/language/learn-ql/python/analyzing-data-flow-and-tracking-tainted-data-in-python.rst b/docs/language/learn-ql/python/analyzing-data-flow-and-tracking-tainted-data-in-python.rst
index 14be3eb3527..428329c9d0b 100644
--- a/docs/language/learn-ql/python/analyzing-data-flow-and-tracking-tainted-data-in-python.rst
+++ b/docs/language/learn-ql/python/analyzing-data-flow-and-tracking-tainted-data-in-python.rst
@@ -15,10 +15,10 @@ Taint tracking differs from basic data flow in that it considers non-value-prese
 For example, in the assignment ``dir = path + "/"``, if ``path`` is tainted then ``dir`` is also tainted,
 even though there is no data flow from ``path`` to ``path + "/"``.
 
-Separate CodeQL libraries have been written to handle 'normal' data flow and taint tracking in :doc:`C/C++ <../cpp/dataflow>`, :doc:`C# <../csharp/dataflow>`, :doc:`Java <../java/dataflow>`, and :doc:`JavaScript <../javascript/dataflow>`. You can access the appropriate classes and predicates that reason about these different modes of data flow by importing the appropriate library in your query.
+Separate CodeQL libraries have been written to handle 'normal' data flow and taint tracking in :doc:`C/C++ <../cpp/analyzing-data-flow-in-cpp>`, :doc:`C# <../csharp/analyzing-data-flow-in-csharp>`, :doc:`Java <../java/analyzing-data-flow-in-java>`, and :doc:`JavaScript <../javascript/analyzing-data-flow-in-javascript>`. You can access the appropriate classes and predicates that reason about these different modes of data flow by importing the appropriate library in your query.
 In Python analysis, we can use the same taint tracking library to model both 'normal' data flow and taint flow, but we are still able make the distinction between steps that preserve values and those that don't by defining additional data flow properties.
 
-For further information on data flow and taint tracking with CodeQL, see ":doc:`Introduction to data flow <../intro-to-data-flow>`."
+For further information on data flow and taint tracking with CodeQL, see ":doc:`Introduction to data flow <../about-data-flow-analysis>`."
 
 Fundamentals of taint tracking using data flow analysis
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -259,7 +259,7 @@ which defines the simplest possible taint kind class, ``HardcodedValue``, and cu
 Further reading
 ---------------
 
-- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-paths.html>`__"
+- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-data-flow-with-path-queries.html>`__"
 
 
 .. include:: ../../reusables/python-further-reading.rst
diff --git a/docs/language/learn-ql/python/codeql-for-python.rst b/docs/language/learn-ql/python/codeql-for-python.rst
index bbbb50701c2..9f6a02fba42 100644
--- a/docs/language/learn-ql/python/codeql-for-python.rst
+++ b/docs/language/learn-ql/python/codeql-for-python.rst
@@ -6,24 +6,24 @@ Experiment and learn how to write effective and efficient queries for CodeQL dat
 .. toctree::
    :hidden:
 
-   basic-query-python
-   introduce-libraries-python
-   functions
-   statements-expressions
-   pointsto-type-infer
-   control-flow
-   taint-tracking
+   basic-query-for-python-code
+   codeql-library-for-python
+   functions-in-python
+   expressions-and-statements-in-python
+   pointer-analysis-and-type-inference-in-python
+   analyzing-control-flow-in-python
+   analyzing-data-flow-and-tracking-tainted-data-in-python
 
--  :doc:`Basic query for Python code <basic-query-python>`: Learn to write and run a simple CodeQL query using LGTM.
+-  :doc:`Basic query for Python code <basic-query-for-python-code>`: Learn to write and run a simple CodeQL query using LGTM.
 
--  :doc:`CodeQL library for Python <introduce-libraries-python>`: When you need to analyze a Python program, you can make use of the large collection of classes in the CodeQL library for Python.
+-  :doc:`CodeQL library for Python <codeql-library-for-python>`: When you need to analyze a Python program, you can make use of the large collection of classes in the CodeQL library for Python.
 
--  :doc:`Functions in Python <functions>`: You can use syntactic classes from the standard CodeQL library to find Python functions and identify calls to them.
+-  :doc:`Functions in Python <functions-in-python>`: You can use syntactic classes from the standard CodeQL library to find Python functions and identify calls to them.
 
--  :doc:`Expressions and statements in Python <statements-expressions>`: You can use syntactic classes from the CodeQL library to explore how Python expressions and statements are used in a codebase.
+-  :doc:`Expressions and statements in Python <expressions-and-statements-in-python>`: You can use syntactic classes from the CodeQL library to explore how Python expressions and statements are used in a codebase.
 
--  :doc:`Analyzing control flow in Python <control-flow>`: You can write CodeQL queries to explore the control-flow graph of a Python program, for example, to discover unreachable code or mutually exclusive blocks of code.
+-  :doc:`Analyzing control flow in Python <analyzing-control-flow-in-python>`: You can write CodeQL queries to explore the control-flow graph of a Python program, for example, to discover unreachable code or mutually exclusive blocks of code.
 
--  :doc:`Pointer analysis and type inference in Python <pointsto-type-infer>`: At runtime, each Python expression has a value with an associated type. You can learn how an expression behaves at runtime by using type-inference classes from the standard CodeQL library.
+-  :doc:`Pointer analysis and type inference in Python <pointer-analysis-and-type-inference-in-python>`: At runtime, each Python expression has a value with an associated type. You can learn how an expression behaves at runtime by using type-inference classes from the standard CodeQL library.
 
--  :doc:`Analyzing data flow and tracking tainted data in Python <taint-tracking>`: You can use CodeQL to track the flow of data through a Python program. Tracking user-controlled, or tainted, data is a key technique for security researchers.
+-  :doc:`Analyzing data flow and tracking tainted data in Python <analyzing-data-flow-and-tracking-tainted-data-in-python>`: You can use CodeQL to track the flow of data through a Python program. Tracking user-controlled, or tainted, data is a key technique for security researchers.
diff --git a/docs/language/learn-ql/python/codeql-library-for-python.rst b/docs/language/learn-ql/python/codeql-library-for-python.rst
index d7bfb447f06..860055ec5d4 100644
--- a/docs/language/learn-ql/python/codeql-library-for-python.rst
+++ b/docs/language/learn-ql/python/codeql-library-for-python.rst
@@ -320,7 +320,7 @@ Summary
    -  ``CallableValue``
    -  ``ModuleValue``
 
-For more information about these classes, see ":doc:`Pointer analysis and type inference in Python <pointsto-type-infer>`."
+For more information about these classes, see ":doc:`Pointer analysis and type inference in Python <pointer-analysis-and-type-inference-in-python>`."
 
 Taint-tracking classes
 ----------------------
@@ -334,7 +334,7 @@ Summary
 - `TaintKind <https://help.semmle.com/qldoc/python/semmle/python/dataflow/TaintTracking.qll/type.TaintTracking$TaintKind.html>`__
 - `Configuration <https://help.semmle.com/qldoc/python/semmle/python/dataflow/Configuration.qll/type.Configuration$TaintTracking$Configuration.html>`__
 
-For more information about these classes, see ":doc:`Analyzing data flow and tracking tainted data in Python <taint-tracking>`."
+For more information about these classes, see ":doc:`Analyzing data flow and tracking tainted data in Python <analyzing-data-flow-and-tracking-tainted-data-in-python>`."
 
 
 Further reading
diff --git a/docs/language/learn-ql/python/expressions-and-statements-in-python.rst b/docs/language/learn-ql/python/expressions-and-statements-in-python.rst
index 0cf6dd73a97..e97a3f107d9 100644
--- a/docs/language/learn-ql/python/expressions-and-statements-in-python.rst
+++ b/docs/language/learn-ql/python/expressions-and-statements-in-python.rst
@@ -197,7 +197,7 @@ The short version is usually used as this is easier to read.
 Example finding Java-style getters
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Returning to the example from ":doc:`Functions in Python <functions>`," the query identified all methods with a single line of code and a name starting with ``get``.
+Returning to the example from ":doc:`Functions in Python <functions-in-python>`," the query identified all methods with a single line of code and a name starting with ``get``.
 
 .. code-block:: ql
 
diff --git a/docs/language/learn-ql/python/functions-in-python.rst b/docs/language/learn-ql/python/functions-in-python.rst
index 44d9771df58..8601a80d1b7 100644
--- a/docs/language/learn-ql/python/functions-in-python.rst
+++ b/docs/language/learn-ql/python/functions-in-python.rst
@@ -3,7 +3,7 @@ Functions in Python
 
 You can use syntactic classes from the standard CodeQL library to find Python functions and identify calls to them.
 
-These examples use the standard CodeQL class `Function <https://help.semmle.com/qldoc/python/semmle/python/Function.qll/type.Function$Function.html>`__. For more information, see ":doc:`CodeQL library for Python <introduce-libraries-python>`."
+These examples use the standard CodeQL class `Function <https://help.semmle.com/qldoc/python/semmle/python/Function.qll/type.Function$Function.html>`__. For more information, see ":doc:`CodeQL library for Python <codeql-library-for-python>`."
 
 Finding all functions called "get..."
 -------------------------------------
@@ -57,7 +57,7 @@ We can modify the query further to include only methods whose body consists of a
     and count(f.getAStmt()) = 1
    select f, "This function is (probably) a getter."
 
-➤ `See this in the query console on LGTM.com <https://lgtm.com/query/667290044/>`__. This query returns fewer results, but if you examine the results you can see that there are still refinements to be made. This is refined further in ":doc:`Expressions and statements in Python <statements-expressions>`."
+➤ `See this in the query console on LGTM.com <https://lgtm.com/query/667290044/>`__. This query returns fewer results, but if you examine the results you can see that there are still refinements to be made. This is refined further in ":doc:`Expressions and statements in Python <expressions-and-statements-in-python>`."
 
 Finding a call to a specific function
 -------------------------------------
diff --git a/docs/language/learn-ql/python/pointer-analysis-and-type-inference-in-python.rst b/docs/language/learn-ql/python/pointer-analysis-and-type-inference-in-python.rst
index 60a3acb7fce..ea0b40c333e 100644
--- a/docs/language/learn-ql/python/pointer-analysis-and-type-inference-in-python.rst
+++ b/docs/language/learn-ql/python/pointer-analysis-and-type-inference-in-python.rst
@@ -181,7 +181,7 @@ The ``Value`` class has a method ``getACall()`` which allows us to find calls to
 
 If we wish to restrict the callables to actual functions we can use the ``FunctionValue`` class, which is a subclass of ``Value`` and corresponds to function objects in Python, in much the same way as the ``ClassValue`` class corresponds to class objects in Python.
 
-Returning to an example from ":doc:`Functions in Python <functions>`," we wish to find calls to the ``eval`` function.
+Returning to an example from ":doc:`Functions in Python <functions-in-python>`," we wish to find calls to the ``eval`` function.
 
 The original query looked this:
 
diff --git a/docs/language/learn-ql/ql-training.rst b/docs/language/learn-ql/ql-training.rst
index e3a9cc59135..61fc0551ecc 100644
--- a/docs/language/learn-ql/ql-training.rst
+++ b/docs/language/learn-ql/ql-training.rst
@@ -25,7 +25,7 @@ When you have selected a presentation, use |arrow-r| and |arrow-l| to navigate b
 Press **p** to view the additional notes on slides that have an information icon |info| in the top right corner, and press **f** to enter full-screen mode.
 
 The presentations contain a number of query examples.
-We recommend that you download `CodeQL for Visual Studio Code <https://help.semmle.com/codeql/codeql-for-vscode/procedures/setting-up.html>`__ and add the example database for each presentation so that you can find the bugs mentioned in the slides. 
+We recommend that you download `CodeQL for Visual Studio Code <https://help.semmle.com/codeql/codeql-for-vscode/procedures/setting-up-codeql-in-visual-studio-code.html>`__ and add the example database for each presentation so that you can find the bugs mentioned in the slides. 
 
 
 .. pull-quote:: 
diff --git a/docs/language/learn-ql/writing-queries/about-codeql-queries.rst b/docs/language/learn-ql/writing-queries/about-codeql-queries.rst
index a0ceb4963ca..e6dfa6a330e 100644
--- a/docs/language/learn-ql/writing-queries/about-codeql-queries.rst
+++ b/docs/language/learn-ql/writing-queries/about-codeql-queries.rst
@@ -35,17 +35,17 @@ Basic query structure
     where /* ... logical formula ... */
     select /* ... expressions ... */
 
-The following sections describe the information that is typically included in a query file for alerts. Path queries are discussed in more detail in ":doc:`Creating path queries <path-queries>`." 
+The following sections describe the information that is typically included in a query file for alerts. Path queries are discussed in more detail in ":doc:`Creating path queries <creating-path-queries>`." 
 
 Query metadata
 ==============
 
-Query metadata is used to identify your custom queries when they are added to the GitHub repository or used in your analysis. Metadata provides information about the query's purpose, and also specifies how to interpret and display the query results. For a full list of metadata properties, see ":doc:`Metadata for CodeQL queries <query-metadata>`." The exact metadata requirement depends on how you are going to run your query:
+Query metadata is used to identify your custom queries when they are added to the GitHub repository or used in your analysis. Metadata provides information about the query's purpose, and also specifies how to interpret and display the query results. For a full list of metadata properties, see ":doc:`Metadata for CodeQL queries <metadata-for-codeql-queries>`." The exact metadata requirement depends on how you are going to run your query:
 
 - If you are contributing a query to the GitHub repository, please read the `query metadata style guide <https://github.com/github/codeql/blob/main/docs/query-metadata-style-guide.md>`__. 
-- If you are adding a custom query to a query pack for analysis using LGTM , see `Writing custom queries to include in LGTM analysis <https://lgtm.com/help/lgtm/writing-custom-queries>`__.
+- If you are adding a custom query to a query pack for analysis using LGTM , see `Writing custom queries to include in LGTM analysis <https://lgtm.com/help/lgtm/writing-using-custom-queries-with-the-codeql-cli>`__.
 - If you are analyzing a database using the `CodeQL CLI <https://help.semmle.com/codeql/codeql-cli.html>`__, your query metadata must contain ``@kind``.
-- If you are running a query in the query console on LGTM or with the CodeQL extension for VS Code, metadata is not mandatory. However, if you want your results to be displayed as either an 'alert' or a 'path', you must specify the correct ``@kind`` property, as explained below. For more information, see `Using the query console <https://lgtm.com/help/lgtm/using-query-console>`__ on LGTM.com and "`Analyzing your projects <https://help.semmle.com/codeql/codeql-for-vscode/procedures/using-extension.html>`__" in the CodeQL for VS Code help.
+- If you are running a query in the query console on LGTM or with the CodeQL extension for VS Code, metadata is not mandatory. However, if you want your results to be displayed as either an 'alert' or a 'path', you must specify the correct ``@kind`` property, as explained below. For more information, see `Using the query console <https://lgtm.com/help/lgtm/using-query-console>`__ on LGTM.com and "`Analyzing your projects <https://help.semmle.com/codeql/codeql-for-vscode/procedures/analyzing-your-projects.html>`__" in the CodeQL for VS Code help.
 
 .. pull-quote:: 
 
@@ -73,7 +73,7 @@ When writing your own alert queries, you would typically import the standard lib
 - JavaScript/TypeScript: ``javascript``
 - Python: ``python``
 
-There are also libraries containing commonly used predicates, types, and other modules associated with different analyses, including data flow, control flow, and taint-tracking. In order to calculate path graphs, path queries require you to import a data flow library into the query file. For more information, see ":doc:`Creating path queries <path-queries>`."
+There are also libraries containing commonly used predicates, types, and other modules associated with different analyses, including data flow, control flow, and taint-tracking. In order to calculate path graphs, path queries require you to import a data flow library into the query file. For more information, see ":doc:`Creating path queries <creating-path-queries>`."
 
 You can explore the contents of all the standard libraries in the `CodeQL library reference documentation <https://help.semmle.com/QL/ql-libraries.html>`__ or in the `GitHub repository <https://github.com/github/codeql>`__.
 
@@ -106,9 +106,9 @@ Select clauses for alert queries (``@kind problem``) consist of two 'columns', w
 - ``element``: a code element that is identified by the query, which defines where the alert is displayed.
 - ``string``: a message, which can also include links and placeholders, explaining why the alert was generated. 
 
-You can modify the alert message defined in the final column of the ``select`` statement to give more detail about the alert or path found by the query using links and placeholders. For more information, see ":doc:`Defining the results of a query <select-statement>`." 
+You can modify the alert message defined in the final column of the ``select`` statement to give more detail about the alert or path found by the query using links and placeholders. For more information, see ":doc:`Defining the results of a query <defining-the-results-of-a-query>`." 
 
-Select clauses for path queries (``@kind path-problem``) are crafted to display both an alert and the source and sink of an associated path graph. For more information, see ":doc:`Creating path queries <path-queries>`."
+Select clauses for path queries (``@kind path-problem``) are crafted to display both an alert and the source and sink of an associated path graph. For more information, see ":doc:`Creating path queries <creating-path-queries>`."
 
 Viewing the standard CodeQL queries
 ***********************************
@@ -123,12 +123,12 @@ Contributing queries
 Contributions to the standard queries and libraries are very welcome. For more information, see our `contributing guidelines <https://github.com/github/codeql/blob/main/CONTRIBUTING.md>`__.
 If you are contributing a query to the open source GitHub repository, writing a custom query for LGTM, or using a custom query in an analysis with the CodeQL CLI, then you need to include extra metadata in your query to ensure that the query results are interpreted and displayed correctly. See the following topics for more information on query metadata:
 
--  ":doc:`Metadata for CodeQL queries <query-metadata>`"
+-  ":doc:`Metadata for CodeQL queries <metadata-for-codeql-queries>`"
 -  `Query metadata style guide on GitHub <https://github.com/github/codeql/blob/main/docs/query-metadata-style-guide.md>`__
 
-Query contributions to the open source GitHub repository may also have an accompanying query help file to provide information about their purpose for other users. For more information on writing query help, see the `Query help style guide on GitHub <https://github.com/github/codeql/blob/main/docs/query-help-style-guide.md>`__ and the ":doc:`Query help files <query-help>`."
+Query contributions to the open source GitHub repository may also have an accompanying query help file to provide information about their purpose for other users. For more information on writing query help, see the `Query help style guide on GitHub <https://github.com/github/codeql/blob/main/docs/query-help-style-guide.md>`__ and the ":doc:`Query help files <query-help-files>`."
 
 Query help files
 ****************
 
-When you write a custom query, we also recommend that you write a query help file to explain the purpose of the query to other users. For more information, see the `Query help style guide <https://github.com/github/codeql/blob/main/docs/query-help-style-guide.md>`__ on GitHub, and the ":doc:`Query help files <query-help>`." 
+When you write a custom query, we also recommend that you write a query help file to explain the purpose of the query to other users. For more information, see the `Query help style guide <https://github.com/github/codeql/blob/main/docs/query-help-style-guide.md>`__ on GitHub, and the ":doc:`Query help files <query-help-files>`." 
diff --git a/docs/language/learn-ql/writing-queries/codeql-queries.rst b/docs/language/learn-ql/writing-queries/codeql-queries.rst
index bdf702ded1c..277593577d9 100644
--- a/docs/language/learn-ql/writing-queries/codeql-queries.rst
+++ b/docs/language/learn-ql/writing-queries/codeql-queries.rst
@@ -6,20 +6,20 @@ CodeQL queries are used in code scanning analyses to find problems in source cod
 .. toctree::
    :hidden:
 
-   introduction-to-queries
-   query-metadata
-   query-help
-   select-statement
-   ../locations
-   ../intro-to-data-flow
-   path-queries
-   debugging-queries
+   about-codeql-queries
+   metadata-for-codeql-queries
+   query-help-files
+   defining-the-results-of-a-query
+   ../providing-locations-in-codeql-queries
+   ../about-data-flow-analysis
+   creating-path-queries
+   troubleshooting-query-performance
 
-- :doc:`About CodeQL queries <introduction-to-queries>`: CodeQL queries are used to analyze code for issues related to security, correctness, maintainability, and readability. 
-- :doc:`Metadata for CodeQL queries <query-metadata>`: Metadata tells users important information about CodeQL queries. You must include the correct query metadata in a query to be able to view query results in source code.
-- :doc:`Query help files <query-help>`: Query help files tell users the purpose of a query, and recommend how to solve the potential problem the query finds.
-- :doc:`Defining the results of a query <select-statement>`: You can control how analysis results are displayed in source code by modifying a query's ``select`` statement.
-- :doc:`Providing locations in CodeQL queries <../locations>`: CodeQL includes mechanisms for extracting the location of elements in a codebase. Use these mechanisms when writing custom CodeQL queries and libraries to help display information to users.
-- :doc:`About data flow analysis <../intro-to-data-flow>`: Data flow analysis is used to compute the possible values that a variable can hold at various points in a program, determining how those values propagate through the program and where they are used. 
-- :doc:`Creating path queries <path-queries>`: You can create path queries to visualize the flow of information through a codebase.
-- :doc:`Troubleshooting query performance <debugging-queries>`: Improve the performance of your CodeQL queries by following a few simple guidelines.
+- :doc:`About CodeQL queries <about-codeql-queries>`: CodeQL queries are used to analyze code for issues related to security, correctness, maintainability, and readability. 
+- :doc:`Metadata for CodeQL queries <metadata-for-codeql-queries>`: Metadata tells users important information about CodeQL queries. You must include the correct query metadata in a query to be able to view query results in source code.
+- :doc:`Query help files <query-help-files>`: Query help files tell users the purpose of a query, and recommend how to solve the potential problem the query finds.
+- :doc:`Defining the results of a query <defining-the-results-of-a-query>`: You can control how analysis results are displayed in source code by modifying a query's ``select`` statement.
+- :doc:`Providing locations in CodeQL queries <../providing-locations-in-codeql-queries>`: CodeQL includes mechanisms for extracting the location of elements in a codebase. Use these mechanisms when writing custom CodeQL queries and libraries to help display information to users.
+- :doc:`About data flow analysis <../about-data-flow-analysis>`: Data flow analysis is used to compute the possible values that a variable can hold at various points in a program, determining how those values propagate through the program and where they are used. 
+- :doc:`Creating path queries <creating-path-queries>`: You can create path queries to visualize the flow of information through a codebase.
+- :doc:`Troubleshooting query performance <troubleshooting-query-performance>`: Improve the performance of your CodeQL queries by following a few simple guidelines.
diff --git a/docs/language/learn-ql/writing-queries/creating-path-queries.rst b/docs/language/learn-ql/writing-queries/creating-path-queries.rst
index 6c31621ff2c..cfc36cbb566 100644
--- a/docs/language/learn-ql/writing-queries/creating-path-queries.rst
+++ b/docs/language/learn-ql/writing-queries/creating-path-queries.rst
@@ -16,17 +16,17 @@ This topic provides information on how to structure a path query file so you can
 
     Note
 
-    The alerts generated by path queries are displayed by default in `LGTM <https://lgtm.com>`__ and included in the results generated using the `CodeQL CLI <https://help.semmle.com/codeql/codeql-cli.html>`__. You can also view the path explanations generated by your path query `directly in LGTM <https://lgtm.com/help/lgtm/exploring-data-flow-paths>`__ or in the CodeQL `extension for VS Code <https://help.semmle.com/codeql/codeql-for-vscode.html>`__.
+    The alerts generated by path queries are displayed by default in `LGTM <https://lgtm.com>`__ and included in the results generated using the `CodeQL CLI <https://help.semmle.com/codeql/codeql-cli.html>`__. You can also view the path explanations generated by your path query `directly in LGTM <https://lgtm.com/help/lgtm/exploring-data-flow-paths>`__ or in the CodeQL `extension for VS Code <https://help.semmle.com/codeql/codeql-for-visual-studio-code.html>`__.
 
 
-To learn more about modeling data flow with CodeQL, see ":doc:`About data flow analysis <../intro-to-data-flow>`."
+To learn more about modeling data flow with CodeQL, see ":doc:`About data flow analysis <../about-data-flow-analysis>`."
 For more language-specific information on analyzing data flow, see:
 
-- ":doc:`Analyzing data flow in C/C++ <../cpp/dataflow>`"
-- ":doc:`Analyzing data flow in C# <../csharp/dataflow>`"
-- ":doc:`Analyzing data flow in Java <../java/dataflow>`" 
-- ":doc:`Analyzing data flow in JavaScript/TypeScript <../javascript/dataflow>`"
-- ":doc:`Analyzing data flow and tracking tainted data in Python <../python/taint-tracking>`"
+- ":doc:`Analyzing data flow in C/C++ <../cpp/analyzing-data-flow-in-cpp>`"
+- ":doc:`Analyzing data flow in C# <../csharp/analyzing-data-flow-in-csharp>`"
+- ":doc:`Analyzing data flow in Java <../java/analyzing-data-flow-in-java>`" 
+- ":doc:`Analyzing data flow in JavaScript/TypeScript <../javascript/analyzing-data-flow-in-javascript>`"
+- ":doc:`Analyzing data flow and tracking tainted data in Python <../python/analyzing-data-flow-and-tracking-tainted-data-in-python>`"
 
 
 Path query examples
@@ -56,7 +56,7 @@ For C/C++, C#, Java, and JavaScript you should use the following template::
      * ...
      */
 
-    import <language>
+    import <ql-language-specification>
     import DataFlow::PathGraph
     ...
 
@@ -98,7 +98,7 @@ Path query metadata
 *******************
 
 Path query metadata must contain the property ``@kind path-problem``–this ensures that query results are interpreted and displayed correctly.
-The other metadata requirements depend on how you intend to run the query. For more information, see ":doc:`Metadata for CodeQL queries <query-metadata>`."
+The other metadata requirements depend on how you intend to run the query. For more information, see ":doc:`Metadata for CodeQL queries <metadata-for-codeql-queries>`."
 
 Generating path explanations
 ****************************
@@ -149,7 +149,7 @@ The configuration class is accessed by importing the data flow library. This cla
 - ``isSource()`` defines where data may flow from.
 - ``isSink()`` defines where data may flow to.
 
-For more information on using the configuration class in your analysis see the sections on global data flow in ":doc:`Analyzing data flow in C/C++ <../cpp/dataflow>`" and ":doc:`Analyzing data flow in C# <../csharp/dataflow>`."
+For more information on using the configuration class in your analysis see the sections on global data flow in ":doc:`Analyzing data flow in C/C++ <../cpp/analyzing-data-flow-in-cpp>`" and ":doc:`Analyzing data flow in C# <../csharp/analyzing-data-flow-in-csharp>`."
 
 You can also create a configuration for different frameworks and environments by extending the ``Configuration`` class. For more information, see "`Types <https://help.semmle.com/QL/ql-handbook/types.html#defining-a-class>`__" in the QL language reference.
 
@@ -182,16 +182,16 @@ Select clauses for path queries consist of four 'columns', with the following st
 
     select element, source, sink, string
 
-The ``element`` and ``string`` columns represent the location of the alert and the alert message respectively, as explained in ":doc:`About CodeQL queries <introduction-to-queries>`." The second and third columns, ``source`` and ``sink``, are nodes on the path graph selected by the query. 
-Each result generated by your query is displayed at a single location in the same way as an alert query. Additionally, each result also has an associated path, which can be viewed in LGTM or in the `CodeQL extension for VS Code <https://help.semmle.com/codeql/codeql-for-vscode.html>`__.
+The ``element`` and ``string`` columns represent the location of the alert and the alert message respectively, as explained in ":doc:`About CodeQL queries <about-codeql-queries>`." The second and third columns, ``source`` and ``sink``, are nodes on the path graph selected by the query. 
+Each result generated by your query is displayed at a single location in the same way as an alert query. Additionally, each result also has an associated path, which can be viewed in LGTM or in the `CodeQL extension for VS Code <https://help.semmle.com/codeql/codeql-for-visual-studio-code.html>`__.
 
 The ``element`` that you select in the first column depends on the purpose of the query and the type of issue that it is designed to find. This is particularly important for security issues. For example, if you believe the ``source`` value to be globally invalid or malicious it may be best to display the alert at the ``source``. In contrast, you should consider displaying the alert at the ``sink`` if you believe it is the element that requires sanitization.
 
-The alert message defined in the final column in the ``select`` statement can be developed to give more detail about the alert or path found by the query using links and placeholders. For more information, see ":doc:`Defining the results of a query <select-statement>`." 
+The alert message defined in the final column in the ``select`` statement can be developed to give more detail about the alert or path found by the query using links and placeholders. For more information, see ":doc:`Defining the results of a query <defining-the-results-of-a-query>`." 
 
 Further reading
 ***************
 
-- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-paths.html>`__"
+- "`Exploring data flow with path queries <https://help.semmle.com/codeql/codeql-for-vscode/procedures/exploring-data-flow-with-path-queries.html>`__"
 
 - `CodeQL repository <https://github.com/github/codeql>`__
diff --git a/docs/language/learn-ql/writing-queries/defining-the-results-of-a-query.rst b/docs/language/learn-ql/writing-queries/defining-the-results-of-a-query.rst
index bc593932064..3462cea01ec 100644
--- a/docs/language/learn-ql/writing-queries/defining-the-results-of-a-query.rst
+++ b/docs/language/learn-ql/writing-queries/defining-the-results-of-a-query.rst
@@ -7,7 +7,7 @@ About query results
 -------------------
 
 The information contained in the results of a query is controlled by the ``select`` statement. Part of the process of developing a useful query is to make the results clear and easy for other users to understand.
-When you write your own queries in the query console or in the CodeQL `extension for VS Code <https://help.semmle.com/codeql/codeql-for-vscode.html>`__ there are no constraints on what can be selected.
+When you write your own queries in the query console or in the CodeQL `extension for VS Code <https://help.semmle.com/codeql/codeql-for-visual-studio-code.html>`__ there are no constraints on what can be selected.
 However, if you want to use a query to create alerts in LGTM or generate valid analysis results using the `CodeQL CLI <https://help.semmle.com/codeql/codeql-cli.html>`__, you'll need to make the ``select`` statement report results in the required format. 
 You must also ensure that the query has the appropriate metadata properties defined. 
 This topic explains how to write your select statement to generate helpful analysis results. 
@@ -15,7 +15,7 @@ This topic explains how to write your select statement to generate helpful analy
 Overview
 --------
 
-Alert queries must have the property ``@kind problem`` defined in their metadata. For more information, see ":doc:`Metadata for CodeQL queries <query-metadata>`." 
+Alert queries must have the property ``@kind problem`` defined in their metadata. For more information, see ":doc:`Metadata for CodeQL queries <metadata-for-codeql-queries>`." 
 In their most basic form, the ``select`` statement must select two 'columns':
 
 -  **Element**—a code element that's identified by the query. This defines the location of the alert.
@@ -27,7 +27,7 @@ If you look at some of the LGTM queries, you'll see that they can select extra e
 
     Note
 
-    An in-depth discussion of ``select`` statements for path queries is not included in this topic. However, you can develop the string column of the ``select`` statement in the same way as for alert queries. For more specific information about path queries, see ":doc:`Creating path queries <path-queries>`."
+    An in-depth discussion of ``select`` statements for path queries is not included in this topic. However, you can develop the string column of the ``select`` statement in the same way as for alert queries. For more specific information about path queries, see ":doc:`Creating path queries <creating-path-queries>`."
 
 Developing a select statement
 -----------------------------
diff --git a/docs/language/learn-ql/writing-queries/metadata-for-codeql-queries.rst b/docs/language/learn-ql/writing-queries/metadata-for-codeql-queries.rst
index a50c4f183cb..c00c71e366d 100644
--- a/docs/language/learn-ql/writing-queries/metadata-for-codeql-queries.rst
+++ b/docs/language/learn-ql/writing-queries/metadata-for-codeql-queries.rst
@@ -6,47 +6,47 @@ Metadata tells users important information about CodeQL queries. You must includ
 About query metadata
 --------------------
 
-Any query that is run as part of an analysis includes a number of properties, known as query metadata. Metadata is included at the top of each query file as the content of a `QLDoc <https://help.semmle.com/QL/ql-spec/qldoc.html>`__ comment. 
-This metadata tells LGTM and the CodeQL `extension for VS Code <https://help.semmle.com/codeql/codeql-for-vscode.html>`__ how to handle the query and display its results correctly. 
+Any query that is run as part of an analysis includes a number of properties, known as query metadata. Metadata is included at the top of each query file as the content of a `QLDoc <https://help.semmle.com/QL/ql-spec/qldoc-comment-specification.html>`__ comment. 
+This metadata tells LGTM and the CodeQL `extension for VS Code <https://help.semmle.com/codeql/codeql-for-visual-studio-code.html>`__ how to handle the query and display its results correctly. 
 It also gives other users information about what the query results mean. For more information on query metadata, see the `query metadata style guide <https://github.com/github/codeql/blob/main/docs/query-metadata-style-guide.md>`__ in our `open source repository <https://github.com/github/codeql>`__ on GitHub.
 
 .. pull-quote::
 
     Note
 
-    The exact metadata requirement depends on how you are going to run your query. For more information, see the section on query metadata in ":doc:`About CodeQL queries <introduction-to-queries>`."
+    The exact metadata requirement depends on how you are going to run your query. For more information, see the section on query metadata in ":doc:`About CodeQL queries <about-codeql-queries>`."
     
 Metadata properties
 -------------------
 
 The following properties are supported by all query files:
 
-+-----------------------+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Property              | Value                     | Description                                                                                                                                                                                                                                                                                                                                          |
-+=======================+===========================+======================================================================================================================================================================================================================================================================================================================================================+
-| ``@description``      | ``<text>``                | A sentence or short paragraph to describe the purpose of the query and *why* the result is useful or important. The description is written in plain text, and uses single quotes (``'``) to enclose code elements.                                                                                                                                   |
-+-----------------------+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| ``@id``               | ``<text>``                | A sequence of words composed of lowercase letters or digits, delimited by ``/`` or ``-``, identifying and classifying the query. Each query must have a **unique** ID. To ensure this, it may be helpful to use a fixed structure for each ID. For example, the standard LGTM queries have the following format: ``<language>/<brief-description>``. |
-+-----------------------+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| ``@kind``             | | ``problem``             | Identifies the query is an alert (``@kind problem``) or a path (``@kind path-problem``). For more information on these query types, see ":doc:`About CodeQL queries <introduction-to-queries>`."                                                                                                                                                     |
-|                       | | ``path-problem``        |                                                                                                                                                                                                                                                                                                                                                      |
-+-----------------------+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| ``@name``             | ``<text>``                | A statement that defines the label of the query. The name is written in plain text, and uses single quotes (``'``) to enclose code elements.                                                                                                                                                                                                         |
-+-----------------------+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| ``@tags``             | | ``correctness``         | These tags group queries together in broad categories to make it easier to search for them and identify them. In addition to the common tags listed here, there are also a number of more specific categories. For more information, see the                                                                                                         |
-|                       | | ``maintainability``     | `Query metadata style guide <https://github.com/github/codeql/blob/main/docs/query-metadata-style-guide.md>`__.                                                                                                                                                                                                                                      |
-|                       | | ``readability``         |                                                                                                                                                                                                                                                                                                                                                      |
-|                       | | ``security``            |                                                                                                                                                                                                                                                                                                                                                      |
-+-----------------------+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| ``@precision``        | | ``low``                 | Indicates the percentage of query results that are true positives (as opposed to false positive results). This, along with the ``@problem.severity`` property, determines whether the results are displayed by default on LGTM.                                                                                                                      |
-|                       | | ``medium``              |                                                                                                                                                                                                                                                                                                                                                      |
-|                       | | ``high``                |                                                                                                                                                                                                                                                                                                                                                      |
-|                       | | ``very-high``           |                                                                                                                                                                                                                                                                                                                                                      |
-+-----------------------+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| ``@problem.severity`` | | ``error``               | Defines the level of severity of any alerts generated by the query. This, along with the ``@precision`` property, determines whether the results are displayed by default on LGTM.                                                                                                                                                                   |
-|                       | | ``warning``             |                                                                                                                                                                                                                                                                                                                                                      |
-|                       | | ``recommendation``      |                                                                                                                                                                                                                                                                                                                                                      |
-+-----------------------+---------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
++-----------------------+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Property              | Value                     | Description                                                                                                                                                                                                                                                                                                                                                           |
++=======================+===========================+=======================================================================================================================================================================================================================================================================================================================================================================+
+| ``@description``      | ``<text>``                | A sentence or short paragraph to describe the purpose of the query and *why* the result is useful or important. The description is written in plain text, and uses single quotes (``'``) to enclose code elements.                                                                                                                                                    |
++-----------------------+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``@id``               | ``<text>``                | A sequence of words composed of lowercase letters or digits, delimited by ``/`` or ``-``, identifying and classifying the query. Each query must have a **unique** ID. To ensure this, it may be helpful to use a fixed structure for each ID. For example, the standard LGTM queries have the following format: ``<ql-language-specification>/<brief-description>``. |
++-----------------------+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``@kind``             | | ``problem``             | Identifies the query is an alert (``@kind problem``) or a path (``@kind path-problem``). For more information on these query types, see ":doc:`About CodeQL queries <about-codeql-queries>`."                                                                                                                                                                         |
+|                       | | ``path-problem``        |                                                                                                                                                                                                                                                                                                                                                                       |
++-----------------------+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``@name``             | ``<text>``                | A statement that defines the label of the query. The name is written in plain text, and uses single quotes (``'``) to enclose code elements.                                                                                                                                                                                                                          |
++-----------------------+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``@tags``             | | ``correctness``         | These tags group queries together in broad categories to make it easier to search for them and identify them. In addition to the common tags listed here, there are also a number of more specific categories. For more information, see the                                                                                                                          |
+|                       | | ``maintainability``     | `Query metadata style guide <https://github.com/github/codeql/blob/main/docs/query-metadata-style-guide.md>`__.                                                                                                                                                                                                                                                       |
+|                       | | ``readability``         |                                                                                                                                                                                                                                                                                                                                                                       |
+|                       | | ``security``            |                                                                                                                                                                                                                                                                                                                                                                       |
++-----------------------+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``@precision``        | | ``low``                 | Indicates the percentage of query results that are true positives (as opposed to false positive results). This, along with the ``@problem.severity`` property, determines whether the results are displayed by default on LGTM.                                                                                                                                       |
+|                       | | ``medium``              |                                                                                                                                                                                                                                                                                                                                                                       |
+|                       | | ``high``                |                                                                                                                                                                                                                                                                                                                                                                       |
+|                       | | ``very-high``           |                                                                                                                                                                                                                                                                                                                                                                       |
++-----------------------+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``@problem.severity`` | | ``error``               | Defines the level of severity of any alerts generated by the query. This, along with the ``@precision`` property, determines whether the results are displayed by default on LGTM.                                                                                                                                                                                    |
+|                       | | ``warning``             |                                                                                                                                                                                                                                                                                                                                                                       |
+|                       | | ``recommendation``      |                                                                                                                                                                                                                                                                                                                                                                       |
++-----------------------+---------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
 Additional properties for filter queries
 ----------------------------------------
diff --git a/docs/language/learn-ql/writing-queries/troubleshooting-query-performance.rst b/docs/language/learn-ql/writing-queries/troubleshooting-query-performance.rst
index b8e2f668b0c..098594d19fe 100644
--- a/docs/language/learn-ql/writing-queries/troubleshooting-query-performance.rst
+++ b/docs/language/learn-ql/writing-queries/troubleshooting-query-performance.rst
@@ -11,7 +11,7 @@ Before reading the tips below, it is worth reiterating a few important points ab
 
 - CodeQL `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ and `classes <https://help.semmle.com/QL/ql-handbook/types.html#classes>`__ are evaluated to database `tables <https://en.wikipedia.org/wiki/Table_(database)>`__. Large predicates generate large tables with many rows, and are therefore expensive to compute.
 - The QL language is implemented using standard database operations and `relational algebra <https://en.wikipedia.org/wiki/Relational_algebra>`__ (such as join, projection, and union). For more information about query languages and databases, see `About the QL language <https://help.semmle.com/QL/learn-ql/about-ql.html>`__.
-- Queries are evaluated *bottom-up*, which means that a predicate is not evaluated until *all* of the predicates that it depends on are evaluated. For more information on query evaluation, see "`Evaluation of QL programs <https://help.semmle.com/QL/ql-handbook/evaluation.html>`__." 
+- Queries are evaluated *bottom-up*, which means that a predicate is not evaluated until *all* of the predicates that it depends on are evaluated. For more information on query evaluation, see "`Evaluation of QL programs <https://help.semmle.com/QL/ql-handbook/evaluations-of-ql-programs.html>`__." 
 
 Performance tips
 ----------------
diff --git a/docs/language/ql-handbook/about-the-ql-language.rst b/docs/language/ql-handbook/about-the-ql-language.rst
index 8cb5d265054..5241f4c035d 100644
--- a/docs/language/ql-handbook/about-the-ql-language.rst
+++ b/docs/language/ql-handbook/about-the-ql-language.rst
@@ -42,7 +42,7 @@ When you write this process in QL, it closely resembles the above structure. Not
 For more information about the important concepts and syntactic constructs of QL, see the individual reference topics such as ":doc:`Expressions <expressions>`" and ":doc:`Recursion <recursion>`."
 The explanations and examples help you understand how the language works, and how to write more advanced QL code.
 
-For formal specifications of the QL language and QLDoc comments, see the ":doc:`QL language specification <language>`" and ":doc:`QLDoc comment specification <qldoc>`."
+For formal specifications of the QL language and QLDoc comments, see the ":doc:`QL language specification <ql-language-specification>`" and ":doc:`QLDoc comment specification <qldoc-comment-specification>`."
 
 QL and object orientation
 -------------------------
diff --git a/docs/language/ql-handbook/annotations.rst b/docs/language/ql-handbook/annotations.rst
index 75611f317a5..968fda5f045 100644
--- a/docs/language/ql-handbook/annotations.rst
+++ b/docs/language/ql-handbook/annotations.rst
@@ -41,7 +41,7 @@ Overview of annotations
 
 This section describes what the different annotations do, and when you can use them.
 You can also find a summary table in the Annotations section of the 
-`QL language specification <https://help.semmle.com/QL/ql-spec/language.html#annotations>`_.
+`QL language specification <https://help.semmle.com/QL/ql-spec/language.html#annotations-in-java>`_.
 
 .. index:: abstract
 .. _abstract:
diff --git a/docs/language/ql-handbook/evaluations-of-ql-programs.rst b/docs/language/ql-handbook/evaluation-of-ql-programs.rst
similarity index 98%
rename from docs/language/ql-handbook/evaluations-of-ql-programs.rst
rename to docs/language/ql-handbook/evaluation-of-ql-programs.rst
index e76a0898b23..31520ebc0a6 100644
--- a/docs/language/ql-handbook/evaluations-of-ql-programs.rst
+++ b/docs/language/ql-handbook/evaluation-of-ql-programs.rst
@@ -33,7 +33,7 @@ results of the program. The results are sorted according to any ordering directi
 (``order by``) in the queries.
 
 For more details about each step of the evaluation process, see the "`QL language specification
-<https://help.semmle.com/QL/ql-spec/language.html#evaluation>`_."
+<https://help.semmle.com/QL/ql-spec/language.html#evaluations-of-ql-programs>`_."
 
 Validity of programs
 ********************
diff --git a/docs/language/ql-handbook/index.rst b/docs/language/ql-handbook/index.rst
index ec4ab6d671e..1b68f5d8586 100644
--- a/docs/language/ql-handbook/index.rst
+++ b/docs/language/ql-handbook/index.rst
@@ -19,6 +19,6 @@ Learn all about QL, the powerful query language that underlies the code scanning
    recursion
    lexical-syntax
    name-resolution
-   evaluation
-   language
-   qldoc
\ No newline at end of file
+   evaluation-of-ql-programs
+   ql-language-specification
+   qldoc-comment-specification
\ No newline at end of file
diff --git a/docs/language/ql-handbook/lexical-syntax.rst b/docs/language/ql-handbook/lexical-syntax.rst
index f9e1dc59912..48af48f4614 100644
--- a/docs/language/ql-handbook/lexical-syntax.rst
+++ b/docs/language/ql-handbook/lexical-syntax.rst
@@ -19,7 +19,7 @@ All standard one-line and multiline comments, as described in the "`QL language
 compiler and are only visible in the source code.
 You can also write another kind of comment, namely **QLDoc comments**. These comments describe
 QL entities and are displayed as pop-up information in QL editors. For information about QLDoc
-comments, see the "`QLDoc comment specification <https://help.semmle.com/QL/ql-spec/qldoc.html>`_."
+comments, see the "`QLDoc comment specification <https://help.semmle.com/QL/ql-spec/qldoc-comment-specification.html>`_."
 
 The following example uses these three different kinds of comments::
 

From d749b839fa2a7bc8492a77c48bc7b4b61e6eda3b Mon Sep 17 00:00:00 2001
From: james <james@semmle.com>
Date: Thu, 5 Nov 2020 14:40:45 +0000
Subject: [PATCH 3/5] ql lang spec: update links

---
 docs/language/learn-ql/beginner/cross-the-river.rst     | 2 +-
 docs/language/learn-ql/introduction-to-ql.rst           | 2 +-
 docs/language/ql-handbook/annotations.rst               | 2 +-
 docs/language/ql-handbook/evaluation-of-ql-programs.rst | 4 ++--
 docs/language/ql-handbook/expressions.rst               | 4 ++--
 docs/language/ql-handbook/formulas.rst                  | 2 +-
 docs/language/ql-handbook/lexical-syntax.rst            | 4 ++--
 docs/language/ql-handbook/modules.rst                   | 4 ++--
 docs/language/ql-handbook/name-resolution.rst           | 8 ++++----
 docs/language/ql-handbook/predicates.rst                | 4 ++--
 docs/language/ql-handbook/types.rst                     | 6 +++---
 docs/language/ql-handbook/variables.rst                 | 2 +-
 12 files changed, 22 insertions(+), 22 deletions(-)

diff --git a/docs/language/learn-ql/beginner/cross-the-river.rst b/docs/language/learn-ql/beginner/cross-the-river.rst
index 33eaeea2f2e..cce51fadfaa 100644
--- a/docs/language/learn-ql/beginner/cross-the-river.rst
+++ b/docs/language/learn-ql/beginner/cross-the-river.rst
@@ -203,7 +203,7 @@ the given path without revisiting any previously visited states.
     revisiting any previous states, and there is a ``safeFerry`` action from the intermediate state to
     the result state.
     (Hint: To check whether a state has previously been visited, you could check if
-    there is an `index of <https://help.semmle.com/QL/ql-spec/language.html#built-ins-for-string>`__
+    there is an `index of <ql-language-specification#built-ins-for-string>`__
     ``visitedStates`` at which the state occurs.)
 
 .. container:: toggle
diff --git a/docs/language/learn-ql/introduction-to-ql.rst b/docs/language/learn-ql/introduction-to-ql.rst
index 9305f3e404f..6ab7e11b1b4 100644
--- a/docs/language/learn-ql/introduction-to-ql.rst
+++ b/docs/language/learn-ql/introduction-to-ql.rst
@@ -53,7 +53,7 @@ You can write simple queries using the some of the basic functions that are avai
 Exercise 1
 ~~~~~~~~~~
 
-Write a query which returns the length of the string ``"lgtm"``. (Hint: `here <https://help.semmle.com/QL/ql-spec/language.html#built-ins-for-string>`__ is the list of the functions that can be applied to strings.)
+Write a query which returns the length of the string ``"lgtm"``. (Hint: `here <ql-language-specification#built-ins-for-string>`__ is the list of the functions that can be applied to strings.)
 
 ➤ `See answer in the query console on LGTM.com <https://lgtm.com/query/2103060623/>`__
 
diff --git a/docs/language/ql-handbook/annotations.rst b/docs/language/ql-handbook/annotations.rst
index 968fda5f045..9ef2f269432 100644
--- a/docs/language/ql-handbook/annotations.rst
+++ b/docs/language/ql-handbook/annotations.rst
@@ -41,7 +41,7 @@ Overview of annotations
 
 This section describes what the different annotations do, and when you can use them.
 You can also find a summary table in the Annotations section of the 
-`QL language specification <https://help.semmle.com/QL/ql-spec/language.html#annotations-in-java>`_.
+`QL language specification <ql-language-specification#annotations-in-java>`_.
 
 .. index:: abstract
 .. _abstract:
diff --git a/docs/language/ql-handbook/evaluation-of-ql-programs.rst b/docs/language/ql-handbook/evaluation-of-ql-programs.rst
index 31520ebc0a6..da61306252d 100644
--- a/docs/language/ql-handbook/evaluation-of-ql-programs.rst
+++ b/docs/language/ql-handbook/evaluation-of-ql-programs.rst
@@ -21,7 +21,7 @@ A QL program is evaluated from the bottom up, so a predicate is usually only eva
 all the predicates it depends on are evaluated. 
 
 The database includes sets of ordered tuples for the `built-in predicates 
-<https://help.semmle.com/QL/ql-spec/language.html#built-ins>`_ and :ref:`external predicates <external>`. 
+<ql-language-specification#built-ins>`_ and :ref:`external predicates <external>`. 
 Each evaluation starts from these sets of tuples.
 The remaining predicates and types in the program are organized into a number of layers, based 
 on the dependencies between them.
@@ -33,7 +33,7 @@ results of the program. The results are sorted according to any ordering directi
 (``order by``) in the queries.
 
 For more details about each step of the evaluation process, see the "`QL language specification
-<https://help.semmle.com/QL/ql-spec/language.html#evaluations-of-ql-programs>`_."
+<ql-language-specification#evaluations-of-ql-programs>`_."
 
 Validity of programs
 ********************
diff --git a/docs/language/ql-handbook/expressions.rst b/docs/language/ql-handbook/expressions.rst
index f7ad2527833..cd3e65c982e 100644
--- a/docs/language/ql-handbook/expressions.rst
+++ b/docs/language/ql-handbook/expressions.rst
@@ -55,7 +55,7 @@ You can express certain values directly in QL, such as numbers, booleans, and st
     "hello"
     "They said, \"Please escape quotation marks!\""
   
-  See `String literals <https://help.semmle.com/QL/ql-spec/language.html#string-literals-string>`_ 
+  See `String literals <ql-language-specification#string-literals-string>`_ 
   in the QL language specification for more details. 
     
   Note: there is no "date literal" in QL. Instead, to specify a :ref:`date <date>`, you should
@@ -529,7 +529,7 @@ The following table lists some examples of different forms of ``any`` expression
 +------------------------------------------+-------------------------------------------------+
 
 .. note::
-   There is also a `built-in predicate <https://help.semmle.com/QL/ql-spec/language.html#non-member-built-ins>`_
+   There is also a `built-in predicate <ql-language-specification#non-member-built-ins>`_
    ``any()``. This is a predicate that always holds.
 
 Unary operations
diff --git a/docs/language/ql-handbook/formulas.rst b/docs/language/ql-handbook/formulas.rst
index bc9b70ecdea..a124315eb8a 100644
--- a/docs/language/ql-handbook/formulas.rst
+++ b/docs/language/ql-handbook/formulas.rst
@@ -33,7 +33,7 @@ Order
 
 To compare two expressions using one of these order operators, each expression must have a type
 and those types must be :ref:`compatible <type-compatibility>` and 
-`orderable <https://help.semmle.com/QL/ql-spec/language.html#ordering>`_.
+`orderable <ql-language-specification#ordering>`_.
 
 +--------------------------+--------+
 | Name                     | Symbol |
diff --git a/docs/language/ql-handbook/lexical-syntax.rst b/docs/language/ql-handbook/lexical-syntax.rst
index 48af48f4614..fc57cc6ef5b 100644
--- a/docs/language/ql-handbook/lexical-syntax.rst
+++ b/docs/language/ql-handbook/lexical-syntax.rst
@@ -6,7 +6,7 @@ Lexical syntax
 The QL syntax includes different kinds of keywords, identifiers, and comments.
 
 For an overview of the lexical syntax, see "`Lexical syntax 
-<https://help.semmle.com/QL/ql-spec/language.html#lexical-syntax>`_" in the QL language specification.
+<ql-language-specification#lexical-syntax>`_" in the QL language specification.
 
 .. index:: comment, QLDoc
 .. _comments:
@@ -15,7 +15,7 @@ Comments
 ********
 
 All standard one-line and multiline comments, as described in the "`QL language specification 
-<https://help.semmle.com/QL/ql-spec/language.html#comments>`_," are ignored by the QL 
+<ql-language-specification#comments>`_," are ignored by the QL 
 compiler and are only visible in the source code.
 You can also write another kind of comment, namely **QLDoc comments**. These comments describe
 QL entities and are displayed as pop-up information in QL editors. For information about QLDoc
diff --git a/docs/language/ql-handbook/modules.rst b/docs/language/ql-handbook/modules.rst
index 9991ef70f4e..dbfc1678d00 100644
--- a/docs/language/ql-handbook/modules.rst
+++ b/docs/language/ql-handbook/modules.rst
@@ -25,7 +25,7 @@ a class ``OneTwoThree``::
       }
     } 
 
-The name of a module can be any `identifier <https://help.semmle.com/QL/ql-spec/language.html#identifiers>`_
+The name of a module can be any `identifier <ql-language-specification#identifiers>`_
 that starts with an uppercase or lowercase letter. 
 
 ``.ql`` or ``.qll`` files also implicitly define modules.
@@ -178,5 +178,5 @@ for example ``import javascript as js``.
 The ``<module_expression>`` itself can be a module name, a selection, or a qualified
 reference. For more information, see ":ref:`name-resolution`."
 
-For information about how import statements are looked up, see "`Module resolution <https://help.semmle.com/QL/ql-spec/language.html#module-resolution>`__"
+For information about how import statements are looked up, see "`Module resolution <ql-language-specification#module-resolution>`__"
 in the QL language specification. 
\ No newline at end of file
diff --git a/docs/language/ql-handbook/name-resolution.rst b/docs/language/ql-handbook/name-resolution.rst
index 95f6b669751..93cdbd97c43 100644
--- a/docs/language/ql-handbook/name-resolution.rst
+++ b/docs/language/ql-handbook/name-resolution.rst
@@ -74,7 +74,7 @@ statement as follows:
   #. If the compiler can't find the library file using the above two checks, it looks up ``examples/security/MyLibrary.qll``
      relative to each library path entry.
      The library path is usually specified using the ``libraryPathDependencies`` of the ``qlpack.yml`` file, though it may also depend on the tools you use to run your query, and whether you have specified any extra settings.
-     For more information, see "`Library path <https://help.semmle.com/QL/ql-spec/language.html#library-path>`__" in the QL language specification.
+     For more information, see "`Library path <ql-language-specification#library-path>`__" in the QL language specification.
      
 If the compiler cannot resolve an import statement, then it gives a compilation error.
 
@@ -146,7 +146,7 @@ Namespaces
 **********
 
 When writing QL, it's useful to understand how namespaces (also known as 
-`environments <https://help.semmle.com/QL/ql-spec/language.html#name-resolution>`_) work.
+`environments <ql-language-specification#name-resolution>`_) work.
 
 As in many other programming languages, a namespace is a mapping from **keys** to
 **entities**. A key is a kind of identifier, for example a name, and a QL entity is
@@ -173,7 +173,7 @@ In particular:
     - The **global module namespace** is empty.
     - The **global type namespace** has entries for the :ref:`primitive types <primitive-types>` ``int``, ``float``, 
       ``string``, ``boolean``, and ``date``, as well as any :ref:`database types <database-types>` defined in the database schema.
-    - The **global predicate namespace** includes all the `built-in predicates <https://help.semmle.com/QL/ql-spec/language.html#built-ins>`_,
+    - The **global predicate namespace** includes all the `built-in predicates <ql-language-specification#built-ins>`_,
       as well as any :ref:`database predicates <database-predicates>`.
 
 In practice, this means that you can use the built-in types and predicates directly in a QL module (without
@@ -289,7 +289,7 @@ The type namespace of ``S`` has entries for:
 The predicate namespace of ``Villagers`` has entries for:
     - The predicate ``isBald``, with arity 1.
     - Any predicates (and their arities) exported by ``tutorial``. 
-    - The `built-in predicates <https://help.semmle.com/QL/ql-spec/language.html#built-ins>`_.
+    - The `built-in predicates <ql-language-specification#built-ins>`_.
 
 The predicate namespace of ``S`` has entries for:
     - All the above predicates.
diff --git a/docs/language/ql-handbook/predicates.rst b/docs/language/ql-handbook/predicates.rst
index cf5b7fdc0cd..512f7d8109d 100644
--- a/docs/language/ql-handbook/predicates.rst
+++ b/docs/language/ql-handbook/predicates.rst
@@ -33,7 +33,7 @@ The `arity <https://en.wikipedia.org/wiki/Arity>`_ of these predicates is one an
 In general, all tuples in a predicate have the same number of elements. The **arity** of 
 a predicate is that number of elements, not including a possible ``result`` variable. For more information, see ":ref:`predicates-with-result`."
 
-There are a number of `built-in predicates <https://help.semmle.com/QL/ql-spec/language.html#built-ins>`_ 
+There are a number of `built-in predicates <ql-language-specification#built-ins>`_ 
 in QL. You can use these in any queries without needing to :ref:`import <importing-modules>`
 any additional modules. In addition to these built-in predicates, you can also define your
 own:
@@ -45,7 +45,7 @@ When defining a predicate, you should specify:
 
 #. The keyword ``predicate`` (for a :ref:`predicate without result <predicates-without-result>`), 
    or the type of the result (for a :ref:`predicate with result <predicates-with-result>`).
-#. The name of the predicate. This is an `identifier <https://help.semmle.com/QL/ql-spec/language.html#identifiers>`_ 
+#. The name of the predicate. This is an `identifier <ql-language-specification#identifiers>`_ 
    starting with a lowercase letter.
 #. The arguments to the predicate, if any, separated by commas. For each argument, specify the
    argument type and an identifier for the argument variable.
diff --git a/docs/language/ql-handbook/types.rst b/docs/language/ql-handbook/types.rst
index 7765f5de4b8..e6342fef3ba 100644
--- a/docs/language/ql-handbook/types.rst
+++ b/docs/language/ql-handbook/types.rst
@@ -48,7 +48,7 @@ independent of the database that you are querying.
     
 
 QL has a range of built-in operations defined on primitive types. These are available by using dispatch on expressions of the appropriate type. For example, ``1.toString()`` is the string representation of the integer constant ``1``. For a full list of built-in operations available in QL, see the
-section on `built-ins <https://help.semmle.com/QL/ql-spec/language.html#built-ins>`__ in the QL language specification.
+section on `built-ins <ql-language-specification#built-ins>`__ in the QL language specification.
 
 .. index:: class
 .. _classes:
@@ -74,7 +74,7 @@ Defining a class
 To define a class, you write:
 
 #. The keyword ``class``. 
-#. The name of the class. This is an `identifier <https://help.semmle.com/QL/ql-spec/language.html#identifiers>`_ 
+#. The name of the class. This is an `identifier <ql-language-specification#identifiers>`_ 
    starting with an uppercase letter.
 #. The types to extend. 
 #. The :ref:`body of the class <class-bodies>`, enclosed in braces.
@@ -419,7 +419,7 @@ The branch definitions have the following form::
 
     <BranchName>(<arguments>) { <body> }
 
-- The type name and the branch names must be `identifiers <https://help.semmle.com/QL/ql-spec/language.html#identifiers>`_ 
+- The type name and the branch names must be `identifiers <ql-language-specification#identifiers>`_ 
   starting with an uppercase letter. Conventionally, they start with ``T``.
 - The different branches of an algebraic datatype are separated by ``or``.
 - The arguments to a branch, if any, are :ref:`variable declarations <variable-declarations>`
diff --git a/docs/language/ql-handbook/variables.rst b/docs/language/ql-handbook/variables.rst
index 5137000020c..7a007b93de4 100644
--- a/docs/language/ql-handbook/variables.rst
+++ b/docs/language/ql-handbook/variables.rst
@@ -20,7 +20,7 @@ Declaring a variable
 ********************
 
 All variable declarations consist of a :ref:`type <types>` and a name for the variable. 
-The name can be any `identifier <https://help.semmle.com/QL/ql-spec/language.html#identifiers>`_
+The name can be any `identifier <ql-language-specification#identifiers>`_
 that starts with an uppercase or lowercase letter.
 
 For example, ``int i``, ``SsaDefinitionNode node``, and ``LocalScopeVariable lsv`` declare

From e5fff6445a15e768283b034adfb471070d5ed55e Mon Sep 17 00:00:00 2001
From: james <james@semmle.com>
Date: Thu, 5 Nov 2020 14:43:39 +0000
Subject: [PATCH 4/5] rename ql-handbook -> ql-language-reference

---
 docs/language/{ql-handbook => ql-language-reference}/.gitignore   | 0
 .../about-the-ql-language.rst                                     | 0
 docs/language/{ql-handbook => ql-language-reference}/aliases.rst  | 0
 .../{ql-handbook => ql-language-reference}/annotations.rst        | 0
 docs/language/{ql-handbook => ql-language-reference}/conf.py      | 0
 .../evaluation-of-ql-programs.rst                                 | 0
 .../{ql-handbook => ql-language-reference}/expressions.rst        | 0
 docs/language/{ql-handbook => ql-language-reference}/formulas.rst | 0
 docs/language/{ql-handbook => ql-language-reference}/index.rst    | 0
 .../{ql-handbook => ql-language-reference}/lexical-syntax.rst     | 0
 docs/language/{ql-handbook => ql-language-reference}/modules.rst  | 0
 .../{ql-handbook => ql-language-reference}/name-resolution.rst    | 0
 .../{ql-handbook => ql-language-reference}/predicates.rst         | 0
 .../ql-language-specification.rst                                 | 0
 .../qldoc-comment-specification.rst                               | 0
 docs/language/{ql-handbook => ql-language-reference}/queries.rst  | 0
 .../language/{ql-handbook => ql-language-reference}/recursion.rst | 0
 docs/language/{ql-handbook => ql-language-reference}/types.rst    | 0
 .../language/{ql-handbook => ql-language-reference}/variables.rst | 0
 19 files changed, 0 insertions(+), 0 deletions(-)
 rename docs/language/{ql-handbook => ql-language-reference}/.gitignore (100%)
 rename docs/language/{ql-handbook => ql-language-reference}/about-the-ql-language.rst (100%)
 rename docs/language/{ql-handbook => ql-language-reference}/aliases.rst (100%)
 rename docs/language/{ql-handbook => ql-language-reference}/annotations.rst (100%)
 rename docs/language/{ql-handbook => ql-language-reference}/conf.py (100%)
 rename docs/language/{ql-handbook => ql-language-reference}/evaluation-of-ql-programs.rst (100%)
 rename docs/language/{ql-handbook => ql-language-reference}/expressions.rst (100%)
 rename docs/language/{ql-handbook => ql-language-reference}/formulas.rst (100%)
 rename docs/language/{ql-handbook => ql-language-reference}/index.rst (100%)
 rename docs/language/{ql-handbook => ql-language-reference}/lexical-syntax.rst (100%)
 rename docs/language/{ql-handbook => ql-language-reference}/modules.rst (100%)
 rename docs/language/{ql-handbook => ql-language-reference}/name-resolution.rst (100%)
 rename docs/language/{ql-handbook => ql-language-reference}/predicates.rst (100%)
 rename docs/language/{ql-handbook => ql-language-reference}/ql-language-specification.rst (100%)
 rename docs/language/{ql-handbook => ql-language-reference}/qldoc-comment-specification.rst (100%)
 rename docs/language/{ql-handbook => ql-language-reference}/queries.rst (100%)
 rename docs/language/{ql-handbook => ql-language-reference}/recursion.rst (100%)
 rename docs/language/{ql-handbook => ql-language-reference}/types.rst (100%)
 rename docs/language/{ql-handbook => ql-language-reference}/variables.rst (100%)

diff --git a/docs/language/ql-handbook/.gitignore b/docs/language/ql-language-reference/.gitignore
similarity index 100%
rename from docs/language/ql-handbook/.gitignore
rename to docs/language/ql-language-reference/.gitignore
diff --git a/docs/language/ql-handbook/about-the-ql-language.rst b/docs/language/ql-language-reference/about-the-ql-language.rst
similarity index 100%
rename from docs/language/ql-handbook/about-the-ql-language.rst
rename to docs/language/ql-language-reference/about-the-ql-language.rst
diff --git a/docs/language/ql-handbook/aliases.rst b/docs/language/ql-language-reference/aliases.rst
similarity index 100%
rename from docs/language/ql-handbook/aliases.rst
rename to docs/language/ql-language-reference/aliases.rst
diff --git a/docs/language/ql-handbook/annotations.rst b/docs/language/ql-language-reference/annotations.rst
similarity index 100%
rename from docs/language/ql-handbook/annotations.rst
rename to docs/language/ql-language-reference/annotations.rst
diff --git a/docs/language/ql-handbook/conf.py b/docs/language/ql-language-reference/conf.py
similarity index 100%
rename from docs/language/ql-handbook/conf.py
rename to docs/language/ql-language-reference/conf.py
diff --git a/docs/language/ql-handbook/evaluation-of-ql-programs.rst b/docs/language/ql-language-reference/evaluation-of-ql-programs.rst
similarity index 100%
rename from docs/language/ql-handbook/evaluation-of-ql-programs.rst
rename to docs/language/ql-language-reference/evaluation-of-ql-programs.rst
diff --git a/docs/language/ql-handbook/expressions.rst b/docs/language/ql-language-reference/expressions.rst
similarity index 100%
rename from docs/language/ql-handbook/expressions.rst
rename to docs/language/ql-language-reference/expressions.rst
diff --git a/docs/language/ql-handbook/formulas.rst b/docs/language/ql-language-reference/formulas.rst
similarity index 100%
rename from docs/language/ql-handbook/formulas.rst
rename to docs/language/ql-language-reference/formulas.rst
diff --git a/docs/language/ql-handbook/index.rst b/docs/language/ql-language-reference/index.rst
similarity index 100%
rename from docs/language/ql-handbook/index.rst
rename to docs/language/ql-language-reference/index.rst
diff --git a/docs/language/ql-handbook/lexical-syntax.rst b/docs/language/ql-language-reference/lexical-syntax.rst
similarity index 100%
rename from docs/language/ql-handbook/lexical-syntax.rst
rename to docs/language/ql-language-reference/lexical-syntax.rst
diff --git a/docs/language/ql-handbook/modules.rst b/docs/language/ql-language-reference/modules.rst
similarity index 100%
rename from docs/language/ql-handbook/modules.rst
rename to docs/language/ql-language-reference/modules.rst
diff --git a/docs/language/ql-handbook/name-resolution.rst b/docs/language/ql-language-reference/name-resolution.rst
similarity index 100%
rename from docs/language/ql-handbook/name-resolution.rst
rename to docs/language/ql-language-reference/name-resolution.rst
diff --git a/docs/language/ql-handbook/predicates.rst b/docs/language/ql-language-reference/predicates.rst
similarity index 100%
rename from docs/language/ql-handbook/predicates.rst
rename to docs/language/ql-language-reference/predicates.rst
diff --git a/docs/language/ql-handbook/ql-language-specification.rst b/docs/language/ql-language-reference/ql-language-specification.rst
similarity index 100%
rename from docs/language/ql-handbook/ql-language-specification.rst
rename to docs/language/ql-language-reference/ql-language-specification.rst
diff --git a/docs/language/ql-handbook/qldoc-comment-specification.rst b/docs/language/ql-language-reference/qldoc-comment-specification.rst
similarity index 100%
rename from docs/language/ql-handbook/qldoc-comment-specification.rst
rename to docs/language/ql-language-reference/qldoc-comment-specification.rst
diff --git a/docs/language/ql-handbook/queries.rst b/docs/language/ql-language-reference/queries.rst
similarity index 100%
rename from docs/language/ql-handbook/queries.rst
rename to docs/language/ql-language-reference/queries.rst
diff --git a/docs/language/ql-handbook/recursion.rst b/docs/language/ql-language-reference/recursion.rst
similarity index 100%
rename from docs/language/ql-handbook/recursion.rst
rename to docs/language/ql-language-reference/recursion.rst
diff --git a/docs/language/ql-handbook/types.rst b/docs/language/ql-language-reference/types.rst
similarity index 100%
rename from docs/language/ql-handbook/types.rst
rename to docs/language/ql-language-reference/types.rst
diff --git a/docs/language/ql-handbook/variables.rst b/docs/language/ql-language-reference/variables.rst
similarity index 100%
rename from docs/language/ql-handbook/variables.rst
rename to docs/language/ql-language-reference/variables.rst

From f85f99c6c2e01e55e5319123ff5ad6652ca3cdf4 Mon Sep 17 00:00:00 2001
From: james <james@semmle.com>
Date: Thu, 5 Nov 2020 14:54:14 +0000
Subject: [PATCH 5/5] update ql-language-reference links

---
 docs/language/README.rst                       |  2 +-
 .../learn-ql/about-data-flow-analysis.rst      |  4 ++--
 .../beginner/catch-the-fire-starter.rst        |  4 ++--
 .../learn-ql/beginner/cross-the-river.rst      | 18 +++++++++---------
 .../beginner/crown-the-rightful-heir.rst       |  2 +-
 .../learn-ql/beginner/find-the-thief.rst       | 10 +++++-----
 ...ining-a-query-to-account-for-edge-cases.rst |  4 ++--
 .../learn-ql/go/basic-query-for-go-code.rst    |  4 ++--
 docs/language/learn-ql/index.rst               |  2 +-
 docs/language/learn-ql/introduction-to-ql.rst  |  2 +-
 .../overflow-prone-comparisons-in-java.rst     |  2 +-
 .../writing-queries/about-codeql-queries.rst   | 12 ++++++------
 .../writing-queries/creating-path-queries.rst  |  6 +++---
 .../troubleshooting-query-performance.rst      | 10 +++++-----
 .../codeql-ref-tools-further-reading.rst       |  2 +-
 15 files changed, 42 insertions(+), 42 deletions(-)

diff --git a/docs/language/README.rst b/docs/language/README.rst
index d47dc641b4d..e9f17d39d3e 100644
--- a/docs/language/README.rst
+++ b/docs/language/README.rst
@@ -18,7 +18,7 @@ Project structure
 The documentation currently consists of the following Sphinx projects:
 
 - ``learn-ql``–help topics to help you learn CodeQL and write queries
-- ``ql-handbook``–an overview of important concepts in QL, the language that underlies CodeQL analysis
+- ``ql-language-reference``–an overview of important concepts in QL, the language that underlies CodeQL analysis
 - ``support``–the languages and frameworks currently supported in CodeQL analysis
 - ``ql-training``–source files for the CodeQL training and variant analysis examples slide decks
 
diff --git a/docs/language/learn-ql/about-data-flow-analysis.rst b/docs/language/learn-ql/about-data-flow-analysis.rst
index edb4689fec1..61c59617379 100644
--- a/docs/language/learn-ql/about-data-flow-analysis.rst
+++ b/docs/language/learn-ql/about-data-flow-analysis.rst
@@ -49,8 +49,8 @@ flow between functions and through object properties. Global data flow, however,
 graph that do not precisely correspond to the flow of values, but model whether some value at runtime may be derived from another, for instance through a string manipulating
 operation.
 
-The data flow graph is computed using `classes <https://help.semmle.com/QL/ql-handbook/types.html#classes>`__ to model the program elements that represent the graph's nodes.
-The flow of data between the nodes is modeled using `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ to compute the graph's edges.
+The data flow graph is computed using `classes <https://help.semmle.com/QL/ql-language-reference/types.html#classes>`__ to model the program elements that represent the graph's nodes.
+The flow of data between the nodes is modeled using `predicates <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__ to compute the graph's edges.
 
 Computing an accurate and complete data flow graph presents several challenges:
 
diff --git a/docs/language/learn-ql/beginner/catch-the-fire-starter.rst b/docs/language/learn-ql/beginner/catch-the-fire-starter.rst
index 32ac89e27d6..b9886533c52 100644
--- a/docs/language/learn-ql/beginner/catch-the-fire-starter.rst
+++ b/docs/language/learn-ql/beginner/catch-the-fire-starter.rst
@@ -14,7 +14,7 @@ Read the examples below to learn how to define predicates and classes in QL. The
 Select the southerners
 ----------------------
 
-This time you only need to consider a specific group of villagers, namely those living in the south of the village. Instead of writing ``getLocation() = "south"`` in all your queries, you could define a new `predicate <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ ``isSouthern``:
+This time you only need to consider a specific group of villagers, namely those living in the south of the village. Instead of writing ``getLocation() = "south"`` in all your queries, you could define a new `predicate <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__ ``isSouthern``:
 
 .. code-block:: ql
 
@@ -41,7 +41,7 @@ You can now list all southerners using:
    where isSouthern(p)
    select p
 
-This is already a nice way to simplify the logic, but we could be more efficient. Currently, the query looks at every ``Person p``, and then restricts to those who satisfy ``isSouthern(p)``. Instead, we could define a new `class <https://help.semmle.com/QL/ql-handbook/types.html#classes>`__ ``Southerner`` containing precisely the people we want to consider.
+This is already a nice way to simplify the logic, but we could be more efficient. Currently, the query looks at every ``Person p``, and then restricts to those who satisfy ``isSouthern(p)``. Instead, we could define a new `class <https://help.semmle.com/QL/ql-language-reference/types.html#classes>`__ ``Southerner`` containing precisely the people we want to consider.
 
 .. code-block:: ql
 
diff --git a/docs/language/learn-ql/beginner/cross-the-river.rst b/docs/language/learn-ql/beginner/cross-the-river.rst
index cce51fadfaa..9212fcaeee2 100644
--- a/docs/language/learn-ql/beginner/cross-the-river.rst
+++ b/docs/language/learn-ql/beginner/cross-the-river.rst
@@ -20,8 +20,8 @@ A solution should be a set of instructions for how to ferry the items, such as "
 across the river, and come back with nothing. Then ferry the cabbage across, and come back with ..."
 
 There are lots of ways to approach this problem and implement it in QL. Before you start, make
-sure that you are familiar with how to define `classes <https://help.semmle.com/QL/ql-handbook/types.html#classes>`__
-and `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ in QL.
+sure that you are familiar with how to define `classes <https://help.semmle.com/QL/ql-language-reference/types.html#classes>`__
+and `predicates <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__ in QL.
 The following walkthrough is just one of many possible implementations, so have a go at writing your
 own query too! To find more example queries, see the list :ref:`below <alternatives>`.
 
@@ -69,7 +69,7 @@ For example, if the man is on the left shore, the goat on the right shore, and t
 shore, the state should be ``Left, Right, Left, Left``.
 
 You may find it helpful to introduce some variables that refer to the shore on which the man and the cargo items are. These
-temporary variables in the body of a class are called `fields <https://help.semmle.com/QL/ql-handbook/types.html#fields>`__.
+temporary variables in the body of a class are called `fields <https://help.semmle.com/QL/ql-language-reference/types.html#fields>`__.
 
 .. container:: toggle
 
@@ -159,12 +159,12 @@ could ferry the goat back and forth any number of times without ever reaching an
 Such a path would have an infinite number of river crossings without ever solving the puzzle.
 
 One way to restrict our paths to a finite number of river crossings is to define a 
-`member predicate <https://help.semmle.com/QL/ql-handbook/types.html#member-predicates>`__
+`member predicate <https://help.semmle.com/QL/ql-language-reference/types.html#member-predicates>`__
 ``State reachesVia(string path, int steps)``.
 The result of this predicate is any state that is reachable from the current state (``this``) via
 the given path in a specified finite number of steps.
 
-You can write this as a `recursive predicate <https://help.semmle.com/QL/ql-handbook/recursion.html>`__,
+You can write this as a `recursive predicate <https://help.semmle.com/QL/ql-language-reference/recursion.html>`__,
 with the following base case and recursion step:
 
   - If ``this`` *is* the result state, then it (trivially) reaches the result state via an
@@ -218,7 +218,7 @@ the given path without revisiting any previously visited states.
 Display the results
 ~~~~~~~~~~~~~~~~~~~
 
-Once you've defined all the necessary classes and predicates, write a `select clause <https://help.semmle.com/QL/ql-handbook/queries.html#select-clauses>`__
+Once you've defined all the necessary classes and predicates, write a `select clause <https://help.semmle.com/QL/ql-language-reference/queries.html#select-clauses>`__
 that returns the resulting path.
 
 .. container:: toggle
@@ -230,7 +230,7 @@ that returns the resulting path.
    .. literalinclude:: river-crossing.ql
       :lines: 115-117
 
-The `don't-care expression <https://help.semmle.com/QL/ql-handbook/expressions.html#don-t-care-expressions>`__ (``_``),
+The `don't-care expression <https://help.semmle.com/QL/ql-language-reference/expressions.html#don-t-care-expressions>`__ (``_``),
 as the second argument to the ``reachesVia`` predicate, represents any value of ``visitedStates``.
 
 For now, the path defined in ``reachesVia`` just lists the order of cargo items to ferry.
@@ -254,12 +254,12 @@ Here are some more example queries that solve the river crossing puzzle:
      ➤ `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>`__
+     `abstract <https://help.semmle.com/QL/ql-language-reference/annotations.html#abstract>`__
      class and predicate. It also displays the resulting path in a more visual way.
 
      ➤ `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>`__
+  #. This query introduces `algebraic datatypes <https://help.semmle.com/QL/ql-language-reference/types.html#algebraic-datatypes>`__
      to model the situation, instead of defining everything as a subclass of ``string``.
 
      ➤ `See solution in the query console on LGTM.com <https://lgtm.com/query/7260748307619718263/>`__
diff --git a/docs/language/learn-ql/beginner/crown-the-rightful-heir.rst b/docs/language/learn-ql/beginner/crown-the-rightful-heir.rst
index 7e6c6a80d67..a433740bc12 100644
--- a/docs/language/learn-ql/beginner/crown-the-rightful-heir.rst
+++ b/docs/language/learn-ql/beginner/crown-the-rightful-heir.rst
@@ -106,7 +106,7 @@ You can translate this into QL as follows:
      result = parentOf(ancestorOf(p))
    }
 
-As you can see, you have used the predicate ``ancestorOf()`` inside its own definition. This is an example of `recursion <https://help.semmle.com/QL/ql-handbook/recursion.html>`__.
+As you can see, you have used the predicate ``ancestorOf()`` inside its own definition. This is an example of `recursion <https://help.semmle.com/QL/ql-language-reference/recursion.html>`__.
 
 This kind of recursion, where the same operation (in this case ``parentOf()``) is applied multiple times, is very common in QL, and is known as the *transitive closure* of the operation. There are two special symbols ``+`` and ``*`` that are extremely useful when working with transitive closures:
 
diff --git a/docs/language/learn-ql/beginner/find-the-thief.rst b/docs/language/learn-ql/beginner/find-the-thief.rst
index 2109e5d17d4..55ff6150d49 100644
--- a/docs/language/learn-ql/beginner/find-the-thief.rst
+++ b/docs/language/learn-ql/beginner/find-the-thief.rst
@@ -53,7 +53,7 @@ There is too much information to search through by hand, so you decide to use yo
 QL libraries
 ------------
 
-We've defined a number of QL `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ to help you extract data from your table. A QL predicate is a mini-query that expresses a relation between various pieces of data and describes some of their properties. In this case, the predicates give you information about a person, for example their height or age.
+We've defined a number of QL `predicates <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__ to help you extract data from your table. A QL predicate is a mini-query that expresses a relation between various pieces of data and describes some of their properties. In this case, the predicates give you information about a person, for example their height or age.
 
 +--------------------+----------------------------------------------------------------------------------------+
 | Predicate          | Description                                                                            |
@@ -84,14 +84,14 @@ The villagers answered "yes" to the question "Is the thief taller than 150cm?" T
    where t.getHeight() > 150
    select t
 
-The first line, ``from Person t``, declares that ``t`` must be a ``Person``. We say that the `type <https://help.semmle.com/QL/ql-handbook/types.html>`__ of ``t`` is ``Person``.
+The first line, ``from Person t``, declares that ``t`` must be a ``Person``. We say that the `type <https://help.semmle.com/QL/ql-language-reference/types.html>`__ of ``t`` is ``Person``.
 
 Before you use the rest of your answers in your QL search, here are some more tools and examples to help you write your own QL queries:
 
 Logical connectives
 -------------------
 
-Using `logical connectives <https://help.semmle.com/QL/ql-handbook/formulas.html#logical-connectives>`__, you can write more complex queries that combine different pieces of information.
+Using `logical connectives <https://help.semmle.com/QL/ql-language-reference/formulas.html#logical-connectives>`__, you can write more complex queries that combine different pieces of information.
 
 For example, if you know that the thief is older than 30 *and* has brown hair, you can use the following ``where`` clause to link two predicates:
 
@@ -157,7 +157,7 @@ Notice that we have only temporarily introduced the variable ``c`` and we didn't
 
    Note
 
-   If you are familiar with logic, you may notice that ``exists`` in QL corresponds to the existential `quantifier <https://help.semmle.com/QL/ql-handbook/formulas.html#quantified-formulas>`__ in logic. QL also has a universal quantifier ``forall(vars | formula 1 | formula 2)`` which is logically equivalent to ``not exists(vars | formula 1 | not formula 2)``.
+   If you are familiar with logic, you may notice that ``exists`` in QL corresponds to the existential `quantifier <https://help.semmle.com/QL/ql-language-reference/formulas.html#quantified-formulas>`__ in logic. QL also has a universal quantifier ``forall(vars | formula 1 | formula 2)`` which is logically equivalent to ``not exists(vars | formula 1 | not formula 2)``.
 
 The real investigation
 ----------------------
@@ -218,7 +218,7 @@ You are getting closer to solving the mystery! Unfortunately, you still have qui
 More advanced queries
 ---------------------
 
-What if you want to find the oldest, youngest, tallest, or shortest person in the village? As mentioned in the previous topic, you can do this using ``exists``. However, there is also a more efficient way to do this in QL using functions like ``max`` and ``min``. These are examples of `aggregates <https://help.semmle.com/QL/ql-handbook/expressions.html#aggregations>`__.
+What if you want to find the oldest, youngest, tallest, or shortest person in the village? As mentioned in the previous topic, you can do this using ``exists``. However, there is also a more efficient way to do this in QL using functions like ``max`` and ``min``. These are examples of `aggregates <https://help.semmle.com/QL/ql-language-reference/expressions.html#aggregations>`__.
 
 In general, an aggregate is a function that performs an operation on multiple pieces of data and returns a single value as its output. Common aggregates are ``count``, ``max``, ``min``, ``avg`` (average) and ``sum``. The general way to use an aggregate is:
 
diff --git a/docs/language/learn-ql/cpp/refining-a-query-to-account-for-edge-cases.rst b/docs/language/learn-ql/cpp/refining-a-query-to-account-for-edge-cases.rst
index 28651a32f68..0b2043f8966 100644
--- a/docs/language/learn-ql/cpp/refining-a-query-to-account-for-edge-cases.rst
+++ b/docs/language/learn-ql/cpp/refining-a-query-to-account-for-edge-cases.rst
@@ -102,7 +102,7 @@ You may also wish to consider methods called by constructors that assign to the
      int m_value;
    };
 
-This case can be excluded by creating a recursive predicate. The recursive predicate is given a function and a field, then checks whether the function assigns to the field. The predicate runs itself on all the functions called by the function that it has been given. By passing the constructor to this predicate, we can check for assignments of a field in all functions called by the constructor, and then do the same for all functions called by those functions all the way down the tree of function calls. For more information, see "`Recursion <https://help.semmle.com/QL/ql-handbook/recursion.html>`__" in the QL language reference.
+This case can be excluded by creating a recursive predicate. The recursive predicate is given a function and a field, then checks whether the function assigns to the field. The predicate runs itself on all the functions called by the function that it has been given. By passing the constructor to this predicate, we can check for assignments of a field in all functions called by the constructor, and then do the same for all functions called by those functions all the way down the tree of function calls. For more information, see "`Recursion <https://help.semmle.com/QL/ql-language-reference/recursion.html>`__" in the QL language reference.
 
 .. code-block:: ql
 
@@ -126,7 +126,7 @@ This case can be excluded by creating a recursive predicate. The recursive predi
 Refinement 4—simplifying the query
 ----------------------------------
 
-Finally we can simplify the query by using the transitive closure operator. In this final version of the query, ``c.calls*(fun)`` resolves to the set of all functions that are ``c`` itself, are called by ``c``, are called by a function that is called by ``c``, and so on. This eliminates the need to make a new predicate all together. For more information, see "`Transitive closures <https://help.semmle.com/QL/ql-handbook/recursion.html#transitive-closures>`__" in the QL language reference.
+Finally we can simplify the query by using the transitive closure operator. In this final version of the query, ``c.calls*(fun)`` resolves to the set of all functions that are ``c`` itself, are called by ``c``, are called by a function that is called by ``c``, and so on. This eliminates the need to make a new predicate all together. For more information, see "`Transitive closures <https://help.semmle.com/QL/ql-language-reference/recursion.html#transitive-closures>`__" in the QL language reference.
 
 .. code-block:: ql
 
diff --git a/docs/language/learn-ql/go/basic-query-for-go-code.rst b/docs/language/learn-ql/go/basic-query-for-go-code.rst
index e4dc177e903..853ac6c131f 100644
--- a/docs/language/learn-ql/go/basic-query-for-go-code.rst
+++ b/docs/language/learn-ql/go/basic-query-for-go-code.rst
@@ -99,8 +99,8 @@ After the initial ``import`` statement, this simple query comprises three parts
 | ``where recv = m.getReceiver() and                            | Defines a condition on the variables.                                                                             | ``recv = m.getReceiver()`` states that ``recv`` must be the receiver variable of ``m``.                                              |
 | w.writesField(recv.getARead(), f, _) and                      |                                                                                                                   |                                                                                                                                      |
 | not recv.getType() instanceof PointerType``                   |                                                                                                                   | ``w.writesField(recv.getARead(), f, _)`` states that ``w`` must be a location in the code where field ``f`` of ``recv`` is modified. |
-|                                                               |                                                                                                                   | We use a `'don't-care' expression <https://help.semmle.com/QL/ql-handbook/expressions.html#don-t-care-expressions>`__ _ for the      |
-|                                                               |                                                                                                                   | value that is written to ``f``—the actual value doesn't matter in this query.                                                        |
+|                                                               |                                                                                                                   | We use a `'don't-care' expression <https://help.semmle.com/QL/ql-language-reference/expressions.html#don-t-care-expressions>`__ ``_``|
+|                                                               |                                                                                                                   | for the value that is written to ``f``—the actual value doesn't matter in this query.                                                |
 |                                                               |                                                                                                                   |                                                                                                                                      |
 |                                                               |                                                                                                                   | ``not recv.getType() instanceof PointerType`` states that ``m`` is not a pointer method.                                             |
 +---------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
diff --git a/docs/language/learn-ql/index.rst b/docs/language/learn-ql/index.rst
index 0284075f3c1..54f8c9c91d7 100644
--- a/docs/language/learn-ql/index.rst
+++ b/docs/language/learn-ql/index.rst
@@ -36,4 +36,4 @@ CodeQL is based on a powerful query language called QL. The following topics hel
 Further reading
 ***************
 
-- `QL language reference <https://help.semmle.com/QL/ql-handbook/index.html>`__: A description of important concepts in QL and a formal specification of the QL language.
+- `QL language reference <https://help.semmle.com/QL/ql-language-reference/index.html>`__: A description of important concepts in QL and a formal specification of the QL language.
diff --git a/docs/language/learn-ql/introduction-to-ql.rst b/docs/language/learn-ql/introduction-to-ql.rst
index 6ab7e11b1b4..67e998f010f 100644
--- a/docs/language/learn-ql/introduction-to-ql.rst
+++ b/docs/language/learn-ql/introduction-to-ql.rst
@@ -159,4 +159,4 @@ Further reading
 
 -  To find out more about how to write your own queries, try working through the ":doc:`QL tutorials <beginner/ql-tutorials>`."
 -  For an overview of the other available resources, see ":doc:`Learning CodeQL <../index>`."
--  For a more technical description of the underlying language, see the "`QL language reference <https://help.semmle.com/QL/ql-handbook>`__."
\ No newline at end of file
+-  For a more technical description of the underlying language, see the "`QL language reference <https://help.semmle.com/QL/ql-language-reference>`__."
\ No newline at end of file
diff --git a/docs/language/learn-ql/java/overflow-prone-comparisons-in-java.rst b/docs/language/learn-ql/java/overflow-prone-comparisons-in-java.rst
index d25892c0a57..3d9c636b69e 100644
--- a/docs/language/learn-ql/java/overflow-prone-comparisons-in-java.rst
+++ b/docs/language/learn-ql/java/overflow-prone-comparisons-in-java.rst
@@ -61,7 +61,7 @@ Notice that we use the predicate ``getType`` (available on all subclasses of ``E
 
 The class ``LoopStmt`` is a common superclass of all loops, including, in particular, ``for`` loops as in our example above. While different kinds of loops have different syntax, they all have a loop condition, which can be accessed through predicate ``getCondition``. We use the reflexive transitive closure operator ``*`` applied to the ``getAChildExpr`` predicate to express the requirement that ``expr`` should be nested inside the loop condition. In particular, it can be the loop condition itself.
 
-The final conjunct in the ``where`` clause takes advantage of the fact that `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ can return more than one value (they are really relations). In particular, ``getAnOperand`` may return *either* operand of ``expr``, so ``expr.getAnOperand().isCompileTimeConstant()`` holds if at least one of the operands is constant. Negating this condition means that the query will only find expressions where *neither* of the operands is constant.
+The final conjunct in the ``where`` clause takes advantage of the fact that `predicates <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__ can return more than one value (they are really relations). In particular, ``getAnOperand`` may return *either* operand of ``expr``, so ``expr.getAnOperand().isCompileTimeConstant()`` holds if at least one of the operands is constant. Negating this condition means that the query will only find expressions where *neither* of the operands is constant.
 
 Generalizing the query
 ----------------------
diff --git a/docs/language/learn-ql/writing-queries/about-codeql-queries.rst b/docs/language/learn-ql/writing-queries/about-codeql-queries.rst
index e6dfa6a330e..0bed8105ef4 100644
--- a/docs/language/learn-ql/writing-queries/about-codeql-queries.rst
+++ b/docs/language/learn-ql/writing-queries/about-codeql-queries.rst
@@ -13,13 +13,13 @@ CodeQL includes queries to find the most relevant and interesting problems for e
 
 You can add custom queries to `custom query packs <https://lgtm.com/help/lgtm/about-queries#what-are-query-packs>`__ to analyze your projects in `LGTM <https://lgtm.com>`__, use them to analyze a database with the "`CodeQL CLI <https://help.semmle.com/codeql/codeql-cli.html>`__," or you can contribute to the standard CodeQL queries in our `open source repository on GitHub <https://github.com/github/codeql>`__.
 
-This topic is a basic introduction to query files. You can find more information on writing queries for specific programming languages `here <https://help.semmle.com/QL/learn-ql/>`__, and detailed technical information about QL in the `QL language reference <https://help.semmle.com/QL/ql-handbook/index.html>`__.
+This topic is a basic introduction to query files. You can find more information on writing queries for specific programming languages `here <https://help.semmle.com/QL/learn-ql/>`__, and detailed technical information about QL in the `QL language reference <https://help.semmle.com/QL/ql-language-reference/index.html>`__.
 For more information on how to format your code when contributing queries to the GitHub repository, see the `CodeQL style guide <https://github.com/github/codeql/blob/main/docs/ql-style-guide.md>`__.
 
 Basic query structure
 *********************
 
-`Queries <https://help.semmle.com/QL/ql-handbook/queries.html>`__ written with CodeQL have the file extension ``.ql``, and contain a ``select`` clause. Many of the existing queries include additional optional information, and have the following structure::
+`Queries <https://help.semmle.com/QL/ql-language-reference/queries.html>`__ written with CodeQL have the file extension ``.ql``, and contain a ``select`` clause. Many of the existing queries include additional optional information, and have the following structure::
 
     /**
      * 
@@ -61,7 +61,7 @@ Query metadata is used to identify your custom queries when they are added to th
 Import statements
 =================
 
-Each query generally contains one or more ``import`` statements, which define the `libraries <https://help.semmle.com/QL/ql-handbook/modules.html#library-modules>`__ or `modules <https://help.semmle.com/QL/ql-handbook/modules.html>`__ to import into the query. Libraries and modules provide a way of grouping together related `types <https://help.semmle.com/QL/ql-handbook/types.html>`__, `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__, and other modules. The contents of each library or module that you import can then be accessed by the query. 
+Each query generally contains one or more ``import`` statements, which define the `libraries <https://help.semmle.com/QL/ql-language-reference/modules.html#library-modules>`__ or `modules <https://help.semmle.com/QL/ql-language-reference/modules.html>`__ to import into the query. Libraries and modules provide a way of grouping together related `types <https://help.semmle.com/QL/ql-language-reference/types.html>`__, `predicates <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__, and other modules. The contents of each library or module that you import can then be accessed by the query. 
 Our `open source repository on GitHub <https://github.com/github/codeql>`__ contains the standard CodeQL libraries for each supported language.   
 
 When writing your own alert queries, you would typically import the standard library for the language of the project that you are querying, using ``import`` followed by a language:
@@ -80,18 +80,18 @@ You can explore the contents of all the standard libraries in the `CodeQL librar
 Optional CodeQL classes and predicates
 --------------------------------------
 
-You can customize your analysis by defining your own predicates and classes in the query. For further information, see `Defining a predicate <https://help.semmle.com/QL/ql-handbook/predicates.html#defining-a-predicate>`__ and `Defining a class <https://help.semmle.com/QL/ql-handbook/types.html#defining-a-class>`__. 
+You can customize your analysis by defining your own predicates and classes in the query. For further information, see `Defining a predicate <https://help.semmle.com/QL/ql-language-reference/predicates.html#defining-a-predicate>`__ and `Defining a class <https://help.semmle.com/QL/ql-language-reference/types.html#defining-a-class>`__. 
 
 From clause
 ===========
 
 The ``from`` clause declares the variables that are used in the query. Each declaration must be of the form ``<type> <variable name>``. 
-For more information on the available `types <https://help.semmle.com/QL/ql-handbook/types.html>`__, and to learn how to define your own types using `classes <https://help.semmle.com/QL/ql-handbook/types.html#classes>`__, see the `QL language reference <https://help.semmle.com/QL/ql-handbook/index.html>`__.
+For more information on the available `types <https://help.semmle.com/QL/ql-language-reference/types.html>`__, and to learn how to define your own types using `classes <https://help.semmle.com/QL/ql-language-reference/types.html#classes>`__, see the `QL language reference <https://help.semmle.com/QL/ql-language-reference/index.html>`__.
 
 Where clause
 ============
 
-The ``where`` clause defines the logical conditions to apply to the variables declared in the ``from`` clause to generate your results. This clause uses `aggregations <https://help.semmle.com/QL/ql-handbook/expressions.html#aggregations>`__, `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__, and logical `formulas <https://help.semmle.com/QL/ql-handbook/formulas.html>`_ to limit the variables of interest to a smaller set, which meet the defined conditions. 
+The ``where`` clause defines the logical conditions to apply to the variables declared in the ``from`` clause to generate your results. This clause uses `aggregations <https://help.semmle.com/QL/ql-language-reference/expressions.html#aggregations>`__, `predicates <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__, and logical `formulas <https://help.semmle.com/QL/ql-language-reference/formulas.html>`_ to limit the variables of interest to a smaller set, which meet the defined conditions. 
 The CodeQL libraries group commonly used predicates for specific languages and frameworks. You can also define your own predicates in the body of the query file or in your own custom modules, as described above.
 
 Select clause
diff --git a/docs/language/learn-ql/writing-queries/creating-path-queries.rst b/docs/language/learn-ql/writing-queries/creating-path-queries.rst
index cfc36cbb566..9fa0f7980f4 100644
--- a/docs/language/learn-ql/writing-queries/creating-path-queries.rst
+++ b/docs/language/learn-ql/writing-queries/creating-path-queries.rst
@@ -104,7 +104,7 @@ Generating path explanations
 ****************************
 
 In order to generate path explanations, your query needs to compute a `path graph <https://en.wikipedia.org/wiki/Path_graph>`__.
-To do this you need to define a `query predicate <https://help.semmle.com/QL/ql-handbook/queries.html#query-predicates>`__ called ``edges`` in your query.
+To do this you need to define a `query predicate <https://help.semmle.com/QL/ql-language-reference/queries.html#query-predicates>`__ called ``edges`` in your query.
 This predicate defines the edge relations of the graph you are computing, and it is used to compute the paths related to each result that your query generates. 
 You can import a predefined ``edges`` predicate from a path graph module in one of the standard data flow libraries. In addition to the path graph module, the data flow libraries contain the other ``classes``, ``predicates``, and ``modules`` that are commonly used in data flow analysis. The import statement to use depends on the language that you are analyzing.
 
@@ -151,7 +151,7 @@ The configuration class is accessed by importing the data flow library. This cla
 
 For more information on using the configuration class in your analysis see the sections on global data flow in ":doc:`Analyzing data flow in C/C++ <../cpp/analyzing-data-flow-in-cpp>`" and ":doc:`Analyzing data flow in C# <../csharp/analyzing-data-flow-in-csharp>`."
 
-You can also create a configuration for different frameworks and environments by extending the ``Configuration`` class. For more information, see "`Types <https://help.semmle.com/QL/ql-handbook/types.html#defining-a-class>`__" in the QL language reference.
+You can also create a configuration for different frameworks and environments by extending the ``Configuration`` class. For more information, see "`Types <https://help.semmle.com/QL/ql-language-reference/types.html#defining-a-class>`__" in the QL language reference.
 
 If you are querying Python code (and you have used ``import semmle.python.security.Paths`` in your query) you should declare ``TaintedPathSource source, TaintedPathSink sink`` in your ``from`` statement. You do not need to declare a ``Configuration`` class as the definitions of the ``TaintedPathSource`` and ``TaintedPathSink`` contain all of the type information that is required::
 
@@ -163,7 +163,7 @@ Defining flow conditions
 ************************
 
 The ``where`` clause defines the logical conditions to apply to the variables declared in the ``from`` clause to generate your results. 
-This clause can use `aggregations <https://help.semmle.com/QL/ql-handbook/expressions.html#aggregations>`__, `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__, and logical `formulas <https://help.semmle.com/QL/ql-handbook/formulas.html>`_ to limit the variables of interest to a smaller set which meet the defined conditions. 
+This clause can use `aggregations <https://help.semmle.com/QL/ql-language-reference/expressions.html#aggregations>`__, `predicates <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__, and logical `formulas <https://help.semmle.com/QL/ql-language-reference/formulas.html>`_ to limit the variables of interest to a smaller set which meet the defined conditions. 
 
 When writing a path queries, you would typically include a predicate that holds only if data flows from the ``source`` to the ``sink``. 
 
diff --git a/docs/language/learn-ql/writing-queries/troubleshooting-query-performance.rst b/docs/language/learn-ql/writing-queries/troubleshooting-query-performance.rst
index 098594d19fe..b6bc9e6988d 100644
--- a/docs/language/learn-ql/writing-queries/troubleshooting-query-performance.rst
+++ b/docs/language/learn-ql/writing-queries/troubleshooting-query-performance.rst
@@ -9,9 +9,9 @@ About query performance
 This topic offers some simple tips on how to avoid common problems that can affect the performance of your queries.
 Before reading the tips below, it is worth reiterating a few important points about CodeQL and the QL language:
 
-- CodeQL `predicates <https://help.semmle.com/QL/ql-handbook/predicates.html>`__ and `classes <https://help.semmle.com/QL/ql-handbook/types.html#classes>`__ are evaluated to database `tables <https://en.wikipedia.org/wiki/Table_(database)>`__. Large predicates generate large tables with many rows, and are therefore expensive to compute.
+- CodeQL `predicates <https://help.semmle.com/QL/ql-language-reference/predicates.html>`__ and `classes <https://help.semmle.com/QL/ql-language-reference/types.html#classes>`__ are evaluated to database `tables <https://en.wikipedia.org/wiki/Table_(database)>`__. Large predicates generate large tables with many rows, and are therefore expensive to compute.
 - The QL language is implemented using standard database operations and `relational algebra <https://en.wikipedia.org/wiki/Relational_algebra>`__ (such as join, projection, and union). For more information about query languages and databases, see `About the QL language <https://help.semmle.com/QL/learn-ql/about-ql.html>`__.
-- Queries are evaluated *bottom-up*, which means that a predicate is not evaluated until *all* of the predicates that it depends on are evaluated. For more information on query evaluation, see "`Evaluation of QL programs <https://help.semmle.com/QL/ql-handbook/evaluations-of-ql-programs.html>`__." 
+- Queries are evaluated *bottom-up*, which means that a predicate is not evaluated until *all* of the predicates that it depends on are evaluated. For more information on query evaluation, see "`Evaluation of QL programs <https://help.semmle.com/QL/ql-language-reference/evaluations-of-ql-programs.html>`__." 
 
 Performance tips
 ----------------
@@ -54,7 +54,7 @@ To avoid making this mistake, ``this`` should be restricted in the member predic
 Use specific types
 ~~~~~~~~~~~~~~~~~~
 
-"`Types <https://help.semmle.com/QL/ql-handbook/types.html>`__" provide an upper bound on the size of a relation. 
+"`Types <https://help.semmle.com/QL/ql-language-reference/types.html>`__" provide an upper bound on the size of a relation. 
 This helps the query optimizer be more effective, so it's generally good to use the most specific types possible. For example::
 
   predicate foo(LoggingCall e)
@@ -90,7 +90,7 @@ Use ``getAQlClass()`` as a debugging tool, but don't include it in the final ver
 Avoid complex recursion
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-"`Recursion <https://help.semmle.com/QL/ql-handbook/recursion.html>`__" is about self-referencing definitions.
+"`Recursion <https://help.semmle.com/QL/ql-language-reference/recursion.html>`__" is about self-referencing definitions.
 It can be extremely powerful as long as it is used appropriately.
 On the whole, you should try to make recursive predicates as simple as possible.
 That is, you should define a *base case* that allows the predicate to *bottom out*, along with a single *recursive call*::
@@ -103,7 +103,7 @@ That is, you should define a *base case* that allows the predicate to *bottom ou
 
 .. pull-quote:: Note
 
-   The query optimizer has special data structures for dealing with `transitive closures <https://help.semmle.com/QL/ql-handbook/recursion.html#transitive-closures>`__.
+   The query optimizer has special data structures for dealing with `transitive closures <https://help.semmle.com/QL/ql-language-reference/recursion.html#transitive-closures>`__.
    If possible, use a transitive closure over a simple recursive predicate, as it is likely to be computed faster.
 
 Fold predicates
diff --git a/docs/language/reusables/codeql-ref-tools-further-reading.rst b/docs/language/reusables/codeql-ref-tools-further-reading.rst
index 539d9c7e709..c2149ed0ae1 100644
--- a/docs/language/reusables/codeql-ref-tools-further-reading.rst
+++ b/docs/language/reusables/codeql-ref-tools-further-reading.rst
@@ -1,2 +1,2 @@
-- "`QL language reference <https://help.semmle.com/QL/ql-handbook>`__"
+- "`QL language reference <https://help.semmle.com/QL/ql-language-reference>`__"
 - "`CodeQL tools <https://help.semmle.com/codeql/codeql-tools.html>`__"
\ No newline at end of file