hi all,
i would like to see a structure-reference in future
documentation. it’s so nerved to search the hole documentation,
or to read the include outside the helpviewer, just only to
have a look what members a structure have.
thnx.
–
gruss
michael
Michael Taubert <taubert@managementakademie.de> wrote:
: hi all,
: i would like to see a structure-reference in future
: documentation. it’s so nerved to search the hole documentation,
: or to read the include outside the helpviewer, just only to
: have a look what members a structure have.
The Library References (and the Widget Reference for Photon) do describe
the main data structures. They’re filed alphabetically with the functions.
If there are specific ones you think we should add, please let us know.
(Most of the docs also have an online index that should help you find
things quickly. Again, if there are entries missing, please let us know
– building a good index isn’t a trivial exercise.)
Steve Reid stever@qnx.com
TechPubs (Technical Publications), QNX Software Systems
“Another damned, thick, square book! Scribble, scribble, scribble!”
Steve,
well, the really helpful thing would be to have references from the function
pages.
E.g. The documentation of PtForwardWindowEvent() does it - it has a
reference to PhWindowEvent_t in the “See also” section. But most of the
functions don’t have it (E.g., it would be nice to get from PtWidgetDim()
doc right to the PhDim_t doc).
It almost looks to me that this process could be automated - Just go through
the files, look for keywords, and insert links?
Markus
“Steve Reid” <stever@qnx.com> wrote in message
news:8tbuja$7kp$1@nntp.qnx.com…
Michael Taubert <> taubert@managementakademie.de> > wrote:
: hi all,: i would like to see a structure-reference in future
: documentation. it’s so nerved to search the hole documentation,
: or to read the include outside the helpviewer, just only to
: have a look what members a structure have.The Library References (and the Widget Reference for Photon) do describe
the main data structures. They’re filed alphabetically with the functions.
If there are specific ones you think we should add, please let us know.(Most of the docs also have an online index that should help you find
things quickly. Again, if there are entries missing, please let us know
– building a good index isn’t a trivial exercise.)
Steve Reid > stever@qnx.com
TechPubs (Technical Publications), QNX Software Systems“Another damned, thick, square book! Scribble, scribble, scribble!”
- attributed to William Henry, Duke of Gloucester (1743 - 1805)
Markus Loffler <loffler@ces.clemson.edu> wrote:
: Steve,
: well, the really helpful thing would be to have references from the function
: pages.
: E.g. The documentation of PtForwardWindowEvent() does it - it has a
: reference to PhWindowEvent_t in the “See also” section. But most of the
: functions don’t have it (E.g., it would be nice to get from PtWidgetDim()
: doc right to the PhDim_t doc).
That’s something I’ve started doing – the links are useful, but they
take time to put in place.
: It almost looks to me that this process could be automated - Just go through
: the files, look for keywords, and insert links?
Unfortunately, every occurrence of the name becomes a link, which gets
annoying if the structure is mentioned several times in one file.
Previously, Steve Reid wrote in comp.os.qnx:
Michael Taubert <> taubert@managementakademie.de> > wrote:
: hi all,: i would like to see a structure-reference in future
: documentation. it’s so nerved to search the hole documentation,
: or to read the include outside the helpviewer, just only to
: have a look what members a structure have.The Library References (and the Widget Reference for Photon) do describe
the main data structures. They’re filed alphabetically with the functions.
If there are specific ones you think we should add, please let us know.(Most of the docs also have an online index that should help you find
things quickly. Again, if there are entries missing, please let us know
– building a good index isn’t a trivial exercise.)
Steve Reid > stever@qnx.com
TechPubs (Technical Publications), QNX Software Systems“Another damned, thick, square book! Scribble, scribble, scribble!”
- attributed to William Henry, Duke of Gloucester (1743 - 1805)
well,
what i need is a datatype-reference. the most time i dont know the
function on wich page the structure is explained. so i have a look
at the include file to save time. for an example have a look at
the glibc-documentation.
http://www.netppl.fi/~pp/glibc21/libc_toc.html
something like the type index near the end is what i suggest.
–
gruss
michael
Steve Reid <stever@qnx.com> wrote:
Markus Loffler <> loffler@ces.clemson.edu> > wrote:
…
: It almost looks to me that this process could be automated - Just go through
: the files, look for keywords, and insert links?Unfortunately, every occurrence of the name becomes a link, which gets
annoying if the structure is mentioned several times in one file.
Why does that annoy you? Are you using an annoyingly unreadable colour
for links or something? 
Personally, I like the idea of making every occurence of a name a link.
This way, when I’m reading about something, it’s easy to find relevant
links (or find out that they don’t exist at all) without having to
search through the entire file.
–
Wojtek Lerch (wojtek@qnx.com) QNX Software Systems Ltd.
I agree with Wojtek. It is beneficial and does not need to effect the
readibility.
Doxygen created manuals are like that. E.g.,
http://doc.trolltech.com/qslider.html
Markus
“Wojtek Lerch” <wojtek@qnx.com> wrote in message
news:8tmqru$iaa$1@nntp.qnx.com…
Steve Reid <> stever@qnx.com> > wrote:
Markus Loffler <> loffler@ces.clemson.edu> > wrote:
…
: It almost looks to me that this process could be automated - Just go
through
: the files, look for keywords, and insert links?Unfortunately, every occurrence of the name becomes a link, which gets
annoying if the structure is mentioned several times in one file.Why does that annoy you? Are you using an annoyingly unreadable colour
for links or something? >Personally, I like the idea of making every occurence of a name a link.
This way, when I’m reading about something, it’s easy to find relevant
links (or find out that they don’t exist at all) without having to
search through the entire file.–
Wojtek Lerch (> wojtek@qnx.com> ) QNX Software Systems Ltd.
Wojtek Lerch <wojtek@qnx.com> wrote:
: Personally, I like the idea of making every occurence of a name a link.
: This way, when I’m reading about something, it’s easy to find relevant
: links (or find out that they don’t exist at all) without having to
: search through the entire file.
I shouldn’t have implied that I put just one link per file. I put one in
the first time a function/widget/resource/data type/etc. is mentioned and
then put additional links when I think it’s merited. But there are places
where a widget is mention several times in two or three sucessive paragraphs,
and that’s when multiple links become visual noise.
Steve Reid <stever@qnx.com> wrote:
Wojtek Lerch <> wojtek@qnx.com> > wrote:
: Personally, I like the idea of making every occurence of a name a link.
: This way, when I’m reading about something, it’s easy to find relevant
: links (or find out that they don’t exist at all) without having to
: search through the entire file.I shouldn’t have implied that I put just one link per file. I put one in
the first time a function/widget/resource/data type/etc. is mentioned and
then put additional links when I think it’s merited. But there are places
where a widget is mention several times in two or three sucessive paragraphs,
and that’s when multiple links become visual noise.
I guess this depends on how a person reads the docs.
If the question you typically ask while looking at a docs page is “How
many different places can I go from this page”, then I agree that having
multiple instances of the same link may make counting more difficult,
and I understand that’s why you consider them noise.
But when I am actually reading the text, the question I’m interested
in more often is “Where can I find more about this term or function that
is mentioned here”, and what I consider noise is that I have to look
around and search two or three paragraphs before I know whether what I
was just reading about is explained elsewhere or not; and if not, then I
have to look for the spot where I interrupted reading, and then I
probably need to find and go back to the beginning of the interrupted
sentence because I have forgotten how the sentence started… I would
much rather rely on the assumption that if the name that I am looking at
is not a link, it’s because there is no link, and all I can do is just
keep reading.
Wojtek Lerch (wojtek@qnx.com) QNX Software Systems Ltd.
May I butt in? I recently saw a page where every occurance of each of
several phrases was a link. My first reaction was annoyance at all the
links. If there was so much additional detail to be discussed, why
wasn’t the document organised differently?
My second reaction was to wonder if all the links for the same phrase
pointed to the same place. It turns out they did for the most part, but
not for all. Not good, in my estimation, not that anyone here has
advocated this.
The QNX page for setting up mail, as an example which gets my vote,
refers to the sendmail program ten times. There is one link - the first
time sendmail is mentioned. In my opinion, that’s just about right for a
page that is about three screens long.
Richard
Wojtek Lerch wrote:
Steve Reid <> stever@qnx.com> > wrote:
Wojtek Lerch <> wojtek@qnx.com> > wrote:
: Personally, I like the idea of making every occurence of a name a link.
: This way, when I’m reading about something, it’s easy to find relevant
: links (or find out that they don’t exist at all) without having to
: search through the entire file.I shouldn’t have implied that I put just one link per file. I put one in
the first time a function/widget/resource/data type/etc. is mentioned and
then put additional links when I think it’s merited. But there are places
where a widget is mention several times in two or three sucessive paragraphs,
and that’s when multiple links become visual noise.I guess this depends on how a person reads the docs.
If the question you typically ask while looking at a docs page is “How
many different places can I go from this page”, then I agree that having
multiple instances of the same link may make counting more difficult,
and I understand that’s why you consider them noise.But when I am actually reading the text, the question I’m interested
in more often is “Where can I find more about this term or function that
is mentioned here”, and what I consider noise is that I have to look
around and search two or three paragraphs before I know whether what I
was just reading about is explained elsewhere or not; and if not, then I
have to look for the spot where I interrupted reading, and then I
probably need to find and go back to the beginning of the interrupted
sentence because I have forgotten how the sentence started… I would
much rather rely on the assumption that if the name that I am looking at
is not a link, it’s because there is no link, and all I can do is just
keep reading.But that’s just my personal preference. I won’t be surprised if
human-machine interface specialists disagree with me…–
Wojtek Lerch (> wojtek@qnx.com> ) QNX Software Systems Ltd.