Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

E-Book design - initial design #356

Closed
finanalyst opened this issue Mar 25, 2024 · 17 comments
Closed

E-Book design - initial design #356

finanalyst opened this issue Mar 25, 2024 · 17 comments
Milestone
2024-Quarter-2

Comments

@finanalyst
Copy link
Collaborator

@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.
finanalyst added a commit that referenced this issue Mar 25, 2024
@finanalyst
Start creating EBook mode
ca2506e 
- the aim of this node is to create an epub version of the Raku Documentation suite
- An epub can be described as a web site encapsulated into a file.
- See issue #356 for initial design goals.
@finanalyst finanalyst mentioned this issue Mar 25, 2024
Merged
@coke
Copy link
Contributor

coke commented Mar 25, 2024

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 added a commit that referenced this issue Mar 25, 2024
@finanalyst
Start creating EBook mode (#357)
e14f751 
- the aim of this node is to create an epub version of the Raku Documentation suite
- An epub can be described as a web site encapsulated into a file.
- See issue #356 for initial design goals.
@finanalyst
Copy link
Collaborator Author

finanalyst commented Mar 26, 2024 •
edited
Loading

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

@coke coke added this to the 2024-Quarter-2 milestone Mar 31, 2024
finanalyst added a commit that referenced this issue Apr 26, 2024
@finanalyst
Docs dev (#364)
98f36e7 
* Start creating EBook mode
- the aim of this node is to create an epub version of the Raku Documentation suite
- An epub can be described as a web site encapsulated into a file.
- See issue #356 for initial design goals.

* resolves issue #316 adds commit id & date to files
- uses new Collection functionality to gather information about each file rendered
- information added at bottom and in 'edit button' on right

* bump versions for Collection and Raku-Pod-Render

* fix template for doc-website commit
@finanalyst
Copy link
Collaborator Author

@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
Copy link
Contributor

coke commented Apr 26, 2024 via email

@coke
Copy link
Contributor

coke commented Apr 27, 2024 via email

@finanalyst
Copy link
Collaborator Author

@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
Copy link
Collaborator Author

@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
Copy link
Collaborator Author

@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
Copy link
Contributor

coke commented Apr 28, 2024 •
edited
Loading

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

@coke
Copy link
Contributor

coke commented Apr 28, 2024 •
edited
Loading

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
Copy link
Collaborator Author

@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
Copy link
Contributor

coke commented Apr 28, 2024

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

@coke
Copy link
Contributor

coke commented Apr 28, 2024

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
Copy link
Collaborator Author

@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
Copy link
Collaborator Author

@coke

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

@finanalyst finanalyst mentioned this issue Apr 29, 2024
Closed
@dontlaugh dontlaugh mentioned this issue May 7, 2024
Merged
@dontlaugh
Copy link
Collaborator

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

@finanalyst
Copy link
Collaborator Author

closing design thread. Failure issues in #374

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
2024-Quarter-2
Development

No branches or pull requests
3 participants
@coke @finanalyst @dontlaugh