Interactive eBook

[ccoupe]

This is something @BackOrder and I discussed in email a year to so ago and he wrote some proof of concept code but there were gems issues on Windows that prevented progress and we correctly went about fixing bugs and implementing lots of new features like svg and video. I don't want to loose track of the idea. This idea is not really an enhancement to Shoes but a use of Shoes as a platform.

The basic idea was the Shoes manual is damn cool with it's side bars and search and run this/copy this functions and back/forward buttons. What if we could use do those things for other content that used more mainstream markup/down than what the Shoes manual uses? My thought was to extract all my .md files from the wiki and produce a packaged Shoes app so my wiki wisdom was search-able and more structured supplement to the manual. We all hate the mark up of the Manual but their are existing gems to move one markup to another.

Generalizing higher. Just about any body's markup could become an Shoes.App and searchable (unlike pdf). @BackOrder found a better full text search engine gem that is superior to the fragile one in Shoes. But there was problem. That text indexer requires a gem that won't compile with the older gcc used in RubyInstaller or my cross compiler. in #209 I mention building a new set of Windows deps using the mingw gcc 4.9 compiler instead what's in RubyInstaller. Guess which gcc version was needed for that text indexing gem? Go ahead, guess.

Along with the proposed #212 ability to hide Shoes this might become something interesting. What if your ebook had svg or video or audo links playable from the Shoes ebook?

[IanTrudel]

Thank you for the reminder.I still got to send you my proof of concept.

[passenger94]

i wrote something like that : https://github.com/passenger94/Gimp-Ruby/blob/master/doc/shoes_guide.rb Hand crafted though

I'm all for the idea

[ccoupe]

@BackOrder , I think I have a copy. I don't remember the name of the problematic gem but I do remember talking with the author and he then posted on RubyInstaller ML hoping for gcc updrade . He had some sort of c++ class initiation thingy that needed gcc 4.9.x

Couple of years ago I downloaded an epub about Artificial Intelligence (AI) algorithms written in Ruby and there was no 'copy this' or 'run this' buttons and I thought what an opportunity for Shoes! Now, we're close enough that it is not impossible to create such a document. Difficult perhaps. Perhaps not so hard. I also like a guiding vision, a stretch goal. Even if it's never complete or exactly like I imagine.

[ccoupe]

After much scrolling through the email archives the problematic gem was 'Picky'. @passenger94 , it don't have that code for the ebook experiment - I've got the older ftsearch example.

Well that's embarrassing. I meant to invoke @BackOrder and it was google-hash with the gcc compiler version problem.

[passenger94]

While contemplating this idea, i experimented the, confusing to me, url/visit protocol. I found that visit method is not the only way to leverage the class approach, "visit" is basically driving you to a new app, so every time you visit, you have to rewrite what's on screen and sharing variables happens at the class level (unless some meta voodoo allows it !?). class-book.rb doesn't use visit method (like expert-url.rb) but rewrite everything, a design choice, and use url protocol to switch between "screens" hence the confusion, but you don't have to ! Here's expert-url rewritten without visit method, sharing variables is easy like in regular Shoes app (no need for class variables)

class MyApp < Shoes
  url "/", :setupscreen # Mandatory entry for Shoes.app

  def setupscreen
    @main_slot = stack do 
      @intro = para "Welcome to My Demo app"
      @btns_slot = flow do
        button "entry" do entryscreen end
        button "help" do helpscreen end
      end
      @secret_slot = flow hidden: true do
        para "found a secret : "
        @found = para ""
      end
    end
  end

  def homescreen(a_secret="")
    @intro.text = "Welcome to My Demo app \n", span("#{@shared}", size: 10)
    @btns_slot.clear do
      button "entry" do @secret_slot.hide; entryscreen end
      button "help" do @secret_slot.hide; helpscreen end
    end
    @found.text = a_secret
    @secret_slot.show
  end

  def entryscreen
    @intro.text = "Entry Screen - whats your secret?\n", span("#{@shared}", size: 10)
    the_secret = edit_line text: "I'm not telling you"

    @btns_slot.clear do
      button "home" do homescreen(the_secret.text); the_secret.remove end
      button "help" do helpscreen; the_secret.remove end
    end
  end

  def helpscreen
    @intro.text =  "This page describes MyApp, a very demo for structuring a Shoes application"
    @shared = "helpscreen was so glad to see somebody !"
    @btns_slot.clear  do
      button "entry" do entryscreen end
      button "home" do homescreen("no secret at Help page !") end
    end
  end
end
Shoes.app :width => 400, :height => 300, :margin => 5

Just another option (i kept the "screen" suffix for easy comparison but screen is more pertinent to visit)

The real fun begins when you realize one can probably mix both approach !!! (Tabulated, panelled interface, comes to mind)

Oh , i came to this because Shoes has a hard time dealing with big quantity of text, (too much redrawing ?) In case of a novel, for example, we would have to split the text, presenting parts of it only (chapters being an obvious option, like manual)

[passenger94]

Picky goes straight to the marrows but picky about Windows ?

[passenger94]

FWIW wrote a tiny script to translate manual to markdown, result is here https://github.com/passenger94/shoes3/blob/manual_mardown/shoesManual_redcarpet01.md

[IanTrudel]

@passenger94 great job!

I had the idea that Shoes help should also use markdown. Some of my preliminary tests were promising.

[passenger94]

Thanks :-) I mostly reused the Regex in help.rb, still lots of tiny glitches due to not so simple things to translate from Shoes "markdown" (redcloth i guess) to more standard markdown (RedCarpet html renderer). Do you know how to feed a markdown file so it uses a ssl style sheet to render, i mean here at github for example, if it's at all possible ? Also there is those images to place correctly ...

Github pages seems the way to go for more control ...

[passenger94]

Ah ! markdown inside Shoes ! would be easier to dewikify ? (in Shoes manual parlance)

[ccoupe]

Don't forget - there is a Shoes command line switch '--manual-html DIRECTORY' to convert the manual to html. It's been a while since since I've tried it. I never liked myself but it might be have clues in the code.

[ccoupe]

And https://github.com/gettalong/kramdown might be useful.

[IanTrudel]

@passenger94 exactly, using markdown inside Shoes manual. Kramdown is what I used for my tests.

[IanTrudel]

@ccoupe are you sure that I sent you my eBook code? I found in our email correspondance eShoes.7z but it's a standalone version of The Shoes Manual. There is no Picky, Kramdown, etc. in this version.

[ccoupe]

@BackOrder. That's what I have. But sometime after that , you replaced ftsearch with picky and it's many dependencies because the shoes markdown/ftsearch combo was too sensitive to trailing spaces (or some other trivial textual thing) and you thought it was a better full text engine. . It ran on your Windows box, it ran on my Ubuntu box but google_hash gem would not install on my Windows VM and after some back and forth with the google_hash author, he determined my (RubyInstaller's) version of gcc was too old for his code. I wouldn't make that up. Maybe you did the work on your Mac laptop? It was just before you vanished into Euro Land or a many months.

[passenger94]

command line switch '--manual-html DIRECTORY' doesn't work because it uses hpricot, which we don't ship anymore, right ? The html building part is disabled. Never worked for me, anyway, did anyone had success with this ?

[passenger94]

@BackOrder The idea is to write the manual in markdown/kramdown notation and then to write a kramdown => Shoes converter, inherited from Kramdown::Converter::Base ?

Once the concept works, could be easily generalized for any markdown/ebook, do i get this right ?

[ccoupe]

There were several ideas going around back then. One issues is the Shoes markdown is pretty odd. Another issue was that ftsearsch is fragile about slight errors in whatever it parses and lacks some full text search features that other gems (picky) can provide. Then I thought one day we'll be able to package native gems with Shoes app and we could build more interactive ebooks and put the content in something like the Shoes manual with it back/forward button and table of contents on the left side and clicking and linking with the document. @BackOrder did proof of concept of converting the manual.en.txt to markdown (much like you did) and a Small Shoes app that replaced shoes.rb and only runs the Manual.

We never got to defining what that markdown or syntax to use for run-this buttons and copy-this or Shoes capabilies. We used manual-en.txt because it was convenient and well formated because of the ftsearch issues. Lots of tangled agendas and ideas. It can be approached from several directions. Converting the Shoes Manual to a better markdown is one approach (and a good approach). So, yes you are correct, @passenger94 - markdown (md and perhaps other formats) converted to something a new shoes/help.rb can layout and navigate around.

Heres a link to backorder first code: http://walkabout.mvmanila.com/public/share/eShoes.7z

[ccoupe]

Gem Picky has a newer version 4.31.3 with fewer dependent gems and only two of them are native and google_hash is not one of them.

cccoupe@mintvm ~ $ gem install picky --no-doc
Fetching: url_escape-2009.06.24.gem (100%)
Building native extensions.  This could take a while...
Successfully installed url_escape-2009.06.24
Fetching: rack_fast_escape-2009.06.24.gem (100%)
============================================================

Thank you for installing RackFastEscape!

============================================================
Successfully installed rack_fast_escape-2009.06.24
Fetching: concurrent-ruby-1.0.2.gem (100%)
Successfully installed concurrent-ruby-1.0.2
Fetching: thread_safe-0.3.5.gem (100%)
Successfully installed thread_safe-0.3.5
Fetching: tzinfo-1.2.2.gem (100%)
Successfully installed tzinfo-1.2.2
Fetching: i18n-0.7.0.gem (100%)
Successfully installed i18n-0.7.0
Fetching: activesupport-5.0.0.1.gem (100%)
Successfully installed activesupport-5.0.0.1
Fetching: picky-4.31.3.gem (100%)
Building native extensions.  This could take a while...
Successfully installed picky-4.31.3
8 gems installed
ccoupe@mintvm ~ $

Will those build with devkit and the cross compiler?

[ccoupe]

Yes!!! After the dance with the old ssl certificate picky does build on Windows, Which means we can include it and all it's dependent gems in Shoes. I prefer to cross compile so I'll try that next. Assume success Then what?

We still need a way do the run this and copy_this buttons for the {{{ }}} examples.

[ccoupe]

One thing I'd like to consider is moving the ebook into a new github project. Now that we can do merge-packaging (doesn't depend on a Shoes). For example, call the project ' ebook' and distribute ebook.exe, ebook.app, ebook.deb and ebook.rpm. It's a real app installed into system dirs and completely indifferent to any Shoes that might be installed or not installed. Merge packaging has the ability to include gems in the installed Ruby.

The Shoes manual or the wiki could be just one of many 'ebooks' in kramdown format that could be read' by the new app. Not deeply tied too any shoes versions or ruby version since it has its own. It's really quite liberating. Consider: There would not have to be a Splash screen link in Shoes for " Read the Manual" - its a different app in the menu system.

Let me float a name past you. I kind of 'ShoesBook' as an project and app name. (hard to reverse later so let's get it correct first). The 'books' would be .tgz inside since we have that code already in rubygems and it works everywhere. What would be the file extension? I don't think Windows 8.3 doesn't has to apply. ".shoesbook"? ".rubybook"?

[IanTrudel]

This is a fantastic idea. I like it very much.

We could simply use the repository name Shoes3/eBook.

How about one of those cool names in the line of Shoes? Like ShoesMagazine. We have a logo of a magazine about Shoes shopping (haha) with Shoes logo stamped on it. Glamorous. Or we can go simply with Shoes Book as you suggest with extension of .sb (might collide with Scratch) or .skb (Shoes Kramdown Book).

RE: Shoes Book integration to Shoes

Shoes eBook would be a dependency of Shoes, the Picky database would be generated so the users don't have to wait the database to build the first time they open the eBook.

What do you think?

[ccoupe]

There is much to be done. I think I mentioned it once before but I download an .epub of some Ruby AI algorithms - the code was part of the epub but you had to download the code from the authors website. In a ShoesBook you could run/copy them as you study the text. Now that we have the new terminal even simple bare Ruby can display it. Imagine the whole Pickaxe Book with runnable examples! - not practical but newer tomes could be written - like the manual and wiki.

There would be a ShoesBook.exe and a ShoesBook.app and a ShoesBook.deb (rpm ...) which can load any .skb file. A user level Shoes-er and author could create his ebook in .skb format, test it with that app and then distribute the .skb , or if he only cares about Windows folks, create his own .exe and distribute that as mybook.exe. Or if his ebook only applies to Raspberry Pi users he can a create a mybook-rpi.deb and include what ever gems in the deb that makes sense to them.

Windows 'publishers' would have to install NSIS, Linux publishers would have to install the fpm gem. Windows folk will have to some basic NSIS things like their icon and installer images. Then they can turn their .skb into a exe/app/deb. This a burden that can't be avoided.

Shoes eBook would be a dependency of Shoes

I tend to think that ShoesBook is dependent on shoes3 and exe-shoes, osx-shoes, and linux-shoes.

I'm just spec-ing out loud as I type, so reality will be different. The github shoes3/ebook project would just be load/test/save (save is running platform dependent).

It gets weird.

[IanTrudel]

This all make sense to me. Additionally, we may actually be able to support epub using epub-parser. It would not be a stretch to recognize Ruby code and make it runnable in Ruby ePub books. We could also provide web support, which would make it possible to read and run examples from The Pragmatic Programmer's Guide. Nothing becomes a stretch once the engine supports Kramdown as a backend. We can add any backend.

Shoes eBook would be a dependency of Shoes

I should clarify: Shoes Manual would be written using Shoes eBook. Circular dependency. Shoes eBook is built on top of Shoes, Shoes has Shoes Manual built using Shoes eBook.

[ccoupe]

Circular dependency. Shoes eBook is built on top of Shoes, Shoes has Shoes Manual built using Shoes eBook.

Yes, sigh. Like needing RubyInstaller to build devkit and needing devkit to build rubyinstaller. Once you create one it's very difficult to break later. I'll create a github shoes3/ebook project/repo and an initial README.md, add you two to the membership and populate with what ever sample code noted above. and create the first issue.

I may attempt to use git submodules to pull in the shoes3/exe-shoes, shoes3/osx-shoes, and shoes3/linux-shoes projects because I might want to include them in shoes3/shoes too.

[IanTrudel]

Circular dependency.

It's actually not a big deal. Shoes itself will only need Ruby files from the eBook repository. We can then prebuild a Picky database and that's about it.

For building a standalone Shoes eBook, we might simply need shoes3/exe-shoes, shoes3/osx-shoes, and shoes3/linux-shoes.

I may attempt to use git submodules to pull in the shoes3/exe-shoes, shoes3/osx-shoes, and shoes3/linux-shoes projects because I might want to include them in shoes3/shoes too.

It was duly noticed. Hence I suggested Shoes3/eBook.

http://walkabout.mvmanila.com/public/share/eShoes.7z

Interestingly, I had named it eShoes. Why didn't we stick to that? :)