From the data vis chapter, step 4 represent:

    float y = dimensions.y + ofMap( dataPoints[i].pop, 0, maxValue, dimensions.height, 0);

and dataPoints is defined like this:

typedef struct {

    int year;
    float ny;
    float lou;
    float ala;

} popData;

....
    vector < popData > dataPoints;

And maybe having a link to formatted data in csv for the chapter could be useful, so here it is:

Year,New York,Louisiana,Alabama,U.S. 
1900,1381625,7268894,1828697,76212168
1910,1656388,9113614,2138093,92228496
1920,1798509,10385227,2348174,106021537
1930,2101593,12588066,2646248,123202624
1940,2363880,13479142,2832961,132164569
1950,2683516,14830192,3061743,151325798
1960,3257022,16782304,3266740,179323175
1970,3641306,18236967,3444165,203211926
1980,4205900,17558072,3893888,226545805
1990,4219973,17990455,4040587,248709873

I think it would be a good time to start talking about chapter order and the flow of reading.

After the reading the outlines, I see there are a few core chapters that need to be read in order, and then the others can be read in whatever order the reader prefers. (I'm thinking about absolute beginners here.)

Here's a suggested order of chapters to get people making openFrameworks apps as quickly as possible (important), while also covering the cores:

1. Intro
2. C++ Basics
3. Setup and Project Structure
4. Introduction to Graphics
   • I won't be using much that isn't already covered by C++ and Setup other than vectors
5. OOPs!
6. Animation
   • @ofZach, this chapter has OOP I assume; otherwise, it could come before the OOP chapter
7. Advanced Graphics
8. Memory
9. Network
10. Threads

The rest of the chapters can be explored however the reader feels like exploring. There is probably some sort of progression in terms of difficulty that could be used to organize these chapters, but I'm just listing them arbitrarily:

• Image Processing Computer Vision
• Game Design
• Hardware
• Sound
• iOS
• Android
• Version Control
• Shaders
• Project Elliot
• Project Eva
• Project Joel
• Project Memo

Some chapters are currently blank, so I left them out:

• Media
• Interaction Leaving the Screen
• Data Vis
• Arm Linux
• C++11

the chapter installation_up_4evr_macosx added by @arturoc incorrectly contains links to online images, instead of the local ones, so book generation fails if you don't have internet access.
I tried to fix that, but the script to create the pdf book by @mikewesthad doesn't correctly pick up the link style when creating the chapter_modified_for_print.md, so pdf generation still fails as pandoc can't find the images.
@mikewesthad could you take a stab at this? I didn't have the nerve to start wrestling with your regex to make it work. ;-)

Player::setup, update and draw methods are not described in the chapter
i found the example src in the chapter folder but since the chapter describes game development step by step, maybe it should be included too

Hi everyone,
I need to ask for some help.
I'm writing chapter 3 setup and project structure. In it I explain how to start using OF in each IDE.
What I need to ask you is if you can provide me with a simple screenshot of Eclipse on Linux with the emptyExample opened.
Something like this https://github.com/openframeworks/ofBook/blob/master/03_setup_and_project_structure/images/xCodeScreenShot.jpg
If you can please push the screenshot to
https://github.com/openframeworks/ofBook/blob/master/03_setup_and_project_structure/images folder.

On the other hand, are there any tips or things I should mention that the user must do in order to run an example for the first time? In particular for Eclipse on Linux and C::B.
For example, to run any example using Xcode you must change the compile target from openFrameworks to the example. I mention it here https://github.com/openframeworks/ofBook/edit/master/03_setup_and_project_structure/chapter.md#L70

I'll really appreciate any help.

All the best!

three chapters give mention to OSC--

Phoenix (Game Design) will be covering it in-depth, followed by Caitlin/Pierre (Hardware) and Eva's Project Breakdown. You guys should check in with each other, depending on your specific use-case, you can perhaps reference Phoenix's chapter/section without repeating the same text.

ping @ruxrux -- I'm pretty sure there's a memory leak here :) you use new but no delete....

for (int i =0; i < myBall.size(); i++) {
    float distance = ofDist(x,y, myBall[i]->x, myBall[i]->y); // a method OF give us to check the distance between two coordinates

    if (distance < myBall[i]->dim) {
        myBall.erase(myBall.begin()+i); // we need to use an iterator/ reference to the vector position we want to delete
    }
}

I generally don't think it's such a good idea to use non default constructors and pointers -- will you mind if I simplify the code / chapter a bit this week? I think pointers / non default constructors is helpful, but I would guess this chapter can be written without the word new in it...

I'm starting to read the book more linearly now and seeing things that seem maybe unfriendly for a beginner audience.

at the end of the chapter 'language basics' the unabridged version is mentioned, but the link gives a 404

I'm getting ready to start a second pass at my chapter, and one of the biggest things on my mind right now is chapter length. @jtnimoy's and my chapter drafts definitely blew past the originally proposed chapter length of 15-25. (I'm still in the process of reading and submitting feedback for other chapters, so maybe there are a couple others that are over 25 pages.)

I tend to be verbose when drafting, and then when editing, explanations become more concise. But I have a feeling that the chapter will still end up clocking over 25 pages (or at least over 25 pages when graphics and code are included).

It seems to me that some chapters have a lot of ground to cover (especially the C++ basics chapter) and need the extra space to be able to bring people who have little or no coding knowledge up to speed.

So what is everyone thinking in terms of chapter length? @ofZach suggested breaking the C++ basics chapter into multiple chapters. I assume that suggestion would apply to other long chapters.

Ive drafted an Editing Guide to help get all of us editors on the same page. I wanted to propose it for discussion before pushing it to the repo and calling it official. If it is generally OK I can push it to the repo and then everyone can make changes as they see fit.

Thoughts?

THe code section is inconsistent in formulation. It says "please use the github markdown for code", but then goes ahead and tells us not to use github-flavored-markdown for the code sections, but prefer indented code.

To clarify: GFM-style code blocks use three backticks (and an optional language name for correct syntax highlighting). Vanilla markdown uses indentation by at least 4 spaces for code blocks (with no facility to name the language for syntax highlighting).
Which should it be?

Can't build into PDF, don't know why :(

➜ ofBook git:(master) ✗ ./create_ofBook.sh pdf
pandoc: Error producing PDF from TeX source.
! Use of @array doesn't match its definition.
\new@ifnextchar ...served@d = #1\def \reserved@a {
#2}\def \reserved@b {#3}\f...
l.15100 ...4\times 4} = \left[\begin{array}{ccc|c}

Some error occured!

My machine:

➜ ofBook git:(master) pandoc -v
pandoc 1.9.4.2
Compiled with citeproc-hs 0.3.4, texmath 0.6.0.6, highlighting-kate 0.5.1.
Syntax highlighting is supported for the following languages:
Actionscript, Ada, Alert, Alert_indent, Apache, Asn1, Asp, Awk, Bash,
Bibtex, Boo, C, Changelog, Clojure, Cmake, Coffeescript, Coldfusion,
Commonlisp, Cpp, Cs, Css, D, Diff, Djangotemplate, Doxygen, Dtd, Eiffel,
Email, Erlang, Fortran, Fsharp, Gnuassembler, Go, Haskell, Haxe, Html, Ini,
Java, Javadoc, Javascript, Json, Jsp, Latex, Lex, LiterateHaskell, Lua,
Makefile, Mandoc, Matlab, Maxima, Metafont, Mips, Modula2, Modula3,
Monobasic, Nasm, Noweb, Objectivec, Objectivecpp, Ocaml, Octave, Pascal,
Perl, Php, Pike, Postscript, Prolog, Python, R, Relaxngcompact, Rhtml, Ruby,
Scala, Scheme, Sci, Sed, Sgml, Sql, SqlMysql, SqlPostgresql, Tcl, Texinfo,
Verilog, Vhdl, Xml, Xorg, Xslt, Xul, Yacc, Yaml
Copyright (C) 2006-2012 John MacFarlane
Web: http://johnmacfarlane.net/pandoc
This is free software; see the source for copying conditions. There is no
warranty, not even for merchantability or fitness for a particular purpose.

➜ ofBook git:(master) ✗ lsb_release -a
No LSB modules are available.
Distributor ID: Debian
Description: Debian GNU/Linux 7.5 (wheezy)
Release: 7.5
Codename: wheezy

Zach,

I went through your chapter thus far and made some minor grammatical/spelling changes, which I didn’t indicate in comments because they were so small. The chapter is coming along nicely, with a good balance of technical elements of animation and relatable examples.

Animation is tough because it gets into physics with all of the time based movement and acceleration, etc. You covered these physics lessons well. I think they’re necessary to the chapter if it’s an all-encompassing course on animation, which it seems like you’re interested in covering. Maybe throwing a few further-reading physics references into the chapter would be useful for those interested.

As you’re progressing, I’d encourage you to consider mentioning push/pop matrix and ofTranslate. This method of animating seems more accessible for beginners, where sin and cos is a little harder to wrap your head around. I’d definitely keep the sin and cos elements, but covering push/pop matrix and ofTranslate earlier on seems relevant to this chapter, especially because they’re oF specific commands, and go along with the idea of this book being about openFrameworks.

You used ‘OF’ and not ‘oF,’ which I left, but I thought the consensus was to use oF? It’s just really important that we choose one to stick with.

This is picky but also important as you're adding to the chapter. I made it so there was only one space in between a period and the letter of the next sentence. I think this should be uniform throughout the entire book, too. It will cut down pages, and it’s more standard than two spaces.

Another technical comment would be choosing between em dashes or parentheses:
–words– or (words).

…I may bring these grammatical concerns into another note because they apply to the entire book.

Again, great analogies throughout. The best ones tied this digital way of animating to old forms of animation. These comparisons bring the artist’s role back into animating in oF, because sometimes this form of animation feels dominated by the computer and less hands on than years ago when animation was much more manual.

I look forward to seeing this chapter finished! Animation is a really important topic to cover.

one thing i think would be good, is a chapter on explaining how you can have classes talk to each other. i think its called pointers, i tired, so please excuse.

but would be good to explain to folks and example on how you can send data from one class to another, which then talks to the main application.

just things like these are so valuable to know, especially when projects get big

There is a small mixup of variable names in the Graphics chapter about creating a brush with polylines:
"Initialize minDistance and currentedAddingPoints in setup():
minDistance = 10; currentlyAddingPoints = false;"

should be:
minDistance = 10; leftMouseButtonPressed = false;

should we have a basic 'markup' for annotations (e.g. which should be noted by graphics designers).

for instance

$$NOTE$$
to designers:
make sure this image is in colour and full width
$$/NOTE$$

With the coming release, maybe it's time to renumber some of the chapters. The thread in issue #12 left the ordering at this (to guide beginners through a core set of fundamentals):

1. Intro
2. C++ Basics
3. Setup and Project Structure
4. Introduction to Graphics
5. OOPs!
6. Animation
7. Advanced Graphics
8. Memory
9. Network
10. Threads

Hardware, image processing, data vis, game design, sound, ios, c++11, version control, math chapters, project elliot, project eva, project joel and project memo(?) should be on that list. (05_Media, 07_interaction_leaving_the_screen, 13_android, 14_arm_linux and 19_shaders are chapterless, so i'm leaving those out.)

Thoughts?

Hi all! I know that you are all moving into first drafts of all chapters and I am interested in being an extra set of eyes/submitting a round of grammar, spelling, and code clarity edits. What is the best way to go about doing this? Forking and submitting pull requests on each chapter? How about annotations, notes, or suggestions? Are we using <!-- html comments --> in markdown, or [bd: obvious comments] like the style guide mentions?

i think there might be some explanations about ofMesh, ofPolyline, ofPath, ofVboMesh, ofNode

How to go from using ofTranslate/Rotate/Scale to using ofNode. The difference between ofMesh/ofVboMesh

Also going from immediate mode with ofBegin/End to using ofPath, see how ofPath tessellates and stores that so you can create a shape at the beginning of the application and draw it several times...

this could even be a 2nd part, like advanced graphics or something like that

Since the deadline for release is getting closer, I updated the style guide with my current understanding of what we should be doing.

Code formatting is one of the top things to get consistent at the moment. Do we have a consensus on the number of characters wide a line should be allowed to be?

I know @Onna-no-hito mentioned focusing on the Animation chapter and beyond, but I wanted to weigh in with some feedback on this chapter since I think it is a very important one for beginners.

Disclaimer. @roymacdonald, since much of the draft is missing (as you mention in your last commit), I realize some of the feedback might be things you are already planning on doing.

Anyway, feedback:

I like that you are trying to explain what openFrameworks is with a spatial analogy. Thinking of openFrameworks as a room in your house probably makes the concept more inviting for beginners to approach. At the moment though, the analogy didn't quite work for me. It's not exactly clear to me how you are trying to map the IDE, openFrameworks classes/functions, OOP, etc. onto a kitchen. Here's what I'm getting: The IDE is the whole kitchen? Counter top for coding, stove for compiling, etc.? openFrameworks fills the pantry with ready-to-go ingredients? Then you mention fast food and how it doesn't taste as good as homemade food. So is fast food then some third party C++ library that provides a sloppy solution for some task?

Some of this could be solved by clearly stating the analogy in your first section. Still, some of the problem results from the analogy becoming confusing when things get detailed. It needs to be immediately clear what is part of the analogy and what isn't. Aside from the taste of fast food vs homemade, you go into the details of killing a cow and growing vegetables. Here is where the analogy started to get muddy. I think the underlying concepts would be clearer if you tackled them directly, rather than via an analogy.

Instead of talking about a burger you could do something like the following. Ask the reader to imagine some project (e.g. detecting faces from your webcam and drawing masks). Then you explain what you would have to do if you were to start from scratch: learning how to read the webcam, computer vision, drawing polygons, etc. Then you explain the head start that you get if you approach the same project with openFrameworks: webcam access, opencv, drawing, etc.. If you explain the concepts in simple terms (like talking about the webcam without relying on the word "driver", etc.), I think the advantages of the "OF Pantry" are immediately graspable to any reader.

As for the overall structure of the draft, it looks like you are packing a lot into the chapter - super, super useful things like IDE guides and an overview of openFramework's libs and addons. All of that is invaluable, but I think this draft of the chapter would be hard to approach for a beginner. Your chapter comes right after the C++ chapter. The C++ chapter takes place completely inside of ideone, so a complete novice reading ofBook will have no idea about getting set up with openFrameworks. Your chapter starts off by pointing to the installation guides and then says to test "that installation went fine, by opening any example, compiling and running it without problems." The guides (or at least the win guide) don't explain any of the following: how to find an example, how to open it in the IDE, how to compile it, how to verify that it ran without problems, how to troubleshoot any errors, etc. It would be a huge plus if your chapter could walk users through that process. You don't have to walk through the installation, but everything after that point would be great. Tell the reader where to find the examples (you do this, but it comes in the section after you tell them to run an example). Direct them to a specific example and tell them what it should do, so that they know what it looks like when there aren't any errors. (It also gives you an excuse to include a pretty screenshot from an example.) You could mention some common install mistakes, or at least, direct the reader to troubleshoot using the forums.

After the installation is verified, I might even have the reader build their own blank project with the project generator. It isn't as exciting as running an example, but it gets the readers hands dirty, and it is essential to becoming comfortable with the openFrameworks workflow.

After that, then you can move into your "OF Structure" section. I would suggest reordering the way you explore the root directory to match the order in which a beginner would explore these things. Something like: 1) apps + project generator, 2) examples, 3) addons, 4) libs and 5) other + scripts. That way no one gets overwhelmed by trying to wrap their heads around all the addons before they know the basics.

For your "OF Pantry" section, it might make sense to include a picture here. If you are sticking with the pantry analogy, could you organize all of this information into a visual diagram of a pantry? Something simple like throwing the information into a graphic of a shelving unit. It would give readers something to grab onto and make the analogy concrete.

The info you have listed at the very end of your draft is all great. Explaining why there is both a header and a source file answers an almost universal beginner C++ question. The anatomy of an openFrameworks app helps to orient the reader to what they can do. And the one about peeking into other's files is very important because you can empower readers to not be afraid of reading code. This section could be expanded to explain how to look through the openFrameworks libs when something isn't working how you expect.

So, again, I realize the draft is incomplete. It is chock full of goodies! But I think the organization of it needs to be shifted around a bit to make it accessible for the beginner - especially since your chapter is so important for orienting new users in the landscape of openFrameworks.

Hey @ofZach
I can see in chapter 1 that there are several topics that I have to cover, as part of my chapter "project structure and setup", I think that the intro you already have is good enough, just leaving it on the abstract side of things, opposed to my chapter which is totally pragmatic. I'm already adding to my chapter the following topics that you have listed in yours. So, shall I cover these topics, and leave them out from yours? (It will also make my writing easier as I need to explain them).
OF structure
project generator
.h and .cpp
setup/update/draw
first project a circle moving in the screen (I didn't had in mind this one but wont hurt adding it)
scary things in OF code (#ifdefs pragma once...)
preprocessor/compiler/linker

best

hey @jtnimoy awesome work! if you have a moment, can you break apart the outline and the writing ? (I think we are just trying to get a clear sense of outlines from everyone)

Moving the discussion from the book-length-commits over to here, so no one has to load that mess anymore. To summarize what's been said:

• @ofZach said that newDesign branch is a work in progress branch to show the new CSS work coming through. We can eventually merge it into master, and when we do, we can combine the python generation script with the shell script into one generation method for both PDF and html.
• You can use github preview to checkout any of the generated HTML versions of the chapters
• @bilderbuchi said "instead of putting rendered content into the repo, we should probably use the render generator @arturoc set up already when we fold this into the main branch."
• @ofZach mentioned mocking up a book table of contents, accordian style on a sidebar. Something to allow navigation between chapters. For now, we just have within-chapter table of contents from pandoc.
• In the generated HTML, .cpp fenced code blocks should now be highlighted with the appropriate syntax coloring

Open issues:

• @OmerShapira should weigh in on the math rendering. Pandoc math rendering options include: using LaTeXMathML, converting text to mathml, using jsMath, using MathJax and using webtex to render images. Here is a preview of the current rendering, using mathjax.
• @bilderbuchi mentioned: If there's code in headings, there's a font size mismatch, e.g. here
• @bilderbuchi: Link styling doesn't differentiate hyperlinks from regular text well enough for readers
• I added the fonts files for the fira font Andy and Ishac were using for styling the chapters, but the rendering is wonky. Paragraph text is not terribly legible - compare with the rendering on the fira site. Some characters aren't being rendered, like vertical bars in the git chapter.

A couple chapters discuss how classes work:
JTNimoy (C++ Basics), Rui (OOPs)

and several chapters give mention to C++ versus other langauges:
JTNimoy (C++ Basics), Rui (OOPs), Lukasz (iOS), Arturo (Android--java)

just wanted you guys to check-in with each other to possibly save yourselves time
and not repeat the same explanations.

some questions:
is it more fitting for Rui to talk about classes when explaining OOP?
should the OOP chapter come before the C++ chapter?

Josh-- do you cover differences between Obj.C and Java?
obviously Lukasz and Arturo-- you get more in-depth as far as use case but for the
basics differences of the languages maybe Josh has that covered?

After cloning, How can we create book from latest master?
What command do we need to run?

Figured a github issue's as good as any to talk about this :)

IMO the thread chapter should be a little earlier, maybe woven in around the chapter 6/7/8 range. I realize threading is relatively advanced, but it could probably be explained in a straightforward enough way as to not seem jarring in the mid-range of the book.

The reason I single this out is that it's pretty crucial for the sound chapter (and I imagine the hardware one too?) to know enough about threads to at least internalize things like "if you try to write to the same buffer from different threads, you're gonna have a bad time".

Not sure if this is a non-issue already with the whole meatlof-y lasagna-y thing, though :) Maybe it's fine to just shout out to the threads chapter mid-prose (for more on this, see chapter 17..)

@bilderbuchi or any other latex experts.

Below are two things that break with pandoc and the --listings option. Aside from these, everything seems to be working. My solutions were to make edits to the markdown versions of the chapters (a total of only 3 edits). Ideas on better solutions?

1. Exclamation points within an block of inline code:
   • e.g. cout << "Hello world!"; from git chapter.
   • pandoc normally uses ! to delimit inline code, like \lstinline!c=a+b!. But when a chunk of inline has an ! within it, pandoc tries using # as the delimiter. I assume this breaks because # is a reserved character in latex.
   • Current solution: I just removed the exclamation points from the inline code.
2. Percent signs within a block of inline code that is italicized:
   • e.g. ...write code that looks like sin((ofGetElapsedTimeMillis() % 6283) / 6283.0) or something similar,... from animation chapter.
   • in latex that would be: \emph{write code that looks like \lstinline!sin((ofGetElapsedTimeMillis() % 6283) / 6283.0)! or something similar,}
   • Something about lstinline being within emph causes the % to be read as a comment, rather than verbatim, and the listinline doesn't get closed. This problem doesn't occur for code that isn't wrapped in emph.
   • Current solution: I didn't let the italics wrap around the code.

I see libsass is an added dependency for the webBook now. If any windows folks try building the book, they might encounter some trouble getting libsass working. pip install sass looks for visual studio for compiling, specifically VS2008 on python 2.7. After installing VS2008 (and running vcvarsall.bat to set up cmd environment), sass breaks during compiling.

I didn't have enough time to figure out how to get it running, but I just wanted to throw it out there.

Intro to graphics should come before the anim chapter, or? that way x/y coordinate system and drawing to screen are already discussed before talking about how to animate objects on screen.

although-- Zach are you covering those two topics in the Intro?

you wrote:
setup/update/draw
first project a circle moving in the screen

i feel there might be some overlap between Zach (Intro/Anim), Mike (Intro to Graphics) and Mike, some things you propose which Golan (Image Processing) might be covering.
You (Mike) seem to be touching on a lot of topics--

can you guys please look over each other's outlines and see where there might be redundancies? thanks!

Will the chapters be written in markdown, (la)tex or any other language ?
Is there any place that I can get this information, or is not yet decided ?
Will be any script to build the book, or it will be only for online visualization ?

The intro and oF mission statement gives a good picture of openFrameworks. However, I’d consider explicitly addressing how the book itself is being written by a group of people, each contributing chapters. This isn’t very common–at least for programming books I’ve seen. I can see where having a different voice in each chapter could pose an inconsistency that could be frowned upon. BUT we can play into this by stressing how the oF community “thrives” off many people working together to contribute something greater.

How are all of these different voices affecting a newcomer to oF? Maybe stressing that yes, chapters were written by different people but we’ve all had access, read, and edited each other’s will help promote this open source community. Chapters have received a lot of feedback but will still emerge with the voice of the author…this can be compared to the oF community that wants to help others with projects without muting the vision of the person proposing the idea, even if they are less skilled in the art of computer programming. There’s no hierarchy, we’re just all working together (at least, that’s the goal).

@jtnimoy I just got a chance to give your draft a close read. It's definitely great so far - easy to read and entertaining (Back to the Future reference is my favorite).

Your figures that explore the code visually (e.g. figs 11, 18, 21, etc.) will be a huge boon for those readers who are coding for the first time. Figs 28 + 29 are simple examples that are particularly effective. They help elucidate what is going memory-wise with just a few extra marks+words, and that's great for helping beginners see "beyond" the code to what is happening underneath.

I like ideone though I did run into a bug (that I couldn't replicate). Changes to the code wouldn't get compiled into the version that was being run. Tried saving, running multiple times, making multiple edits. I ended up chalking it up to having the page open to long and just refreshed it to get it working again.

I think it would be cool if your chapter had some companion site (or oF app) that would animate the ASCII output your code generates in ideone. Having to scroll is completely fine, so this is wish list type stuff, but being able to copy+paste the output into a textbox and then watching it move would be pretty cool. (Esp for your prime "random" generator.) An alternative might be to just include a few animated gifs.

I think a couple sections could use a conceptual introduction before jumping into code. The functions section comes to mind. It wouldn't require more than a sentence or two talking about what a function is, even if it is just from an english dictionary perspective. It would help orient readers for what is coming next. Same idea goes for the Variables (part 1) section and for the looping section.

Your email to the ofBook list mentioned cutting signed/unsigned and leaving out bitwise operators. That seems fine to me, and I take the silence on the email front as confirmation from the rest of the group? There could be a section at the end of the chapter where you just show some syntax, drop names/concepts and say where to go to find more info. That would arm readers with enough knowledge to feel comfortable diving into those things should they come across them in someone's code.

I feel mixed about the twitter thing since it feels a bit forced and transparent in that it is just about promoting ofBook. It might feel more appropriate in a place like at the end of your ball animation where you ask the reader to tackle some extensions. Or if you were to suggest they design their own random functions and then tweet a link to their ideone code (or a screenshot/gif of their stdout). Etc.

You jump into discussion about compiling and precompiling pretty quickly, which makes sense, but it could benefit from a simply flow chart thrown in there. Something that shows what happens to your code, so that newbies who aren't familiar with compiling have some visuals to grab on to.

For your namespaces analogies, the 3rd grader bus paragraph had plenty of character, but I found it distracted from the point. Maybe you could merge that seat space conflict analogy with your second namespace analogy by focusing on school buses. Multiple buses: there can be people with the same name, but on different buses, etc.

I think the namespace section points out a tricky balance you are trying to strike. In namespace, you are referencing things like ofBackground and glBlendMode for the benefit of advanced readers, but also trying to not overwhelm readers who don't yet know what a variable or function is. Another example of this is Fig 10 where you are introducing types and functions before handling variables. You've set up a flow where you explain every line in the hello world code before really getting into variables.

One approach to tailoring that balance to beginners might be to lead the chapter with variables (logic of single lines of code), then work your way into functions (chunks of code), then all the other goodies like precompiling, namespaces, etc. That would just require letting the reader know to ignore #include <iostream.h>, using namespace std; for the moment and just focus in on what is happening within the { }. Then the concepts reveal themselves in a way that allows them to build upon each other (or at least, that's how I imagine it happening in the brain of someone just learning to code).

Anyway, those were the big notes that I wrote down while reading. I'll throw in some inline comments into your chapter for smaller things. Again, chapter is great so far!

@arturoc, you used HTML to control the size of your images in the markdown for your chapters. Those don't get converted into figs by pandoc and are then missed in the python script, so they don't load in the web book. Can we switch over to markdown syntax for those chapters? (If you still want 300px images, you can save out 300px versions of your images, and the CSS will load them without stretching.)

Lukasz (iOS) and Patricio (Shaders), just wanted to point out you're both proposing to speak about differences between dif't versions of opengl.

Lukasz wrote: OpenGL ES1 & ES2 renderers, what are the differences.

Patricio: Differences between openGL2, openGL ES and openGL3

maybe you guys can combine forces and keep it in the Shaders chapter, with Lukasz referencing it in the iOS discussion?

again just to check

what would a level 1 header be? #

would it be either:

1. book title
2. chapter title
3. major section of a chapter

hey joel, can you tighten up your outline? ie, take the three projects and maybe elaborate on how you would write about them? I think it will help here. The other material (such as things for other parts of the book) is probably useful on the hackpad (or talk to other chapter authors), but it would be good to get an as detailed as possible outline regarding the projects you want to discuss.

So far I've taken the approach of putting the function signature in the head of a specific chapter, like so:

Affine Mapping: The ofMap

float ofMap(float value, float inputMin, float inputMax, float outputMin, float outputMax, bool clamp = false)

adding the default params for better understanding. I don't know if others are doing it, but if this doesn't become a standard, what is the standard for doing so?

Regarding the title of the chapter, "Introduction to version control with git" is definitely a precise description of the contents. It's quite a mouthful, though, so I'm thinking about shortening it to "Version control with Git".
Thoughts?

adam probably you plan to explain it but it's probably useful starting with the different ways of using audio in OF then go into details of dsp programming?

like explaining how the soundplayer can play a sound file but, at least right now, you can't access the audio wave, (perhaps compare the audio wave with pixels in an image?)

then explain how the soundstream works, callbacks, different threads...

@patriciogonzalezvivo @memo have both proposed to discuss vertex and fragment shaders. if one of you is covering theory and the other use case, maybe not a prob but ya might wanna check in on that.

I am making a list here of things I'm spotting that need fixing in the book and from the OF forum post (http://forum.openframeworks.cc/t/openframeworks-book-review-request/18436). I will keep editing this issue as I review....

Overall

• root index page needs a design or a redirect (ie, this looks bad! http://openframeworks.cc/ofBook/)
• chapter standardization (capitalization, etc) some chapters also have the word chapter in them, ie "Data Visualization Chapter" -- would be good to remove and standardize
• javascript for the sidebar doesn't really highlight last section (via clayh)
• tools section should come earlier
• 2nd half of Roy's chapter should come back (I split it in half to work on it)
• functions linked to API possible ? (via clayh)
• rename the "Project Breakdowns" section to "Case Studies." (via clayh)
• missing: the use of the power of the hypertext (needs more links and cross referencing) (via chemabc)
• explain differences between platforms and IDE's, pros and cons, how to manage dependencies, etc (via chemabc)
• ofxaddons chapter (addons chapter) (via amnon)
• comparison may be suitable with regard to the image options: ofPixels, ofImage, ofTexture, ofFbo. Also clarifying their respective constants with regard to GREYSCALE / RGB / RGBA. (via amnon) (could this be in an appendix?)

Chapters

• foreward
  • need full list of participants
• Basics
  • In Basics > Compiling My First App the reader is directed towards ideone. On this site the C++11 language is no longer in the list, only C++14. (via amnon)
• OOPs
  • generally feels like it needs a push with modern practices
• Animation
  • [note: add screenshot of simple particle examples]
  • [more: show example]
  • where to go further seems incomplete
• Data vis chapter
  • markdown formatting can be given some love here
  • has IMAGE HERE
  • *Vectors? Explain here – or has this happened elsewhere?
  • code formatting needs help
    • lots of things like ofToInt(split[ 0]);
  • Working with APIs seems unfinished
  • Further resources seems unfinished
  • this chapter seems fairly desperate for images
• Memory
  • In Advanced Topics > Memory in C++ there are many code snippets. Some of them miss a semicolon, which means you get compiler errors, when you copy-paste them to actually try it out in practice. (via amnon)
  • change 4/8 to "A pointer usually occupies 4 or 8 bytes" (via cabral1349)
  • graphics can be given a makeover (they are fine as is, but would be good to look at consistency with vector graphics / line weight / fonts)
• Image processing
  • 3.# section needs completing
• Hardware
  • I think this image of serial cable is taken from sparkfun, we might want to shoot an image or find one that we have rights for.
• Advanced Graphics
  • it may be useful to have some kind of quick-view comparison schematic of the different options mentioned on this page: ofPolyline, ofPath, ofMesh, ofVboMesh, and of3dPrimitive. For example when each should be used, unique features/limitations, 2D/3D, CPU/GPU, etc. (via amnon)
• IOS
  • suggest to add some information on how to publish to the App Stores (via xavivives)
  • ending (lifehacks? case studies?) seems kind of unfinished, chapter ends a bit abruptly
• Math
  • CSS work to make the figures more formatted like other images in the book (ie stuff like this needs love http://i.imgur.com/U7YA0zL.png)
  • Markdown formatting (chapter structure) seems a little wonky, H5 tags (this might be the only chapter to have them) are kind of small and overall it feels a little confusing to navigate.
• Threads
  • graphics can be given a makeover (they are fine as is, but would be good to look at consistency with vector graphics / line weight / fonts)
• C++ 11
  • chapter is not finished
• Case Study : Line Segments Space
  • Chapter still has editing notes in it
  • chapter is not finished
  • graphics can be given a makeover (they are fine as is, but would be good to look at consistency with vector graphics / line weight / fonts) -- author asks for redraw
  • side by side images can be done via image editing (ie, make one image w/ side by side)
• Case Study: Anthropocene, an body reactive video installation
  • this chapter still feels like needs some editing down to more manageable length
  • markdown formatting help is needed

Roy,

I went through your chapter thus far and changed some sentence structures and wording. I tried to omit words that just add fluff to sentences to make explanations more concise and understandable. The chapter is laid out well and I look forward to reading the rest. I'd think more into unifying list formats to make them more cohesive. Great job!

ok, I took a look at the PDF and I think my chapter will breakdown into 5 smaller chapters. I'm going to try and call them "Intro to C++ part 1", "Intro to C++ Part 2", etc. I hope that is acceptable, realizing we're trying to keep it at group effort. If I'm lucky, I'll be able to nickname each of the 5 parts.

The alternative is to write a succinct little advertisement for the real book references, and that doesn't warrant even a single chapter.

@arturoc - you used polyline.moveTo(20,20);. Since that's not in the oF release I have, I assume that is a post 0.8.0 function?

@evsc - just got a chance to look over the chapter. It's a very cool (and massive) project that you’ve covered in a compelling way so far.

First suggestion:

I believe the email thread suggested that more project images be added to the end of the chapter, but I would suggest spending a little bit more time on the description of the finished project early on in the chapter. The project overview gives a nice high level description, but as I started to get into the details of the project - both the descriptions of the idea generation and the technical solutions - I realized I didn't have a clear picture of what "Choreographies for Humans and Stars" was, especially from the perspective of a participant. That first picture was great, but I didn’t pick up on all the pieces, like that the led steles defining the “dance stage” and that instructions were being projected on the building. The chronological approach you take is great, but it is also important for the reader to have an idea of where the chapter is heading (so that they have an easy way to make sense of the chronological approach).

The videos on the daily tous les jours vimeo channel do a really nice job of giving the viewer a glimpse into both the myriad of working parts that came together for the final piece and what the experience was for a participant. So I would definitely link to that.

I'd also suggest adding some more explanation using words and pictures (for those reading a print version) - describing the types of instructions the participants are given, mentioning exactly what you are tracking with the cameras, showing what types of images are being projected, mentioning that the imagery is generated from the local community, etc. If you have some more schematic diagrams like the one showing the projector setup, that would definitely be worth including.

Second suggestion:

I think the most interesting parts of these breakout chapters is showing how you go about tackling “real life” art: talking about things like the iterative process of idea generation->prototyping->testing, controlling the environment to make the coding easier, dealing with unexpected challenges you encounter, workarounds to keep the project on schedule, etc.

You already have a ton of really great things that address these topics. The comments, directed at specific sections, below might help hone the focus towards “real life” art:

“Call, Competition and Commission”:
Interesting and relevant (at least to me) to see process around getting funding

“Timeline, wished-for and realistic”:
The description of how you all blew past your estimated timeline was important. The specific timeline, though, could be abbreviated or excluded (or turned into a horizontal image.)

“Ideation, Narrative and Content”:
This is mostly a word choice thing, but it sounds like most of your “ideation” was prototyping. If I’m not misunderstanding your process, then this is an important point. When working on a project like this, it sounds like it is invaluable to build cheap (both in time and money) mockups and then critically thinking about why they work/fail. So maybe you cut this section down a little and frame it in terms of the iterative process.
By the way - I like how you directly mentioned what the challenges were with the interaction design.

“Finding the Technical Solutions”
This section seems particularly important because it is all about technology in the real world.
The hardware choices are less interesting to me – maybe it could be a footnote?

The ideas around tracking would be pretty valuable to the reader (assuming Golan’s chapter isn’t already covering them). I’d be personally interested in hear a little more on how the system ended up performing (like how you got snowy/rainy/sunny/etc. conditions into your database).

“Developing the Visualization Software”
I some of the specific code segments - like the transitions based on time - could be omitted and the ideas could just be tackled conceptually. This is pretty dependent on what is already covered in other chapters.

“Fail-safes and dirty fixes”
Definitely like the tip about keeping the app running with daemontools

This chapter is fantastic. It's very strategic and clearly written. I had a few suggestions and minor corrections but there is nothing pressing that I can find.

Some parts used "we" talking at the viewer as though there are multiple writers–which there are–so I'd introduce the chapter with a little background on Code Liberation Foundation, which is a great organization to make people aware of anyway.

Since it is pretty dense, I would suggest adding a little more positive reinforcement toward the end. Those following the tutorial will probably be exhausted (in the best way possible) by the end, so hearing something like "You made it!" can be helpful. I'm not a fan of sappy writing, but I think in this scenario an occasional pat on the back is necessary as the chapter comes to a close. I actually followed the tutorial for the beginning parts, and they worked fine. I'm going to make it a point to follow all the way through and give more feedback then.

Again, really impressive.

So I looked around a bit and I'm not sure this was ever brought up? Maybe I missed the memo :)

I have a few "footnotes" in the sound chapter that are small elaborations on the subject matter, but would be too overkill to include inline. I see @arturoc is using quote levels for the same thing, is that the way to go?

Log given below

$ python createPDFBook.py 
Generating ../output/ofBook.pdf from:
    ../chapters/foreword/chapter_modified_for_print.md
    ../chapters/of_philosophy/chapter_modified_for_print.md
    ../chapters/cplusplus_basics/chapter_modified_for_print.md
    ../chapters/setup_and_project_structure/chapter_modified_for_print.md
    ../chapters/intro_to_graphics/chapter_modified_for_print.md
    ../chapters/OOPs!/chapter_modified_for_print.md
    ../chapters/animation/chapter_modified_for_print.md
    ../chapters/data_vis/chapter_modified_for_print.md
    ../chapters/game_design/chapter_modified_for_print.md
    ../chapters/image_processing_computer_vision/chapter_modified_for_print.md
    ../chapters/hardware/chapter_modified_for_print.md
    ../chapters/sound/chapter_modified_for_print.md
    ../chapters/network/chapter_modified_for_print.md
    ../chapters/advanced_graphics/chapter_modified_for_print.md
    ../chapters/math/chapter_modified_for_print.md
    ../chapters/memory/chapter_modified_for_print.md
    ../chapters/threads/chapter_modified_for_print.md
    ../chapters/ios/chapter_modified_for_print.md
    ../chapters/c++11/chapter_modified_for_print.md
    ../chapters/project_elliot/chapter_modified_for_print.md
    ../chapters/project_eva/chapter_modified_for_print.md
    ../chapters/project_joel/chapter_modified_for_print.md
    ../chapters/version_control_with_git/chapter_modified_for_print.md
    ../chapters/ofSketch/chapter_modified_for_print.md
    ../chapters/installation_up_4evr_macosx/chapter_modified_for_print.md
    ../chapters/installation_up_4evr_linux/chapter_modified_for_print.md
Using the following flags:
    -N
    --smart
    --no-tex-ligatures
    --toc
    --toc-depth=4
    --standalone
    --preserve-tabs
    --template=ofBookTemplate.tex
    --latex-engine=xelatex
    --variable=papersize:a4
    --variable=documentclass:scrbook
    --listings
    --variable=links-as-notes
Successful building of ../output/ofBook.tex
pandoc: Could not find image `../chapters/image_processing_computer_vision/https://dl.dropboxusercontent.com/u/10137599/ofbook/interleaved.jpg', skipping...
pandoc: Could not find image `../chapters/image_processing_computer_vision/https://dl.dropboxusercontent.com/u/10137599/ofbook/rgb-screen.jpg', skipping...
pandoc: Error producing PDF from TeX source.
! Dimension too large.
\G@measure@QTm ... }\dimen 0=\wd 0 \dimen 2=\ht 0 
                                                  \edef \next {\egroup \edef...
l.8751 ...sing_computer_vision/images/iq_font.jpg}

Error in building of ../output/ofBook.pdf

i get this output:

pandoc: Error producing PDF from TeX source.
! LaTeX Error: File `ulem.sty' not found.

Type X to quit or <RETURN> to proceed,
or enter new name. (Default extension: sty)

Enter file name: 
! Emergency stop.
<read *> 

l.84 \pdfstringdefDisableCommands

Some error occured!

any suggestions?