[
https://issues.apache.org/jira/browse/SOLR-11646?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17287205#comment-17287205
]
Cassandra Targett commented on SOLR-11646:
------------------------------------------
bq. there a pattern you like for formatting URLS in the docs?
It's done in different ways by different people. I'm probably as guilty of
doing it different ways at different times as anyone else is. I'd like to
standardize it but have never decided how.
I do know that one approach that uses curly brackets like { } (in
configsets-api.adoc) causes errors, so don't do that. Curly brackets are used
for variable attributes in Asciidoctor so it's constantly trying to figure out
what to replace the values with...not a failure but annoying so let's not do it
everywhere.
I like the idea of italicizing them, but it would require some special handling
to do it in the source blocks and I also prefer putting URLs in source blocks
instead of free-floating on the page. But does that make sense everywhere? Not
sure. And that's really as far as I've thought about it.
bq. also, do we prefer urls to have the
http://localhost:8983/solr/admin/collections?action=CREATE or do we prefer the
/admin/collections?action=CREATE style?
I prefer full URLs because there's no question about the full path to the
endpoint. My plan when I finally got the motivation to go back to this
thankless task ;-) was going to be to fix all the example endpoints to be full
URLs. I may not have done that in the earlier pages I did, I may have decided I
wanted to do that after I did the other pages.
> Ref Guide: Update API examples to include v2 style examples
> -----------------------------------------------------------
>
> Key: SOLR-11646
> URL: https://issues.apache.org/jira/browse/SOLR-11646
> Project: Solr
> Issue Type: Improvement
> Components: documentation, v2 API
> Reporter: Cassandra Targett
> Assignee: Cassandra Targett
> Priority: Major
> Time Spent: 20m
> Remaining Estimate: 0h
>
> The Ref Guide currently only has a single page with what might be generously
> called an overview of the v2 API added in 6.5
> (https://lucene.apache.org/solr/guide/v2-api.html) but most of the actual
> APIs that support the v2 approach do not show an example of using it with the
> v2 style. A few v2-style APIs are already used as examples, but there's
> nothing consistent.
> With this issue I'll add API input/output examples throughout the Guide. Just
> in terms of process, my intention is to have a series of commits to the pages
> as I work through them so we make incremental progress. I'll start by adding
> a list of pages/APIs to this issue so the scope of the work is clear.
> Once this is done we can figure out what to do with the V2 API page itself -
> perhaps it gets archived and replaced with another page that describes Solr's
> APIs overall; perhaps by then we figure out something else to do with it.
--
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
