You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/language/learn-ql/writing-queries/query-help.rst
+31-31Lines changed: 31 additions & 31 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -26,7 +26,7 @@ Each query help file provides detailed information about the purpose and use of
26
26
Structure
27
27
=========
28
28
29
-
Query help files are written using an XML format called Qhelp (``.qhelp``). Query help files must have the same base name as the query they describe, and must be located in the same directory. The basic structure is as follows:
29
+
Query help files are written using a custom XML format, and stored in a file with a ``.qhelp`` extension. Query help files must have the same base name as the query they describe, and must be located in the same directory. The basic structure is as follows:
30
30
31
31
.. code-block:: xml
32
32
@@ -44,32 +44,32 @@ Section-level elements
44
44
45
45
Section-level elements are used to group the information in the help file into sections. Many sections have a heading, either defined by a ``title`` attribute or a default value. The following section-level elements are optional child elements of the ``qhelp`` element.
| ``example`` | None | Any block element | Demonstrate an example of code that violates the rule implemented by the query with guidance on how to fix it. Default heading. |
| ``include`` | ``src`` The Qhelp file to include. | None | Include a Qhelp file at the ___location of this element. See :ref:`Qhelp inclusion <qhelp-inclusion>` below. No heading.|
| ``overview`` | None | Any block element | Overview of the purpose of the query. Typically this is the first section in a query document. No heading. |
| ``semmleNotes`` | None | Any block element | Semmle-specific notes about the query. This section is used only for queries that implement a rule defined by a third party. Default heading. |
| ``example`` | None | Any block element | Demonstrate an example of code that violates the rule implemented by the query with guidance on how to fix it. Default heading. |
| ``include`` | ``src`` The query help file to include. | None | Include a query help file at the ___location of this element. See :ref:`Query help inclusion <qhelp-inclusion>` below. No heading. |
| ``overview`` | None | Any block element | Overview of the purpose of the query. Typically this is the first section in a query document. No heading. |
| ``semmleNotes`` | None | Any block element | Semmle-specific notes about the query. This section is used only for queries that implement a rule defined by a third party. Default heading. |
The following elements are optional child elements of the ``section``, ``example``, ``fragment``, ``recommendation``, ``overview`` and ``semmleNotes`` elements.
72
+
The following elements are optional child elements of the ``section``, ``example``, ``fragment``, ``recommendation``, ``overview``, and ``semmleNotes`` elements.
73
73
74
74
.. table::
75
75
:widths: 7 20 10 25
@@ -84,7 +84,7 @@ The following elements are optional child elements of the ``section``, ``example
84
84
||| ``height`` Optional, height of the image. |||
85
85
||| ``width`` Optional, the width of the image. |||
| ``include`` | ``src`` The Qhelp file to include. | None | Include a Qhelp file at the ___location of this element. See :ref:`Qhelp inclusion <qhelp-inclusion>` below for more information.|
87
+
| ``include`` | ``src`` The query help file to include. | None | Include a query help file at the ___location of this element. See :ref:`Query help inclusion <qhelp-inclusion>` below for more information. |
@@ -105,12 +105,12 @@ The following elements are optional child elements of the ``section``, ``example
105
105
List elements
106
106
=============
107
107
108
-
Qhelp files support two types of block elements for lists: ``ul`` and ``ol``. Both block elements support only one child elements of the type ``li``. Each ``li`` element contains either inline content or a block element.
108
+
Query help files support two types of block elements for lists: ``ul`` and ``ol``. Both block elements support only one child elements of the type ``li``. Each ``li`` element contains either inline content or a block element.
109
109
110
110
Table elements
111
111
==============
112
112
113
-
The ``table`` block element is used to include a table in a Qhelp file. Each table includes a number of rows, each of which includes a number of cells. The data in the cells will be rendered as a grid.
113
+
The ``table`` block element is used to include a table in a query help file. Each table includes a number of rows, each of which includes a number of cells. The data in the cells will be rendered as a grid.
@@ -159,12 +159,12 @@ Inline content is used to define the content for paragraphs, list items, table c
159
159
160
160
.. _qhelp-inclusion:
161
161
162
-
Qhelp inclusion
163
-
===============
162
+
Query help inclusion
163
+
====================
164
164
165
-
To enable the reuse of content between different help topics, shared content can be stored in one Qhelp file and then included in a number of other Qhelp files using the ``include`` element. The shared content can stored either in the same directory as the including files, or in ``SEMMLE_DIST/docs/include``.
165
+
To reuse content between different help topics, you can store shared content in one query help file and then include it in a number of other query help files using the ``include`` element. The shared content can be stored either in the same directory as the including files, or in ``SEMMLE_DIST/docs/include``.
166
166
167
-
The ``include`` element can be used as a section or block element, the content of the Qhelp file defined by the ``src`` attribute must contain elements that are appropriate to the ___location of the ``include`` element.
167
+
The ``include`` element can be used as a section or block element. The content of the query help file defined by the ``src`` attribute must contain elements that are appropriate to the ___location of the ``include`` element.
168
168
169
169
Section-level include elements
170
170
------------------------------
@@ -177,7 +177,7 @@ Section-level ``include`` elements can be located beneath the top-level ``qhelp`
177
177
<includesrc="XSS.qhelp" />
178
178
</qhelp>
179
179
180
-
In this example, the `XSS.qhelp <https://github.com/Semmle/ql/blob/master/csharp/ql/src/Security%20Features/CWE-079/XSS.qhelp>`__ file must conform to the standard for a full Qhelp file as described above. That is, the ``qhelp`` element may only contain non-``fragment``, section-level elements.
180
+
In this example, the `XSS.qhelp <https://github.com/Semmle/ql/blob/master/csharp/ql/src/Security%20Features/CWE-079/XSS.qhelp>`__ file must conform to the standard for a full query help file as described above. That is, the ``qhelp`` element may only contain non-``fragment``, section-level elements.
0 commit comments