Skip to content

docs: clarify 'query help' usage in 'Query help style guide' #3226

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Apr 8, 2020
Merged

docs: clarify 'query help' usage in 'Query help style guide' #3226

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7a3b310
docs: clarify 'query help' usage
Apr 8, 2020
ff599a5
docs: html -> HTML
Apr 8, 2020
6ca8653
Apply suggestions from code review
jf205 Apr 8, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions docs/query-help-style-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Query help files must have the same base name as the query they describe and mus

### File structure and layout

Query files are written using an XML format called Qhelp, and stored in a file with a `.qhelp` extension. The basic structure is as follows:
Query help files are written using a custom XML format, and stored in a file with a `.qhelp` extension. The basic structure is as follows:

```
<!DOCTYPE qhelp SYSTEM "qhelp.dtd">
Expand All @@ -25,7 +25,7 @@ Query files are written using an XML format called Qhelp, and stored in a file w
</qhelp>
```

The header and single top-level `qhelp` element are both mandatory.
The header and single top-level `<qhelp>` element are both mandatory.

### Section-level elements

Expand All @@ -36,7 +36,7 @@ Section-level elements are used to group the information within the query help f
3. `example`—an example of code showing the problem. Where possible, this section should also include a solution to the issue.
4. `references`—relevant references, such as authoritative sources on language semantics and best practice.

For further information about the other section-level, block, list and table elements supported by the qhelp format, see the [Query help reference](https://help.semmle.com/QL/learn-ql/ql/writing-queries/query-help.html) on help.semmle.com.
For further information about the other section-level, block, list and table elements supported by query help files, see the [Query help reference](https://help.semmle.com/QL/learn-ql/ql/writing-queries/query-help.html) on help.semmle.com.


## English style
Expand Down Expand Up @@ -86,7 +86,7 @@ For example:

>W. C. Wake, _Refactoring Workbook_, pp. 93 – 94, Addison-Wesley Professional, 2004.

Note, & symbols need to be replaced by \&amp;. The symbol will be displayed correctly in the html files generated from the qhelp files.
Note, & symbols need to be replaced by \&amp;. The symbol will be displayed correctly in the HTML files generated from the query help files.

### Academic papers

Expand All @@ -107,11 +107,11 @@ For example:

### Referencing potential security weaknesses

If your query checks code for a CWE weakness, you should use the `@tags` element in the query file to reference the associated CWEs, as explained [here](query-metadata-style-guide.md). When you use these tags, a link to the appropriate entry from the [MITRE.org](https://cwe.mitre.org/scoring/index.html) site will automatically appear as a reference in the qhelp file.
If your query checks code for a CWE weakness, you should use the `@tags` element in the query file to reference the associated CWEs, as explained [here](query-metadata-style-guide.md). When you use these tags, a link to the appropriate entry from the [MITRE.org](https://cwe.mitre.org/scoring/index.html) site will automatically appear as a reference in the output HTML file.

## Query help example

The following example is a qhelp file for a query from the standard query suite for Java:
The following example is a query help file for a query from the standard query suite for Java:

```
<!DOCTYPE qhelp PUBLIC
Expand Down Expand Up @@ -179,4 +179,4 @@ tab width settings cannot be taken into account.

</references>
</qhelp>
```
```