Shorter URLs to Solr ref-guide?

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

Shorter URLs to Solr ref-guide?

Jan Høydahl / Cominvent
Hi,

I started to replace old wiki.apache.org/solr and cwiki.apache.org/solr links to point to relevant
sections in the new online Reference Guide lucene.apache.org/solr/guide/ and discover pretty soon
that the URLs for the new guide are pretty long, e.g:

Wiki:
  http://wiki.apache.org/solr/SchemaXml#Similarity
Cwiki:
  https://cwiki.apache.org/confluence/display/solr/Other+Schema+Elements#OtherSchemaElements-Similarity
New ref-guide:
  http://lucene.apache.org/solr/guide/other-schema-elements.html#OtherSchemaElements-Similarity


There are several things to note here:
* Long domain and prefix: http://lucene.apache.org/solr/guide/
* The anchor name typically repeats the page name: other-schema-elements.html # OtherSchemaElements-Similarity
  This is a legacy from how Confluence auto generated anchors

Since ref-guide is the main goto-docs for Solr I’d like the URLs to be as short as possible, preferable
so that you can remember the most prominent pages and type them by hand, and that they can easily be pasted
into a flowing text without always breaking to the next line because they are too long.

Proposals:
1. Register a domain for the guide, e.g. http://solr.guide/ — 12 chars instead of 30 ($35/yr)
2. Write a script that removes the duplicate names in anchors, and run a one-time conversion
   e.g. converts #OtherSchemaElements-Similarity to #Similarity
3. Introduce a shortcut page for the refGuide, to create shortcuts for the most frequently used
   guide locations, e.g. create a page s.adoc that contains a long list of short-links and a Javascript
   that performs a redirect. Example:
   http://solr.guide/s/schema.html ==> http://solr.guide/6_6/documents-fields-and-schema-design.html

Just throwing this out here before creating JIRAs. What do you think?

--
Jan Høydahl, search solution architect
Cominvent AS - www.cominvent.com


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Shorter URLs to Solr ref-guide?

david.w.smiley@gmail.com
Your 3 proposals look excellent Jan!

#2 (write script to shorten redundant page names in anchor names) is especially needed.

~ David

On Sun, Jul 9, 2017 at 3:53 PM Jan Høydahl <[hidden email]> wrote:
Hi,

I started to replace old wiki.apache.org/solr and cwiki.apache.org/solr links to point to relevant
sections in the new online Reference Guide lucene.apache.org/solr/guide/ and discover pretty soon
that the URLs for the new guide are pretty long, e.g:

Wiki:
  http://wiki.apache.org/solr/SchemaXml#Similarity
Cwiki:
  https://cwiki.apache.org/confluence/display/solr/Other+Schema+Elements#OtherSchemaElements-Similarity
New ref-guide:
  http://lucene.apache.org/solr/guide/other-schema-elements.html#OtherSchemaElements-Similarity


There are several things to note here:
* Long domain and prefix: http://lucene.apache.org/solr/guide/
* The anchor name typically repeats the page name: other-schema-elements.html # OtherSchemaElements-Similarity
  This is a legacy from how Confluence auto generated anchors

Since ref-guide is the main goto-docs for Solr I’d like the URLs to be as short as possible, preferable
so that you can remember the most prominent pages and type them by hand, and that they can easily be pasted
into a flowing text without always breaking to the next line because they are too long.

Proposals:
1. Register a domain for the guide, e.g. http://solr.guide/ — 12 chars instead of 30 ($35/yr)
2. Write a script that removes the duplicate names in anchors, and run a one-time conversion
   e.g. converts #OtherSchemaElements-Similarity to #Similarity
3. Introduce a shortcut page for the refGuide, to create shortcuts for the most frequently used
   guide locations, e.g. create a page s.adoc that contains a long list of short-links and a Javascript
   that performs a redirect. Example:
   http://solr.guide/s/schema.html ==> http://solr.guide/6_6/documents-fields-and-schema-design.html

Just throwing this out here before creating JIRAs. What do you think?

--
Jan Høydahl, search solution architect
Cominvent AS - www.cominvent.com


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

--
Lucene/Solr Search Committer, Consultant, Developer, Author, Speaker
Reply | Threaded
Open this post in threaded view
|

Re: Shorter URLs to Solr ref-guide?

Jan Høydahl / Cominvent
#2 (write script to shorten redundant page names in anchor names) is especially needed.

There may be a plan to auto redirect Confluence links to the new guide, see https://issues.apache.org/jira/browse/SOLR-10595
and if someone clicks a link with an anchor, the redirect will not manage to scroll to correct sub heading if we change every single
anchor. But the redirect will get to the correct page, which is probably good enough.

I haven’t thought through the redirect/alias part very much yet. The idea would be that you could add an alias with a commit
to the guide itself, not introducing any .htaccess, servlets or other things. If we used Javascript for the redirect, then perhaps
we could have a format such as http://solr.guide/s.html#schema and have the JS parse the string after # and change .location ?

Idea #4: 
Provide an icon next to every header, that will generate a version-independent link, i.e. a link without “/6_6“ in it. The
way the site is setup now, omitting the version in the URL will redirect to that page in the current version of the guide (htaccess?)
This is useful for links that describe concepts, but is of course prone to page renames in the future, unless we enforce a polify
that a page rename shall leave the old page.html in place with a redirect?

--
Jan Høydahl, search solution architect
Cominvent AS - www.cominvent.com

10. jul. 2017 kl. 05.59 skrev David Smiley <[hidden email]>:

Your 3 proposals look excellent Jan!

#2 (write script to shorten redundant page names in anchor names) is especially needed.

~ David

On Sun, Jul 9, 2017 at 3:53 PM Jan Høydahl <[hidden email]> wrote:
Hi,

I started to replace old wiki.apache.org/solr and cwiki.apache.org/solr links to point to relevant
sections in the new online Reference Guide lucene.apache.org/solr/guide/ and discover pretty soon
that the URLs for the new guide are pretty long, e.g:

Wiki:
  http://wiki.apache.org/solr/SchemaXml#Similarity
Cwiki:
  https://cwiki.apache.org/confluence/display/solr/Other+Schema+Elements#OtherSchemaElements-Similarity
New ref-guide:
  http://lucene.apache.org/solr/guide/other-schema-elements.html#OtherSchemaElements-Similarity


There are several things to note here:
* Long domain and prefix: http://lucene.apache.org/solr/guide/
* The anchor name typically repeats the page name: other-schema-elements.html # OtherSchemaElements-Similarity
  This is a legacy from how Confluence auto generated anchors

Since ref-guide is the main goto-docs for Solr I’d like the URLs to be as short as possible, preferable
so that you can remember the most prominent pages and type them by hand, and that they can easily be pasted
into a flowing text without always breaking to the next line because they are too long.

Proposals:
1. Register a domain for the guide, e.g. http://solr.guide/ — 12 chars instead of 30 ($35/yr)
2. Write a script that removes the duplicate names in anchors, and run a one-time conversion
   e.g. converts #OtherSchemaElements-Similarity to #Similarity
3. Introduce a shortcut page for the refGuide, to create shortcuts for the most frequently used
   guide locations, e.g. create a page s.adoc that contains a long list of short-links and a Javascript
   that performs a redirect. Example:
   http://solr.guide/s/schema.html ==> http://solr.guide/6_6/documents-fields-and-schema-design.html

Just throwing this out here before creating JIRAs. What do you think?

--
Jan Høydahl, search solution architect
Cominvent AS - www.cominvent.com


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

--
Lucene/Solr Search Committer, Consultant, Developer, Author, Speaker

Reply | Threaded
Open this post in threaded view
|

Re: Shorter URLs to Solr ref-guide?

Malcolm Upayavira Holmes
If you do want to register a new domain, I suggest getting the Infrastructure team to do it (an INFRA ticket?) and point it at a requisite location. It will likely be easier to do it that way, so that the ASF owns the domain name from the get go.

Upayavira

On Mon, 10 Jul 2017, at 09:56 AM, Jan Høydahl wrote:
#2 (write script to shorten redundant page names in anchor names) is especially needed.

There may be a plan to auto redirect Confluence links to the new guide, see https://issues.apache.org/jira/browse/SOLR-10595
and if someone clicks a link with an anchor, the redirect will not manage to scroll to correct sub heading if we change every single
anchor. But the redirect will get to the correct page, which is probably good enough.

I haven’t thought through the redirect/alias part very much yet. The idea would be that you could add an alias with a commit
to the guide itself, not introducing any .htaccess, servlets or other things. If we used Javascript for the redirect, then perhaps
we could have a format such as http://solr.guide/s.html#schema and have the JS parse the string after # and change .location ?

Idea #4: 
Provide an icon next to every header, that will generate a version-independent link, i.e. a link without “/6_6“ in it. The
way the site is setup now, omitting the version in the URL will redirect to that page in the current version of the guide (htaccess?)
This is useful for links that describe concepts, but is of course prone to page renames in the future, unless we enforce a polify
that a page rename shall leave the old page.html in place with a redirect?

--
Jan Høydahl, search solution architect
Cominvent AS - www.cominvent.com

10. jul. 2017 kl. 05.59 skrev David Smiley <[hidden email]>:

Your 3 proposals look excellent Jan!

#2 (write script to shorten redundant page names in anchor names) is especially needed.

~ David

On Sun, Jul 9, 2017 at 3:53 PM Jan Høydahl <[hidden email]> wrote:
Hi,

I started to replace old wiki.apache.org/solr and cwiki.apache.org/solr links to point to relevant
sections in the new online Reference Guide lucene.apache.org/solr/guide/ and discover pretty soon
that the URLs for the new guide are pretty long, e.g:

Wiki:
Cwiki:
New ref-guide:


There are several things to note here:
* Long domain and prefix: http://lucene.apache.org/solr/guide/
* The anchor name typically repeats the page name: other-schema-elements.html # OtherSchemaElements-Similarity
  This is a legacy from how Confluence auto generated anchors

Since ref-guide is the main goto-docs for Solr I’d like the URLs to be as short as possible, preferable
so that you can remember the most prominent pages and type them by hand, and that they can easily be pasted
into a flowing text without always breaking to the next line because they are too long.

Proposals:
1. Register a domain for the guide, e.g. http://solr.guide/ — 12 chars instead of 30 ($35/yr)
2. Write a script that removes the duplicate names in anchors, and run a one-time conversion
   e.g. converts #OtherSchemaElements-Similarity to #Similarity
3. Introduce a shortcut page for the refGuide, to create shortcuts for the most frequently used
   guide locations, e.g. create a page s.adoc that contains a long list of short-links and a Javascript
   that performs a redirect. Example:

Just throwing this out here before creating JIRAs. What do you think?

--
Jan Høydahl, search solution architect
Cominvent AS - www.cominvent.com


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

--
Lucene/Solr Search Committer, Consultant, Developer, Author, Speaker

Reply | Threaded
Open this post in threaded view
|

Re: Shorter URLs to Solr ref-guide?

Jan Høydahl / Cominvent
If you do want to register a new domain, I suggest getting the Infrastructure team to do it (an INFRA ticket?)

That would be the way to go, INFRA would renew the domain etc. But first we need to have consensus. We could perhaps run a VOTE thread and quote the result in an INFRA ticket.

I suppose that if we acquire solr.guide domain, we would ask Infra to mount it as a www-root in some location, and publish the guide there INSTEAD of committing it to the CMS svn? That would probably simplify the publishing instructions as well, if we could use scp/rsync/ftp instead of svn. Cassandra?

--
Jan Høydahl, search solution architect
Cominvent AS - www.cominvent.com

10. jul. 2017 kl. 11.32 skrev Upayavira <[hidden email]>:

If you do want to register a new domain, I suggest getting the Infrastructure team to do it (an INFRA ticket?) and point it at a requisite location. It will likely be easier to do it that way, so that the ASF owns the domain name from the get go.

Upayavira

On Mon, 10 Jul 2017, at 09:56 AM, Jan Høydahl wrote:
#2 (write script to shorten redundant page names in anchor names) is especially needed.

There may be a plan to auto redirect Confluence links to the new guide, see https://issues.apache.org/jira/browse/SOLR-10595
and if someone clicks a link with an anchor, the redirect will not manage to scroll to correct sub heading if we change every single
anchor. But the redirect will get to the correct page, which is probably good enough.

I haven’t thought through the redirect/alias part very much yet. The idea would be that you could add an alias with a commit
to the guide itself, not introducing any .htaccess, servlets or other things. If we used Javascript for the redirect, then perhaps
we could have a format such as http://solr.guide/s.html#schema and have the JS parse the string after # and change .location ?

Idea #4: 
Provide an icon next to every header, that will generate a version-independent link, i.e. a link without “/6_6“ in it. The
way the site is setup now, omitting the version in the URL will redirect to that page in the current version of the guide (htaccess?)
This is useful for links that describe concepts, but is of course prone to page renames in the future, unless we enforce a polify
that a page rename shall leave the old page.html in place with a redirect?

--
Jan Høydahl, search solution architect
Cominvent AS - www.cominvent.com

10. jul. 2017 kl. 05.59 skrev David Smiley <[hidden email]>:

Your 3 proposals look excellent Jan!

#2 (write script to shorten redundant page names in anchor names) is especially needed.

~ David

On Sun, Jul 9, 2017 at 3:53 PM Jan Høydahl <[hidden email]> wrote:
Hi,

I started to replace old wiki.apache.org/solr and cwiki.apache.org/solr links to point to relevant
sections in the new online Reference Guide lucene.apache.org/solr/guide/ and discover pretty soon
that the URLs for the new guide are pretty long, e.g:

Wiki:
Cwiki:
New ref-guide:


There are several things to note here:
* Long domain and prefix: http://lucene.apache.org/solr/guide/
* The anchor name typically repeats the page name: other-schema-elements.html # OtherSchemaElements-Similarity
  This is a legacy from how Confluence auto generated anchors

Since ref-guide is the main goto-docs for Solr I’d like the URLs to be as short as possible, preferable
so that you can remember the most prominent pages and type them by hand, and that they can easily be pasted
into a flowing text without always breaking to the next line because they are too long.

Proposals:
1. Register a domain for the guide, e.g. http://solr.guide/ — 12 chars instead of 30 ($35/yr)
2. Write a script that removes the duplicate names in anchors, and run a one-time conversion
   e.g. converts #OtherSchemaElements-Similarity to #Similarity
3. Introduce a shortcut page for the refGuide, to create shortcuts for the most frequently used
   guide locations, e.g. create a page s.adoc that contains a long list of short-links and a Javascript
   that performs a redirect. Example:

Just throwing this out here before creating JIRAs. What do you think?

--
Jan Høydahl, search solution architect
Cominvent AS - www.cominvent.com


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

--
Lucene/Solr Search Committer, Consultant, Developer, Author, Speaker


Reply | Threaded
Open this post in threaded view
|

Re: Shorter URLs to Solr ref-guide?

Cassandra Targett
I was out on vacation last week, so just catching up to this discussion.

Upfront I'll say I'm +0 on this effort - short URLs are nice, but in
my mind I balance the effort against its relative priority with other
things the Ref Guide needs and, for me, this would be lower on my
list. I don't wish to stop anyone from improving things, though, if
this is where available skills/energy lie.

That said, a few more specific comments:

>> Register a domain for the guide, e.g. http://solr.guide/ — 12 chars instead of 30 ($35/yr)

Without "apache.org" in the domain, comments don't work today.
Supposedly it's possible to make it work, but whatever docs INFRA has
already written about it are out of date. Investigating that further
would need to be a step in the process if the permanent URL is
"solr.guide" instead of "apache.org".

>> Long domain and prefix: http://lucene.apache.org/solr/guide/

It's really no longer than the old domain & prefix:
https://cwiki.apache.org/confluence/solr/.

>> Write a script that removes the duplicate names in anchors, and run a one-time conversion
   e.g. converts #OtherSchemaElements-Similarity to #Similarity

There is a reason why these are there for now and it's because every
section heading throughout the entire guide must be unique. It's not
so bad for the HTML version, because each HTML page is a separate
entity but for the PDF it can cause real problems. The build process
has a step where it checks the built pages/pdf to ensure all section
titles or related anchor tags are unique - if there are any
duplicates, the build fails (it also fails if an anchor doesn't
exist). So you can't just automatically change them without ensuring
that there aren't any other pages with a section titled "Similarity",
or "Examples", or "Parameters", "Input", etc. (the latter 3 being very
common).

To make the conversion simpler and ensure stuff just worked we simply
copied Confluence's anchors, knowing we would remove them later after
some review, which I've been doing with other edits. It's a multi-step
process - find where might be referring to the anchor you want to
remove & fix the reference, remove the Confluence-style anchor, then
run the build to ensure you didn't make a duplicate. And if you did,
figure out how to change one or more section titles or add simpler
anchor tags and fix the reference again. A script would help some of
this, but there will be a long list of things to fix afterwards, and
many of those probably need some human intervention.

This is also pretty much exactly the same as before, by the way, just
Confluence had some built-in logic to obscure it in many cases (and
most probably don't realize how many inter-page links I used to find
broken all the time).

>> That would probably simplify the publishing instructions as well, if we could use scp/rsync/ftp instead of svn. Cassandra?

I'm not sure what you're asking me to comment on - perhaps it would
simplify publishing instructions? Not really sure. It's not that
onerous today, really, once you do it once. It's nearly exactly the
same as publishing the javadocs for a release, which is update a
single file in the CMS then issue a single SVN command to import the
new pages. And the PDF still requires SVN no matter what you do with
the online version.

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

Re: Shorter URLs to Solr ref-guide?

Cassandra Targett
>> To make the conversion simpler and ensure stuff just worked we simply
copied Confluence's anchors, knowing we would remove them later after
some review, which I've been doing with other edits.

In reference to this and inspired by this conversation, I'm making a
sweep through to remove anchors that aren't being used by other pages
for links. I filed SOLR-11050 for this.

On Tue, Jul 11, 2017 at 9:41 AM, Cassandra Targett
<[hidden email]> wrote:

> I was out on vacation last week, so just catching up to this discussion.
>
> Upfront I'll say I'm +0 on this effort - short URLs are nice, but in
> my mind I balance the effort against its relative priority with other
> things the Ref Guide needs and, for me, this would be lower on my
> list. I don't wish to stop anyone from improving things, though, if
> this is where available skills/energy lie.
>
> That said, a few more specific comments:
>
>>> Register a domain for the guide, e.g. http://solr.guide/ — 12 chars instead of 30 ($35/yr)
>
> Without "apache.org" in the domain, comments don't work today.
> Supposedly it's possible to make it work, but whatever docs INFRA has
> already written about it are out of date. Investigating that further
> would need to be a step in the process if the permanent URL is
> "solr.guide" instead of "apache.org".
>
>>> Long domain and prefix: http://lucene.apache.org/solr/guide/
>
> It's really no longer than the old domain & prefix:
> https://cwiki.apache.org/confluence/solr/.
>
>>> Write a script that removes the duplicate names in anchors, and run a one-time conversion
>    e.g. converts #OtherSchemaElements-Similarity to #Similarity
>
> There is a reason why these are there for now and it's because every
> section heading throughout the entire guide must be unique. It's not
> so bad for the HTML version, because each HTML page is a separate
> entity but for the PDF it can cause real problems. The build process
> has a step where it checks the built pages/pdf to ensure all section
> titles or related anchor tags are unique - if there are any
> duplicates, the build fails (it also fails if an anchor doesn't
> exist). So you can't just automatically change them without ensuring
> that there aren't any other pages with a section titled "Similarity",
> or "Examples", or "Parameters", "Input", etc. (the latter 3 being very
> common).
>
> To make the conversion simpler and ensure stuff just worked we simply
> copied Confluence's anchors, knowing we would remove them later after
> some review, which I've been doing with other edits. It's a multi-step
> process - find where might be referring to the anchor you want to
> remove & fix the reference, remove the Confluence-style anchor, then
> run the build to ensure you didn't make a duplicate. And if you did,
> figure out how to change one or more section titles or add simpler
> anchor tags and fix the reference again. A script would help some of
> this, but there will be a long list of things to fix afterwards, and
> many of those probably need some human intervention.
>
> This is also pretty much exactly the same as before, by the way, just
> Confluence had some built-in logic to obscure it in many cases (and
> most probably don't realize how many inter-page links I used to find
> broken all the time).
>
>>> That would probably simplify the publishing instructions as well, if we could use scp/rsync/ftp instead of svn. Cassandra?
>
> I'm not sure what you're asking me to comment on - perhaps it would
> simplify publishing instructions? Not really sure. It's not that
> onerous today, really, once you do it once. It's nearly exactly the
> same as publishing the javadocs for a release, which is update a
> single file in the CMS then issue a single SVN command to import the
> new pages. And the PDF still requires SVN no matter what you do with
> the online version.

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]