Inside3D!
     

QuakeC Specs v1.0

 
Post new topic   Reply to topic    Inside3d Forums Forum Index -> QuakeC Programming
View previous topic :: View next topic  
Author Message
DarkSnow



Joined: 02 Mar 2005
Posts: 67
Location: Sweden

PostPosted: Tue Jan 17, 2006 10:46 am    Post subject: QuakeC Specs v1.0 Reply with quote

#1, Who were the original autors of the QC Specs? (anybody)

#2, I have cleaned up the specs and converted it to windows helpfile (.chm), any comments would be nice.

http://darksnow.quakedev.com/downloads/qcspecs.rar
Back to top
View user's profile Send private message Visit poster's website MSN Messenger
MauveBib



Joined: 04 Nov 2004
Posts: 602

PostPosted: Tue Jan 17, 2006 1:19 pm    Post subject: Reply with quote

There are a lot of mistakes in the QC Manual, I suggest you check out the quake wiki for more accurate, uptodate function definitions etc.
_________________
Apathy Now!
Back to top
View user's profile Send private message
Lardarse



Joined: 05 Nov 2005
Posts: 243
Location: Bristol, UK

PostPosted: Wed Jan 18, 2006 5:57 pm    Post subject: Reply with quote

Great idea!

Idea for a future version: include information about the extension system.

LA
Back to top
View user's profile Send private message
DarkSnow



Joined: 02 Mar 2005
Posts: 67
Location: Sweden

PostPosted: Thu Jan 19, 2006 7:49 am    Post subject: Reply with quote

Thanks for both the comments.

As of right now the chm only contains the specifics from qc specs. I thought it would be good to have as a basis to start from.

Populating it with better definitions from the wiki is a great idea, thanks.

In the future i will include documentation on the extensions aswell, la - thanks for bringning it up.

_____

Is the layout done well? Or are there some parts whitch needs improvement?

I think its easier to read/nav in the chm compared to the web specs, but i still think it could be better. Im open for any suggestions.
Back to top
View user's profile Send private message Visit poster's website MSN Messenger
leileilol



Joined: 15 Oct 2004
Posts: 1321

PostPosted: Thu Jan 19, 2006 9:10 am    Post subject: Reply with quote

ew chm
_________________
Back to top
View user's profile Send private message
Error
Inside3D Staff


Joined: 05 Nov 2004
Posts: 558
Location: VA, USA

PostPosted: Thu Jan 19, 2006 10:24 am    Post subject: Reply with quote

would have been nice to have a HTML version for Inside3D

pretty damn cool Smile
_________________
Inside3D : Knowledge Is Power
Darkplaces Documentation Wiki
Back to top
View user's profile Send private message Send e-mail Visit poster's website AIM Address Yahoo Messenger MSN Messenger
DarkSnow



Joined: 02 Mar 2005
Posts: 67
Location: Sweden

PostPosted: Sat Jan 21, 2006 12:51 pm    Post subject: Reply with quote

Error wrote:
would have been nice to have a HTML version for Inside3D

pretty damn cool Smile


Thanks.

Since chm basicly is a compiled compressed form of html files, its not hard to make a plain html conversion - since all the work is already done.

Only problem would be that you'l miss the search functions that chm provides.


http://darksnow.quakedev.com/downloads/qcwebspecs.rar
Inside3d and anyone who would like to may use this in any way possible.
Back to top
View user's profile Send private message Visit poster's website MSN Messenger
Error
Inside3D Staff


Joined: 05 Nov 2004
Posts: 558
Location: VA, USA

PostPosted: Sun Jan 22, 2006 10:29 am    Post subject: Reply with quote

posted on main site Shocked

soon to be integrated
_________________
Inside3D : Knowledge Is Power
Darkplaces Documentation Wiki
Back to top
View user's profile Send private message Send e-mail Visit poster's website AIM Address Yahoo Messenger MSN Messenger
DarkSnow



Joined: 02 Mar 2005
Posts: 67
Location: Sweden

PostPosted: Sun Jan 22, 2006 1:19 pm    Post subject: Reply with quote

Cool Smile
Back to top
View user's profile Send private message Visit poster's website MSN Messenger
FrikaC
Site Admin


Joined: 08 Oct 2004
Posts: 947

PostPosted: Sat Mar 11, 2006 8:20 am    Post subject: Reply with quote

I have heaps of complaints toward the authors of every QuakeC guide to date. Here's just a sampling of what is wrong with QuakeC specs.

1.1 Comments names and types

Quote:
"Those comments are the same as in C++ (and many C languages)."


This would be better phrased "This comment syntax is the same as C and many other C or C based languages."

It's obvious the author favors C++ by his comments, to the point of making awkward and ambiguous phrases to compare QuakeC to C++.

Quote:
"Let's start with the bad news: it is impossible, in Quake-C, to define new types. That means for instance that you cannot create a type named ammo, derived from float, that will only be used to store ammo count. So much for the clean programming habits."


This is condescending bullshit, as it's not "bad news". If you've gone through some people's source code as I have, redefining types can be a headache. Yes, it's useful in a few, rare circumstances, but with preqcc and modern compilers it's not "impossible" either. "Clean programming habits"? There are clean programming habits for every language. QuakeC is no different, and it's lack of typedef or such features don't completely destroy programming habits. It would be better to say:

"QuakeC is strongly typed and allows for no means to alias or subclass types. For example you cannot create a type named ammo derived from float that will only be used to store an ammo count."

Quote:
"It is often convenient, in C (or C++), to create new structures (or Objects, or record) to store a few related information at the same place. For instance, you may wish to use a single structure to store all the ammo count of the player, and also the current selected weapon, since that information are obviously related to each other.

Though both entity and vector are obviously structured types, it is impossible to create new structured types of that kind, in Quake-C. However, the entity type can be modified to suit some of your needs."


If you're well familiarized with C or C++, then yeah, you know that a vector is 'obviously' a structured type. But it is a language feature more than a structure. I think as an introduction to the QC language these paragraphs are completely out of place. They explain, once again, how QC differs from C++. However, this may need to be said for people coming from C/C++ so a better and less condescending rephrase:

"It is often conveinant, in C o C++, to create new structures (called Objects or records in other languages) to store related information in the same place. QuakeC does not provide this functionality, however, the basic entity type can be expanded with new fields."

Simpler too, we don't need a tutorial on C++ here.

1.2 Definition of Variables

Quote:
"where type is one of the pre-defined simple types."


Perhaps a quick list of the simple types should have been included in this statement: float, vector, entity, string, void

Quote:
"There are two levels of scoping. By default all variables are global: they can be accessed by any functions, and they are shared by all the functions (and all the clients of a given network server, of course)."


By default? How about:

"There are type types of scoping, when placed outside a function, variables are considered global. They can be accessed within any function, and are shared by all functions, even across files."

The addendum "(and all the clients of a given network server, of course)" is completely bogus. Variables are not shared with clients, because clients do not run QuakeC.

Quote:
But inside the functions, using the keyword local just before the declaration of a variable, you can make this variable visible only the the function itself (i.e. it will be allocated on the stack).


This is somewhat confusing to a newb. It might be better to say (instead of just saying 'it goes on the stack', actually attempting to explain what that means):

"The second type of scope is the local scope. Variables declared within a function (by prefixing them with the local keyword) are instead only accessible to the function they are declared in. The state of these local variables are stored off upon each function call, so that recalling the same function will not alter the local variables of a previous call to that function."

Quote:
Note that though it looks like a definition of variable, with a default initial value, is is totally different. There is no memory reserved for constants, and they are not saved to game files (only regular variables are).

To make matters worse, if you use a constant like a variable, and try to affect a new value to it... well, it's very likely that you will cause troubles to the program (malfunctions, or crashes). So never modify the value of a constant.


Again, assuming you're proficient with C/C++, this makes complete sense, but I'd rather not assume this. "There is no memory reserved for constants" is wrong. How about:

"To someone proficient with C/C++, that may look like the definition of a variable with a default value, however, in QuakeC this is the definition of a constant. Constants are merged with other constants of the same value, as such, if you accidently change a constant, it will result in odd game behavior. Never assign new values to constants. Constants are not saved to game saves, only regular variables are."

I'm too tired to go through the rest of the specs now. I may post a follow up, but as you can see I've always disliked how this documentation is worded. There are many many errors in it also.
Back to top
View user's profile Send private message Send e-mail
FrikaC
Site Admin


Joined: 08 Oct 2004
Posts: 947

PostPosted: Sun Mar 12, 2006 12:56 pm    Post subject: Reply with quote

Continued...

1.3 Operations

Quote:
Operations on floats or integer


This heading is wrong or misleading. There's no integer type in QuakeC. A better title would have been "Operations on floats or vectors", however, divide (/) is not available on vectors, and one should note that vector * vector yields the dot product.

He goes on to direntiated integers from floats by making not that a float values is truncated when used in a logic operation.

1.4 Definition of Functions

Quote:
It is strictly equivalent to:


This is nitpicky, but strictly equivalent means more than merely functionally identical, it means it is a 1:1 replacement. OP_STATE is not a 1:1 replacement to the example code. as using a state macro is far faster and more compact.

1.5 Loop and conditions

This, again is nitpicky, but most of my response to this file is that. There's no description whatsoever as to what any of this is.

2.1 The Simple Types

I don't like his description of the Entity type, and it appears throughout the document, but he treats the entity less like what it is, a pointer and more like it's some kind of struct. I don't know what I'd rather do here.


And so on...
Back to top
View user's profile Send private message Send e-mail
Lardarse



Joined: 05 Nov 2005
Posts: 243
Location: Bristol, UK

PostPosted: Sun Mar 12, 2006 6:38 pm    Post subject: Reply with quote

Have you guys seen this?

http://www.gue-tech.org/quake/qcrm/index.html
Back to top
View user's profile Send private message
DarkSnow



Joined: 02 Mar 2005
Posts: 67
Location: Sweden

PostPosted: Sun Mar 12, 2006 9:31 pm    Post subject: Reply with quote

Lardarse wrote:
Have you guys seen this?

http://www.gue-tech.org/quake/qcrm/index.html


Sweet, i missed that one Smile
Back to top
View user's profile Send private message Visit poster's website MSN Messenger
FrikaC
Site Admin


Joined: 08 Oct 2004
Posts: 947

PostPosted: Mon Mar 13, 2006 5:34 am    Post subject: Reply with quote

There's more than a few errors in that also, but I'm too lazy to go looking for them currently.
Back to top
View user's profile Send private message Send e-mail
Display posts from previous:   
Post new topic   Reply to topic    Inside3d Forums Forum Index -> QuakeC Programming All times are GMT
Page 1 of 1

 
Jump to:  
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum


Powered by phpBB © 2004 phpBB Group