No man page

[pjungkamp]

I've recently switched from using jq to jaq for the occasional command line JSON processing. And since I'm only crafting small filters, I have to refer to jq's documentation, especially it's man page, regularly.

$ whatis jaq
jaq: nothing appropriate.

Documentation for the jaq command line options and maybe some examples should probably go into section 1 man page. I think most of the language documentation could be copied from jq under its CC license, amended and put into section "3 Library Calls" or "5 File formats and configuration files", I'm not sure what would be more appropriate.

[01mf02]

Hi @pjungkamp, thank you for your comment!

In principle, I am sympathetic to creating a man page for jaq. The question is: What should really go into it? To answer it, it would help me to know what you are looking for when you open the man page. Do you look for a reference, i.e. a list of the available operators and functions with a relatively small description? Do you look for examples? Or do you look for more of a tutorial?

I think that I could identify with a description of the CLI options, as well as a relatively terse summary of the operators/functions, perhaps with one or two examples each. Such as:

• f, g: Returns the concatenation of the outputs of f and g, both applied to the current input.
  Example: jaq -n '{a: 0, b: 1} | .a, length' --> 0, 2
• f | g: For each output of f applied to the current input, apply the output to g and return all its outputs.
  Example: ...

I'm reluctant, on the other hand, to just copy large parts of the jq manual. That will eventually make them diverge and hard to maintain.

State of the art:

• awk man page: very detailed language description (I could imagine something like "Table 4-1: Expressions in Decreasing Precedence" in the jaq man page as well!)
• sed man page: more superficial language description
• gcc man page: no language description whatsoever

What do you think?

[pjungkamp]

I'd like to see:

1. data types
   • list of types in jaq this should differentiate between floating point numbers and integers
   • floating point NaN and infinity representations (since jaq has these but they don't map directly to json)
2. operators
   • list of all operators (sorted by precedence or with and explicit table?)
   • special operator overloads (e.g. multiplying objects for recusive merge, dividing strings for splitting, multiplying strings for repetition, others?)
   • jaq's integer/float conversion semantics
3. definitions and expressions
   • filter/indexing expressions
   • defining variables
   • defining functions
4. builtin/std functions
   • list of all functions by name with one line description for better discoverability (maybe group these somehome for lists/objects/timestamps/etc)
   • long description for functions with typed parameters and maybe an example of the functions input and output.

I think the jq man page already does do a great job in explaining all these concepts, but the bold parts are what I'm missing from the jq man page. It lacks something like and index or overview for a section. The only way you'd find out about e.g. a function is a good guess for search word in the man page or reading it in its entirety.

[pjungkamp]

I love the awk man page. But I think adding the language grammar to the man page of jaq isn't necessary. And I think that jaq's manpage would be larger than the one for awk and interspersing examples would be more helpful than putting all of them at the bottom.

sed man page is just an overview to the language because the real documentation is in the info pages, which I've never really come to like...

[pjungkamp]

I don't think that gcc is a good comparison for jaq. gcc processes C files according to an external standard, the format of the file or it's standard library isn't part of the gcc command invocation. Most awk or jaq invocations will include the executed script in the command line which makes it more reasonable to have a description for this scripting language in the man page.

[01mf02]

I love the awk man page. But I think adding the language grammar to the man page of jaq isn't necessary. And I think that jaq's manpage would be larger than the one for awk and interspersing examples would be more helpful than putting all of them at the bottom.

Yes, I would not have planned on including a language grammar anyway. :) And I agree with you on the utility of interspersed examples.

[01mf02]

I'd like to see:

These points look very reasonable to me. If I understand you correctly, you would like a short reference.

I think the jq man page already does do a great job in explaining all these concepts, but the bold parts are what I'm missing from the jq man page. It lacks something like and index or overview for a section. The only way you'd find out about e.g. a function is a good guess for search word in the man page or reading it in its entirety.

I'm not sure whether you know it, but I have already created something that sounds a lot like what you describe here: jqlang/jq#3189. You can see the "builtin functions" section here.

[01mf02]

(By the way, this motivated me to support URLs such as https://gedenkt.at/jaq/?q=%22a%22&j=null in the jaq playground, in case we want to generate an HTML version of the jaq manual and create playground links from the examples there 0c5c67a. Compare it with the loading time of https://jqplay.org/?q=%22a%22&j=null.)