tahoe-lafs/trac

change all docs and generated URLs to point to "/cap" instead of "/uri" #1715

New issue

Open

opened 2012-04-11 01:44:25 +00:00 by antagonismorg · 9 comments

antagonismorg commented

2012-04-11 01:44:25 +00:00

From #tahoe-lafs:

13:58 < warner> I also noticed that /uri and /cap are synonyms.. not sure if that's documented

13:59 < zooko> I had the idea, many years ago, to rename "uri" to "cap" everywhere, but never finished that process...

14:00 < marlowe> warner: if you create the ticket, and assign it to docs, I will make the change

14:00 < warner> I think that synonym came from that process

14:00 * zooko nods

14:01 < marlowe> also, once I finish #1663 we should have a good idea on what is a synonym for what

14:01 < zooko> I had planned to change the Web API docs to direct programmers to the new name -- /cap/ -- and leave the old one for backward-compatibility.

From #tahoe-lafs: 13:58 < warner> I also noticed that /uri and /cap are synonyms.. not sure if that's documented 13:59 < zooko> I had the idea, many years ago, to rename "uri" to "cap" everywhere, but never finished that process... 14:00 < marlowe> warner: if you create the ticket, and assign it to docs, I will make the change 14:00 < warner> I think that synonym came from that process 14:00 * zooko nods 14:01 < marlowe> also, once I finish #1663 we should have a good idea on what is a synonym for what 14:01 < zooko> I had planned to change the Web API docs to direct programmers to the new name -- /cap/ -- and leave the old one for backward-compatibility.

antagonismorg added the

labels 2012-04-11 01:44:25 +00:00

antagonismorg added this to the undecided milestone 2012-04-11 01:44:25 +00:00

antagonismorg self-assigned this 2012-04-11 01:44:25 +00:00

daira commented

2012-04-11 02:00:54 +00:00

Another option would be to delete /cap. Why have two ways to do things?

Another option would be to delete `/cap`. Why have two ways to do things?

antagonismorg commented

2012-04-11 02:18:44 +00:00

Author

Replying to davidsarah:

Another option would be to delete /cap. Why have two ways to do things?

You read my mind. I think ticket #1663 will help us get an idea where we have synonyms and then create tickets to either remove the cruft or maintain backwards compatibility. I added Brian and Zooko to the ticket as they can shed more light on it than I.

In the meantime until we decide how to proceed on the above, I will make the necessary changes to webapi.rst.

Replying to [davidsarah](/tahoe-lafs/trac/issues/1715#issuecomment-389519): > Another option would be to delete `/cap`. Why have two ways to do things? You read my mind. I think ticket #1663 will help us get an idea where we have synonyms and then create tickets to either remove the cruft or maintain backwards compatibility. I added Brian and Zooko to the ticket as they can shed more light on it than I. In the meantime until we decide how to proceed on the above, I will make the necessary changes to webapi.rst.

zooko changed title from ~~/cap and /uri are synonyms~~ to change all docs and generated URLs to point to "/cap" instead of "/uri"

2012-04-11 02:31:56 +00:00

antagonismorg commented

2012-04-11 02:42:00 +00:00

Author

The attached patch is a workaround, until we get all instances of /uri changed to /cap, we need to have this in webapi.rst. If someone can tell me when /cap was introduced, I will add the version information into webapi.rst. I submitted a pull request to github with this patch.

antagonismorg commented

2012-04-11 02:43:13 +00:00

Author

Attachment ticket-1715.patch (755 bytes) added

**Attachment** ticket-1715.patch (755 bytes) added

ticket-1715.patch

755 B

daira commented

2012-04-11 02:56:26 +00:00

Reasons not to rename /uri to /cap:

it's unnecessary work;
/cap is not that much better a name;
in order not to be disruptive to older third-party tools, or Tahoe CLI instances, connecting to a newer gateway, we'd have to maintain /uri as well as /cap;
there's no evidence that anyone is using /cap, and it wasn't documented, so there's no reason not to just delete it.

Reasons not to rename `/uri` to `/cap`: * it's unnecessary work; * `/cap` is not that much better a name; * in order not to be disruptive to older third-party tools, or Tahoe CLI instances, connecting to a newer gateway, we'd have to maintain `/uri` as well as `/cap`; * there's no evidence that anyone is using `/cap`, and it wasn't documented, so there's no reason not to just delete it.

daira commented

2012-04-11 03:03:41 +00:00

Incidentally, if we are going to change the gateway URLs, I'd rather shorten them by not having any additional prefix, since the URI: prefix (or lafs: if we change it to that) is unambiguous. This would only involve a slight complication in the root handler.

Incidentally, if we are going to change the gateway URLs, I'd rather shorten them by not having any additional prefix, since the `URI:` prefix (or `lafs:` if we change it to that) is unambiguous. This would only involve a slight complication in the root handler.

zooko commented

2012-04-11 03:36:33 +00:00

Also, we use the name cap fairly consistently in all the documentation except for the URL structure itself, so currently someone who reads the docs has to remember "Okay, '/uri/' is where the cap goes.", which seems harder than "Okay, '/cap/' is where the cap goes.".

I like your idea of removing the "/uri/" or "/cap/" altogether. That's intriguing. Want to talk about that?

David-Sarah: I think "cap" is a much better name. These things are not officially URIs, as they aren't officially recognized by IANA and they don't even follow the URI spec. Also, they are not even *conceptually* URIs, because an "identifier" does not, according to most people's conceptions, convey authority. That's how a cap differs from an identifier. Also, we use the name cap fairly consistently in all the documentation *except* for the URL structure itself, so currently someone who reads the docs has to remember "Okay, '/uri/' is where the cap goes.", which seems harder than "Okay, '/cap/' is where the cap goes.". I like your idea of removing the "/uri/" or "/cap/" altogether. That's intriguing. Want to talk about that?

antagonismorg was unassigned by zooko

2012-04-11 03:36:33 +00:00

daira was assigned by zooko

2012-04-11 03:36:33 +00:00

daira commented

2012-05-17 00:30:20 +00:00

Accepting to remind me to talk about removing "/uri/" or "/cap/"

daira commented

2012-11-20 03:02:54 +00:00

So, we can get away with removing "/uri/" or "/cap/" because the URI: prefix (or lafs: if and when we switch to that) makes the meaning unambiguous. The root handler can just check whether the immediate child name starts with "URI:", and if it does, delegate to the same handler as "/uri/".

So, we can get away with removing "/uri/" or "/cap/" because the `URI:` prefix (or `lafs:` if and when we switch to that) makes the meaning unambiguous. The root handler can just check whether the immediate child name starts with "URI:", and if it does, delegate to the same handler as "/uri/".