Re: API Docs Output Snippet Formats

[Jason Gerlowski]

I've uploaded a patch adding the necessary "wt" parameter to the
output snippets.  I agree that aligning all of our API snippets on the
default output format is a better solution, but this serves as a
reasonable stop-gap until I'm (or someone else is) able to put that
together.

On Mon, Oct 23, 2017 at 7:36 PM, Jason Gerlowski  wrote:
> Thanks for the feedback (and context/history) guys.  I've created
> SOLR-11530 (https://issues.apache.org/jira/browse/SOLR-11530) to keep
> track of this.
>
> You're right Cassandra, switching the snippets over to JSON will
> probably take a bit of time.  I'm going to give it a shot this
> evening, in case it's easier than it first appears.  But assuming it's
> not, I plan to upload a patch adding the appropriate "wt" params, as a
> short term fix.
>
> Jason
>
> On Mon, Oct 23, 2017 at 12:14 PM, Cassandra Targett
>  wrote:
>> I did a pass through the Ref Guide for SOLR-10494 and noted there [1]
>> that I neglected to look for places where the output was XML but the
>> sample request did not include "wt=xml". My intent was to look for
>> those later, but then I forgot.
>>
>> It's likely easier to find where the request is missing "wt=xml" than
>> to change the XML examples to JSON, although having them all in JSON
>> is preferable. If you're willing to cook up a patch for either, it
>> would be appreciated.
>>
>> If you think changing them to JSON will take you a while (and it
>> might), I'd be happy to split the work and do the pass through for
>> missing "wt=xml" params as a temporary measure.
>>
>> Cassandra
>>
>> [1] 
>> https://issues.apache.org/jira/browse/SOLR-10494?focusedCommentId=16056403=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-16056403
>>
>> On Sun, Oct 22, 2017 at 9:47 PM, Varun Thacker  wrote:
>>> I'd prefer 1>
>>>
>>> On Sun, Oct 22, 2017 at 7:39 PM, Jason Gerlowski 
>>> wrote:

 Hey all,

 Was doing some poking around the ref-guide this weekend.  I noticed
 that the output snippets given with the API documentation is split
 about 50/50 between xml and json.  Few of the examples contain an
 explicit "wt" parameter.  With the default "wt" format switching to
 json in 7.0, this means that any of the output snippets in XML format
 won't match what a user following along would see themselves.

 This won't trouble experienced users, but it could be a small
 speedbump for any new Solr adopters.  Making the snippets match the
 API calls would make the docs more correct, and more amateur-friendly.

 There's two approaches we could take to bring things into better
 alignment:

 1. Change all API output snippets to JSON.

 2, Don't change the format of any snippets.  Instead, add a "wt"
 parameter to the API call corresponding to any XML snippets, so that
 the input-call matches the output.

 Happy to create a JIRA and propose a patch for either approach if
 people think it's worth it, or have a particular preference on
 approach.  Anyone have any thoughts?

 Best,

 Jason

 -
 To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
 For additional commands, e-mail: dev-h...@lucene.apache.org

>>>
>>
>> -
>> To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
>> For additional commands, e-mail: dev-h...@lucene.apache.org
>>

-
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org

Re: API Docs Output Snippet Formats

[Jason Gerlowski]

Thanks for the feedback (and context/history) guys.  I've created
SOLR-11530 (https://issues.apache.org/jira/browse/SOLR-11530) to keep
track of this.

You're right Cassandra, switching the snippets over to JSON will
probably take a bit of time.  I'm going to give it a shot this
evening, in case it's easier than it first appears.  But assuming it's
not, I plan to upload a patch adding the appropriate "wt" params, as a
short term fix.

Jason

On Mon, Oct 23, 2017 at 12:14 PM, Cassandra Targett
 wrote:
> I did a pass through the Ref Guide for SOLR-10494 and noted there [1]
> that I neglected to look for places where the output was XML but the
> sample request did not include "wt=xml". My intent was to look for
> those later, but then I forgot.
>
> It's likely easier to find where the request is missing "wt=xml" than
> to change the XML examples to JSON, although having them all in JSON
> is preferable. If you're willing to cook up a patch for either, it
> would be appreciated.
>
> If you think changing them to JSON will take you a while (and it
> might), I'd be happy to split the work and do the pass through for
> missing "wt=xml" params as a temporary measure.
>
> Cassandra
>
> [1] 
> https://issues.apache.org/jira/browse/SOLR-10494?focusedCommentId=16056403=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-16056403
>
> On Sun, Oct 22, 2017 at 9:47 PM, Varun Thacker  wrote:
>> I'd prefer 1>
>>
>> On Sun, Oct 22, 2017 at 7:39 PM, Jason Gerlowski 
>> wrote:
>>>
>>> Hey all,
>>>
>>> Was doing some poking around the ref-guide this weekend.  I noticed
>>> that the output snippets given with the API documentation is split
>>> about 50/50 between xml and json.  Few of the examples contain an
>>> explicit "wt" parameter.  With the default "wt" format switching to
>>> json in 7.0, this means that any of the output snippets in XML format
>>> won't match what a user following along would see themselves.
>>>
>>> This won't trouble experienced users, but it could be a small
>>> speedbump for any new Solr adopters.  Making the snippets match the
>>> API calls would make the docs more correct, and more amateur-friendly.
>>>
>>> There's two approaches we could take to bring things into better
>>> alignment:
>>>
>>> 1. Change all API output snippets to JSON.
>>>
>>> 2, Don't change the format of any snippets.  Instead, add a "wt"
>>> parameter to the API call corresponding to any XML snippets, so that
>>> the input-call matches the output.
>>>
>>> Happy to create a JIRA and propose a patch for either approach if
>>> people think it's worth it, or have a particular preference on
>>> approach.  Anyone have any thoughts?
>>>
>>> Best,
>>>
>>> Jason
>>>
>>> -
>>> To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
>>> For additional commands, e-mail: dev-h...@lucene.apache.org
>>>
>>
>
> -
> To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
> For additional commands, e-mail: dev-h...@lucene.apache.org
>

-
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org

Re: API Docs Output Snippet Formats

[Cassandra Targett]

I did a pass through the Ref Guide for SOLR-10494 and noted there [1]
that I neglected to look for places where the output was XML but the
sample request did not include "wt=xml". My intent was to look for
those later, but then I forgot.

It's likely easier to find where the request is missing "wt=xml" than
to change the XML examples to JSON, although having them all in JSON
is preferable. If you're willing to cook up a patch for either, it
would be appreciated.

If you think changing them to JSON will take you a while (and it
might), I'd be happy to split the work and do the pass through for
missing "wt=xml" params as a temporary measure.

Cassandra

[1] 
https://issues.apache.org/jira/browse/SOLR-10494?focusedCommentId=16056403=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-16056403

On Sun, Oct 22, 2017 at 9:47 PM, Varun Thacker  wrote:
> I'd prefer 1>
>
> On Sun, Oct 22, 2017 at 7:39 PM, Jason Gerlowski 
> wrote:
>>
>> Hey all,
>>
>> Was doing some poking around the ref-guide this weekend.  I noticed
>> that the output snippets given with the API documentation is split
>> about 50/50 between xml and json.  Few of the examples contain an
>> explicit "wt" parameter.  With the default "wt" format switching to
>> json in 7.0, this means that any of the output snippets in XML format
>> won't match what a user following along would see themselves.
>>
>> This won't trouble experienced users, but it could be a small
>> speedbump for any new Solr adopters.  Making the snippets match the
>> API calls would make the docs more correct, and more amateur-friendly.
>>
>> There's two approaches we could take to bring things into better
>> alignment:
>>
>> 1. Change all API output snippets to JSON.
>>
>> 2, Don't change the format of any snippets.  Instead, add a "wt"
>> parameter to the API call corresponding to any XML snippets, so that
>> the input-call matches the output.
>>
>> Happy to create a JIRA and propose a patch for either approach if
>> people think it's worth it, or have a particular preference on
>> approach.  Anyone have any thoughts?
>>
>> Best,
>>
>> Jason
>>
>> -
>> To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
>> For additional commands, e-mail: dev-h...@lucene.apache.org
>>
>

-
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org

Re: API Docs Output Snippet Formats

[Varun Thacker]

I'd prefer 1>

On Sun, Oct 22, 2017 at 7:39 PM, Jason Gerlowski 
wrote:

> Hey all,
>
> Was doing some poking around the ref-guide this weekend.  I noticed
> that the output snippets given with the API documentation is split
> about 50/50 between xml and json.  Few of the examples contain an
> explicit "wt" parameter.  With the default "wt" format switching to
> json in 7.0, this means that any of the output snippets in XML format
> won't match what a user following along would see themselves.
>
> This won't trouble experienced users, but it could be a small
> speedbump for any new Solr adopters.  Making the snippets match the
> API calls would make the docs more correct, and more amateur-friendly.
>
> There's two approaches we could take to bring things into better alignment:
>
> 1. Change all API output snippets to JSON.
>
> 2, Don't change the format of any snippets.  Instead, add a "wt"
> parameter to the API call corresponding to any XML snippets, so that
> the input-call matches the output.
>
> Happy to create a JIRA and propose a patch for either approach if
> people think it's worth it, or have a particular preference on
> approach.  Anyone have any thoughts?
>
> Best,
>
> Jason
>
> -
> To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
> For additional commands, e-mail: dev-h...@lucene.apache.org
>
>