jqlang / jq

Command-line JSON processor
https://jqlang.github.io/jq/
Other
30.15k stars 1.57k forks source link

Suggest: add reference to the SQL-style operators in the manual search box #2892

Open qmacro opened 1 year ago

qmacro commented 1 year ago

Often I come across references to the SQL-style operators (JOIN, INDEX, IN) in e.g. StackOverflow answers (this one has both INDEX and IN), and I have wondered what they are and how they work*. And I suspect that I'm not the only one.

Trouble is, when I use my favourite mechanism for this - the search box in the jq manual, I cannot find any reference to them. For example, INDEX doesn't show up:

Screenshot 2023-09-15 at 09 42 02

I thought I'd create this issue to start the conversation. I rigged up a docs test environment in which I could experiment, and here's one way of addressing this gap. I'm not suggesting it's the best way, but I thought I'd share it anyway to get things started.

I just extended the sectionIDs object used by the autocomplete mechanism like this:

 (() => {
   const searchInput = document.querySelector('input#searchbox');
-  const sectionIDs = JSON.parse(document.querySelector('#section-ids').innerText);
+  const sectionIDs = Object.assign(JSON.parse(document.querySelector('#section-ids').innerText), {
+    'JOIN (SQL-style operator)': 'sql-style-operators',
+    'INDEX (SQL-style operator)': 'sql-style-operators',
+    'IN (SQL-style operator)': 'sql-style-operators'
+  });
   const sanitize = (string) => string.replaceAll('<', '&lt;').replaceAll('>', '&gt;');
   new autoComplete({
     selector: `#${searchInput.id}`,

and the result is that these three operators can now be found in the search box, and all lead to the SQL-Style Operators section:

Screenshot 2023-09-14 at 18 31 51

Alternatively, there is also the option of modifying the documentation content to elevate each of the operators so that they have their own section ID, but I'm not sure whether that's ideal.

Anyway, I wonder if this is something you'd consider. Thanks!

* I did dig into a couple of these, they're great!

itchyny commented 1 year ago

Instead of hard coding, it would be great if command line arguments and formatting strings have individual id attributes. We can extract by pattern <li><code>.*</code>:</li> from entry bodies.