[jira] [Commented] (SOLR-18495) Make placeholder name in URL clearer. /mycollection/blah --> /{collectionName}/blah

["Serhiy Bzhezytskyy (Jira)" <ji...@apache.org>]

    [ 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: issues-unsubscribe@solr.apache.org
For additional commands, e-mail: issues-help@solr.apache.org