Labels Milestones

New Issue

Clarify how a reader would find the next chapter/section #9

Open

opened 2 years ago by krixano · 22 comments

krixano commented 2 years ago

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:

1. Look for a file called chapter{n+1}.gmi (where n is the current chapter number, starting at 1)

2. 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.

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: 1. Look for a file called `chapter{n+1}.gmi` (where `n` is the current chapter number, starting at 1) 2. 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.

👍 1

oppenlab commented 2 years ago

Owner

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)

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)

krixano commented 2 years ago

Poster

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)

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)

👍 1

oppenlab commented 2 years ago

Owner

Yeah, that makes sense, will get it in tomorrow.

Yeah, that makes sense, will get it in tomorrow.

oppenlab commented 2 years ago

Owner

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)

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)

krixano commented 2 years ago

Poster

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!

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!

oppenlab commented 2 years ago

Owner

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

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

👍 1

krixano commented 2 years ago

Poster

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.

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.

krixano commented 2 years ago

Poster

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.

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.

raphm commented 2 years ago

Collaborator

Yes, I think we'll probably need to treat the index.gmi file as being just as important to the correct operation of the Gempub reader as the metadata.txt file.

Right now, the spec provides for:

Gempub files are zipped directories of Gemtext .gmi files plus an optional metadata file:

• metadata.txt - a file containing the title, author and any other optional fields, see Metadata below

This file enables Gempub to act as a full eBook format. Gemini capsules can also be simply zip compressed without the metadata file to act as a Gemini archive/offline format - when operating as an archive there must be an index.gmi in the root directory.

What if we expand it to something along the following lines?

Gempub files are zipped directories of Gemtext .gmi files plus an optional metadata file:

• metadata.txt - a file containing the title, author and any other optional fields. See "Metadata", below.

The metadata.txt file enables Gempub to act as a full eBook format. However, a Gempub file can also be a simple zip-compressed capsule directory, which allows the Gempub container to serve as an offline Gemini capsule archive. In this case, however, the zipped Gempbub container must have either a metadata.txt file or an index.gmi file in the root directory of the archive.

2.3 The metadata.txt Metadata file

[Keep as-is]

2.4 The index.gmi Index file

The index.gmi file must be a text/gemini compliant UTF-8 file. Gempub reader applications shall display this file in accordance with the text/gemini specification.

If a Gempub reader application uses the index.gmi file to automatically generate a table of contents, the following requirements apply:

Links within the table of contents must be displayed in the order in which they are listed in the index.gmi file (from top to bottom). In other words, the first link in the table of contents must be the first link in the index.gmi file.

If a link within the index.gmi file has a user-friendly link name, the Gempub reader application must display the user-friendly link name in the table of contents without prepending or appending any numbering or additional text. This permits Gempub authors to use their own chapter numbering and naming conventions. On the other hand, if a link within the index.gmi file has no user-friendly link name, the Gempub reader must display the link URL, and may prepend or append a number or other short descriptive text to the URL.

During the reading process, the user should be able to begin with the first chapter and seamlessly advance through the contents of the Gempub archive by instructing the reader application to display the next page. The Gempub reader application must automatically advance through the contents of the Gempub archive in the order in which links are listed in the index.gmi file. For example, in the case where a user has completed reading the text of the file pointed to by the first link in the index.gmi file, and the user then instructs the reader application to advance to the next page, the reader application must automatically load and display the beginning of the file pointed to by the second link in the index.gmi file.

This behavior is only permitted with respect to relative links that point to files contained within the Gempub archive. Per the text/gemini specification (section 5.4.2), clients must not automatically make any network connections as part of displaying [remote] links. Transparently loading a remote file in response to a user's "display next page" request would violate this prohibition. Therefore, in response to a "display next page" request by the user, Gempub reader applications must automatically load and display the contents of the next link in the index.gmi file that points to a file within the Gempub archive.

2.5 Content

...

Or... something along those lines. :)

Yes, I think we'll probably need to treat the `index.gmi` file as being just as important to the correct operation of the Gempub reader as the `metadata.txt` file. Right now, the spec provides for: > Gempub files are zipped directories of Gemtext .gmi files plus an optional metadata file: > > • metadata.txt - a file containing the title, author and any other optional fields, see Metadata below > > This file enables Gempub to act as a full eBook format. Gemini capsules can also be simply zip compressed without the metadata file to act as a Gemini archive/offline format - when operating as an archive there must be an index.gmi in the root directory. What if we expand it to something along the following lines? > Gempub files are zipped directories of Gemtext .gmi files plus an optional metadata file: > > • metadata.txt - a file containing the title, author and any other optional fields. See "Metadata", below. > > The `metadata.txt` file enables Gempub to act as a full eBook format. However, a Gempub file can also be a simple zip-compressed capsule directory, which allows the Gempub container to serve as an offline Gemini capsule archive. In this case, however, the zipped Gempbub container must have either a `metadata.txt` file or an `index.gmi` file in the root directory of the archive. > > ### 2.3 The `metadata.txt` Metadata file > > [Keep as-is] > > ### 2.4 The `index.gmi` Index file > > The `index.gmi` file must be a `text/gemini` compliant UTF-8 file. Gempub reader applications shall display this file in accordance with the `text/gemini` specification. > > If a Gempub reader application uses the `index.gmi` file to automatically generate a table of contents, the following requirements apply: > > Links within the table of contents must be displayed in the order in which they are listed in the `index.gmi` file (from top to bottom). In other words, the first link in the table of contents must be the first link in the `index.gmi` file. > > If a link within the `index.gmi` file has a user-friendly link name, the Gempub reader application must display the user-friendly link name in the table of contents without prepending or appending any numbering or additional text. This permits Gempub authors to use their own chapter numbering and naming conventions. On the other hand, if a link within the `index.gmi` file has no user-friendly link name, the Gempub reader must display the link URL, and may prepend or append a number or other short descriptive text to the URL. > > During the reading process, the user should be able to begin with the first chapter and seamlessly advance through the contents of the Gempub archive by instructing the reader application to display the next page. The Gempub reader application must automatically advance through the contents of the Gempub archive in the order in which links are listed in the `index.gmi` file. For example, in the case where a user has completed reading the text of the file pointed to by the first link in the `index.gmi` file, and the user then instructs the reader application to advance to the next page, the reader application must automatically load and display the beginning of the file pointed to by the second link in the `index.gmi` file. > > This behavior is only permitted with respect to relative links that point to files contained within the Gempub archive. Per the `text/gemini` specification (section 5.4.2), clients must not automatically make any network connections as part of displaying [remote] links. Transparently loading a remote file in response to a user's "display next page" request would violate this prohibition. Therefore, in response to a "display next page" request by the user, Gempub reader applications must automatically load and display the contents of the next link in the `index.gmi` file that points to a file within the Gempub archive. > > ### 2.5 Content > ... Or... something along those lines. :)

👍 2

krixano commented 2 years ago

Poster

Links within the table of contents must be displayed in the order in which they are listed in the index.gmi file (from top to bottom). In other words, the first link in the table of contents must be the first link in the index.gmi file.

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. :)

> Links within the table of contents must be displayed in the order in which they are listed in the index.gmi file (from top to bottom). In other words, the first link in the table of contents must be the first link in the index.gmi file. 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. :)

krixano commented 2 years ago

Poster

Btw, I like everything raphm wrote above.

Btw, I like everything raphm wrote above.

oppenlab commented 2 years ago

Owner

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.

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.

skyjake commented 2 years ago

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.gmi since the actual filename can be specified in the metadata.

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.gmi` since the actual filename can be specified in the metadata.

👍 2

oppenlab commented 2 years ago

Owner

Good catch.

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!

Good catch. 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!

raphm commented 2 years ago

Collaborator

How about:

Gempub files are zip archives that contain a Gempub index file (see "Gempub Index", below), a collection of text/gemini (.gmi) files, any supporting files such as images (see "Images", below), and an optional metadata file containing the title, author and any other optional fields (see "Metadata", below).

A Gempub container can be created by simply zip-compressing a capsule directory. This allows the Gempub container to serve as both an e-book container and as an offline Gemini capsule archive. In either case, however, the root of the zipped Gempub container must have either a Gempub index file named index.gmi or a metadata file named metadata.txt with an index value that points to the location of a valid Gempub index file. (See "Example", above.)

2.3 The metadata.txt Metadata File

The metadata.txt file enables Gempub to act as a full e-book format by allowing the author to specify data such as a title, a cover image, copyright information, a book description, and author information.

[Keep the rest of this section as-is]

2.4 The Gempub Index File

The Gempub index file is a text/gemini compliant UTF-8 file that consists primarily (or solely) of a list of links to text/gemini content.

This file is a required file, and must either be located in the root directory of the archive and have the name index.gmi, or must have its name and location in the archive specified in the index entry of the metadata.txt file.

If a reader application cannot find a valid Gempub index file in either the root of the archive or the location pointed to by the index entry of the metadata.txt file, the reader application must display an error indicating that the archive is not a valid Gempub archive. The reader application may then either (a) refuse to open the archive, or (b) display the contents of the zip archive's root directory and allow the user to choose a file to use as the Gempub index file.

If a user directly views the Gempub index file, Gempub reader applications must display the file in accordance with the text/gemini specification. However, it is expected that the reader application will not typically directly display the Gempub index file, but will instead use this file to automatically generate a table of contents and to determine reading order, as follows:

The table of contents must be generated by assembling the links to local resources (items contained within the Gempub archive itself) and displaying them in the order in which they are listed in the Gempub index file (from top to bottom). In other words, the first link in the table of contents must be the first link in the Gempub index file.

If a link within the Gempub index file has a user-friendly link name, the Gempub reader application must display the user-friendly link name in the table of contents without prepending or appending any numbering or additional text. This permits Gempub authors to use their own chapter numbering and naming conventions. On the other hand, if a link within the Gempub index file has no user-friendly link name, the Gempub reader must display the link URL, and may prepend or append a number or other short descriptive text to the URL.

During the reading process, the user should be able to begin with the first item in the table of contents and seamlessly advance through the contents of the Gempub archive by instructing the reader application to display the next page. The Gempub reader application must automatically advance through the contents of the Gempub archive in the order in which links are listed in the Gempub index file. For example, in the case where a user has completed reading the text of the file pointed to by the first link in the Gempub index file, and the user then instructs the reader application to advance to the next page, the reader application must automatically load and display the beginning of the file pointed to by the second link in the Gempub index file.

This automatic load-and-display behavior is only permitted with respect to local links that point to files contained within the Gempub archive. Per the text/gemini specification (section 5.4.2), clients must not automatically make any network connections as part of displaying [remote] links. Transparently loading a remote file in response to a user's "display next page" request would violate this prohibition. Therefore, in response to a "display next page" request by the user, Gempub reader applications must automatically skip over links to remote resources, and instead must load and display the contents of the next link in the Gempub index file that points to a local resource (i.e., a file contained within the Gempub archive).

The automatic load-and-display behavior must be performed only for top-level links that are directly listed in the Gempub index file. In other words, the reader application must not recursively descend through linked files to determine reading order. In the case of an e-book, for example, the first chapter displayed to the user must be the contents of the first link in the Gempub index file. When the user asks the reader to "display next page" at the end of the first chapter, the reader application must display the contents of the next link in the Gempub index fie.

2.5 Content

All content must follow the text/gemini specification.

2.6 Images

...

How about: > Gempub files are `zip` archives that contain a Gempub index file (see "Gempub Index", below), a collection of `text/gemini` (`.gmi`) files, any supporting files such as images (see "Images", below), and an optional metadata file containing the title, author and any other optional fields (see "Metadata", below). > > A Gempub container can be created by simply zip-compressing a capsule directory. This allows the Gempub container to serve as both an e-book container and as an offline Gemini capsule archive. In either case, however, the root of the zipped Gempub container must have either a Gempub index file named `index.gmi` or a metadata file named `metadata.txt` with an `index` value that points to the location of a valid Gempub index file. (See "Example", above.) > > ### 2.3 The `metadata.txt` Metadata File > > The `metadata.txt` file enables Gempub to act as a full e-book format by allowing the author to specify data such as a title, a cover image, copyright information, a book description, and author information. > > [Keep the rest of this section as-is] > > ### 2.4 The Gempub Index File > > The Gempub index file is a `text/gemini` compliant UTF-8 file that consists primarily (or solely) of a list of links to `text/gemini` content. > > This file is a required file, and must either be located in the root directory of the archive and have the name `index.gmi`, or must have its name and location in the archive specified in the `index` entry of the `metadata.txt` file. > > If a reader application cannot find a valid Gempub index file in either the root of the archive or the location pointed to by the `index` entry of the `metadata.txt` file, the reader application must display an error indicating that the archive is not a valid Gempub archive. The reader application may then either (a) refuse to open the archive, or (b) display the contents of the `zip` archive's root directory and allow the user to choose a file to use as the Gempub index file. > > If a user directly views the Gempub index file, Gempub reader applications must display the file in accordance with the `text/gemini` specification. However, it is expected that the reader application will not typically directly display the Gempub index file, but will instead use this file to automatically generate a table of contents and to determine reading order, as follows: > > The table of contents must be generated by assembling the links to local resources (items contained within the Gempub archive itself) and displaying them in the order in which they are listed in the Gempub index file (from top to bottom). In other words, the first link in the table of contents must be the first link in the Gempub index file. > > If a link within the Gempub index file has a user-friendly link name, the Gempub reader application must display the user-friendly link name in the table of contents without prepending or appending any numbering or additional text. This permits Gempub authors to use their own chapter numbering and naming conventions. On the other hand, if a link within the Gempub index file has no user-friendly link name, the Gempub reader must display the link URL, and may prepend or append a number or other short descriptive text to the URL. > > During the reading process, the user should be able to begin with the first item in the table of contents and seamlessly advance through the contents of the Gempub archive by instructing the reader application to display the next page. The Gempub reader application must automatically advance through the contents of the Gempub archive in the order in which links are listed in the Gempub index file. For example, in the case where a user has completed reading the text of the file pointed to by the first link in the Gempub index file, and the user then instructs the reader application to advance to the next page, the reader application must automatically load and display the beginning of the file pointed to by the second link in the Gempub index file. > > This automatic load-and-display behavior is only permitted with respect to local links that point to files contained within the Gempub archive. Per the `text/gemini` specification (section 5.4.2), clients must not automatically make any network connections as part of displaying [remote] links. Transparently loading a remote file in response to a user's "display next page" request would violate this prohibition. Therefore, in response to a "display next page" request by the user, Gempub reader applications must automatically skip over links to remote resources, and instead must load and display the contents of the next link in the Gempub index file that points to a local resource (i.e., a file contained within the Gempub archive). > > The automatic load-and-display behavior must be performed only for top-level links that are directly listed in the Gempub index file. In other words, the reader application must not recursively descend through linked files to determine reading order. In the case of an e-book, for example, the first chapter displayed to the user must be the contents of the first link in the Gempub index file. When the user asks the reader to "display next page" at the end of the first chapter, the reader application must display the contents of the next link in the Gempub index fie. > > ### 2.5 Content > > All content must follow the `text/gemini` specification. > > ### 2.6 Images > ...

skyjake commented 2 years ago

That sounds quite good!

@raphm wrote:

However, it is expected that the reader application will not typically directly display the Gempub index file, but will instead use this file to automatically generate a table of contents and to determine reading order

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:

• Allow a simple reader application to show the page as the TOC, no additional work required.
• Give the Gempub author full control over its appearance with regard to any content in addition to the navigational links. For example, it could include brief summaries of each chapter.
• Archive Gempubs can use the capsule index page as-is.

The exact rules for generating a TOC and how navigation should behave are good to specify, though, as you suggest.

That sounds quite good! @raphm wrote: > However, it is expected that the reader application will not typically directly display the Gempub index file, but will instead use this file to automatically generate a table of contents and to determine reading order 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: * Allow a simple reader application to show the page as the TOC, no additional work required. * Give the Gempub author full control over its appearance with regard to any content in addition to the navigational links. For example, it could include brief summaries of each chapter. * Archive Gempubs can use the capsule index page as-is. The exact rules for generating a TOC and how navigation should behave are good to specify, though, as you suggest.

raphm commented 2 years ago

Collaborator

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:

If a user directly views the Gempub index file, Gempub reader applications must display the file in accordance with the text/gemini specification. However, it is expected that the reader application will not typically directly display the Gempub index file, but will instead use this file to automatically generate a table of contents and to determine reading order, as follows:

The table of contents must be generated by assembling the links to local resources (items contained within the Gempub archive itself) and displaying them in the order in which they are listed in the Gempub index file (from top to bottom). In other words, the first link in the table of contents must be the first link in the Gempub index file.

If a link within the Gempub index file has a user-friendly link name, the Gempub reader application must display the user-friendly link name in the table of contents without prepending or appending any numbering or additional text. This permits Gempub authors to use their own chapter numbering and naming conventions. On the other hand, if a link within the Gempub index file has no user-friendly link name, the Gempub reader must display the link URL, and may prepend or append a number or other short descriptive text to the URL.

With these:

When opening a Gempub archive, Gempub reader applications shall use the Gempub index page as the archive's table of contents, and shall display the archive's Gempub index page in accordance with the text/gemini specification. Gempub authors are expected to build the Gempub index page by adding links to content pages contained elsewhere within the archive. Remote links (links to remote resources that are not contained in the archive) are permitted within the Gempub index page, but reader applications must ignore remote links when creating an application-specific representation of the table of contents (see below) and when determining reading order (see below).

The Gempub index file may include content other than links. For example, the Gempub index file could include introductory text, or brief summaries of each chapter next to the link pointing to the chapter's content.

There are no other requirements with respect to the Gempub index file. Simple reader applications may display the page as the table of contents, with no additional work required, and archival Gempubs may use the "root" file of the capsule as-is.

More complex reader applications may use the Gempub index file to generate an application-specific representation of the archive's table of contents and to determine automatic reading order, as follows:

An application-specific representation of an archive's table of contents must be generated by assembling links to local resources (items contained within the Gempub archive itself) and displaying them in the order in which they are listed in the Gempub index file (from top to bottom). In other words, the first link in the application-specific representation of the table of contents must be the first local link in the Gempub index file.

If a link within the Gempub index file has a user-friendly link name, the Gempub reader application must display the user-friendly link name in the application-specific representation of the table of contents without prepending or appending any numbering or additional text. This permits Gempub authors to use their own chapter numbering and naming conventions. On the other hand, if a link within the Gempub index file has no user-friendly link name, the Gempub reader must display the link URL, and may prepend or append a number or other short descriptive text to the URL.

Does that capture it properly?

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: > If a user directly views the Gempub index file, Gempub reader applications must display the file in accordance with the text/gemini specification. However, it is expected that the reader application will not typically directly display the Gempub index file, but will instead use this file to automatically generate a table of contents and to determine reading order, as follows: > > The table of contents must be generated by assembling the links to local resources (items contained within the Gempub archive itself) and displaying them in the order in which they are listed in the Gempub index file (from top to bottom). In other words, the first link in the table of contents must be the first link in the Gempub index file. > > If a link within the Gempub index file has a user-friendly link name, the Gempub reader application must display the user-friendly link name in the table of contents without prepending or appending any numbering or additional text. This permits Gempub authors to use their own chapter numbering and naming conventions. On the other hand, if a link within the Gempub index file has no user-friendly link name, the Gempub reader must display the link URL, and may prepend or append a number or other short descriptive text to the URL. With these: > When opening a Gempub archive, Gempub reader applications shall use the Gempub index page as the archive's table of contents, and shall display the archive's Gempub index page in accordance with the `text/gemini` specification. Gempub authors are expected to build the Gempub index page by adding links to content pages contained elsewhere within the archive. Remote links (links to remote resources that are not contained in the archive) are permitted within the Gempub index page, but reader applications must ignore remote links when creating an application-specific representation of the table of contents (see below) and when determining reading order (see below). > > The Gempub index file may include content other than links. For example, the Gempub index file could include introductory text, or brief summaries of each chapter next to the link pointing to the chapter's content. > > There are no other requirements with respect to the Gempub index file. Simple reader applications may display the page as the table of contents, with no additional work required, and archival Gempubs may use the "root" file of the capsule as-is. > > More complex reader applications may use the Gempub index file to generate an application-specific representation of the archive's table of contents and to determine automatic reading order, as follows: > > An application-specific representation of an archive's table of contents must be generated by assembling links to local resources (items contained within the Gempub archive itself) and displaying them in the order in which they are listed in the Gempub index file (from top to bottom). In other words, the first link in the application-specific representation of the table of contents must be the first local link in the Gempub index file. > > If a link within the Gempub index file has a user-friendly link name, the Gempub reader application must display the user-friendly link name in the application-specific representation of the table of contents without prepending or appending any numbering or additional text. This permits Gempub authors to use their own chapter numbering and naming conventions. On the other hand, if a link within the Gempub index file has no user-friendly link name, the Gempub reader must display the link URL, and may prepend or append a number or other short descriptive text to the URL. Does that capture it properly?

👍 1

raphm commented 2 years ago

Collaborator

@oppenlab If you sign off on the above changes I am happy to get them into the current working version of the spec. :)

@oppenlab If you sign off on the above changes I am happy to get them into the current working version of the spec. :)

skyjake commented 2 years ago

@raphm

Does that capture it properly?

Sounds good to me at least. 👍

@raphm > Does that capture it properly? Sounds good to me at least. :+1:

oppenlab commented 2 years ago

Owner

@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.

@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.

raphm referenced this issue from a commit 2 years ago

Added language describing ZIP structure. Should allow us to close #2, #9, and #15.

raphm commented 2 years ago

Collaborator

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. :)

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. :)

oppenlab commented 2 years ago

Owner

@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.

@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.

👍 2

Sign in to join this conversation.

No Branch/Tag Specified

Branches Tags

main

Labels

Apply labels

Clear labels

No items

No Label

Milestone

Set milestone

Clear milestone

No items

No Milestone

Projects

Set Project

Clear projects

No project

Assignees

Assign users

Clear assignees

No Assignees

4 Participants

Notifications

Subscribe

Due Date

The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: oppenlab/gempub#9

Write Preview

Loading…

Cancel

Save

There is no content yet.