[
https://issues.apache.org/jira/browse/SOLR-14383?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17169070#comment-17169070
]
Chris M. Hostetter commented on SOLR-14383:
-------------------------------------------
{quote}Hoss: please use PRs, which are much easier to peer review. I've been
dragging my feet, not looking forward to reading asciidoc diffs. ...
{quote}
No thank you. I have no interest in using github specific features –
particularly for ASF projects.
I've created a {{jira/SOLR-14383}} branch for this issue (about to push) if
that will help lower the bar for your future review.
{quote} * I really appreciate the conversion of plain JSON input docs to a real
curl equivalent that I could use right away.
* The bullet advising the ID to be a composite ID for all docs in the block
really seems like it should be a TIP.
* Typo: thir -> their
* Typo: garuntee -> guarantee (multiple)
* The example about office supplies uses a child doc label of "docs", seen in
sending the data to Solr and in retrieval. I find the use of this word
confusing because it's a common word in Solr, so I suspect others might as
well. Perhaps "documentation" or "files" might be alternatives? "files" is nice
and short.{quote}
All great points, these edits are all made on the branch – i went with
"manuals" over "files" because in general (not just in this situation) i feel
like "files" is _WAY_ too ambiguious in many examples when dealing with Solr
(ie: "JSON Files" that you index containing metadata about "Example files" that
you want to search – except you aren't searching them, you're searching the
metadata about them ... maybe?")
I had my own doubts about using whether "docs" as a "document type" would be
confusing when i first started on this issue, but it wasn't until i went to
change it that i realized just _how_ confusing it was, especially in the
"search" examples, where {{"docs"}} is also the "response key" used for the
SolrDocumentList, which then contained "docs" sub-documents ... eesh!
{quote}* In a section showing the child doc transformer, it used to have a link
to further details at
{{transforming-result-documents.adoc#child-childdoctransformerfactory}} but you
changed it to {{other-parsers.adoc#block-join-children-query-parser}}. That
doesn't make sense to me.
{quote}
i have no idea what this is in reference to? ... there are only 2 instances of
"{{other-parsers.adoc#block-join-children-query-parser}}" and they are both in
paragraphs discussing the "child" *parser*, not the transformer?
{noformat}
$ grep 'other-parsers.adoc#block-join-children-query-parser' src/*.adoc
src/searching-nested-documents.adoc:The `{!child}` query parser can be used to
search for the _descendent_ documents of parent documents matching a wrapped
query. For a detailed explanation of this parser, see the section
<<other-parsers.adoc#block-join-children-query-parser, Block Join Children
Query Parser>>.
src/searching-nested-documents.adoc:NOTE: The `of` local param is neccessary to
tell the `{!child}` parser the set of _all_ "ancestor" documents to consider
when looking for matching children. In this example we've used `\*:*
-\_nest_path_:*` to indicate we want to consider all documents which don't have
a nest path field -- ie: all "root" level document. When dealing with multiple
levels of nested documents, it can be very tricky to define a correct `of`
param -- see the
<<other-parsers.adoc#block-join-children-query-parser,`{!child}` parser
section>> for details.
{noformat}
> Fix indexing-nested-documents.adoc XML/JSON examples to be accurate,
> consistent, and clear
> ------------------------------------------------------------------------------------------
>
> Key: SOLR-14383
> URL: https://issues.apache.org/jira/browse/SOLR-14383
> Project: Solr
> Issue Type: Sub-task
> Reporter: Chris M. Hostetter
> Assignee: Chris M. Hostetter
> Priority: Major
> Attachments: SOLR-14383.patch, SOLR-14383.patch, SOLR-14383.patch,
> SOLR-14383.patch
>
>
> As reported on solr-user@lucene by Peter Pimley...
> {noformat}
> The page "Indexing Nested Documents" has an XML example showing two
> different ways of adding nested documents:
> https://lucene.apache.org/solr/guide/8_5/indexing-nested-documents.html#xml-examples
> The text says:
> "It illustrates two styles of adding child documents: the first is
> associated via a field "comment" (preferred), and the second is done
> in the classic way now referred to as an "anonymous" or "unlabelled"
> child document."
> However in the XML directly below there is no field named "comment".
> There is one named "content" and another named "comments" (plural),
> but no field named "comment". In fact, looking at the Json example
> immediately below, I wonder if the XML element currently named
> "content" should be named "comments", and what is currently marked
> "comments" should be "content"?
> Secondly, in the Json example it says:
> "The labelled relationship here is one child document but could have
> been wrapped in array brackets."
> However in the actual Json, the parent document (ID=1) with a labelled
> relationship has two child documents (IDs 2 and 3), and they are
> already in array brackets.
> {noformat}
> * The 2 examples (XML and JSON) should be updated to contains *structurally*
> identical content, (ie: same number of documents, with same field values, and
> same hierarchical relationships) to focus on demonstrating the syntax
> differences (ie: things like the special {{\_childDocuments\_}} key in json)
> * The paragraphs describing the examples should be updated to:
> ** refer to the correct field names -- since both "comments" and "contents"
> fields exist in the examples, it's impossible for novice users to even
> udnerstand where th "typo" might be in the descriptions (I'm pretty
> knowledgeable about Solr and even i'm second guessing myself as to what the
> intent in these paragraphs are)
> ** refer to documents by {{"id"}} value, not just descriptors like "first"
> and "second"
> * it might be worth considering rewriting this section to use "callouts":
> https://asciidoctor.org/docs/user-manual/#callouts -- similar to how we use
> them in other sections like this:
> https://lucene.apache.org/solr/guide/8_5/uploading-data-with-index-handlers.html#sending-json-update-commands
--
This message was sent by Atlassian Jira
(v8.3.4#803005)
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscr...@lucene.apache.org
For additional commands, e-mail: issues-h...@lucene.apache.org
