[
https://issues.apache.org/jira/browse/SOLR-11573?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16224240#comment-16224240
]
Hoss Man commented on SOLR-11573:
---------------------------------
i'm not very familiar with ATOM or live eidting asciidoc files, but in
searching a bit to see if there were options in ATOM's asciidoc support for
configuring an "include path" i noticed this bug report...
https://github.com/asciidoctor/atom-asciidoc-preview/issues/189
3 things jump out at me in this report...
# the ATOM asciidoctor live-preview functionality evidently supports the
ability to specify configure custom attributes used when doing the preview?
# the idea of using an attribute reference in an {{include::}} path ... an
attribute might be declared in the document metadata with one (default) value
for previewing but the build system could specify a different value when
generating the final html/pdf output.
# adjusting the SAFE mode level of asciidoctor can aparently make it possible
to {{include::}} files with relative paths outside of the base_dir.
...between those 3 things it seems like it *should* be possible to...
* use a new "rel-path-for-solr-root" attribute in {{using-solrj.adoc}} setup in
such a way that by default, any editor that's configured to be "unsafe" can
find the original {{\*.java}} files we might want to include...{noformat}
= Using SolrJ
:rel-path-for-solr-root: ../../
:test-dir:
{rel-path-for-solr-root}solrj/src/test/org/apache/solr/client/ref_guide_examples/
...
include::{test-dir}UsingSolrJRefGuideExamplesTest.java[tag=solrj-solrclient-timeouts]
{noformat}
* update our build.xml to override {{rel-path-for-solr-root}} to something that
makes sense realtive to the {{build/content}} dir we use -- hopefully no longer
needing to copy the {{\*.java files at all?}}
* add an {{ant setup-atom}} target (if needed) that generates the appropriate
ATOM config with the "unsafe" level we need for those paths to work?
The devil will obviously be in the details ... we've encountered enough weird
bugs with asciidoctor include paths and deep dirs in the past
(https://github.com/asciidoctor/asciidoctor/issues/1866 comes to mind) ... but
it certainly seems like we have some options.
> 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
>
> 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: [email protected]
For additional commands, e-mail: [email protected]
