Clarify how a reader would find the next chapter/section
Openopened 2 years ago by krixano · 22 comments
Reference in New Issue
There is no content yet.
Delete Branch '%!s(<nil>)'
Deleting a branch is permanent. It CANNOT be undone. Continue?
BTW this was written by nytpu, krixano was just nice enough to post it for me since they have a codeberg account and I don't.
The current spec is very ambiguous about how an ebook reader (kindle, kobo, calibre's reader, etc) would actually read a file as a book. In the layout you show each “chapter” as being a single gemtext file, which makes it simple because you just paginate it like you would an epub or other format. But, then how does it move to the next chapter to create a feeling of linearity like a book? I think it'd be a good idea to have some suggestion to implementers so everyone is on the same page.
There's 2 main options that I can think of:
Look for a file called
nis the current chapter number, starting at 1)
Move through the index file link by link, so the first link in the file is the first chapter, the second link is the second chapter, and so on.
My assumption was that at the end of one chapter the reader would simply start the next one from the index file - 'assumptions are the mother of all fXXX ups' though so it may be wise for us to add that to the recommendations section mentioned in another ticket (not added yet)
Yes, that seems to make the most sense. I just think it should be explicit in the spec/doc. I don't think it should be in the recommendations, personally. It's so important that it should be a spec thing.
(This is krixano speaking now, btw)
Yeah, that makes sense, will get it in tomorrow.
have added a note, let me know if you think it's enough and I'll close this: https://codeberg.org/oppenlab/gempub#user-content-2-4-content
It may be clearer once we have the addition of a reference implementation .gpub in the repo too (working on it)
Ok, so I think you should be a little bit more specific by clarifying that the order of the chapters is the order of the links from top to bottom on the index page.
Otherwise, it's good, thanks!
Related to this, I've just added a reference implementation: https://codeberg.org/oppenlab/gempub/src/branch/main/reference_gpub/gpub_star_maker_olaf_stapledon/index.gmi
Ok, so one thing I noticed was that in the reference gpub, the location of the index file is in the root. However, you do not specify the index location in the metadata. So I'm confused on where the index file is by default, because the text of the spec seems to suggest the default location if no index location is specified should be in a "capsule" folder.
So, I think the spec intends that the default location for the index file is in the root. However, the spec provides an example where it is not in the root. I think to make the spec easier to understand, the example provided (within the text of the spec) should be in the root, and then make sure people know that they can specify a different location for the index.
Yes, I think we'll probably need to treat the
index.gmifile as being just as important to the correct operation of the Gempub reader as the
Right now, the spec provides for:
What if we expand it to something along the following lines?
Or... something along those lines. :)
Ok, more about this part. It's good to specify that the links should be displayed in the same order, but that's not completely what I was trying to say before.
We also need to make sure that in gpub readers that display gpubs as pages, than when you click "next page", the order of the pages follows the same order of the links on the index.gmi file.
Edit: Ah, I now see you do cover this farther down. :)
Btw, I like everything raphm wrote above.
The whole capsule/ thing is a confusing red-herring, it was in my initial idea - then removed but left in the example because it's still valid (if the capsule/index.gmi is defined in the metadata.txt), I'll clean up that example to remove this misdirection it causes.
And yes - good stuff from Raph above - let's get that in too.
I also agree with @raphm about relying on the index page for chapter navigation, it seems like the best solution. I'm planning to implement that in Lagrange after the v1.4 release is done.
The spec should probably refer to it as the "Gempub index page" or something more generic like that, and not as
index.gmisince the actual filename can be specified in the metadata.
I also described how I was splitting chapters into screen sized chunks (not a problem for any reader that scrolls vertically) here: https://codeberg.org/oppenlab/OppenBok#parsing
I'll try and write a whole section on both these points - but obviously clarity is very important here and I'm not the best at it!
That sounds quite good!
I would prefer not using the word "typically" here, if we consider that archive Gempubs are also typical use.
IMO the index page should by default be considered the table of contents, as-is. The benefits:
The exact rules for generating a TOC and how navigation should behave are good to specify, though, as you suggest.
This is great! I've been struggling with how to conceptualize the Gempub index. Should it be displayed verbatim? Or should it only be used to generate reading order? I think you've come up with the exact right balance.
What if we replace the following three paragraphs from the above attempt:
Does that capture it properly?
@oppenlab If you sign off on the above changes I am happy to get them into the current working version of the spec. :)
Sounds good to me at least. 👍
@raphm of course go for it - sorry I've not been as active on this lately, I've just started a new job and family life is hectic at the moment.
Okay, the new language is integrated into the spec. I think we're at the point where it would be interesting to get this into the "awesome-gemini" list (https://github.com/kr1sp1n/awesome-gemini/blob/master/contributing.md). I shall submit the pull request. :)
@raphm thanks for your outstanding work on this. I'm going to be pushing this whole area more heavily as soon as I've got Ariane 4 done (and my new Gemini server), I'll hopefully be setting up a gemini based library of gempub books.