URL structure for github-book

[Kathi Fletcher]

Folks, I really lean toward a clean URL structure that doesn't rely on position and allows things to be optional (like branches, and books or folders)

Here is what I would propose

/repo/<user>/<repo>/branch/<branch>/edit/<content>/in/<book-or-folder>

First it makes it clear to new people what all these is doing, and second it allows us to have everything be optional.

Kathi

--
Katherine Fletcher, kathi.f...@gmail.com

Twitter: kefletcher Blog: kefletcher.blogspot.com

[Izak Burger]

On Thu, Sep 26, 2013 at 4:51 PM, Kathi Fletcher <Kathi.F...@gmail.com> wrote:

Folks, I really lean toward a clean URL structure that doesn't rely on position and allows things to be optional (like branches, and books or folders)

Here is what I would propose

/repo/<user>/<repo>/branch/<branch>/edit/<content>/in/<book-or-folder>

The present structure (which is on the repo-on-url branch) is very close to this. Of course everything comes AFTER the #, otherwise apache (or nginx or whatever web server is in use, most critically whatever runs github pages) would attempt to dereference that path server side. The /branch/<branch> bit is currently optional. If you omit that, it uses the default branch. The bit after edit is simply the "id" of the module you're editing, and this is url-encoded, but other than that, it essentially has the <book-or-folder> part first, followed by <content> later, in other words, it is now:

#/repo/<user>/<repo>/branch/<branch>/edit/<id>

Where id in turn can be <folder-or-book>/<another-folder>/<content>, but because it is urlencoded you won't see the /, you will instead see a %2F.

Phil would have to advise whether we can unobfuscate this bit. Personally I would prefer to keep the book-or-folder bit on the left. Most significant bits first and all that. But I'm an engineer, not a UI person, so I will gladly revise my preference.

Cheers,

Izak

[Kathi Fletcher]

OK -- If the # is needed, that is fine.

I don't really care if the ID contains both the book and module part as long as it will be ok to have a module that isn't in a book.

Kathi

--
You received this message because you are subscribed to the Google Groups "OERPUB Team" group.
To unsubscribe from this group and stop receiving emails from it, send an email to oerpub-tools-d...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.

[Izak Burger]

On Thu, Sep 26, 2013 at 8:28 PM, Kathi Fletcher <Kathi.F...@gmail.com> wrote:

I don't really care if the ID contains both the book and module part as long as it will be ok to have a module that isn't in a book. 

This is a little confusing to me, perhaps because there's some re-use of terminology here. An ebook will always have one or more opf files inside. Usually it will have only one, but you can have more than one, allowing more than one book per epub. So it is not exactly possible, within this terminology, to have a module that isn't in a book.

But there is also a convention that has been adopted, as far as I understand it, within the books we have been working on, that each book lives in a subdirectory off the root. This is strictly a convention and there is no reason why modules (html files) cannot live in the root, or in any directory in the epub, as long as the relevant opf file correctly lists the path in its manifest. In this sense you CAN have a module that is not inside a book, in the sense that it won't be in a subfolder corresponding to any particular book.

With the present url structure, you'd have:

#/repo/<user>/<repo>/branch/<branch>/edit/<optional-directories>/<content>

And the option where a module is not in a "book", is simply where the optional directories are left out. Of course, it would be nice if that bit (after the edit) wasn't as obfuscated as it is. You do learn to "read" urlencoding after some years as a developer... but that's not really good enough I think. I think a little bit of research into making this look cleaner is in order.