Re: [Luxasm-devel] luxasm/documents/Xlib

From: Beth (BethStone21_at_hotmail.NOSPICEDHAM.com)
Date: 06/22/04 

Date: Tue, 22 Jun 2004 14:45:29 +0100

Frankie says:
> Beth wrote:
> > Guess what appears to have happened? Now "MailMan" is
deciding
> > not to deliver to me, rather than C!! I could tell something
was
> > wrong because the CVS replies "Sending log Email" or
whatever
> > and they aren't showing up at my inbox at all...
> >
> > Hence, if anything has been said on the LuxAsm list recently
> > then it's quite possible that I didn't see it...yes, this
"GNU
> > MailMan" on SourceForge seems really reliable, doesn't he?
He
> > doesn't bother sending anything to C at first...then fixes
that,
> > only to stop sending it to me instead...
> >
> > I guess it'll be your turn next, Frank ;)...
>
> My problem seems to be that outgoing mail to Wilhelm and/or
Jonathan
> Bartlett is bouncing back to me (note to self: perservere!).

[ On the NASM list you mean there, I presume...because if these
people are now posting to the LuxAsm list then I've _really_
missed out on developments lately ;) ]

> SourceFog has been treating me pretty good lately (touch
wood)...

Doesn't mean much, mind you...I had no problems either until
recently...

> since I figured out that they changed the name of the CVS
server(!).

Did they?!? Because I don't think I changed my settings and
those Xlib files popped up, no problem...perhaps an "alias" to
the old name or something (and I'd better change it before they
eventually declare it "obselete"??)?

I'll take a look at the "status page"...that is a mighty useful
page, in fact (it was stumbling into it totally by accident that
made me notice that "bug" where you have to change your password
in order to properly propogate it to the CVS and shell
servers...the "bug" being that when you first create an account,
it doesn't actually set it up properly...so you have to do a
"dummy" password change - "change" it to whatever it already
is - just to force it to propogate the password to all the
servers properly :)...that's actually perhaps a design mistake
on SourceFrog in general that such a useful and important page
is actually somewhat "hidden" and not drawn attention to...you
know, there should probably be some "server status" link
attached to all the other links on the left that jumps you
straight there...or perhaps - should you click on the CVS link -
that those pages themselves say something like "Server currently
down" or whatever at the top...it's the old rule: "Hope for the
best, plan for the worst"...even if they _intend_ that the
server should not go down all that often, the design should
still have the "error messages" worked into it for those
"unforeseen" occasions...

> Their status page
> talks about some of this stuff - some of it is "planned
outages" - maybe
> if we monitored that page, we'd do better...

Yeah; But they could also make it slightly simpler to find
it...considering its relative importance, it's almost like they
are delibrately trying to "hide" it or something ;)...

> I almost didn't copy that message to the NG - obviously, it's
not of
> interest to everybody - but then I figured a little "backup"
wouldn't
> hurt. I suppose a little "advertising" doesn't hurt, either -
both for
> LuxAsm (we're still open to developers - last chance to get in
on the
> ground floor!) and your html Xlib doc conversion. As you point
out, it's
> useful to much more than the almost-nonexistant LuxAsm
community!

Yup; I'd considered something like this perhaps being useful for
HLA (you know, for the "portable GUI library" stuff :), prior to
LuxAsm starting...and once LuxAsm appeared, then it clearly was
going to be useful to lots of people that that "pro" finally
outweighed the "con" of the effort it takes (well, it is a large
text...the "conversion" is all fairly easy and automatic but
there's an _awful lot_ of it...you know, the old "easy but
tedious" situation ;)...

> > > Everybody: Please give *some* log message...
>
> > Message understood;
>
> Thanks. Doesn't have to be too detailed, just an idea "what
it's about".
> Your latest log messages are perfect.

Sure; Like I say, I only didn't bother that last time, just
because it really would have been a quite pointless set of
comments...but, you're right that I should always attach a
comment from the perspective of "looking back" in the future,
perhaps...what seems "obvious" or "pointless" now does often
turn out to be "useful" when looking back from six months hence
or whatever ;)...

> > To be honest, as you note, the real reason
> > why I didn't put log messages this particular time is
because,
> > as you've probably seen, I'm just posting up some HTML stuff
> > about Xlib...the original is a Plain Text file - one long
> > massive file - so just a case of splitting it up, adding
HTML
> > "tags" so it looks nice on the screen and "hyperlinking" it
all
> > up so all the pages point at each other (or, well, you
wouldn't
> > be able to get anywhere otherwise ;)...
>
> Looks really great! I'm surprised this hasn't already been
done.

In a sense, yes, I was also surprised...I mean, there are
references out there but they are usually a case of getting the
whole text but no hyperlinks (plain text, like I'm actually
copying the text from ;)...or you get hyperlinks but not the
whole text (like there's a website out there that has a "list of
functions" and links up to the function descriptions but the
rest of the text is missing...although, I've _introduced_ that
"Index of Functions" section at the end, by the way...that's not
in the original book (well, it was "treeware" originally ;) but
being able to look up functions and jump straight to the
definitions _is_ a good idea from that site I saw, that I
"borrowed" the idea and added it :)...

> I've been consulting:
>
>
<http://www.ac3.edu.au/SGI_Developer/books/XLib_PG/sgi_html/inde
x.html>
>
> It's similar, but not the same document. I like yours better,
I think.
> Especially the glossary :)

Indeed; The basic idea, as you may guess, is simply to load it
up with everything...not just the full text but to put in the
hyperlinks...they make quite a bit of difference, I think, when
you can "navigate" around it all quickly and easily...

As I stated, the glossary is an "independent" kind of thing so
what's there is mostly completed (why I worked on that
early...plus, of course, because I want the main text to have
hyperlinks to the glossary throughout :)...the idea will be to
eventually make the main text just as "rich"...you know, where
it says something like "to free memory, use XFree" then the
"XFree" becomes a link over to the page about "XFree"...

It's what I was saying to Randy...this kind of reference
material is actually best when it's "non-linear"...you know,
while you're coding, you just want to know something specific
like "What are the parameters for XCreateWindow?" or "Right,
I've opened the display...what was the opposite function to
close it again?"...so being able to just go directly to
"XCreateWindow" or to "Closing the display" directly is what the
programmer often needs from their reference material...

The original text - much like Randy's stuff - is "treeware" so
it's written in mostly a "linear" way...but the good old
(British; just to be patriotic there ;) invention of the
"hyperlink" means that you can actually make it _BOTH_ at the
same time...

I also noticed that though the text is rather large, none of the
"sections" are particularly big...so splitting it into "one page
per section" (with the "previous" / "next" links so you can read
"linear", if you like ;) makes it a much easier read...indeed,
Hopefully - this is the intention - you'll (anyone'll) find Xlib
a whole lot easier and less mysterious when using my
documentation here because the built-in links to the glossary
for any new terminology avoids the typical "what did 'ancestor'
mean again?" confusions...you can easily "skip" bits you don't
care about at the moment...jump straight to "XCreateWindow" or
whatever...

Indeed, Hopefully the documentation kind of proves a point I'd
make that even something as simple as the _layout_ can make a
big difference to how easy it is to absorb information...

> > I'm not the original author of the actual text,
>
> No, prolific as you are, I don't think you can crank 'em out
*that*
> quick :)

Also, I don't know Xlib _that_ well yet...mind you, this is
another advantage of doing this, of course...in doing it, I have
to read the whole thing as I go...so, even if I was not
specifically intending to do so, I'll pick it all up as I go
along subconsciously, anyway...that's why I started this, of
course...because it's a "win / win" situation in many ways :)...

> > ...or "ancestor" and "inferior"...
>
> Let's see... If A is an inferior of B, then B is an ancestor
of A... I
> get it! It's ancestor worship! I can dig that. I'm not too
sure about
> these "gods", but I *know* I had ancestors!

The question is, though, whether A is "occluded" or "obscured"
by its inferiority to B...also, kind of weird, ain't it, to have
"inferior" rather than "descendent" as the opposite of
"ancestor"?

> > X guys Love their obscure terminology (or should that be
> > "occluded terminology"? ;)
>
> Well, it's "the X files" after all...

Oh dear, does that mean little green men are going to appear and
perform "cow mutilations" and flash bright lights at passing
drunken rednecks?

Hmmm, although, that would make for an amusing screen-saver,
perhaps...called "Xfiles", following a "day in the life" of a
mischievous alien creating crop circles, flashing lights at
passing motorists and abducting people with his tractor beam and
stuff ;)...

> > [ And, yeah, after the "episode" last time with the SysCalls
> > (sorry, "syscalls" ;), I just decided to go ahead without
> > bothering with an announcement... ]
>
> What's the current status of "SysCalls.lst", anyway?

Temporarily delayed; I'll do that next, probably...the thing is
whether to bother with XML or not...it's a good idea in some
regards...but introducing XSLT and that kind of thing isn't
quite so good because, well, as noted, it has a weird structure
(the XML data "loads" the XSLT "code" that shows it on the
screen rather than the other way around, which is infinitely
more useful)...

But, indeed, what I'm thinking is that if the list is made more
"generic" then it's not just "interrupts" it could cover...there
could also be alternative "lists" that detail things like Xlib
functions or Win32 API or OpenGL libraries or whatever...of
course, the Win32 part would be "beyond the scope of the LuxAsm
project"...but, well, it's only a case of defining a "standard"
for making and reading and using these "lists" then I can just
do Linux syscalls and perhaps Xlib with it...but, if there's a
"standard" for these things (XML interesting allows for "XML
schemas" which are XML documents themselves which are used to
"define" the layout of other XML documents...a kind of "BNF"
definition for how a list should be structured :) then, more
generally, a more comprehensive Ralf Brown-like list for Linux
could eventually come out of starting something like that (or,
alternatively, a Win32 version)...because, after all, Ralf
Brown's is _THE_ list for DOS coders...having something similar
for Linux would likely be very useful...it would, of course,
need some "extension" in that not everything is done through
"interrupts"...but a "standard" could easily be created that
detailed functions and their parameters in a similar way or
whatever...

Anyway, again, the thing here is that, well, it's all heading
towards "beyond the scope of this project" areas...I can't,
indeed, "save the universe" with every single thing I do, after
all...but, well, if I'm making a "list", anyway, then taking
some time to think up a flexible "standard" to make the list
under that could also be used for other lists...

On the other hand, maybe that's all barking up the wrong tree
and would be a waste of time bothering with...that is, as
"fancy" an idea that XML is, would I already have been done with
my list, if I'd just carried on as it was without all the XML
suggestions? You know, not that these are bad suggestions in any
way but, indeed, as I say, you can't "save the universe" with
every single thing you do...and if, after all the effort, nobody
bothers to expand on the list or anything then are we talking
"diminishing returns"? You know, it's all in XML...but the
_only_ person who bothers to make use of the list in XML format
is just the person who made the suggestion to me to do it in XML
;)...

> > Oh, does our main page still have "X licence" as well as GPL
> > listed? Well, if it doesn't, it will do straight after this
> > posting ;)...
>
> Does now, so if it didn't, you must have gotten to it :)
Thanks, Beth!

I got to it...OSI call it "MIT licence", apparently...or, at
least, I compared the text on the OSI website to that in the X
documentation and it seems to be word-for-word the same...and X
was originally from MIT...so I'm thinking I've got the right
licence there...but I wouldn't put large sums of money on it or
anything, as I haven't seen it spelt out anyway specifically
that it's "MIT licence"...I "deduced" that from it coming from
MIT originally and that, when I looked at the OSI's example
licence texts, it reads word-for-word the same...

But, indeed, as always: I am not a lawyer...this is not legal
advice...blah-blah-blah...

Generally, in fact, "licences" tend to be an "necessary evil" to
me...you've got to keep with them and apply some kind of
"licence" on your work (even if the "non-licence" licence of
"public domain", so to speak :)...but they are often a lot of
pedantic nonsense for no good reason...except you can't really
avoid it or, indeed, the second you do, that will be the instant
some commercial company "steals" it or a user sues you because
you lacked a "disclaimer of responsibility" and all that
nonsense...a case of "if only people were generally sensible and
honest, we wouldn't need these stupid things" but,
unfortunately, there _are_ people who aren't sensible nor
honest, who'd end up being even more trouble again than dealing
with this licence stuff...like most law, it can be annoying and
you think "Do we need this crap?"...but the instant you don't
bother, then all hell breaks loose...

Beth :)

Quantcast