Fix sort_by example

[owenthereal]

No description provided.

[ghost]

See the wiki page on editing documentation: https://github.com/stedolan/jq/wiki/Docs-and-tests

Note that sort(f) and sort_by(f) are aliases of each other, so I'm not sure what this actually fixes. If the example given fails, perhaps you aren't using the latest version of jq?

[owenthereal]

@slapresta It doesn't work with 1.4: https://jqplay.org/jq?q=sort(.foo)&j=%5B%7B%22foo%22%3A4%2C%20%22bar%22%3A10%7D%2C%20%7B%22foo%22%3A3%2C%20%22bar%22%3A100%7D%2C%20%7B%22foo%22%3A2%2C%20%22bar%22%3A1%7D%5D. sort_by works though.

[ghost]

You need to compile from master.

2014-10-02 17:55 GMT+02:00 Jingwen Owen Ou notifications@github.com:

@slapresta https://github.com/slapresta It doesn't work with 1.4:
https://jqplay.org/jq?q=sort(.foo)&j=%5B%7B%22foo%22%3A4%2C%20%22bar%22%3A10%7D%2C%20%7B%22foo%22%3A3%2C%20%22bar%22%3A100%7D%2C%20%7B%22foo%22%3A2%2C%20%22bar%22%3A1%7D%5D

—
Reply to this email directly or view it on GitHub
#590 (comment).

[owenthereal]

@slapresta So the fix is in master? jqplay is using 1.4 from the build

[ghost]

It's not "fixed" because there is no bug. The problem is that you're looking at the documentation for the master version but trying to make it work on 1.4. sort() didn't take arguments back then.

[owenthereal]

@slapresta Sure...does it make more sense if the doc is for a released version? I believe there're few people compile jq from master though...

[ghost]

I agree, some form of versioning for documentation is needed (although you
could just use the documentation on the 1.4 tag)

2014-10-02 18:01 GMT+02:00 Jingwen Owen Ou notifications@github.com:

@slapresta https://github.com/slapresta Sure...does it make more sense
if the doc is for a release version? I believe there're few people compile
jq from master though...

—
Reply to this email directly or view it on GitHub
#590 (comment).

[owenthereal]

Closing it and hope this raises awareness a bit

[wtlangford]

It is important to remember that there are two places the documentation can be found.
We have documentation on the website (http://stedolan.github.io/jq/) and that's 1.4-based. (the gh-pages branch)
Then there's the documentation that lives in master, which is up-to-date for the features in master.

If the documentation on the website isn't correct for 1.4, that IS an issue and it needs to be handled. In this case, the 1.4 docs say that sort/1 exists, when it definitely doesn't for 1.4.

@jingweno, if you'd like to redo the pull request by editing manual.yml as in https://github.com/stedolan/jq/wiki/Docs-and-tests, that would be great. When you submit the pull request, add a note that it is for the 1.4 docs and we'll make sure it makes it out to the site.

[pkoppstein]

@wtlangford wrote:

If the documentation on the website isn't correct for 1.4, that IS an issue ...

Yes, it has been noted before, e.g. #552 (comment)
If it's not possible to "roll back" the documentation, then would it be feasible to tag the "1.5" features as such? There is of course something to be said for having (and retaining) such tags, at least in the manual.

[wtlangford]

Personally, I like the version tags. That being said, features not in an
official release shouldn't have snuck in to the official docs.
On Oct 2, 2014 12:49 PM, "pkoppstein" notifications@github.com wrote:

@wtlangford https://github.com/wtlangford wrote:

If the documentation on the website isn't correct for 1.4, that IS an
issue ...

Yes, it has been noted before, e.g. #552 (comment)
#552 (comment)
If it's not possible to "roll back" the documentation, then would it be
feasible to tag the "1.5" features as such? There is of course something to
be said for having (and retaining) such tags, at least in the manual.

—
Reply to this email directly or view it on GitHub
#590 (comment).

[nicowilliams]

FYI, I'm going to remove the sort/1 alias of sort_by/1. It makes more
sense to leave sort/1 as a sort with a jq-coded comparator closure.

[wtlangford]

Seems logical. What are your thoughts on the version stamping in the docs?
On Oct 2, 2014 5:16 PM, "Nico Williams" notifications@github.com wrote:

FYI, I'm going to remove the sort/1 alias of sort_by/1. It makes more
sense to leave sort/1 as a sort with a jq-coded comparator closure.

—
Reply to this email directly or view it on GitHub
#590 (comment).

[owenthereal]

FYI, i found out this issue when people run the example on jqplay.org: https://twitter.com/statemachine/status/517321978219229184

[pkoppstein]

@nicowilliams wrote:

I'm going to remove the sort/1 alias of sort_by/1.

Great. As a reminder, the following sentence in http://stedolan.github.io/jq/manual should be revised (ASAP?):

sort_by(foo) is an alias of sort(foo); sort_by() is deprecated and will be removed in the next major release.