New editing reference (well, sort of)

News about ZDoom, its child ports, or any closely related projects.
[ZDoom Home] [Documentation (Wiki)] [Official News] [Downloads] [Discord]
[🔎 Google This Site]

Moderator: GZDoom Developers

User avatar
randi
Site Admin
Posts: 7746
Joined: Wed Jul 09, 2003 10:30 pm
Contact:

New editing reference (well, sort of)

Post by randi »

I feel bad about not having updated the documentation for ZDoom in ages, so although I'm not by any means done with it yet, I have uploaded what could be considered a very early preview edition of the new editing documentation. Right now, it's just a bunch of HTML files. If you have a look at some of it, you should be able to see that this is more more than just an update of the old documentation. I'm trying to make everything more descriptive and useful. Eventually, the final product will also be available in an HTML help version for added convenience.
User avatar
Hirogen2
Posts: 2033
Joined: Sat Jul 19, 2003 6:15 am
Graphics Processor: Intel with Vulkan/Metal Support
Location: Central Germany
Contact:

Post by Hirogen2 »

OMG, it's MSDN CSS Style!
User avatar
Biff
Posts: 1061
Joined: Wed Jul 16, 2003 5:29 pm
Location: Monrovia, CA, USA

Post by Biff »

Randy, maybe it's too early for us to start noting anything left out as you said it's a very early preview. Do you want any comments?

Spawnspot.
User avatar
Hirogen2
Posts: 2033
Joined: Sat Jul 19, 2003 6:15 am
Graphics Processor: Intel with Vulkan/Metal Support
Location: Central Germany
Contact:

Post by Hirogen2 »

Comments.
Compare against ref1.
Cyb
Posts: 912
Joined: Tue Jul 15, 2003 5:12 pm

Post by Cyb »

Biff wrote:Randy, maybe it's too early for us to start noting anything left out as you said it's a very early preview. Do you want any comments?

Spawnspot.
these are all specials, spawnspot is an internal fucntion, plus: http://zdoom.doomworld.com/reference/acsintern.html scroll around 3/4 down the page
User avatar
randi
Site Admin
Posts: 7746
Joined: Wed Jul 09, 2003 10:30 pm
Contact:

Post by randi »

Hirogen2 wrote:OMG, it's MSDN CSS Style!
Is that bad or good? I like it, but I'm also very used to seeing it. The stylesheet is actually modified from one included with NDoc (which was aptly named MSDN.css).
User avatar
Enjay
 
 
Posts: 26516
Joined: Tue Jul 15, 2003 4:58 pm
Location: Scotland
Contact:

Post by Enjay »

First impression comments:

I like:

remarks - which seem good and informative,

examples - which are always useful

first appeared in - which may be simply a piece of trivia a lot of the time, but will also be useful if a person is trying to make something compatible with a certain version.

I dislike:

The parameters being listed vertically

Code: Select all

ACS_Execute (
  script,    // script to execute
  map,       // map containing the script
  s_arg1,    // first argument passed to the script
  s_arg2,    // second argument passed to the script
  s_arg3     // third argument passed to the script
);
I know that does allow you to put a description of each parameter beside it, but it looks different to how most people will use it in their scripts...

Code: Select all

ACS_Execute (script, map, s_arg1, s_arg2, s_arg3);
I'd prefer something a little more like that, and then have an explanation of what the parameters mean below. It would also make things easier to copy and paste. Although, the example section does kind of cover my objections to the layout you have used.

I'm also not sure about the black on white text. A little harsh on the eyes? Just dulling the whiteness of the background (like the message boxes here) would do nicely IMO.
User avatar
arcticwolf
Posts: 245
Joined: Mon Jul 28, 2003 4:52 am
Location: The world
Contact:

Post by arcticwolf »

randy wrote:
Hirogen2 wrote:OMG, it's MSDN CSS Style!
Is that bad or good? I like it, but I'm also very used to seeing it. The stylesheet is actually modified from one included with NDoc (which was aptly named MSDN.css).
I think the stylesheet's fine; it looks good, and what matters is the contents, anyway. Outside of that, I think it would be better to put the description of what a given special does under the box describing the parameters instead of over it; furthermore, the description should be verbose enough to let even a newbie like me understand what the special is supposed to do. ;) Right now, the actual description seems to be mostly contained in the "remarks" section.

Another small error I noticed: the examples for ACS_LockedExecute use ACS_Execute instead.

Generally, it looks fine to me, though. The only thing I'm wondering about is whether you can read minds now, too - I was just thinking a few days ago that the old reference really was in need of an update. :)
User avatar
Ultraviolet
Posts: 1152
Joined: Tue Jul 15, 2003 9:08 pm
Location: PROJECT DETAILS CLASSIFIED.

Post by Ultraviolet »

arcticwolf: Everyone's been saying the reference has been in need of an update for a while.
User avatar
arcticwolf
Posts: 245
Joined: Mon Jul 28, 2003 4:52 am
Location: The world
Contact:

Post by arcticwolf »

Ultraviolet wrote:arcticwolf: Everyone's been saying the reference has been in need of an update for a while.
And I'm no exception. :) I was seriously considering to try an update myself, though.
User avatar
randomlag
Posts: 405
Joined: Thu Jul 17, 2003 10:10 pm

Post by randomlag »

Nice job.

I like the parameters being listed vertically, that's usually my function style since it makes commenting each parm very clear - so must be a coder thing :D

As a note, it's much faster to have ALL the commands on one continous page without having to click each as a topic. The way it is now looks cool, but is cumbersome to use as a study guide. IOW, there are 2 ways to always look at documentation - as a reference once you know it and as a learning tool.

If you put it into a style help (either format), it's easy to browse too, since all you do is push the forward button. IOW, you get both topic indexing and easy browsing with little extra effort via packaging.
User avatar
randi
Site Admin
Posts: 7746
Joined: Wed Jul 09, 2003 10:30 pm
Contact:

Post by randi »

I have updated the files slightly with some Amiga Autodoc conventions (Name and Synopsis headings). Everything now has a short description, and per Enjay's suggestion, a one-line prototype has been provided. I like being able to include short comments after each parameter, so the vertical versions are still there. I also fixed a few copy-and-paste errors.
User avatar
Hirogen2
Posts: 2033
Joined: Sat Jul 19, 2003 6:15 am
Graphics Processor: Intel with Vulkan/Metal Support
Location: Central Germany
Contact:

Post by Hirogen2 »

randy wrote:
Hirogen2 wrote:OMG, it's MSDN CSS Style!
Is that bad or good? I like it, but I'm also very used to seeing it. The stylesheet is actually modified from one included with NDoc (which was aptly named MSDN.css).
I dunno. Microsoft's success is the look. (since ... Win2.0 heh or at least W95).

Randy: well, for the look it's good, I do not care. Certain text blocks are "highlighted" per background color to distinguish, it's fine as it is
For what if MS doesnot like using their style? (if they ever got to know... possibly not)

Conclusion: keep it if you like it
User avatar
Enjay
 
 
Posts: 26516
Joined: Tue Jul 15, 2003 4:58 pm
Location: Scotland
Contact:

Post by Enjay »

Revised version - much better IMO. Name and synopsis headings make things clearer, and I like the way you kept the vertical listing and added the short description. I hadn't noticed the "See also" section before. Is that new? It's a good idea anyway.

I forgot to mention before, that I also like the ; being at the end of the synopsis and examples. The number of times I copied and pasted something from the old manual (which did not include the ; ) , forgot to add the ; myself and got a compile error...
User avatar
HotWax
Posts: 10002
Joined: Fri Jul 18, 2003 6:18 pm
Location: Idaho Falls, ID

Post by HotWax »

In the Remarks section of ACS_Suspend:

"Rather from starting at the beginning, it will continue execution at the point where it was suspended."

from should be than.

In the Examples section:

"This example executes a script on a map with levelnum 3."

executes should be suspends.

ACS_Terminate and Autosave have two ACS sections.

In the Synopsis section of Ceiling_LowerByValue (and Ceiling_LowerByValueTimes8):

"// how quickly the ceiling lower"

ceiling should be ceiling(s) (or lower should be lowers).

In the Synopsis section of Ceiling_RaiseByValue (and Ceiling_RaiseByValueTimes8):

"// how quickly the ceiling raise"

ceiling should be ceiling(s) (or raise should be raises).

The example section for Ceiling_RaiseInstant claims that this:

Ceiling_RaiseInstant (1, 0, 4);

is the same as this:

Ceiling_RaiseByValue (1, 32, 4);

The first function will instantly raise the ceiling by 32 units. The second will instantly raise the ceiling 4 units.

The correct function is:

Ceiling_RaiseByValue(1, 256, 32);

In the Remarks section of Ceiling_Raise*:

"Because each sector acts separately, if a ceiling is blocked in one sector, the other sectors will still be able to move their ceilings."

This line seems unnecessary since an upwards-moving ceiling can't be blocked (that I'm aware of), though it doesn't do any harm either.

The speed argument is also not adequately explained in any of the functions in which it is used.

On each of the Light_* pages, there is either no Examples section at all, or there is a section but it is empty.

In the Remarks section of Light_Glow:

"When you use Light_Fade, the sector's current light level is ignored. The glow will always start at upper."

Light_Fade should be Light_Glow.

Line_Horizon has two ACS sections.

Line_Mirror's Synopsis section is lost and needs to be shown the way home.

Line_Mirror's ACS section reads:

"Line_Horizon cannot be used from inside a script. It must be placed on a line. However, you can use SetLineSpecial to place Line_Mirror on a line or remove it as desired while the level is played."

Line_Horizon should be Line_Mirror.

Line_SetIdentification's Example section is empty.

In the Remarks section of Sector_SetColor:

"You can use the testcolor console command to set the color of all sectors that don't already have a custom color so that you can see how different colors look ingame."

Okay, so this is technically true. However, testcolor doesn't support a desaturation value (at least not in 47i), which is a little misleading. Personally I'd rather have the desaturation option added to testcolor than have this line altered to make note that it doesn't support it. :D Of course, since the page also says the desaturate param was added in 2.1.0, maybe I just need to wait . . . .

In the Remarks section for SetPlayerProperty:

"If you use this special inside an open script, then it will always effect all players no matter what value you use for who because open scripts are activated by the world and not any particular player."

effect should be affect.

The Examples section for SetPlayerProperty is empty.

In the Remarks section for Thing_Destroy:

"This specials kills monsters and anything else that takes damage (such as some of the trees in Hexen)."

specials should be special.

The Remarks section of Thing_Projectile and Thing_ProjectileGravity disagree.

Thing_Projectile:

"The box at the back of Heresiarch's Semetary in Hexen (MAP27) uses the Thing_SpawnGravity special to spawn random items and monsters."

Thing_ProjectileGravity:

"The box at the back of Heresiarch's Semetary in Hexen (MAP27) uses this special to spawn random items and monsters."

So which is it? :)

In the Parameters section for Thing_SetGoal:

"If this is 0, then effects the monster that activated it."

effects should be affects.

Thing_SpawnFacing incorrectly uses Thing_Spawn in the Examples section. The examples given wouldn't work as intended using the Thing_Spawn special.

TranslucentLine's Example section is empty.
Post Reply

Return to “ZDoom (and related) News”