SDK Docs

[RedBull]

Okay, i have to say these Docs suck!..

1) Please at least make a nice PDF version of the SDK docs (ala LScript)
**** i'll rewrite them with the help of the LW-P crew.... If need be...
(Iv'e already converted the HTML docs, to my own PDF's)
Just so i can do searches for Keywords..

2)As far as i can see for the most part, most of the docs and examples have not been updated really since LW6. and not much at all since Ernie has left.

3)Currently their are pages missing, and incorrect links, like typedef.html....
which is there, but is actually named structs.html, there are also other linking inconsistancies... within the docs...

4)Since LW6, SDK updates have made their way to their own html files
listing the differences or updates in each revision. i.e 6.5.html, 6.5.html,
7.0html, etc....

With LW 8.21, NT decided to add all the changes to the 8.21 addendum (PDF)
(which were all apparently new features in 8.01, but never mentioned anywhere)

So for the most part, most programmers would be unaware of these changes,
and i would like to see these changes added to a 8.21 or 8.3.html file....
(to make it consistant, with all previous versions)

Programming C plugins for LW is hard enough without having to keep track of these documentation mistakes, and QA issues. Please improve NT....

5) The LW SDK also includes a directory for Lscript called.... Eg.
C:\Lightwave83\SDK\html\lscript\
This directory contains Bob's old Lscript docs..... And 2x PDF documents....

The documents are, UserGuide.PDF, and Reference.PDF....
Both of which, contain nothing but a Title Page, and are 295K each....

The Real Docs, must be downloaded from the Website, and even that is almost impossible to find, (I did google and NT searches, and still could not find the current link) NT's searches managed to produce, useless removed link, after another.

Just to confuse users, these docs are called, LscriptUserGuide and Lscript Reference.PDF.. Shouldn't we remove the useless 1 page .pdf's (included in the updates) and replace them with the actual (several MB) versions which are actually usefull. And hard to find on the website?

Really the LScript Docs, are excellent, and i'd love to see NT improve the C SDK
docs to the same standard...

[Chuck]

Hi, Scott!

I'll bring your message to the attention of the Documentation writer and the Dev team, and see if they can give you an update on what's being done to address these issues. I know the issue regarding the "one-page" pdf files on the CD has been previously reported (by me oddly enough; we had the same erroneous files on the web site, took quite a bit of searching to turn up the actual files and in the process I noted they were not correct on the CD and reported that to the dev team); not sure if it got corrected on the most recent version of the program CD, but I'll see what I can find out.

We've done a makeover on the LightWave section, and the left side menu now has a "Developer" link that goes to the SDK docs. I also spec'd changes to the Developer page this morning (and the web team implemented in under an hour) to include the LScript links, so those are now just one link from the main LightWave home page.

The LScript Docs are being updated, so there should be new PDFs before long.

Thanks for your feedback! I'll get additional info posted as quickly as I find out the info.

[Dodgy]

The LScript Docs are being updated, so there should be new PDFs before long.



Yippee!

Any news on updates to lscript itself? Not really been much in the way of announcements as far as that's concerned. I expect you've all been bustling away behind the scenes, but it's been very quiet on the stage so to speak...

[Silkrooster]

Chuck,
Do you have a time frame on the docs yet, or will be be available same time as an upgrade? Just curious, as I love hearing progress reports.
Silk

[Chuck]

Apologies, no time frame info I can provide on the new docs.

I've done an install from the 8.3 version Program CD, and the proper LScript PDFs are indeed present in the SDK folder following the installation, so that issue is corrected.

[Lightwolf]

1) Please at least make a nice PDF version of the SDK docs (ala LScript)
**** i'll rewrite them with the help of the LW-P crew.... If need be...
(Iv'e already converted the HTML docs, to my own PDF's)
Just so i can do searches for Keywords...
I've converted them (7.5) to a MS Help file (which is a breeze from the HTMLs) and would gladly do so for the 8.3 docs and provide them to NT.
I find it to be a bit easier to handle on a PC, and it provdes full text search as well.
Incidentally, Dstorm in Japan has offered the SDK docs (in Japanese) as a MS help file for some time now.

But I agree, the SDK docs need an upgrade badly to cover all the changes since 7.5, including a decent changelog.


Really the LScript Docs, are excellent, and i'd love to see NT improve the C SDK
docs to the same standard...
Ouch... please no. I quite like the way the SDK docs are if they were complete (and optionally offered as a chm and may be PDF, but only optionally).
I think a PDF is bad enough to search or organize docs, I'm not sure if there is something compareable to a MS help file on the Mac side of the world though...

Cheers,
Mike

[RedBull]

Hi, Scott!

The LScript Docs are being updated, so there should be new PDFs before long.

Thanks for your feedback! I'll get additional info posted as quickly as I find out the info.

Thanks for the update Chuck, i do appreciate the efforts, i know NT are moving
forwards in these areas.

And i know in terms of production, Docs are considered the lowest of priorities...

I agree with you Lightwolf, Ernies SDK docs are really usefull....
But in comparison to the documentation, bob's HTML Lscript notes, together
with the PDF Lscript docs, really i think the C SDK could be far better organized.

Anyway, I appreciate the feedback. Thanks!

[Lightwolf]

I agree with you Lightwolf, Ernies SDK docs are really usefull....
But in comparison to the documentation, bob's HTML Lscript notes, together
with the PDF Lscript docs, really i think the C SDK could be far better organized.

Not wanting to start an argument here... but ... ;)
The HTML LScript notes are a complete mess, sorted by release and not by functionality (allthough it would be nice in the SDK docs to note in the function descriptions at what release they were added).
The PDF LScript docs aren't much better, I see no clear diferentiation between language features and the API, and having it spread across two documents doesn't help me much either.
I tried LScript a couple of times, but found in the end that, even though I need to compile, the SDK route seems to be quicker for me to get my plugins done. Then again, that might just be me ;) LScript can be a huge mess because you never know which part of the documentation to rely on, which can be quite frustrating when you get one (meaningless) error after the other.

I have to say that help file I created helped me a lot, I keep it open all the time, it is one document, it contains the samples as well and I can tuck it away by just minimizing it.

Cheers,
Mike

[Lynx3d]

I'm also the kind of person who didn't find the LScript docs very usefull, but finds the SDK to be very logically structured. So i didn't really touch LScript again after my first "hello world"-style C-programs, although i knew nothing technical about C yet, let alone how dynamic linked libraries work...but most of my ideas are near or beyond the limits if LScript these days anyway...

Sure, the SDK does NOT teach you C, it clearly is a reference, no textbook. If you don't understand the structure of the SDK (which i have to admit can take a bit) you most likely haven't understood how Lightwave actually works.
But of course things can still be improved...

And yes, the SDK needs maintenance, in the latest version just a new broken link occured, the PolygonHandler class link is wrong now (and i happen to write one of those plugins currently), and please, what happened to those usefull change logs telling you which global versions were bumped, and what members are new?
This is very important stuff when you plan to write a plugin that should not only work with the latest version (but that's probably what Newtek wants to achieve amyway...?)
Often enough the comments in the headers tell you more about new features than the SDK...the 8.3_addendum.pdf doesn't even contain the word SDK...the only place i found the 8.3 changes is the readme that is basicaly a copy of the infos from the download page.

[RedBull]

And yes, the SDK needs maintenance, in the latest version just a new broken link occured, the PolygonHandler class link is wrong now (and i happen to write one of those plugins currently), and please, what happened to those usefull change logs telling you which global versions were bumped, and what members are new?
This is very important stuff when you plan to write a plugin that should not only work with the latest version (but that's probably what Newtek wants to achieve amyway...?)
Often enough the comments in the headers tell you more about new features than the SDK...the 8.3_addendum.pdf doesn't even contain the word SDK...the only place i found the 8.3 changes is the readme that is basicaly a copy of the infos from the download page.

Yep i understand peoples problems with the Lscript stuff, but really, LScript is
far more literal, and their are many more free and open source code examples,
and i think the HTML progress of Lscript together with the PDF's gives you enough
to work most things out quickly, LSCommander is another thing..

When you combine these things, together a quick keyword search for "file" or "parse" and bingo, it shows the syntax and usually a quick example.....

And of course Lscript returns a specific line error, to quicky fix mistakes,
no need for a recompile just to add a semicolon... :)

Tom Winnicki and Lernie both had sites, full of excellent LScript examples...
And Bob always gave excellent feedback on the LScript list.....

Bob also used to release Lscript updates independantly of LW, and would
have a bug fixed, within a day or two.

(Note: None of those sites are still around, and I'm not sure who's
doing the lead Lscript development) (didn't Jay just get that job?)

Really for an internally based language, (ie not python or perl) It's very
well supported.. IMO... Lscript limitations for myself are speed and access....
not documentation...... (Bob did an exceptionl job of expanding and building
Lscript from a ARexx and beyond)

However, without Ernie, Carl, and Marvin..... I would not of been able
to really make any C plugins.

Anyway i believe NT are working on improving the LScript docs,
for the massess already, this was just a suggestion for the SDK
to improve in the same way....

On a side note: Lynx i noticed you use DevC++, I think you mentioned a bug
with the templates in the tutorial, It is actually a bug, (should be fixed next version) but you can manually edit the templated files, (and change the cpp to c)
(DevC makes the C template a C++ template) I perfer to use a template then a library. Thought you may want to know...


PS Lightwolf, that .chm looks very handy.....

[Lightwolf]

PS Lightwolf, that .chm looks very handy.....
Believe me, it is. I use it _all_ the time.
I just wish I was allowed to distribute it because many others could profit from it.

BTW, I still think the SDK documentation is grand, but as was mentioned before, it is just an API documenation. Language or system specifics don't really belong there (except may be the basics to get the compiler going).
Actually, I think DStorm even have a MSVC add-in that creates plugin skeletons.
What the SDK requires you to do is to really look at the sample code, but unlike LScript there is sample code for just about any global and plugin class (even though it doesn't cover all surprises you may encounter).
I also think the basics in the SDK docs are pretty much up to par compared to other vendors, even more concise in areas (but the SDK Docs have sadly not got much attention during 8.x).

Cheers,
Mike

[RedBull]

Believe me, it is. I use it _all_ the time.
I just wish I was allowed to distribute it because many others could profit from it.

BTW, I still think the SDK documentation is grand, but as was mentioned before, it is just an API documenation. Language or system specifics don't really belong there (except may be the basics to get the compiler going).
Actually, I think DStorm even have a MSVC add-in that creates plugin skeletons.
What the SDK requires you to do is to really look at the sample code, but unlike LScript there is sample code for just about any global and plugin class (even though it doesn't cover all surprises you may encounter).
I also think the basics in the SDK docs are pretty much up to par compared to other vendors, even more concise in areas (but the SDK Docs have sadly not got much attention during 8.x).

Cheers,
Mike

All i really would like to see is searchable .PDF's (perhaps with bookmarks)
or the .chm would be good enough.... I just made a global PDF which contains
all files except the introduction stuff, and then i made seperate , Globals, Commands, Macros' etc reference..... Which is better than wading through
unlinked html files.... (but i don't have the full version of Acrobat, so i can't add
bookmarks etc..)

An SDKReference.PDF.... With just a little tidy-up and some housecleaning...
is really all that is needed.

For Lscript, I think i'm still using Richard Braks enhanced PDF he made available to NT for LW7..... So i'm not sure really if the current docs are the same, better or worse, than he's version than his improved versions...

But LScript you can almost guess just about any command, as it mimics LW itself.
The SDk however requires an XPanel or activation function, a error handler, etc..
etc..... Searchable docs are more important for myself...

Anyways....back to C.... :)

[Lightwolf]

All i really would like to see is searchable .PDF's (perhaps with bookmarks) or the .chm would be good enough.... I just made a global PDF which contains all files except the introduction stuff, and then i made seperate , Globals, Commands, Macros' etc reference..... Which is better than wading through
unlinked html files....
??? The SDK is linked quite well, except for two or three links that end up on wrong files...
I guess I just loathe Acrobat because it is dog slow and takes ages to start up ;)

But LScript you can almost guess just about any command, as it mimics LW itself.

The main problem I had is that I found myself guessing too much ... and then ended up doing it in C again ;)
Unfortunately both paths (SDK and LScript) are limited in their ways, but you can at least call Commands from the SDK to make up for some of the shortcomings.

The SDk however requires an XPanel or activation function, a error handler, etc..
etc..... Searchable docs are more important for myself...

Absolutely true, C plugins are more work. Then again, once you get into the nitty gritty bits and write something more complex in LScript I find that doing it the C way doesn't add much more time, if at all...
C++ is a good alternative as well, since it allows you to extend the SDK a bit more and make it a lot more comfortable to use.
One of my goals is to co-author a C++ wrapper that basically allows you to generate an empty plugin with one line of code, extending as needed. This is a very different philosophy from LScript though.
In the end, the docs are the least problem (looking at some gaping holes in the SDK ;) ).
Cheers,
Mike

[RedBull]

Absolutely true, C plugins are more work. Then again, once you get into the nitty gritty bits and write something more complex in LScript I find that doing it the C way doesn't add much more time, if at all...
C++ is a good alternative as well, since it allows you to extend the SDK a bit more and make it a lot more comfortable to use.
One of my goals is to co-author a C++ wrapper that basically allows you to generate an empty plugin with one line of code, extending as needed. This is a very different philosophy from LScript though.
In the end, the docs are the least problem (looking at some gaping holes in the SDK ;) ).
Cheers,
Mike

Yeah, i just made a rather complex Lscript, the interface code however i kept
the .lid so it's convertible to C at the touch of a button, so i'm kinda using Lscript as sketchpad really. I can't see why it would be hard to make an Lscript parser
to convert the rest to C.. (it's on my to do list.. :) Really you only need
to copy the variables across anyway.

Graham from Happy Digital has a C++ wrapper and library and it's a great idea..
and i'm sure i'll use that and the modlib more than i currently am.

[Lightwolf]

Yeah, i just made a rather complex Lscript, the interface code however i kept the .lid so it's convertible to C at the touch of a button, so i'm kinda using Lscript as sketchpad really. I can't see why it would be hard to make an Lscript parser
to convert the rest to C.. (it's on my to do list.. :) Really you only need
to copy the variables across anyway.
I wish it was that easy... Once you want to support all quirks in LW it can be tons of work (depending on the type of plugin). Just getting a "load from scene" if your plugin uses reference objects is a pain...
I did have a look a the interface creator, I do prefer my own set of macros though because they handle the positioning for me. Then again, I'm also a great fan of XPanels and probably one of the only fans as well ;)

Graham from Happy Digital has a C++ wrapper and library and it's a great idea..
and i'm sure i'll use that and the modlib more than i currently am.
Oh yeah, his wrapper is great. Some of his concepts will hopefully make it into the wrapper I'm co-developing (LightWrap++). Once I get my current project out of the door I can hopefully push the wrapper again.

Cheers,
Mike

[Lynx3d]

There's not really a way around XPanels anyway if you want to create an interactive modeling plugin, but i like them too...i never really tried setting up panels, although XPanels sometimes won't do what you want, but the concept is nice since Lightwave can embed them etc.
Only the set/get callbacks are somewhat nasty, always have to adjust several functions to add a new input...

There we are back at Lightwrap++, yea i'm really trying to get my current project out of the door too, but somehow i keep converting it to C++ inevitably anyway...strange dilemma, it's faster to code it in C++, but converting the C-file eats up most of the time again...

[Lightwolf]

Only the set/get callbacks are somewhat nasty, always have to adjust several functions to add a new input...

Yeah, I know. Coupled with the loading and saving of settings etc. this can become quite a chore. On of the core issues I'd like to fic with lwpp (LightWrap++)

There we are back at Lightwrap++, yea i'm really trying to get my current project out of the door too, but somehow i keep converting it to C++ inevitably anyway...strange dilemma, it's faster to code it in C++, but converting the C-file eats up most of the time again...
I know. I decided to implement a mini lwpp for my current project, so once I publish it together with HappyLib we should have a decent base to start off from...

But we're digressing ;)

Cheers,
Mike

[MiniFireDragon]

I was digging around for how to use Modlib with the DNA file in the SDK and came across this old link. It appears nothing was ever really done the the SDK docs, or am I mistaken??