[
https://issues.apache.org/jira/browse/SOLR-18495?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18121996#comment-18121996
]
Serhiy Bzhezytskyy commented on SOLR-18495:
-------------------------------------------
Before touching pages, here is what the Ref Guide uses today for "put your name
here" in a URL or path, and what I would pick. Counts are mentions across
solr-ref-guide/modules on main.
||Style||Count||Example||
|\_core\_name\_ / \_core-name\_ / \_collection-name\_|17 / 6 /
7|/solr/\_core\_name\_/select|
|<collection> / <core>|30 / 9|/solr/<collection>/... (21 of the 30 are in
implicit-requesthandlers)|
|collection_name, collectionName|13, 13|/api/collections/collection_name/...|
|YOUR_COLLECTION|3| |
|\{collection}|2|v2-api.adoc, inside a JSON response|
|\{configSetName}, \{filePath}, \{role}, \{node}, \{taskID}|1-2
each|/api/configsets/\{configSetName}/files/\{filePath}|
|literal names: mycollection, my_collection, test_collection, coll1|32 / 14 /
4 / 5|bin/solr create -c mycollection|
Two things decide the choice:
# In AsciiDoc \{x} is an attribute reference, so it has to be written with a
backslash. In prose and inline code that renders as \{x}. Inside a source block
the backslash is not consumed: the built document-enrichment-with-llms page
shows the
backslash in front of string_field in its XML example. So the escaped form is
right in prose and wrong in code blocks, where the plain form is the only one
that renders cleanly.
# Most mycollection / my_collection hits are not placeholders. They are the
runnable name in {{bin/solr create -c mycollection}} and in the response that
follows, so a blanket replace would break those examples.
Options:
A. \{collectionName} wherever a URL stands for a name (escaped in prose,
plain in source blocks). One convention, and it matches the \{configSetName},
\{role} and \{node} paths already written that way in the guide.
B. <collection> (angle brackets). Already the most common form for collection
and core, needs no escaping, but reads like an XML tag in the same blocks.
C. \_collection\_name\_ (underscore-wrapped). Renders literally in a source
block; in prose AsciiDoc turns it into italics unless escaped, so it is the
most fragile.
Recommendation: A, limited to names inside URLs and paths, with
collectionName, coreName and configSetName as the fixed vocabulary. Literal
names in runnable commands stay as they are. It is the only style that is
visibly a placeholder in the
path itself, and it already has precedent in the guide.
Unless you prefer otherwise, I would cover the pages that use <collection> as
well as the ones with a literal name.
> Make placeholder name in URL clearer. /mycollection/blah -->
> /{collectionName}/blah
> ------------------------------------------------------------------------------------
>
> Key: SOLR-18495
> URL: https://issues.apache.org/jira/browse/SOLR-18495
> Project: Solr
> Issue Type: Sub-task
> Components: documentation
> Reporter: Eric Pugh
> Priority: Major
>
> We should make it clearer when embedding a placeholder name in a url that
> it's a placeholder. We often say "my_collection" but really we should
> proably just say "\{collectionName}" instead with the squqqly quotes?
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
