stringtable tutorial

[macguba]

Here is the first draft of a simple stringtable tute.     I haven't tarted it up yet, what I'm interested in at present is facts.     Any howling errors?   Have I missed anything useful?

An example stringtable is included.

And yes, there is a stringtable tutorial already in the Ed Depot but it is very old and has been described as "a bit like describing New Jersey to someone living on the Sun".

Many thanks.


Edit 19 Nov - New version up (0.2)

Edit 21 Nov - New version up (0.3)

Edit 23 Sep 06 - New version up (0.5 recovered)


[attachment deleted by admin]

[klavan]

It's a good tute.
You should add that the mission maker can isert comments by adding a ; before the line. I find it usefull for organize the stringtable in sections, to avoid confusion between strings, like this example:

Code: [Select]

;----Intro-----
STRN_Int1,"Introduction","Introduzione"

;----Outro----
STRN_Out1,"Mission end","Missione finita"

Klavan


EDIT
Never mind me: after looking at the template file you've included I realized that they're useless!
It's a very good tute!  ;D

[macguba]

Yes stringtable is the "other way around" compared to script files.   Only stuff that is specifically called - that is, the stuff starting STR - matters.   You can chuck in anything else you want.  In fact you can chuck in stuff starting with STR as long as you don't call it.

[Mikero]

I would strongly recommend you delete all mention of Micro$oft Excell except to point out not to use it

That )(&*)#(@@)(_$#@ program is the single reason why people are finding this incredibly straightforward file so difficult to understand.

The *best* method is to simply., and, I mean ,simply, use notepad and organise each value in TAB space columns, just as $#@)(&)($#@ Excell tries to do and makes such a $#)(*_##$_+ MESS OF.

There is a total misperception out there that stringtable.csv is a micro$soft inspired device. These files, this format, has been around the industry since the year dot.

sorry for the flame'ish manner Mac, that's not intended, but that $#_*_#$ program has caused 90% of the problems.
----

Other comment is that there are (now) two reasons for using csv

first is the obvious, it is the easiest by far manner to allow translations.

but the 2nd, and nowadays critical reason for using csv is that all strings can be in one place. In the 'good old days' where we were lucky to get a mission that lasted longer than 2 minutes, it didn't matter muchly. Nowadays, with upwards of thirty script files used in some missions to say nothing of separate folders, it's essential, to look in one place only.

[Fragorl]

So that's how it's done! Cheers mac

As for setting all the scripts' paths and such, I normally reserve that as the init.sqs 's prerogative. Actually, I never thought to look for paths and names in the string table before, but I guess it's possible to define them there. Is it a good idea though? Also - what is wrong with excel for stringtable editing?

[klavan]

Here's another syntax example with the localize command you could add:

hint format [localize "STRN_Stat_1", _value1,_value2]

The string should appear as something like:

STRN_Stat_1,"The variables values are %1 and %2","I valori delle variabili sono %1 e %2"

In addiction you could add that with the stringtable you can define the markers name too, by adding @STRN_StringMarkerName1 in the text field of the marker in the mission editor.

Klavan

[macguba]

@mikero - I've already edited it to make these two benefits clearer.  As for Excel, you're probably right ... however that's what I use and once I'd got over the little foibles I found it very easy.   However I will rebalance the text on this point.     And as for the flamish manner ... well I'd expect nothing else.  ;D

I don't understand what you mean about tab space columns though.  I thought the whole point was that things were seperated by commas?

@Fragorl, yes I suppose you could put script paths in there and then get them out, but that's too advanced for me and this tute.  This is just to get you started.

@klavan, thanks for that, it's going in.

More examples welcome.

[macguba]

New version (0.2) up, comments welcome.      Grab it from the first post.

@mikero, I nicked all the main points from your tute and added you as joint author.     Assuming you're happy with that concept, please make any edits you want.   If not then I apologise for my presumption and I'll make you an acknowledgement.    (Which reminds me, I forgot to put klavan in.... done for next version.)

I don't understand the part about the first non-space character defining the text.   I had no trouble making an entry which started with a long line of spaces.   What am I missing?  In Notepad the entry looks like this

STR_OUTRO_14,                      Judge Roy Bean,                      Judge Roy Bean,                      Giudice Roy Bean,                                        Juez Roy Bean,                      Judge Roy Bean,                      Sêdzia Roy Bean,

and the spaces were picked up (via description.ext) and displayed - if that's the right word - on the screen.    I've never used .csv except in Excel, which is probably why I find using Notepad difficult.

[Mikero]

>I don't understand what you mean about tab space columns though.  I thought the whole point was that things were seperated by commas?

they are separated by commas. however, further to that, whitespace is stripped in the following manner

,"this is a text",
,       this is a text        ,

are identical. Therefore, the same results in notepad are generally achieved as Excel (eg) example

STR1,         English           ,  Pongolian
STR999,     More English  ,  More Pongolian
----
although often used, I have never seen a csv that requires quotes except in the rare instance of making commas transparent in text.
----
you can also have NO phrasing btwn commas. Even truncated commas (ie not as many as there are languages).

In which case, the engine takes the 2nd 'column' by default. Ie, for lack of any other, it will revert to the default, (English eg). This makes it exceptionally easy for a Hungarian to simply build a csv, in hungarian only and let someone else add to it, another language, when it suits.

Language, Hungarian

STR1, Ook?
STR2, More Ook?

other people can, add English, French, or whatever gives them a thrill. If they don't know a phrase, it doesn't matter, the hungarian will take it's place until it's sorted out.

----
also  comment on comments

ANY text (afaik) is a comment if the 1st three chars on a line don't begin STR. Exception is the 1st line of file (Language)

the reason why STR is a fixed in concrete label is that the engine knows to specifically look in STRingtable.csv as opposed to any other.

But, all in all Mac, I think you should keep the text to absolute basics so that people can grasp it's simplicity. Once they're over that, they can experiment for themselves. the format is exceptionally easy to understand, and very forgiving, if people wish to put complex statements between commans, then, fine, but it will mask the simplicity if you elaborate too much (imho)

[Mikero]

>joint author

absolutely. Best choice. I'll delete my little beast later on. *but* as you know I'm on a holy crusade to make up a series of File Format: topics .

is the bit about spacing cleared up? or do we have a problem. My statments are absolutely for certain cast in concrete garanteed for addons and any classname {} constructs. Sqs files which i know nothin about might be different. Did you actually mean

, "       Judge Roy Bean",

 

[macguba]

I understand what you are saying about spaces, and my gut feel is that you are right.   I'll need to look into that counterexample ... its cut and pasted from the stringtable for Unimpossible and appears in the Loose Outro.

[klavan]

What about an example mission?
Nothing more than some radio triggers.
Klavan

[Mikero]

here is an example for an addon, if mac doesn't want to add 'examples' I'd agree with him but here it is anyway, because it's a typical example of how you can make an addon that a person in Pongolia can use in her language, not yours.

class MyGreatTruck: truck // use bis standard truck
{
 vehicleClass=$STREDITOR_MY_FANTASTIC_ADDONS;
 displayName=$STREditorArmoredTruck;
 armor=200000; // make it bulletproof
};

whatever is in the string for my_fantastic_addons, will be shown in the editor as a group name, for, all, my fantastic addons, in the language of the user, not me.

whatever an armored truck is called in Swahili, can be stated, in the csv for people making missions in Basutoland.

I have deliberately shown two distinct StylesOfLabelling.
---
Mac, the tute as it stands, is great. I love my name in lights, where you do all the work ;D

[456820]

i dont really feel like reading this all but you say the mission name should be put straigt nto the intel box but it can still be done using a stringtable IIRC BIS missions use it with the stringtable
anyway since im not in a paticular reading mood ill read through it a different time

but good idea i have often tryed to avoid stringtable.csv mainly becuase i didnt understand them

[klavan]

@456
I've made several attempts in doing so, but I've always failed. Seems like OFP doesn't recognize this. I currently run OFP with italian language, but all the missions appears with their english title, even (if my memory doesn't betrays me) they're defined in the .csv.  
Klavan

[macguba]

I never managed to make it work with the mission name, I suspect because I only checked campaign missions.  I've just looked at acouple of single missions and sure enough, they use the @ spell.    However, from what you say klavan, I'll have to test it and see if it really works.   Thanks for the heads up 456.

I thought about an example mission and although in general I'm a huge fan, in this case I'm not so sure.    It involves a whole description.ext, and remember this is a basic tute - half the people who read it won't have worked out description.ext yet, and I don't want to confuse them or put them off.

One thing bothers me.   If stringtable really is a simple little file, how come writing the tute is such a big job?  

Precisely.

[klavan]

@mac
I've made the same thoughts about an eventual mission yesterday evening, and i came with the same conclusion: the risk to add confision to a (potentially) already confused newbie is high.

One thing bothers me.  If stringtable really is a simple little file, how come writing the tute is such a big job?

I think you've got it. The tute is clear for me (well, i already know what's a stringtable), well written and totally understandable. Better to avoid to fill it with lots of additional info: for example you could add that with the stringtable you can change the default name's of the groups in OFP, but for me it's better to let the neo mission maker to search a specific tute for this, after he will be able to handle the basic functions of the .csv.
Klavan

[macguba]

New and hopefully final version up in the first post.    I've added a very simple demo mission, without a description.ext.   This seems to be to be the least of several evils but I'm open to opionions.

It does work in the name field - use @.

[Mikero]

Just before you start mentioning columns in a majorly way, say this:

The contents of a stringable are separated into columns. A column is defined by a comma. In Excel, this is done automatically for you, and the comma is hidden.


@Anything

$Anththing

@ is a little dangerous as it will treat certain characters inside the string in a special manner. For a wannabe just-get-the-bloody-thing working newbie they're better off with $

>Do not use quotation marks in the stringtable unless you want to them to appear on the screen

this is WRONG. This is an invention of $#@_)*_)*$@_ Excel

quotes are stripped and are absolutely necessary to disguise commas

#$*&)()$#@$@0 Excel Actually inserts """ anything """

You are disguising and writing a tutorial for Excel, not, for stringtable csv

[macguba]

Just before you start mentioning columns in a majorly way, say this:

The contents of a stringable are separated into columns. A column is defined by a comma. In Excel, this is done automatically for you, and the comma is hidden.

Done.

@ is a little dangerous as it will treat certain characters inside the string in a special manner. For a wannabe just-get-the-bloody-thing working newbie they're better off with $

$ doesn't work - I've checked.   You have to use @ for markers and the mission name.   However I will add a warning about @.

>Do not use quotation marks in the stringtable unless you want to them to appear on the screen

this is WRONG. This is an invention of $#@_)*_)*$@_ Excel

quotes are stripped and are absolutely necessary to disguise commas

We need to get this bit clear.    My underlying point (which I will rewrite) is that as a rule you do not put quotes in stringtable.   When you do, it is in special circumstances.  

One circumstance is when you want the quotation marks to appear on the screen.   In Excel, you put one set of quotes in the cell and one set of quotes appear on the screen.    When I look at the file in Notepad, I see it has 3 sets of quotation markes to make one set appear on the screen

Screen             Excel cell               Notepad

"test"                "test"                  """test"""
here, test         here, test             "here, test"

(I had forgotten it, but I first encountered .csv format 20 years ago and comprehending it was well beyond my intellectual capacity.   Nothing has changed.  *sigh*)

What do you use two sets of quotes for?   Are there other similar things we should mention?


Is the following true?

Leading and trailing spaces are stripped out in .csv format.   In other words:-
,            test       ,    == ,test,

You are disguising and writing a tutorial for Excel, not, for stringtable csv

Yes I know, that's why I need your advice.  

[Mikero]

in any csv file (for flashpoint) the following are identical and synonomous

,"Hello there",

Hello there

the engine itself strips and ignores the "

In point of fact it is a 'good habit' (tm) for a user to write quotes around strings

"this", "that", "the other"

This because there are instances when the characters betwen quotes are literal and not to be interpreted. Some examples

,"Morning Captain, what news?",

,"     Intentional space indent",

,"Well here's a %%% funny one",

last example to avoid % being interpreted

$STR_BriefingName is valid (and I assume @STR_Name too).

[Mikero]

Excel writes

|     marbles|

as

, "   marbles",

hence it *appears* leading space is signficant when it is not.

[Mikero]

How does this sound Mac?



Quote characters are treated in a special manner as an escape literal. All text up to the next quote is not to be interpreted in any way. Thus any leading or trailing space between quotes is not filtered out, a comma is not treated as an end of field, and the % characters are not interpreted as such. The text between quotes appears literally on the screen (without the quotes).

To actually embedd a real, genuine, literal quote, the same rules apply

""" means interpret the single quote, between quotes, as a literal and display it!



<phew>

[macguba]

Perhaps

$STR_BriefingName

should work, but it doesn't.    At least not for me, neither for mission name nor markers.




I still have a long way to go but I have found a website which has helped me understand why I find csv so fiendishly difficult to comprehend.

http://www.creativyst.com/Doc/Articles/CSV/CSV01.htm

I've only read it twice so I don't yet fully understand what's what, but I at least I have worked out what at the is at the bottom of my confusion.   (I hope.)  Everybody says that in .csv format values are separated by commas.   This is false.    Commas do not separate values.    They are merely used[/b] in separating values.   They are a flag, if you like:  a warning that you might be at a new value.  

Now that I've realised that, I can figure out what does separate values.  

Edit:  actually no, first I have to figure out the definition of what constitues a valid value.

Edit: actually no, what I really have to do is figure out what the commands are in csv


Notes to self (somebody tell me if any of these are wrong)

• The value separator is a comma preceded in the whole document by an even number (including zero) of double quotation mark characters.  It returns nothing.
• "x where x is any character other than " returns nothing.  Means

1) this is the start/end of a value or
2) a command character within the current value will follow either immediately or later and it is simply to be returned without carrying out the command

• "" returns " providing it is preceded within the value by " otherwise it is invalid.  
• A space character returns

1) space if it is within a value or
2) nothing if it is outside a value

• The start and end of a value is defined with one of the following

1) "
2) any alphanumeric character
3) most punctuation but not a comma
4) """

• "" at the start of a value is not valid unless followed immediately by "
• There are five types of character in a .csv file.   All characters belong to more than one type.  

A character may

1) return itself
      - autonomously (e.g. ordinary alphanumeric)
      - in association with command characters (e.g. one " from a set of "; non-separator comma, space)
      - because it is a command which returns itself as well as doing its command job (e.g. first or last characters in a value)

2) return nothing
      - because it is a command (e.g. separator comma, some ") which returns nothing
      - because it is a space outside a value

• There are subtleties involving @ but I have not yet encountered these
• Ditto %

(The source of the difficulty is becoming ever clearer.   Nobody ever defines what characters mean:  they only tell you how to do certain things.   This was particularly true at my last run in with .csv.   Isn't it funny how certain things - such as this file format - totally corrupt the normal way of doing things?    Actually to call it a file format is itself almost misleading:  it is a coding language.    .csv is not a simple format:  it is a complex one.  So complex, that people shy away from attempting to describe it.    Instead they describe things you can do in it.   Which is like trying to explain swimming to a Martian without telling him what water is.)


This is good.  Making real progress here.

[i.Q]

i am not sure if you aware of this.

it seems that stringtable reference can be used for any string.
i only tested main config - not missions.
yet you can do some very nice things with this  

also by Komuna
But you can put functions in a string table!
and do something like:
player call (localize "$MY_FUNCTION")

like
well think about the basic idea of the stringtable
have different configuration by the language setting
you could make easy ofp, realism ofp, action ofp - by choosing the corresponding "language"
or even some performance settings.

example
STR_DN_M1A1_WEAPON,Gun105,,,,,,
STR_DN_M1A1_AMMO1,Heat105,,,,,,
STR_DN_M1A1_AMMO2,Shell105,,,,,,

 
weapons[]={$STR_DN_M1A1_WEAPON,"MachineGun12_7"};
magazines[]={$STR_DN_M1A1_AMMO1,$STR_DN_M1A1_AMMO2,"MachineGun12_7"};
m1a1 does have m60 weaponry

[h-]

What I would be interested in knowing is about that functions stored in the stringtable idea...
Mainly, would it be more effective to use that instead of preprocessFile/loadFile?

[Mikero]

In offline discussions with MacGuba, where we agreed he could poke my left eye out, if I could pull both his ears down to his kneecaps, I've realised (now) that we have in fact two separate 'documents'

this, is a discussion on a TUTORIAL, as in Howto

the following reference is a submission to ed depot on the FILE FORMAT of csv and really is chalk and cheese.

http://www.ofpec.com/editors/resource_view.php?id=913

Originally Mac & I assumed we'd merge the 'same' writeups into a common one. I don't believe that was in fact a correct assumption.

If anyone believes _that_ document needs further discussion/revision, I'll open a separate thread.

[macguba]

Yes I think you've hit the nail on the head.

[h-]

the reason why STR is a fixed in concrete label is that the engine knows to specifically look in STRingtable.csv as opposed to any other.

This is actually not entirely true.. At least when using localize (haven't tested $ or @ yet)..

If you use stringtable.csv in an AddOn .pbo it gets loaded when OFP starts (ok, if it's in a mod folder that's not 'selected' then it will not) and you can then refer to the strings in it without the STR_..

For example in the new MCAR Engine we have an entry in the stringtable:

Code: [Select]

MCAR_getLD,"if(canMove _this)then{[_this] call(localize ""MCAR_getLaunch"")}else{[_this] call(localize ""MCAR_noCrewInHumvee"")}",gets gamelogics position and direction

which is called in a script with:

Code: [Select]

_ammo = _shooter call (localize "MCAR_getLD")
Same goes for the config.cpp, we call an stringtable entry in an eventhandler:

Code: [Select]

init = "[_this select 0] call (localize ""MCAR_createProxyAT"");
I then made an small test addon with stringtable in it and used a trigger in a mission to localize it and it worked, without the STR_...

But strintable.csv in missions are a different matter..

[bdfy85]

* Schools of thought ...
mikero - Don't use Excel.   That &*)#@_($£! program is the single reason why people are finding this incredibly straightforward file so difficult to understand.  The best method is simply to use Notepad.
macguba - I'm a spreadsheet man myself.
Just use whatever you find easiest.

By default in windows csv files associated with MS Excel. THat's why most people tries to edit *.csv in Excel first.  But Excel 2003 (I do not have other versions at the moment ) adds extra commas to the every line of csv (but you can't see  these commas in Excel ) after saving.  After this stringtable won't be recognized by game and user don't see any errors.
This "bug" is ultimate trouble maker for users. At flashpoint.ru I see newbie questions about this routinely.
Thus IMHO the best idea for a tute is to prohibit user from using Excel.

[Planck]

Yes, junk the Excel.   ;D

Just use NotePad folks......you know it makes sense.


Planck

[nominesine]

An example stringtable is included.

Where is it?

[macguba]

I suspect when we moved forums the attachments were lost.    This probably means that my whole tutorial (including the example) is lost, unless mikero has a copy.   It wasn't quite finished anyway.   

I suffered multiple hardware failures at around the same time as OFPEC and I lost some stuff.  I'll have a look for this, you never know. 

[macguba]

v0.5 attached to the first post in this thread and also here.   (It's a very small file.)  I found a version called 0.4, deleted a weird file that had appeared in it, changed the date and relegated mikero from joint author to an acknowedgement (he'd be appalled to be associated with a crock like this  ), zipped it and here it is.    I don't propose to do any more work on it in the near future, I don't have time.    However, it looks nearly finished to me.    Comments welcome - I suppose I'll finish it one day, or morelikely update for ArmA.

[SniperAndy]

Thanks a million for this tutorial.
I have been looking to get my radio messages etc organised in a stringtbale for a while now. Just didn't find a good tutorial in the past that made it clear to me on how I would have to define it in the editor so the hint or message is called form the entry in the stringtable.

I will give this a swing later today, thanks again OFPEC "111!" as usual... :thumbsup: