Author Topic: How is a person supposed to use and learn Slick-C?  (Read 9798 times)

cgsna@yahoo.com

  • Community Member
  • Posts: 13
  • Hero Points: 0
How is a person supposed to use and learn Slick-C?
« on: January 17, 2007, 10:33:21 PM »
Greetings all,

I had first posted this as a response to the "Slick-C enhancements" post, but pulled it at the last moment, deciding that not to be the appropriate place; it is otherwise intact:

The proposed additions look great.  However, I don't think they will do much for me at this point.  Please read on.

OK, I certainly mean no disrespect to anyone. But you guys seem to actually understand this, and it amazes me to think about just how you might.  I cannot get anywhere with the Slick-C language, due mostly to the extremely limited documentation/help system currently available.  Here are just a few of my complaints:

1.  Only a small percentage of the available commands have example code.
2.  A large percentage of commands show arguments, but then don't go on to explain what those arguments are.
3.  One has no idea what command to use for a given end result without massive, time-consuming, searching.  To understand this, consider "macro functions by category" in the help system.  Then select, say "tagging functions".  You get one very long list.  A huge portion of the items in the list do not do what one might intuitively think they would do given the function name alone.  What am I supposed to do, open up each one of them and read the typically inadequate description that I will find there anyway?
4.  Inconsistencies and/or variances between "prototypes" shown at top of function description and actual usage.

I could go on, but I think that you probably get my point.  Slick-C is way too big and complex to learn by guessing games and trial-and-error alone.  Do you guys have some hidden documentation you are not telling me about?  If not, what is the secret?

Thanks,
Clark

Lisa

  • Senior Community Member
  • Posts: 238
  • Hero Points: 24
  • User-friendly geek-speak translator extraordinaire
Re: How is a person supposed to use and learn Slick-C?
« Reply #1 on: January 18, 2007, 05:01:24 PM »
Slick-C is a lot like C, and therefore, the documentation for Slick-C was written assuming the audience was already familiar with C. But, I understand completely what you mean! I wanted to let you know that we're working on improving the Slick-C guide this year. That should help some. Currently the information seems out of order and is hard to understand.  To get the most out of it, you have to read the whole thing from start to finish a few times. (At least I did - but then, I'm not a programmer, admittedly.)  Improving this information is definitely one of our goals for this year. As for help on commands (Javadoc) - this will be a slower process, as we are improving these entries "as we go," due to - just as you said - the vast quantity of commands that exist. We welcome any and all doc suggestions - if you see a command that doesn't have help, or has "bad help" - let us know and we'll try to get it fixed (docs@slickedit.com).

Best wishes,
Lisa

cgsna@yahoo.com

  • Community Member
  • Posts: 13
  • Hero Points: 0
Re: How is a person supposed to use and learn Slick-C?
« Reply #2 on: January 18, 2007, 05:13:55 PM »
Lisa,

Yes, well, I am quite familiar with C.  It is not the mechanics of the language that concerns me; that seems pretty well covered in the Slick-C pdf file.  It is the vast amount of commands, and how they relate to each other and to the SlickEdit environment.  For example, my first post in here was "traversing subdirectories".  As it turned out, Graeme informed me that one of my subsequent commands was killing my 'find-next' handle returned by a file_match(find_first).  How was I supposed to know that?  Still, to date, I have not found that documented anywhere.

Again, no disrespect -- I am not trying to beat anyone up here.  I will help you improve the docs in any way that I can.

Thanks,
Clark

Lisa

  • Senior Community Member
  • Posts: 238
  • Hero Points: 24
  • User-friendly geek-speak translator extraordinaire
Re: How is a person supposed to use and learn Slick-C?
« Reply #3 on: January 18, 2007, 06:30:24 PM »
You can catch more flies with honey than vinegar - your courteousness is appreciated. I talked to Scott Westfall, our software dev director. Unfortunately, you've got everything we have to give so far. The kind of info you need is the kind of info we want to get into the Slick-C guide. At this point, all we can recommend is to look through our code to see how we've done similar things, and post questions on the forums to get guidance from other users. And, keep an eye out for the aforementioned Slick-C updates. I wish I could provide more help. I hope other users will post with some of their tips and tricks for learning Slick-C!

-Lisa

Graeme

  • Senior Community Member
  • Posts: 2793
  • Hero Points: 347
Re: How is a person supposed to use and learn Slick-C?
« Reply #4 on: January 19, 2007, 11:06:25 AM »
Clark,

The only reason I figured out the problem with file_match was because I was familiar with find-first, find-next on Windows.  The way I see it is that having Slick C source provided is a sort of bonus that you're not really paying for  - sort of like open source software.  I suspect the source for open-source editors like Emacs and JEdit has the same problem - but I've only used Emacs for five minutes so can't say for sure.

I remember struggling to figure out how to use the "ini file" handling functions  - I spent a while trekking through the code to figure it out.  I find Slick's "goto definition" and pop back a huge help with getting to know new code.  I find lots of Slick code hard to follow though and have no clue what it's doing a lot of the time!

If you have maintenance and support, possibly SE support can give you some hints about how to do something.

I should have reported the issues we found with file_match to docs@slickedit.com to get the help file updated (but since Lisa is hopefully reading this I'll post them here...)

1. Having done a file_match with find_first true, you have to do all the file_match calls with find_first false before doing another call with find_first true.
2. The 'T' option does a recursive directory search.
3. If the 'V' option is used, you can't use the string returned by file_match in the next call to file_match.

Graeme


Lisa

  • Senior Community Member
  • Posts: 238
  • Hero Points: 24
  • User-friendly geek-speak translator extraordinaire
Re: How is a person supposed to use and learn Slick-C?
« Reply #5 on: January 19, 2007, 02:34:10 PM »
Got it, Graeme - thank you!

Lisa

  • Senior Community Member
  • Posts: 238
  • Hero Points: 24
  • User-friendly geek-speak translator extraordinaire
Re: How is a person supposed to use and learn Slick-C?
« Reply #6 on: January 19, 2007, 04:23:03 PM »
Clark, I just had a thought that you may find useful an article called "Slick-C Macro Conventions and Best Practices for End Users." It is available in PDF format from our Web site under Support > Documentation > Slick-C. I wasn't sure if you knew about it or not.

FYI to all: we are planning to work this information into the Slick-C guide, but in the meantime, we will be shipping it with SlickEdit 2007 (it will be located in the /docs directory).

-Lisa

cappy2112

  • Community Member
  • Posts: 91
  • Hero Points: 0
Re: How is a person supposed to use and learn Slick-C?
« Reply #7 on: January 20, 2007, 02:01:14 AM »
Clark, I just had a thought that you may find useful an article called "Slick-C Macro Conventions and Best Practices for End Users." It is available in PDF format from our Web site under Support > Documentation > Slick-C. I wasn't sure if you knew about it or not.

FYI to all: we are planning to work this information into the Slick-C guide, but in the meantime, we will be shipping it with SlickEdit 2007 (it will be located in the /docs directory).

-Lisa

Lisa- is Slick 2007 the same as version 12.xxx?

cgsna@yahoo.com

  • Community Member
  • Posts: 13
  • Hero Points: 0
Re: How is a person supposed to use and learn Slick-C?
« Reply #8 on: January 20, 2007, 03:54:04 AM »
Also Graeme, in your listing of 'our' findings for Lisa, you forgot one thing:

_str attrs = file_list_field(filename, DIR_ATTR_COL, DIR_ATTR_WIDTH);

Will kill further usage of a previous file_match(find_first), as it apparently does one of those itself.  This is not documented anywhere.  Of course, this might be readily apparent in the source code for file_list_field(), but at the time I first used this call, I was not even aware that I had the source code at my disposal.

Thanks,
Clark

Graeme

  • Senior Community Member
  • Posts: 2793
  • Hero Points: 347
Re: How is a person supposed to use and learn Slick-C?
« Reply #9 on: January 20, 2007, 04:01:14 AM »
Lisa - I should have said to add to the documentation for file_match, that care has to be taken with what functions  are called whilst doing the find_first, find_next sequence  e.g. calling file_list_field (as Clark was trying to do) doesn't work because file_list_field does a find_first.

[EDIT  - whilst I wrote this post, Clark pointed this out too.]

Clark
I think I have to revise my comments slightly about the slick API documentation.  I think your comments are all valid - I was thinking more of what's involved in customising Slick source.

I suspect if you could give specific examples of what you're trying to do and where the API docs are lacking, SE would at least consider improving the help info at some stage, if it related to things that more than just one or two people were trying to do. 

However I have to qualify this as follows.  I know you gave the example of the problem with file_match  - I think this is mainly in the category of oversight and perhaps a little in the category that the API doc info isn't written with as much discipline as some other APIs (what's the Visual studio customisation API like?).  I suspect very few people actually report problems with the slick docs  - I really think slick help info would benefit from having its own forum here that people can quickly and visibly report problems/ errors to.

You also gave the example of the tagging API.  This API looks hard to use as you say, but I get the feeling there are very few people who would want to use it  - yet SE goes to all the trouble of writing it as Slick C code (instead of C++) and documenting a large number of functions without giving an overview of how to go about using it all, and, as you say, of how it relates to the slickedit environment.  I remember Gary Ash reporting he had difficulties using the tagging API
http://community.slickedit.com/index.php?topic=224.msg852#msg852
and after several weeks  :) , Dennis responded  - but a lot better late than never!

Same goes for the XML API  - there's no overview or complete example of how to create an XML file.  Probably a file like hotfix.e can be used to see how to read an XML file, but from a 5 minute skim through the result of searching for _xmlcfg_ it wasn't obvious to me which code to look at to see how to create a new XML file.  Perhaps someone who is familiar with xml APIs would find it easy.

Regarding missing parameter info  - I guess SE would probably add the missing info eventually if the problem is reported.    Regarding missing examples, maybe SE would consider adding more examples where they're really needed, but these probably take quite a bit of time and I guess SE is only a relatively small company.

So to answer your question, "what's the secret"  - I think most people try to find examples in the existing source and probably spend quite a while doing it sometimes.  Since SE want people to be able to use their API without tearing their hair out, some specific examples of what "typical" people are trying to do and where the docs fail might help.  I'm not sure whether the tagging API would have enough people wanting to use it to justify SE documenting it better  - I'm just guessing though (as I said, they went to all the trouble of "publishing" it. ).

Graeme

cgsna@yahoo.com

  • Community Member
  • Posts: 13
  • Hero Points: 0
Re: How is a person supposed to use and learn Slick-C?
« Reply #10 on: January 20, 2007, 04:07:30 AM »
And also Lisa, I downloaded the document you referred me to.  At this point I have only glossed over it, but yes, it appears that it might prove itself to be very helpful...  Thanks.

Clark

Lisa

  • Senior Community Member
  • Posts: 238
  • Hero Points: 24
  • User-friendly geek-speak translator extraordinaire
Re: How is a person supposed to use and learn Slick-C?
« Reply #11 on: January 22, 2007, 03:09:51 PM »
cappy2112: Yes, SlickEdit 2007 is the same as SlickEdit v12. We've gone with a new naming scheme that is easier to remember.

Graeme & Clark: Got the additional info - thank you!

-Lisa