Fixes #90 (Hi there)

[Joseph Pearson]

I wondered whether we should have a discussion forum and dev community around Monocle at the start of the year, in this GitHub issue:

     https://github.com/joseph/Monocle/issues/90

There wasn't exactly consensus. Now, with the release of Monocle 3.0.0, I thought we could dive in and see if it works.

It's awesome to see experienced Monocle devs helping new Monocle devs in the Issues list (especially since I'm notoriously slow to respond; apologies). Some of those discussions might benefit from a more forum-oriented space like this one. That would also free up the Issues list to track confirmed bugs.

Still, my main purpose for this list is to plan the future of Monocle. I've had pretty exclusive control of Monocle for 2.5 years, but since there's a number of significant projects now being built with the library, I want to hear from people when I'm considering features (or when I'm not and should be).

So, let's see how this goes. Join in if you can.

— J

[Luther Goh Lu Feng]

I am curious. Which projects are built with Monocle? Is there a list somewhere?

[Joseph Pearson]

No, there's no list. Your best bet might be to wander through the list of Monocle forks on Github for clues.

— J

[Dave Bricker]

I'm new to both Monocle and Github so I may be overlooking something stupid, but after downloading the source, I can't get the demos to work. Safari Activity window said some javascript files weren't found so I set up a dist/ directory with copies of the files. That fixed the broken links but I still don't have any functionality. I also tried installing on server to see if that made any difference, but nothing works.

See http://www.spotgrafix.com/Monocle/test

Can you advise of what the possible problem is? I have an innovative book project that might be perfectly suited to Monocle. I'd love to see if I can make it work the way I hope it will.

Many thanks,

Dave Bricker
http://www.theworldsgreatestbook.com

[Nakamura]

Delete what you have put inside dist directory and run rake command in the monocle's root directory. It should create the needed files.

--
 
 

[Dave Bricker]

I still get errors. Thanks for any assistance you can give.

Last login: Tue Oct  9 18:30:09 on ttys000
/Users/dave/...Books/Dinner\ Key/E-Monk/Monocle/Rakefile ; exit;
unknown0023dfff024f:~ dave$ /Users/dave/...Dinner\ Key/E-Monk/Monocle/Rakefile ; exit;
/Users/dave/...Dinner Key/E-Monk/Monocle/Rakefile: line 1: class: command not found
/Users/dave/...Dinner Key/E-Monk/Monocle/Rakefile: line 3: syntax error near unexpected token `('
/Users/dave/...Dinner Key/E-Monk/Monocle/Rakefile: line 3: `  def build(options = {})'
logout

[Joseph Pearson]

You don't need to build Monocle using Ruby/Rake/Sprockets/etc unless you specifically want to make changes to the Monocle code.

You can download the pre-built scripts here: https://github.com/joseph/Monocle/downloads

You can play around with the tests and examples here: http://test.monoclejs.com/test/

— J

[Dave Bricker]

Thanks, Joseph. That link helps.

Now all I'm missing is how to get this stuff to run locally.

[Joseph Pearson]

Well, sure, if you need to. Follow the instructions people have offered. We can help, but this isn't a beginner's class — if you really can't solve something, you need to be more explicit than "I still get errors".

On 12/10/2012, at 12:04 AM, Dave Bricker <inn...@gmail.com> wrote:

Thanks, Joseph. That link helps.

Now all I'm missing is how to get this stuff to run locally.

--
 
 

[Dave Bricker]

Thanks again. I explicitly posted the errors earlier in this thread. I've operated a web development studio since 1995 so I'm not exactly a beginner (though the design side is my forte). My questions are basically:

What am I trying to accomplish with ruby? Why won't the javascript files, css and html run locally? I've built hundreds of websites and never had to compile one for distribution—especially one based on web standards. So, I downloaded the test directory, fixed the links to the scripts where needed, hit "preview in browser, and got no errors or anything on-screen. What's different between my local files and the same files running online in your /test directory?

I don't expect a "beginner's" class, but I've never encountered this. If you would be kind enough to explain what's probably a simple missing link in my understanding, I'll track down the necessary information and educate myself.

Your time and technology are greatly appreciated. Sorry to be a persistent pest, but Monocle seems to be the perfect starting point for an eBook project I've been writing for 3 years. Technology development started a month or so ago. This could save me a ton of work and push forward a project I believe will be groundbreaking. All I want to know is how to develop with it so I can tweak the CSS and preview the result in the usual way (or even n some un-usual way).

Thank you,

Dave

[Joseph Pearson]

If you want to run the tests and examples locally, you can follow the instructions in the wiki: https://github.com/joseph/Monocle/wiki/Building

I can't identify anything you're asking that is not answered by that page or previous responses. Please read the documentation carefully. If you're still confused, you could do some background reading on building large JavaScript projects; http://getsprockets.org is a solid place to start.

— J

--
 
 

--
Joseph Pearson | software inventor | inventivelabs.com.au | +61394163198

[Dave Bricker]

So, I believe the answer is here:

"When mounted, the environment will serve assets from this directory as if they were static files in your public root.…The power of the load path is that it lets you organize your source files into multiple directories -- even directories that live outside your application -- and combine those directories into a single virtual filesystem. That means you can easily bundle JavaScript, CSS and images into a Ruby library and import them into your application."

A Monocle book is a ruby application. That's interesting and worth learning. I'll dive in.

At the risk of being perceived as confrontational (which I'm not; I think you've accomplished something brilliant here, and I respect why you don't want to conduct "beginner's classes" on this forum), that strikes me as something worth mentioning. What do publishers need to know to use Monocle? The site says, "Monocle is software zero. There’s nothing to install." Technically true, but only if you're a ruby developer or have contracted one to deliver and install your compiled book. Your Github intro page says:

"If you want to explore all of Monocle's features, clone this repository and open test/index.html in your browser. This will guide you through Monocle's tests, which incidentally demonstrate all the major features. View source or browse the test directory in your text editor for implementation details."

Sorry, but that doesn't work. Clone the directory and run index.html in your browser. On second thought…

Why am I being a RFPIA about this? Because eBooks and apps are closed-loop systems where bookstores and app stores make 30% (at least) of a publisher's nut without taking an ounce of risk. Like you, I'm a proponent of the open web and now that browsers are being built into eReaders (and everything else), we have an opportunity to publish web-based eBooks that bypass the gatekeepers and offer a reading experience that is superior in many ways. Additionally, you've solved a distribution problem with booki.sh. As an educator and publishing consultant, I work for (and blog for) the writers of the million books that get published every year. How do we empower the average publisher to deliver their ePub as a Monocle book? How do we empower the average web designer to refine and customize the design of a Monocle book? How do we get enough publishers on board to put web-based eBooks on the radar? If it accomplishes nothing else, it will push eReader manufactures to fully support ePub3.

The other advantage for you is that declaring a few details up-front, even if you think everyone should find them obvious, will spare you the hassle of having to deal with newbie questions from people like myself. I tried running http://test.monoclejs.com/test/ in the Github repository but only got access to code. One more obvious thing I should have known, I suppose. A live link in the intro page would have helped.

I'm guessing you don't have to be a full-blown ruby developer to work with Monocle. I'm guessing you just have to install a few things and learn to work with a few command line prompts. I'm still guessing at a lot of things, but I'll keep reading and soon won't be. I'll let you know and then I'll write the damned "what you need to know to use Monocle" tutorial myself.

Again, why am I being a RFPIA about this? The book landscape isn't going to be changed by ruby developers or web developers; it's going to get changed by publishers—and if you want to see technological disconnect, you need look no further. I'm the guy who builds the bridges that give those people access to to the tools and strategies they need to make good books happen in good places. My Flash flipbooks tutorial and free XML-based UI add-on has 16,500 page views. My book typography articles have over 5000. I'm a publisher with an innovative eBook project who wants to make an impact with classic book design principles and web-based technology. I'm a major advocate for self-publishers. I'm an experienced web designer who has won Adobe site-of-the-day awards and professionally published Actionscript courses. Brag. Brag. Who cares? But if people like me are bouncing off of Monocle, the people who might use it most enthusiastically won't even get close. Think of me as a case study—the ideal Monocle user—I'll do what I can to close the gap from my end. And this isn't a bitch letter; I'm grateful when users tell me they don't understand a particularly creative UI or don't like a design I happen to dig (and that happens to the best of us). My comments are intended to be positive and constructive. If there's anything I can test or contribute in the way of design/typography/UI, please reach out and count on my enthusiastic support of your project.

When I figure out how to get the damned thing to run in my local browser, I'll come back and share the love.

[Joseph Pearson]

At this point your failure to understand is a kind of wonderful slapstick. You've made a simple thing seem nigh impossible. I wish you good luck and thoroughness, Dave.

— J

--
 
 

[Dave Bricker]

It's rewarding to write a long letter and have it taken seriously and courteously responded to. I'm glad I amused you.

[Joseph Pearson]

Apologies, folks. I have a fairly low threshold for people who think this is a reasonable way to approach an open source project.

Still, it's worth trying to find ways that even obdurate incomprehension can improve Monocle. I've clarified a section of the README and added a document to the wiki that runs through four simple options for running Monocle (including one that has been something of a hidden feature, which might be useful to contributors):

    https://github.com/joseph/Monocle/wiki/Running-Monocle-locally

— J

On 13 October 2012 01:18, Dave Bricker <inn...@gmail.com> wrote:

It's rewarding to write a long letter and have it taken seriously and courteously responded to. I'm glad I amused you.

--