finanalyst commented 8 months ago

@coke @lizmat I'm creating an issue here and tagging you both, but maybe I should tag a group?

This is in issue form for feed back. I don't think discussions generate much feedback.

Abstract

The E-Book format being targetted is 'epub' as it seems the most widely support and is open-source. An epub can be characterised as a web in a file container that a ebook reader can display. The epub website will be simpler than the internet live website.

Detail

The following simplifications are my initial thoughts as I implement the epub. If anyone has other suggestions based on epub creation experience, please let me know. Otherwise, I expect the first epub creation (draft?) will generate lots of suggestions when we can test it on real users and varied e-book readers.

The simplifications:

The web page headers (ebook chapter headings) will be simpler and do not need so much navigation.
The Table of Contents, a standard in books and replacing the navigation bars common in 'live' websites, will contain
- the three main tabs (as book sections) - Introduction, Reference, Miscellaneous
- within each section, web pages (eg. language/operators) will be listed as chapters, and within each chapter the web page's own Table of Contents will be listed as next level contents.
There will not be a search function (initially, but one may be added in due course when someone in the community figures out the possibilities of search in an epub)
The relation graphs will be omitted for Type pages.
- The reason for this is that the graphs are very large and there are a lot of them. On a website, the graphs are only loaded when a page with a graph is requested from the server. In an epub, they would all need to be included in the book, making it very large.
- The secondary (aka Composite) files are not created or included
- There are several thousand secondary pages. All the information in them is contained in the primary pages.
- links to secondary files will initially yield 404 type errors in the epub.
- A better strategy will need to be thought about.

coke commented 8 months ago

This seems like a great first pass! I especially agree about skipping the class hierarchy images and the majority of the generated pages. We might want to have some generated pages just for the epub- maybe an intro page only to start? I can provide some content for that page.

finanalyst commented 8 months ago

@coke It seems that there is a significant difference between epub v2 and epub v3 in so far as Table of Contents are created and read (toc.ncx vs toc.xhtml). See SO thread

I am going to target v3 initially. This might reduce the ability of some ebook readers. If users report a problem, we can add a separate toc.ncx to the ebook data.

finanalyst commented 7 months ago

@dontlaugh I merged part of the docs-dev branch into main. The patch related to putting commit id information into the edit button. I thought I had deleted the branch. Then I uploaded a large number of files into the EBook directory as part of a "new" 'docs-dev' branch. But there is no new PR. I am confused as to what has happened.

The changes to EBook will NOT affect the website! In order for Collection to build the EBook, the command bin_files/build-site EBook would need to be executed. Note that the flag --without-completion should not be added (which is needed to build the website).

Running build-site EBook will generate a directory unzipped-ebook and RakuDocumentation.epub in the repo's root.

coke commented 7 months ago

PRs are not automatically created.

On Fri, Apr 26, 2024 at 6:13 PM Richard Hainsworth @.***> wrote:

@dontlaugh https://github.com/dontlaugh I merged part of the docs-dev branch into main. The patch related to putting commit id information into the edit button. I thought I had deleted the branch. Then I uploaded a large number of files into the EBook directory as part of a "new" 'docs-dev' branch. But there is no new PR. I am confused as to what has happened.

The changes to EBook will NOT affect the website! In order for Collection to build the EBook, the command bin_files/build-site EBook would need to be executed. Note that the flag --without-completion should not be added (which is needed to build the website).

Running build-site EBook will generate a directory unzipped-ebook and RakuDocumentation.epub in the repo's root.

— Reply to this email directly, view it on GitHub https://github.com/Raku/doc-website/issues/356#issuecomment-2080181669, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAMIUOXVBR445BAIHLPRZ3Y7LGQZAVCNFSM6AAAAABFGWVHF6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDAOBQGE4DCNRWHE . You are receiving this because you were mentioned.Message ID: @.***>

coke commented 7 months ago

Also you committed directly to main with a commit message of "docs-dev", not to a branch.

https://github.com/Raku/doc-website/commit/98f36e73211a7b7675be59716a631f7f0b9c9989

On Fri, Apr 26, 2024 at 6:14 PM Will Coleda @.***> wrote:

PRs are not automatically created.

On Fri, Apr 26, 2024 at 6:13 PM Richard Hainsworth < @.***> wrote:

@dontlaugh https://github.com/dontlaugh I merged part of the docs-dev branch into main. The patch related to putting commit id information into the edit button. I thought I had deleted the branch. Then I uploaded a large number of files into the EBook directory as part of a "new" 'docs-dev' branch. But there is no new PR. I am confused as to what has happened.

The changes to EBook will NOT affect the website! In order for Collection to build the EBook, the command bin_files/build-site EBook would need to be executed. Note that the flag --without-completion should not be added (which is needed to build the website).

Running build-site EBook will generate a directory unzipped-ebook and RakuDocumentation.epub in the repo's root.

— Reply to this email directly, view it on GitHub https://github.com/Raku/doc-website/issues/356#issuecomment-2080181669, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAAMIUOXVBR445BAIHLPRZ3Y7LGQZAVCNFSM6AAAAABFGWVHF6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDAOBQGE4DCNRWHE . You are receiving this because you were mentioned.Message ID: @.***>

finanalyst commented 7 months ago

@coke @dontlaugh (please read question below) I am still very much a newbie when it comes to git. Please have patience with me. After a good night's sleep, here's what I think is the situation (you may know this already, in which case I'm explaining to myself):

The work I did on the docs-dev branch relating to commit-id info was merged to main with 98f36e7.
These changes can be seen in the main branch now
build-kite shows these patches are not affecting the current work flow
I deleted the docs-dev branch, but then replied to @coke, which seems to have re-opened it.
I then uploaded a whole set of new patches to docs-dev relating to EBook.
These files can be seen in the docs-dev branch, but not the main branch

Some questions: question-1. @dontlaugh How to take this work further? I suggest adding the following to .buildkite/pipeline.yaml

  - label: "Build Ebook"
    key: ebook
    if: build.branch == 'docs-dev'
    depends_on:
      - build
    commands:
      - "./bin_files/build-site --no-status EBook"

I have not done this because I do not know the consequences for the build-kite process

The effect of the last command would create 'RakuDocumentation.epub' in the root directory.

question-2. @dontlaugh how do we make the epub available on line? Does it need to be added to the container served by Caddy?

finanalyst commented 7 months ago

@coke You said

We might want to have some generated pages just for the epub- maybe an intro page only to start? I can provide some content for that page.

I have adapted the About page from the website, but it's not really good. So, please change it.

The source is EBook/structure-sources/about.rakudoc

Note the :kinds<...> :subkinds<...> :category<...> metadata in the source's =begin rakudoc line. These metadata are contatenated to create keys in hashes that are used to define the order of the files in the ToC and the reading order (called spline data). Some sets of data have a defined order at the top. Unknown keys (not pre-defined in 'embed-ebook`) are then sorted alphabetically for the ToC and spline data.

If you want to create a file that is at the end (but before the Index) then make kind<ZZZ> or something that sorts last.

finanalyst commented 7 months ago

@coke I have modified my new-raku deployment to download the ebook. It can be accessed by clicking on 'More' in the top-page navigation bar. Clicking on Download Ebook pops up a modal with the download link. This one UX. Other ideas are possible. Let me know your preferences for the official website.

The EBook - I am sure - needs some TLC. It needs a cover. The CSS needs changing, particularly for the code snippets, which mess up my Calibre reader if the page width is not wide enough. I have only tested it on a desktop.

coke commented 7 months ago

The download fails to import into Apple Books app on a mac laptop. No errors are given.

coke commented 7 months ago

I was able to read it with brew install --cask calibre and then using calibre to read the epub. Definitely agree that this needs some tweaking, but it's already good enough to be able to search for (e.g.) uniprop and read the docs.

finanalyst commented 7 months ago

@coke I dont have access to a Mac. I searched Apple Books & epub, and there is a way to import epub. But the description does not mention whether Apple Book App will read the Epub v3 spec or only v2. Current version in this patch targets v3.

I've done as much as I can at present, and I need to return to the RakuAST Rakudoc v2 renderer.

For others to help on the CSS, all it takes (I hope), is to tweak the SCSS files in ebook-embed.

coke commented 7 months ago

If you can update the popup window to mention the epub v3 restriction, I have no problem with this getting merged to main

coke commented 7 months ago

FYI:

13:12 < lizmat> fwiw, I've downloaded Yomu and that at least opens it after complaining it's not compliant because of
                missing TOC

finanalyst commented 7 months ago

@coke

I can add reference to v3 to the Popup for my new-raku deployment.
I'll add a patch to docs-dev to incorporate this UX
It will 404 on docs-dev.raku.org without a change to the infra-structure script, which I dont want to change without feedback from @dontlaugh
I've seen @lizmat 's comment. It looks to me to be related to the v2 standard. Epub v2 requires a toc.ncx file.
I'm looking at creating one in parallel with the xhtml one.

finanalyst commented 7 months ago

@coke

new text on new-raku
docs-dev now has a patch to add item to Nav bar (text from new-raku))

dontlaugh commented 6 months ago

Ebook is now available on https://docs.raku.org (click the "More" navigation link)

finanalyst commented 5 months ago

closing design thread. Failure issues in #374

Raku / doc-website

E-Book design - initial design #356

Abstract

Detail