[
https://issues.apache.org/jira/browse/SOLR-11573?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16260932#comment-16260932
]
Cassandra Targett edited comment on SOLR-11573 at 11/21/17 3:48 PM:
--------------------------------------------------------------------
[~gerlowskija] - I'm looking at the patch, and I'm a little confused so want to
be sure I understand it for later updating the meta-docs for others to use this
also:
* The {{build.xml}} and {{_config.yml.template}} files set a {{solr-root-path}}
parameter that is a path relative to the {{solr/build/solr-ref-guide/content}}
directory, so the root ends up as {{solr/}}.
* The {{using-solrj.adoc}} file sets a {{solr-root-path}} parameter that is a
path relative to the {{solr/solr-ref-guide/src}} directory, again so the root
ends up as {{solr/}}.
* The {{solr-root-path}} param is used in another param {{example-source-dir}}
with the path to the dir that has the example file.
The thing that's confusing me is why the path doesn't break in the file when
the conversion is happening. My understanding of the inheritance here is that
the param on the document overrides the param set in our config files ("passed
to the API or CLI" as described here:
http://asciidoctor.org/docs/user-manual/#attribute-assignment-precedence),
which would mean that the path would be incorrect during build (it would go
only to {{solr/build}} instead of {{solr}}).
Do you have any insights on this from looking at this closer than I have?
was (Author: ctargett):
[~gerlowskija] - I'm looking at the patch, and I'm a little confused so want to
be sure I understand it for later updating the meta-docs for others to use this
also:
* The {{build.xm}}l and {{_config.yml.template}} files set a {{solr-root-path}}
parameter that is a path relative to the {{solr/build/solr-ref-guide/content}}
directory, so the root ends up as {{solr/}}.
* The {{using-solrj.adoc}} file sets a {{solr-root-path}} parameter that is a
path relative to the {{solr/solr-ref-guide/src}} directory, again so the root
ends up as {{solr/}}.
* The {{solr-root-path}} param is used in another param {{example-source-dir}}
with the path to the dir that has the example file.
The thing that's confusing me is why the path doesn't break in the file when
the conversion is happening. My understanding of the inheritance here is that
the param on the document overrides the param set in our config files ("passed
to the API or CLI" as described here:
http://asciidoctor.org/docs/user-manual/#attribute-assignment-precedence),
which would mean that the path would be incorrect during build (it would go
only to {{solr/build}} instead of {{solr}}).
Do you have any insights on this from looking at this closer than I have?
> Add live-preview support for ref-guide files using asciidoc-includes
> --------------------------------------------------------------------
>
> Key: SOLR-11573
> URL: https://issues.apache.org/jira/browse/SOLR-11573
> Project: Solr
> Issue Type: Improvement
> Security Level: Public(Default Security Level. Issues are Public)
> Components: documentation
> Affects Versions: master (8.0)
> Reporter: Jason Gerlowski
> Priority: Trivial
> Attachments: SOLR-11573.patch
>
>
> With the completion of SOLR-11032, the "Using SolrJ" page in the ref-guide
> now imports some Java code snippets from an external file. This is done to
> allow the snippets appearing in the documentation to be compiled/run as part
> of the build...so they will always stay up to date.
> During the ref-guide build, this external file is copied into the ref-guide
> build directory so that the references to it can be resolved. However,
> anyone using the "live preview" feature of modern asciidoc editors (Atom,
> etc.), will find that the snippets don't appear in their live-preview.
> Depending on your editor, a discrete error message may be displayed.
> It would be nice to fix this "papercut" in usability, or at least provide a
> workaround. The easier we can make it to improve the docs, the better.
--
This message was sent by Atlassian JIRA
(v6.4.14#64029)
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org
