ReNamer: Making of new manual

narayan · 2009-02-28 19:56

Also, do we have any wish list for the manual?

If not, please add them here. Some typical examples could be-
* Add new topics (specify)
* Expand certain text (explain something in more depth; add examples, etc.)
* Add navigations (hyperlinks, Index, etc.)

den4b · 2009-02-28 22:02

New topics:
* Rules, explanation of each in general and how the entire "rules system" works for modifying filenames.
* Meta tags, but I don't know what there is to write apart from description for each one of them which isn't much.
* Settings, maybe some options require a bit of explanation.
* Files table, extensive right-click menu and additional options including export/import, etc.

Other ideas:
* Some sort of navigation would be really handy, with cross-links.
* Maybe we should keep examples separate?
* Maybe we should not touch PascalScript section for now? (it can get quite scary and huge)

P.S. Don't hesitate to ask me regarding some particular functionality, e.g. what it does, how it does it, and why it does it that way.

narayan · 2009-03-01 05:12

Sure!

@PascalScript cookbook:

I thought it would be useful to collect user-contributed scripts in one place. A user can copy and paste such scripts from the manual.

For example, script to separate words (insert a space before capitalized letters in a name).

So far as pascalscript syntax is concerned, I will just point to some good reference sites.

What do you think?

Last edited by narayan (2009-03-01 05:12)

narayan · 2009-03-01 05:41

Another idea is to create a separate section at the forum only to serve as repository of scripts.

* Each thread should contain only one script.
* The subject line specifies the purpose of the script.
* If anyone posts comments, and if those are accepted, then the script in the first post ITSELF must be edited. (There should not be 2-3 different variants of the same script in the thread).

prologician · 2009-03-01 08:05

I hope I'm not intruding by putting forth some thoughts on the PascalScript stuff....

One point in the current manual which I feel is lacking, is the table listing various available PascalScript functions. Now, I recognize that being fully comprehensive and listing ALL functions would be much too big for this manual.... that's what something like Delphi Basics is for (sorta, since Delphi != PascalScript).

But it's always been bothering me how many of the functions are merely listed, but given no description as to what they actually do. Even one or two sentences would make things clearer.

The other big thing is that, from that table, you get the illusion that functions are only for specific types.... ie, that Ord() operates ONLY on chars, and ONLY spits out bytes (in fact, it can take in more than that... I myself have utilized its ability to take in WideChars, and get numerical, integer-sized values.... the return value need not be limited to the 0-255 range).

Just a few of my thoughts.... take it or leave it.

report · 2009-03-01 08:23

I like the idea to have a database of working scripts. Therefore I have made a first preliminary step of collecting all the AlphaSerialize scripts.

narayan · 2009-03-01 10:44

prologician,

You are right. Thinking ahead from that point, how should we deal with it? BTW since I won't be able to write in PascalScript, you experts would have to provide the actual stuff (or point to a good source that is not someone else's IP.)

Thanks!

prologician · 2009-03-01 21:01

Well, one thought which comes to mind, is to do something similar to how the Java SDK handles it, as well as a number of SDK documents. Give the function with whatever parameters it takes, indicate what it returns (if it's a function. If it's a procedure, then that would be an empty field), and a one-liner that describes what it does. It shouldn't be TOO hard to adapt the Delphi Basics website information to this purpose... the inherent danger is then propagating information which is incorrect for PascalScript (ie, PascalScript doesn't allow the use of pointers, even though it's perfectly legal in Delphi).

As a different SDK which I use regularly, take a look at the Ruby Doc. A few thoughts to give some sense as to what might be nice to see in a PascalScript doc.

There is also the issue of the overloading of functions.... and I kinda like how Delphi Basics has it. Basically, if there are types X, Y, and Z which a function can take, and they all cause the function to return the same type W, then they're all listed under the same prototype. (See Ord() as an example). It'll make things more compact, without making it ambiguous as to what a function should spit out. (Java's doc lists every variant individually, so it's kinda verbose. And the issue is a moot point in Ruby, since Ruby is duck typed.)

narayan · 2009-03-02 03:33

But then the basic interpretation and syntax of Pascalscript's "standard" commands (including the overloading property) should already be available somewhere on the net. So there is no need to list all the commands or explain them. I will need to point to the appropriate URL.

Only the locally defined functions need to be explained in the manual. Also, if ReNamer is using some of the commands in a special way, then we need to explain that.

What do you think?

Last edited by narayan (2009-03-02 03:46)

narayan · 2009-03-02 03:57

I realized that I will need to build at least some nodding acquaintance with PascalScript, to do justice to the script-related text in the manual.

So I set out to find a good resource by Googling for it.
Although I found multiple hits, unfortunately they seem to be talking of diverse things.

Here are two hits that look most promising to a PascalScript newbie like me:
http://www.remobjects.com/ps.aspx
http://wiki.freepascal.org/Pascal_Script

Then there is this:
http://www.dreamcompany.com/dscriptdesc.html
It adds two more terms: Delphi Script and Object Pascal

Wikipedia does not even mention PascalScript or "Pascal Script".

To sum up, I am unable to find THE PascalScript that is used in ReNamer.

So I will need some pointers to PascalScript documentation AND tutorials from the PascalScript experts.

Last edited by narayan (2009-03-02 04:11)

den4b Forum

#11 2009-02-28 19:56

Re: ReNamer: Making of new manual

#12 2009-02-28 22:02

Re: ReNamer: Making of new manual

#13 2009-03-01 05:12

Re: ReNamer: Making of new manual

#14 2009-03-01 05:41

Re: ReNamer: Making of new manual

#15 2009-03-01 08:05

Re: ReNamer: Making of new manual

#16 2009-03-01 08:23

Re: ReNamer: Making of new manual

#17 2009-03-01 10:44

Re: ReNamer: Making of new manual

#18 2009-03-01 21:01

Re: ReNamer: Making of new manual

#19 2009-03-02 03:33

Re: ReNamer: Making of new manual

#20 2009-03-02 03:57

Re: ReNamer: Making of new manual

Board footer