View previous topic :: View next topic |
Author |
Message |
DarkSnow
Joined: 02 Mar 2005 Posts: 67 Location: Sweden
|
Posted: Tue Jan 17, 2006 10:46 am Post subject: QuakeC Specs v1.0 |
|
|
#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 |
|
 |
MauveBib

Joined: 04 Nov 2004 Posts: 602
|
Posted: Tue Jan 17, 2006 1:19 pm Post subject: |
|
|
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 |
|
 |
Lardarse

Joined: 05 Nov 2005 Posts: 243 Location: Bristol, UK
|
Posted: Wed Jan 18, 2006 5:57 pm Post subject: |
|
|
Great idea!
Idea for a future version: include information about the extension system.
LA |
|
Back to top |
|
 |
DarkSnow
Joined: 02 Mar 2005 Posts: 67 Location: Sweden
|
Posted: Thu Jan 19, 2006 7:49 am Post subject: |
|
|
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 |
|
 |
leileilol

Joined: 15 Oct 2004 Posts: 1321
|
Posted: Thu Jan 19, 2006 9:10 am Post subject: |
|
|
ew chm _________________
 |
|
Back to top |
|
 |
Error Inside3D Staff

Joined: 05 Nov 2004 Posts: 558 Location: VA, USA
|
|
Back to top |
|
 |
DarkSnow
Joined: 02 Mar 2005 Posts: 67 Location: Sweden
|
Posted: Sat Jan 21, 2006 12:51 pm Post subject: |
|
|
Error wrote: | would have been nice to have a HTML version for Inside3D
pretty damn cool  |
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 |
|
 |
Error Inside3D Staff

Joined: 05 Nov 2004 Posts: 558 Location: VA, USA
|
|
Back to top |
|
 |
DarkSnow
Joined: 02 Mar 2005 Posts: 67 Location: Sweden
|
Posted: Sun Jan 22, 2006 1:19 pm Post subject: |
|
|
Cool  |
|
Back to top |
|
 |
FrikaC Site Admin

Joined: 08 Oct 2004 Posts: 947
|
Posted: Sat Mar 11, 2006 8:20 am Post subject: |
|
|
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 |
|
 |
FrikaC Site Admin

Joined: 08 Oct 2004 Posts: 947
|
Posted: Sun Mar 12, 2006 12:56 pm Post subject: |
|
|
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 |
|
 |
Lardarse

Joined: 05 Nov 2005 Posts: 243 Location: Bristol, UK
|
|
Back to top |
|
 |
DarkSnow
Joined: 02 Mar 2005 Posts: 67 Location: Sweden
|
Posted: Sun Mar 12, 2006 9:31 pm Post subject: |
|
|
Sweet, i missed that one  |
|
Back to top |
|
 |
FrikaC Site Admin

Joined: 08 Oct 2004 Posts: 947
|
Posted: Mon Mar 13, 2006 5:34 am Post subject: |
|
|
There's more than a few errors in that also, but I'm too lazy to go looking for them currently. |
|
Back to top |
|
 |
|
|
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
|