Documentation

[Bob Kubinec]

I have recently gotten into C programming, and I am not the best, nor have I
written a college thesis on GUI operating systems. As such, I found the
documentation about Photon to be, well, confusing at best. Could someone
point me to other resources that could feed the information to me at a
slower pace and in simpler terms? Or perhaps I'm just an idiot. Oh well.

[Mitchell Schoenbrun]

Previously, Bob Kubinec wrote in qdn.public.qnxrtp.devtools:

I have recently gotten into C programming, and I am not the best, nor have I
written a college thesis on GUI operating systems. As such, I found the
documentation about Photon to be, well, confusing at best. Could someone
point me to other resources that could feed the information to me at a
slower pace and in simpler terms? Or perhaps I'm just an idiot. Oh well.

No you are not an idiot. The Photon interface is quite
powerful, but there is a big learning curve. It is hard to
learn it in a layered approach. That puts a lot of strain
on new users. I was not comfortable with it for at least a
year, and there are still large areas of that I have not
dealt with.

I do not know of any better resources right now. There have
been rumors and threats of someone doing a book, but I don't
think it has materialized yet.

The best for right now is to look at some of the many free
examples that are around, and get your hands dirty with some
simple programs. If you run into trouble, you will find a
lot of help in either this newsgroup, or at comp.os.qnx.


Mitchell Schoenbrun --------- maschoen@pobox.com

[Norbert Black]

Mitchell Schoenbrun <maschoen@pobox.com> wrote:

Previously, Bob Kubinec wrote in qdn.public.qnxrtp.devtools:
As such, I found the
documentation about Photon to be, well, confusing at best. Could someone
point me to other resources that could feed the information to me at a
slower pace and in simpler terms? Or perhaps I'm just an idiot. Oh well.
[snip]
I do not know of any better resources right now. There have
been rumors and threats of someone doing a book, but I don't
think it has materialized yet.

For what it's worth (and leaving aside arguments about how/if to
restructure the Photon docs), we do offer another resource - a
pair of Photon 2.x courses - one introductory 3-day (which just
had its first run as an internal course here at QNX) and the
advanced 5-day course which I teach for the second time next
week.

Given that I teach, wrote, and make by living off of those
courses, I've admittedly biased, but the feedback I've had from
folks who have taken the couses suggests they found it a really
good value for the price they paid. There's something about
complicated topics like Photon programming that really does seem
to work better with face to face instruction, in my experience.

Anyway, for what it's worth, Bob, take a look on the qnx.com
website - the training schedule is there somewhere in the depths.

The other thing worth knowing is that Steve Reid, the guy
responsible for the majority of the Photon docs (including the
"Programmer's Guide"), reads this newsgroup regularly, and is
really good at accepting feedback. If you could give him an idea
of where you came off the rails (you know, that "What the $#W$#
are they talking about????" moment... ), I'm sure he'd be
happy to know.


Norbert Black
QSSL Training Services

[Bob Kubinec]

The other thing worth knowing is that Steve Reid, the guy
responsible for the majority of the Photon docs (including the
"Programmer's Guide"), reads this newsgroup regularly, and is
really good at accepting feedback. If you could give him an idea

I'm sure I will. Honestly, I found the documentation to be far better than
what comes with most OSes, (such as Linux), I just thought that if you guys
were so concerned about getting new developers, you might want to simplify
the docs.

Bob Kubinec

[Donna Kinsman]

Bob Kubinec <bobarian@softhome.net> wrote:

The other thing worth knowing is that Steve Reid, the guy
responsible for the majority of the Photon docs (including the
"Programmer's Guide"), reads this newsgroup regularly, and is
really good at accepting feedback. If you could give him an idea

I'm sure I will. Honestly, I found the documentation to be far better than
what comes with most OSes, (such as Linux), I just thought that if you guys
were so concerned about getting new developers, you might want to simplify
the docs.

Bob Kubinec

We certainly try to put out the best documentation we can under the
deadlines, and we're always willing to accept constructive feedback!

Steve's on vacation this week; otherwise, he would have chimed in
by now. As Norbert stated, if you give Steve an idea
of where you came off the rails (you know, that "What the $#W$#
are they talking about????" moment... ), he'll be more than
willing to update the docs.

-Donna

[Steve Reid]

Norbert Black <nblack@qnx.com> wrote:
: The other thing worth knowing is that Steve Reid, the guy
: responsible for the majority of the Photon docs (including the
: "Programmer's Guide"), reads this newsgroup regularly, and is
: really good at accepting feedback.

Why, thank-you!

: If you could give him an idea
: of where you came off the rails (you know, that "What the $#W$#
: are they talking about????" moment... ), I'm sure he'd be
: happy to know.

I'd start with the tutorials in the Photon Programmer's Guide. They'll take
you through some simple examples and show you how to work with some of the
widgets. You should also read the introductory chapter.

You should also make yourself _very_ familiar with PtWidget and PtBasic --
they define resources and behaviour that all the other widgets use.

As Norbert said, if you tell me where things went wrong, I might be able
to improve the docs.

------------------------------------------
Steve Reid stever@qnx.com
TechPubs (Technical Publications)
QNX Software Systems
------------------------------------------

[Bob Kubinec]

My first problem is with the introduction chapter. It starts in a good,
simple manner, but the introductory chapter tried to cover too much of
detail on some things, and not a whole lot of time on other things.

Let me explain. The introductory chapter starts with a long talk about
menus, which is very important, but not very confusing to the new developer.
It's not a hard concept to grasp, and the procedures that PhAb uses to make
menus could easily be put in a reference section. I found the concept of
callbacks to be much more confusing. It would be better if they were
explained more in detail, and many more examples on how to use them. Also it
would be (IMHO) to include something about setting and getting resources in
code in the introductory chapter as well.

I hope that this was helpful to you, and I do not want to sound demeaning,
this is simply my opinion.

Bob Kubinec

[Steve Reid]

Bob Kubinec <bobarian@softhome.net> wrote:
: My first problem is with the introduction chapter. It starts in a good,
: simple manner, but the introductory chapter tried to cover too much of
: detail on some things, and not a whole lot of time on other things.

It's a bit like writing a pamphlet that's an introduction to the universe.

: Let me explain. The introductory chapter starts with a long talk about
: menus, which is very important, but not very confusing to the new developer.
: It's not a hard concept to grasp, and the procedures that PhAb uses to make
: menus could easily be put in a reference section. I found the concept of
: callbacks to be much more confusing. It would be better if they were
: explained more in detail, and many more examples on how to use them. Also it
: would be (IMHO) to include something about setting and getting resources in
: code in the introductory chapter as well.

: I hope that this was helpful to you, and I do not want to sound demeaning,
: this is simply my opinion.

Thanks for the feedback. I'll see what I can do.

------------------------------------------
Steve Reid stever@qnx.com
TechPubs (Technical Publications)
QNX Software Systems
------------------------------------------

[Bill Caroselli]

I was porting some code. It used the nap() function.
Helpviewer says that the include file for nap() is
#include <unistd.h>

It is not.

There is a define for nap in unix.h.

Please fix docs.

[Steve Reid]

Bill Caroselli <qtps@earthlink.net> wrote:
: I was porting some code. It used the nap() function.
: Helpviewer says that the include file for nap() is
: #include <unistd.h>

: It is not.

: There is a define for nap in unix.h.

: Please fix docs.

OK -- thanks for pointing out the mistake.

------------------------------------------
Steve Reid stever@qnx.com
TechPubs (Technical Publications)
QNX Software Systems
------------------------------------------

[Bill Caroselli]

Another Oops . . .

In the helpviewer page for MsgReceivePulse(), MsgReceivePulse_r()
about half way down the page it says:

0
A pulse was received. Unlike a message, you should reply to a pulse.

I think you meant to say:

0
A pulse was received. Unlike a message, you should NOT reply to a pulse.

[Steve Reid]

Bill Caroselli <qtps@earthlink.net> wrote:
: Another Oops . . .

: In the helpviewer page for MsgReceivePulse(), MsgReceivePulse_r()
: about half way down the page it says:

: 0
: A pulse was received. Unlike a message, you should reply to a pulse.

: I think you meant to say:

: 0
: A pulse was received. Unlike a message, you should NOT reply to a pulse.

You're right. Thanks for pointing it out.

------------------------------------------
Steve Reid stever@qnx.com
TechPubs (Technical Publications)
QNX Software Systems
------------------------------------------