The Battle for Wesnoth Wiki - User contributions [en]

SpriteSheetApplicationSAB

2014-03-12T23:24:17Z

Timotei21: Fix the category

{{SoC2014Student}}
[[Category:SoC_Ideas_SpriteSheets2014]]

==Description==
<h4>Aishiko GSOC 2014 SpriteSheets</h4>
My proposal is to take the current functions for drawing sprites and
move it to allow for spritesheets, while hiding any of the changes from
campaign designers. It should allow for the seemless intergration of
spritesheets and allow for a period of conversion from multiple files to
sheets.

==IRC==
Aishiko, Aishiko_laptop

==Questionnaire==
Posted 28 Feb 2014
1) Basics

1.1) Write a small introduction to yourself.

1.2) State your preferred email address.

1.3) If you have chosen a nick for IRC and Wesnoth forums, what is it?

1.4) Why do you want to participate in summer of code?

I'd like to participate in the summer of code for several reasons, and
yes money is one of them. but experience is the biggest one.

1.5) What are you studying, subject, level and school?

I am currently studying computer science (read programming) and networking
technology. I am a Softmore in both, I am a current student at Sandhills
Community College.

1.6) What country are you from, at what time are you most likely to be able to
join IRC?

I currently live on the east coast of the US and can be in IRC pretty
much all day, either at home or school, though if at school there will
be a delay if in class and not lab.

1.7) Do you have other commitments for the summer period ? Do you plan to take
any vacations ? If yes, when.

I have no current commitments that would impact my ability to give GSOC
40 hours a week of work and attention. But if an emergency comes up
I'll find a way to make up the hours.

2) Experience

2.1) What programs/software have you worked on before?

Mostly personal projects and class projects, in C, C++, C#, PHP, Python,
& the Arduino. One of C++ classes was using DarkGTK (yes I know its
windows only) but we used SpriteSheets, sprite collision, and mouse interaction.

2.2) Have you developed software in a team environment before? (As opposed to
hacking on something on your own)

I have in a class environment, but I'm usually the only one left doing
the heavy lifting of coding. Though next year I'll be doing the
programming capstone class where the class of 1-20 students work
together to produce a program for a client, either for the college or
for a community member/business. I'm both looking forward to and
dreading working on a team, wondering if I'll be able to fit in and
create code that is easy to maintain and follow.

2.3) Have you participated to the Google Summer of Code before? As a mentor or a
student? In what project? Were you successful? If not, why?

I applied last year, however, I wasn't choosen mostly because I lack
good writing skills for technical documents. At least that is what I
was told.

2.4) Are you already involved with any open source development projects? If yes,
please describe the project and the scope of your involvement.

None, I have submitted patches to the linux kernel but, I never
bothered to see if they made it in.

2.5) Gaming experience - Are you a gamer?

Sometimes, depends on my mood.

2.5.1) What type of gamer are you?

Casual.

2.5.2) What type of games?

2.5.3) What type of opponents do you prefer?

AI oppenents, I'm not really into the whole competetive thing.

2.5.4) Are you more interested in story or gameplay?

I think BOTH have to be there for a successful game.
Though to be honest I'm better at critecing story then gameplay.

2.5.5) Have you played Wesnoth? If so, tell us roughly for how long and whether
you lean towards single player or multiplayer.

We do not plan to favor Wesnoth players as such, but some particular projects
require a good feeling for the game which is hard to get without having played
intensively.

I've played Wesnoth for a year or 2, and I play exclusively single player.

2.6) If you have contributed any patches to Wesnoth, please list them below. You
can also list patches that have been submitted but not committed yet and patches
that have not been specifically written for GSoC. If you have gained commit
access to our repository (during the evaluation period or earlier) please state
so.
commit 5594aeec32d8c8e59c3f3241fbbb68ce9e862474 2/3/2014

3) Communication skills

3.1) Though most of our developers are not native English speakers, English is
the project's working language. Describe your fluency level in written English.

3.2) What spoken languages are you fluent in?

English, I can understand a smattering of other languages but not enough
to do anything deep or programming specific.

3.3) Are you good at interacting with other players? Our developer community is
friendly, but the player community can be a bit rough.

3.4) Do you give constructive advice?

I've been told I do on occasion.

3.5) Do you receive advice well?

I do if its construtive and not attacking. If its yelling, screaming,
and insults as well, not so much. How its given usually impacts how well
I receive it.

3.6) Are you good at sorting useful criticisms from useless ones?

Given enough time yes, but the painfully obvious ones I usually see
right away.

3.7) How autonomous are you when developing ? Would you rather discuss
intensively changes and not start coding until you know what you want to do or
would you rather code a proof of concept to "see how it turn out", taking the
risk of having it thrown away if it doesn't match what the project want

I'm usually fairly autonomous, once the design has been decided, and
if it doesn't work and needs a change I sometimes seek councel on what
way I should go, but sometimes just go ahead and make the change.
Examples:
1) The flow needs changing as it doesn't work right, usually I'll seek
help figuring it how to change the flow so it does work.
2) An array isn't giving the flexablity needed for a function but a
list will, I implement the list instead. And inform whomever needs to
know that I have done that change.

4) Project

4.1) Did you select a project from our list? If that is the case, what project
did you select? What do you want to especially concentrate on?

I selected one from the list, the implementing the SpriteSheets.
I would like to concentrate on 2 tasks, 1 getting SpriteSheets to just
work in wesnoth, and two, provide a script/tool/utility to allow easy
converting from the old single images to the sheet (assuming certian
naming conventions are followed).

4.2) If you have invented your own project, please describe the project and the
scope.

N/A

4.3) Why did you choose this project?

I chosse it because I understand the concepts behind it, and felt it
was a task that I could handle. It will also force me to learn and
will provide immediate gains to all users when the version that
includes the change is pushed out.

4.4) Include an estimated timeline for your work on the project. Don't forget to
mention special things like "I booked holidays between A and B" and "I got an
exam at ABC and won't be doing much then".

I'm still working out a timeline but I would most likely do a commit
at least weekly. And break out the commits so that similar changes
are only in that commit. Example, comment changes in one, (assuming
no code changes), a converted set of sprites (aka the spritesheet) as
one, and then code making use of it. After checking to make sure that
the spritesheet works, removal of the converted individual sprite image
files.

4.5) Include as much technical detail about your implementation as you can

At this point I think I would take 1 sprite (character) and create a
spritesheet of it, and then test with that one. To allow testing I'd
likely have it check for a spritesheet if it finds one it uses that,
otherwise it uses the individual sprite images, in this way the game
still works, until all the sprites have been turned into spritesheets.

Once I have completed getting a character spritesheet to work, I'd
then move on to the map sprites to spritesheets, again using the same
methodology of check and if it finds a spritesheet use it otherwise,
use the individual images. Though, on the grouping I'm not sure how
I'd do that mordante and I'd have to discuss grouping, since a map can
have any or all of the different tiles, and they are not chained like
the unit/character sprites are, I'd have to group similar tiles together.
Like the water images, shorelines, docks, and water villages, as one.
The fields, human villages and castles in one. Swamp things together,
and so on.

I've heard that some devs think that a spritesheet might cause issues
with larger images that don't fit in a hex, I'll intentional create some
sprite sheets just for testing this purpose. I'll also see about creating
some tests to check and see if the performance gains are really showing up.

4.6) What do you expect to gain from this project?

Experience, learning to work on a team where most actually pull their
own weight and the success of the project as a whole is not on my
shoulders. This is too big a project for me to even think of that!
and I'd not be able to, not in 3 months.

4.7) What would make you stay in the Wesnoth community after the conclusion of
SOC?

Finding that the community is a non-hostile place to contribute, that
individuals are treated with courtsey or the respect they have earned.
That I'm encouraged to help other areas of the code, such as, "Aishi,
the spritesheets work, do you think you could help with the transistion
effects for the map?"

5) Practical considerations

5.1) Are you familiar with any of the following tools or languages?

Git (used for all commits)
I don't get it yet but I'm confident that I can get it.
C++ (language used for all the normal source code)
Its my favourite language and I'm comfortable using the language
and looking up what I don't know and making it work. I'm also not
afraid to ask, for help/documentation if I get stuck.
STL, Boost, Sdl (C++ libraries used by Wesnoth)
I've not, YET. Well I might, I never really looked into where a lib or
function comes from when I use, I'll have to pay a bit more attention
now. But they are no on my documentation read list, I'm confident
that by the time coding begins that I'll be able to leverage them to
obtain results, and be more effienent as I go. Even going back and
making a section more effient if I realize that I over looked a better
tool then I orginally used.
Python (optional, mainly used for tools)
I'm familiar enough to use it, follow it (assuming good coding
conventions are followed).
build environments (eg cmake/scons)
I tend to use cmake and the gcc compiler, basically I use which ever
build environment I have available and if its a new one I look up (via
the man page or the internet) how to use it, and if the defaults
settings don't work to add flags/options to get it to compile.
WML (the wesnoth specific scenario language)
Absolutely none before now, again on my read list
Lua (used in combination with WML to create scenarios)
None but I don't create senarios at this point, and if its only used
in that context, it shouldn't have any barring on the project(s) I'm
interested in doing at this point.

5.2) Which tools do you normally use for development? Why do you use them?
Kate, as its just what I'm used to, I like how it's mimaliztic and
non-intrutsive.
Visual Studio for my C# class because that is what they have to work
in when I turn it in.

5.3) What programming languages are you fluent in?
I'm not sure what you mean by fluent, if you mean know every builtin
function and every conseviable combination of calls, I doubt very many
could claim to be fluent. However if you mean, comfortable, and able
to figure out things you don't knoe, either by looking it up or by
context then C (and its children, C++, C#, Arduino) python, and PHP.
After being fluent in English doesn't mean you know every word or
special rule for the language.

5.4) Would you mind talking with your mentor on telephone / internet phone? We
would like to have a backup way for communications for the case that somehow
emails and IRC do fail. If you are willing to do so, please do list a phone
number (including international code) so that we are able to contact you. You
should probably *only* add this number in the application for you submit to
google since the info in the wiki is available in public. We will *not* make any
use of your number unless some case of "there is no way to contact you" does
arise!

I wouldn't mind and in some cases prefer it. I'm not the most observant
when it comes to my email, I usually just get notices and spam that can
be ignored (high noise to signal ratio in my mailbox at the moment).
Though when expecting something I check it more often at least once a
day if not more.

**************Comments and Suggestions**************
Please place them after this line, all are appreciated and if I can't thank you
personally (IE you don't attach your name to it, Thank you.

SoC2014 vorobeez AI

2014-03-12T23:23:59Z

Timotei21: Fix the category

{{SoC2014Student}}
[[Category:SoC_Ideas_AI_Global_strategy]]

=ATTENTION=
This page is not finished yet

=Description=
<h4>TODO: Copy this page and write "your name - proposal title" in this h4 section </h4>
TODO: Write a small (1-4 sentences) description of your proposal here.

TODO: Add more first-level sections to detail your proposal

=IRC=
vorobeez

=Questionnaire=
1) Basics

'''1.1) Write a small introduction to yourself.'''

I'm Andrew Firsov, second-year student of Ivanovo State Power University.

'''1.2) State your preferred email address.'''

vorobeez@gmail.com

'''1.3) If you have chosen a nick for IRC and Wesnoth forums, what is it?'''

vorobeez

'''1.4) Why do you want to participate in summer of code?'''

I have to take experience with open source projects, improve programming skills and fun.

'''1.5) What are you studying, subject, level and school? '''

I'm studying math(combinatorics, probability theory, mathematical analysis, linear algebra...), computer science(algorithms, data structures, cryptography, compilers, C++, Lua, some libraries: SDL, crypto++, STL, boost), and a bit of game theory

'''1.6) What country are you from, at what time are you most likely to be able to join IRC?'''

I study at Ivanovo, Russia (UTC+04:00), but throughout the summer months i will live in the Simferopol (Crimea,Ukraine) (UTC+02:00).

'''1.7) Do you have other commitments for the summer period ? Do you plan to take any vacations ? If yes, when.'''

I want to travel to the Crimea on the weekends. That's all.

2) Experience

'''2.1) What programs/software have you worked on before?'''

i created small projects for my needs and games to learn how works SDL and for realizing my own ideas.

'''2.2) Have you developed software in a team environment before? (As opposed to hacking on something on your own)'''

No, i haven't

'''2.3) Have you participated to the Google Summer of Code before? As a mentor or a student? In what project? Were you successful? If not, why? '''

No, i haven't

'''2.4) Are you already involved with any open source development projects? If yes, please describe the project and the scope of your involvement.'''

No, i'm not. But i love open source and use it every day.

'''2.5) Gaming experience - Are you a gamer?'''

I was a gamer. Now I sometimes play wesnoth and FTL. I like games in which we must think.

'''2.5.1) What type of gamer are you?'''

Hardcore gamer.

'''2.5.2) What type of games?'''

Strategies and little bit of indie-games.

'''2.5.3) What type of opponents do you prefer? '''

Real players with wide experience.

'''2.5.4) Are you more interested in story or gameplay?'''

I love deep and great stories in games. But in order to the gamers could have fun all components of the game should be worked out at high level

'''2.5.5) Have you played Wesnoth? If so, tell us roughly for how long and whether you lean towards single player or multiplayer.'''

I'm playing Wesnoth for 1.5 years. I prefer SP. But sometimes play in MP with other players.

'''2.6) If you have contributed any patches to Wesnoth, please list them below. You can also list patches that have been submitted but not committed yet and patches that have not been specifically written for GSoC. If you have gained commit access to our repository (during the evaluation period or earlier) please state so.'''

3) Communication skills

'''3.1) Though most of our developers are not native English speakers, English is the project's working language. Describe your fluency level in written English.'''

I'm good at written English. And i speak with English native speakers freely.

'''3.2) What spoken languages are you fluent in?'''

Russian (native), Ukrainian, English.

3.3) Are you good at interacting with other players? Our developer community is friendly, but the player community can be a bit rough.

3.4) Do you give constructive advice?

3.5) Do you receive advice well?

3.6) Are you good at sorting useful criticisms from useless ones?

3.7) How autonomous are you when developing ? Would you rather discuss intensively changes and not start coding until you know what you want to do or would you rather code a proof of concept to "see how it turn out", taking the risk of having it thrown away if it doesn't match what the project want

4) Project

4.1) Did you select a project from our list? If that is the case, what project did you select? What do you want to especially concentrate on?

4.2) If you have invented your own project, please describe the project and the scope.

4.3) Why did you choose this project?

4.4) Include an estimated timeline for your work on the project. Don't forget to mention special things like "I booked holidays between A and B" and "I got an exam at ABC and won't be doing much then".

4.5) Include as much technical detail about your implementation as you can

4.6) What do you expect to gain from this project?

4.7) What would make you stay in the Wesnoth community after the conclusion of SOC?

5) Practical considerations

'''5.1) Are you familiar with any of the following tools or languages?'''
* Git (used for all commits) ''' I use basic functionality of git for my projects. '''
* C++ (language used for all the normal source code) '''I good at C++'''
* STL, Boost, Sdl (C++ libraries used by Wesnoth) '''I know STL, SDL 1.2 and a little SDL 2.0. And I learn boost, but not often use it. Also i'm fast learner'''
* Python (optional, mainly used for tools) '''No'''
* build environments (eg cmake/scons) '''basic knowledge and using'''
* WML (the wesnoth specific scenario language) '''In theory, but i don't use in it practice'''
* Lua (used in combination with WML to create scenarios) '''Yes'''

'''5.2) Which tools do you normally use for development? Why do you use them?'''

*'''git''' and '''github''' to commits and verify version of my project.
*'''gcc''' and '''make''' for compiling separate sources.
*'''vim''' or '''sublime''' for coding.

'''5.3) What programming languages are you fluent in?'''

C/C++ and Lua.

5.4) Would you mind talking with your mentor on telephone / internet phone? We would like to have a backup way for communications for the case that somehow emails and IRC do fail. If you are willing to do so, please do list a phone number (including international code) so that we are able to contact you. You should probably *only* add this number in the application for you submit to google since the info in the wiki is available in public. We will *not* make any use of your number unless some case of "there is no way to contact you" does arise!

SoC2014 theflamingskunk MPAnalytics

2014-03-12T23:23:25Z

Timotei21: Fix the category

{{SoC2014Student}}
[[Category:SoC_Ideas_Multiplayer_Data_Analysis]]

==ATTENTION==
This page is a Work in Progress

==Description==
<h4>Jason El-Massih - Multiplayer Data Analyics Proposal</h4>

My proposal is to automate the storage of Game Data and implement a system for aggregating and presenting gathered data for analysis by both developers and the community. This will allow for hard data at both the individual game level, and across the entire user-base to be taken into consideration for both game play balancing and general feedback in the future.

==IRC==

theflamingskunk

==Questionnaire==
'''1) Basics'''

'''1.1) Write a small introduction to yourself.'''

My name is Jason El-Massih and I'm a student at Worcester Polytechnic Institute

You can view my Online Portolio at: http://jel-massih.com/
and my Github at: https://github.com/jel-massih

'''1.2) State your preferred email address.'''

jel-massih@hotmail.com

'''1.3) If you have chosen a nick for IRC and Wesnoth forums, what is it?'''

theflamingskunk

'''1.4) Why do you want to participate in summer of code?'''

I love working on games, and have always been interested in Data Analytics, so when I saw that Wesnoth had a specific proposal idea in the area, I was like Snap Crackle Pop.

I also think it would be awesome to work on an Open Source Game project.

'''1.5) What are you studying, subject, level and school?'''

I'm studying Computer Science/Interactive Media & Game Development at Worcester Polytechnic Institute.

'''1.6) What country are you from, at what time are you most likely to be able to join IRC?'''

Im from United States of America, and will be able to lurk on IRC just about all day on most days (irc is attached to phone).
Will be Active on IRC/Work on Project from (approximately 5PM-12AM EST Time Weekdays and at various times on Weekend. (I am pretty big on having a routine).

'''1.7) Do you have other commitments for the summer period ? Do you plan to take any vacations ? If yes, when.'''

I dont plan to take any Vacations. I will be still be working at my current internship during the summer. However I will be able to dedicate 6-7 hours a day during this time so it will not interfere. (Time stated above).

'''2) Experience'''

'''2.1) What programs/software have you worked on before?'''

You can view my online portfolio at: http://jel-massih.com/ which showcases some of the things I worked on.

Also check out my Github for more stuff: http://github.com/jel-massih (Note that most of my public repos are for projects I worked solo on rapidly, thus the spotty commenting.)

I am the primary programmer on the game Recruits: http://recruitsgame.com/
Which is currently released on Desura and coming to Steam Early Access very soon. Developed in Unreal Engine 3 using a combination of Unrealscript and C++.

I have a plethora of Web Applications I developed for hackathons/fun, several of which can be found on my portfolio page.

I am also currently a Developer Intern at a Web Development Studio where I do backend web development for both client projects and internal projects. Using mostly PHP and Javascript with frameworks like: SlimPHP, BackboneJS and ZendDB. Also use both SQL(MySql) and NoSQL(MongoDB, CouchDB) databases.

I of course can hack together software, but am also able to write production level code that can sustain torment from a large userbase (like what Wesnoth would entail!)

'''2.2) Have you developed software in a team environment before? (As opposed to hacking on something on your own)'''

Indeed! Have been working with other developers on Recruits, as well as at my Internship where I am working with not just fellow developers, but also with clients.

The Recruits team is also dispersed around the globe so i am accustomed to working online. I have been working with an Australian who has the opposite timezone as me (14 hours ahead), so I am able to be very involved and communicative despite any timezone diffrences.

'''2.3) Have you participated to the Google Summer of Code before? As a mentor or a student? In what project? Were you successful? If not, why?'''

I have not participated in a google Summer of code before because this is the first year I am eligible! (Those pesky age restrictions).

'''2.4) Are you already involved with any open source development projects? If yes, please describe the project and the scope of your involvement.'''

Sort of but not really. I am actively working on the next iteration of the CMS Directus (http://getdirectus.com/) [Directus 6]. This Version is a complete restructuring of the existing version so it is still on a private repository until it is at a usable state (Which is very soon!)

'''2.5) Gaming experience - Are you a gamer?'''

Indeed! I am a lover of XCOM, which is probably why Im really enjoying Wesnoth. (Starting playing a couple days ago).

'''2.5.1) What type of gamer are you?'''

Video Gamer. Not a fan of Casinos and can only do Board Games in small servings.

'''2.5.2) What type of games?'''

I play a little bit of everything. I like to see what other games are up to and how they overcame certain challenges (Usually I pair my gameplaying with GDC talks/Papers I have been exposed to.

'''2.5.3) What type of opponents do you prefer?'''

Super Easy AI. I am pretty aweful at games.

'''2.5.4) Are you more interested in story or gameplay?'''

I think they both have their place and it more or less depends on what I am in the mood for.

'''2.5.5) Have you played Wesnoth? If so, tell us roughly for how long and whether you lean towards single player or multiplayer.'''

I've only been playing for 2 days, and played one MP game, got slaughtered, and now exclusively play SP. Yeah im pretty bad.

'''2.6) If you have contributed any patches to Wesnoth, please list them below. You can also list patches that have been submitted but not committed yet and patches that have not been specifically written for GSoC. If you have gained commit access to our repository (during the evaluation period or earlier) please state so.'''

No Contributions :( *yet!*

'''3) Communication skills'''

'''3.1) Though most of our developers are not native English speakers, English is the project's working language. Describe your fluency level in written English.'''

Native language!

'''3.2) What spoken languages are you fluent in?'''

Only English :(

'''3.3) Are you good at interacting with other players? Our developer community is friendly, but the player community can be a bit rough.'''

I am pretty good at getting along with people! I also keep a pretty sane head so even if someone is flipping out idoitic, I still communicate with them respectfully and try to resolve whatever issue they are having.
This was probably developed from having to deal with people who would have issues with Recruits (info above) [There was bugs aplenty!].

'''3.4) Do you give constructive advice?'''

I like to think I try to! I definitely am in advocate of straight talk so I more or less tell it how it is (unless I know the person I am giving it to is fragile, then I will try to pad it a little bit.

'''3.5) Do you receive advice well?'''

I take criticism very well! I actually prefer it since if you arnt getting criticized then there's not much you have to go off of to get better.

Now for general life advice... I havent had the best experiences.... but thats for another place :)

'''3.6) Are you good at sorting useful criticisms from useless ones?'''

I tend to believe that almost all criticism has some reason for its source. So I talk all of it into consideration, and usually filter out ones that dont lineup with the projects future goals or requirements.

'''3.7) How autonomous are you when developing ? Would you rather discuss intensively changes and not start coding until you know what you want to do or would you rather code a proof of concept to "see how it turn out", taking the risk of having it thrown away if it doesn't match what the project want.'''

It depends on what level of impact it will have on others. I am much more careful when whatever I am working on has the potential to waste other peoples time so will seek clearance before I do any intensive changes. However, I am a strong believer in prototyping so I will always be testing things out and creating proof of concepts in my own little bubble, with little care for whether it gets used or not.

'''4) Project'''

'''4.1) Did you select a project from our list? If that is the case, what project did you select? What do you want to especially concentrate on?'''

I selected the Multiplayer Data Analysis Project.

More Details once I discuss some things on IRC

'''4.2) If you have invented your own project, please describe the project and the scope.'''
N/A
'''4.3) Why did you choose this project?'''

I have always had an interest in Data Analytics. I also believe that if done properly, this project will be able to greatly benefit both developers and community creators to be more in tune with player behavior. This will allow for them to create and develop stuff that the players want, making the overall experience much more awesome!

'''4.4) Include an estimated timeline for your work on the project. Don't forget to mention special things like "I booked holidays between A and B" and "I got an exam at ABC and won't be doing much then".'''

TODO: Need to discuss on IRC so i can nail down the scope.

'''4.5) Include as much technical detail about your implementation as you can'''

TODO: Need to discuss on IRC so i can nail down the requirements.

'''4.6) What do you expect to gain from this project?'''

Being able to create sytems to allow developers and the community alike to continue to make a sweet game!...... and of course FAME AND GLORY!

'''4.7) What would make you stay in the Wesnoth community after the conclusion of SOC?'''

If the people are active and amazing!

'''5) Practical considerations'''

'''5.1) Are you familiar with any of the following tools or languages?'''
* Git (used for all commits) Yes!
* C++ (language used for all the normal source code) Yes!
* STL, Boost, Sdl (C++ libraries used by Wesnoth) STL: Yep!, Sdl/Boost: nope :(
* Python (optional, mainly used for tools) Yes!
* build environments (eg cmake/scons) A little
* WML (the wesnoth specific scenario language) Still Familiarizing
* Lua (used in combination with WML to create scenarios) A fair bit (used long time ago)

'''5.2) Which tools do you normally use for development? Why do you use them?'''

I use Visual Studio for C/C#/C++ Development because it makes it happy time with intellisense and the plethora of debugging tools all built in.

Everything else: Sublime Text. Its like Notepad++ on Crack. Makes me feel like a spaceman when I use it.

But Seriously: Super Lightweight, Gets the job done without any fancy shmancy unneeded overhead.

'''5.3) What programming languages are you fluent in?'''

C++, C#, Javascript, PHP, Java, Python.

'''5.4) Would you mind talking with your mentor on telephone / internet phone? We would like to have a backup way for communications for the case that somehow emails and IRC do fail. If you are willing to do so, please do list a phone number (including international code) so that we are able to contact you. You should probably *only* add this number in the application for you submit to google since the info in the wiki is available in public. We will *not* make any use of your number unless some case of "there is no way to contact you" does arise!'''

Would totally be down to hit up Skype or Phone with a mentor.

GSoCSpriteSheetsALourenco

2014-03-12T23:22:54Z

Timotei21: Fix the category

{{SoC2014Student}}
[[Category:SoC_Ideas_SpriteSheets2014]]

==Description==
<h4>ALourenco - SpriteSheet</h4>
I am proposing the development of a SpriteSheet compability, so the number of assets of Wesnoth can be decreased and it's coding gets cleaner. Instead of having a lot of pictures, we can have, for example, just one per character with all animations needed. It works like a chess board where you can acess the previosly separated pictures in it's respective position.
Since Wesnoth uses SDL, we can use OpenGL directly and easily handle several textures from only one SpriteSheet.

==IRC==
ALourenco

==Questionnaire==
1) Basics

1.1) Write a small introduction to yourself.
I am André Lourenço, I'm 19 years old, gonna be 20 at the time GSoC starts. My Career goal is to be a video game developer and I've been working for that. Besides University classes, I'm trying to gather experience in GameDev and gather some software for my portfolio.

1.2) State your preferred email address.
alourenco.94@hotmail.com

1.3) If you have chosen a nick for IRC and Wesnoth forums, what is it?
ALourenco (both in forums and IRC)

1.4) Why do you want to participate in summer of code?
One of the main reasons is because I wan't to work on something "real" and not just a subject work that is just proposed to test some skills. The fact that I'm working with a team, where everybody might aproach the same problem from a diferent prespective can mean a lot to my growth as a programmer. Besides this, I can have fun at the same time I'm gathering good experience and earning a good paycheck. Who knows if someday in the future I can gather up with the team i'll work with to start a new project or even share important information.

1.5) What are you studying, subject, level and school?
I'm Studying Informatics Engineering (Bachelor degree) in "Universidade de Évora", Portugal.

1.6) What country are you from, at what time are you most likely to be able to join IRC?
I can join IRC around 9am and 11pm GMT. If i'm asked for, I can always join IRC sooner or later.

1.7) Do you have other commitments for the summer period ? Do you plan to take any vacations ? If yes, when.
GSoC 2014 is my main goal for summer. I have no commitment.

2) Experience

2.1) What programs/software have you worked on before?
I've made some small things and prototypes in C++, such as a TicTacToe with GUI using a simple SpriteSheet system. I also made a simple particle system and projectiles system. I also have a Numberlink puzzles solver made in python and a simple Gravity Simulator with a C++ window embeded in a C# windows forms interface. I've developed other small and simple things. Most of these I said can be seen in my BitBucket Repository. https://bitbucket.org/CodinGree

2.2) Have you developed software in a team environment before? (As opposed to hacking on something on your own)
My only team experience was in University, besides that I always developed alone.

2.3) Have you participated to the Google Summer of Code before? As a mentor or a student? In what project? Were you successful? If not, why?
This is the first time I'm participating in Google Summer of Code.

2.4) Are you already involved with any open source development projects? If yes, please describe the project and the scope of your involvement.
I am not involven in any open source development projects.

2.5) Gaming experience - Are you a gamer?
Yes I'm a gamer.

2.5.1) What type of gamer are you?
I used to be an hardcore gamer, but now I don't have so much time I used to.

2.5.2) What type of games?
I like to play and try everything. Since I runned a game news website for two years, I got use to play everything.

2.5.3) What type of opponents do you prefer?
Human opponents is always an amazing experience, so my own friends may be my prefered opponents. I also like to play agains the level designer, for example, in puzzle games.

2.5.4) Are you more interested in story or gameplay?
I think both are important, but both got different effects on me. I can play a game with a good gameplay over and over again, without caring about the story, thats a cool game for me. A game with bad gameplay and good story gets hard to play and the story doesn't make any diference. A game with at least medium gameplay, but with a great story, make me feel like a fanboy.

2.5.5) Have you played Wesnoth? If so, tell us roughly for how long and whether you lean towards single player or multiplayer.
I already tried both singleplayer and multiplayer for a couple of hours. I also sent th game to some friends so they can give some feedback as gamers. I have been trying diferent campaigns and features to know the game well enough.

2.6) If you have contributed any patches to Wesnoth, please list them below. You can also list patches that have been submitted but not committed yet and patches that have not been specifically written for GSoC. If you have gained commit access to our repository (during the evaluation period or earlier) please state so.

3) Communication skills

3.1) Though most of our developers are not native English speakers, English is the project's working language. Describe your fluency level in written English.
I have a British Council IELTS exame, my mark is 7 in 9. The exame evaluates interpretation, listening, speaking and writing.

3.2) What spoken languages are you fluent in?
English and portuguese.

3.3) Are you good at interacting with other players? Our developer community is friendly, but the player community can be a bit rough.
Well, the goal of a game is to transmit an experience adn to be fun, so if a player is not having fun it deserves to be listen since that will be good for the game. With the developer comunity, I think it's going to be ok, sice I'm here to learn and also have fun.

3.4) Do you give constructive advice?
I'm looking forward to know where the game can get better so I can give some advices to the developer comunity. Answering the question: Yes I give constructive advices. I won't give destructive ones for sure.

3.5) Do you receive advice well?
Advices are allways welcome.

3.6) Are you good at sorting useful criticisms from useless ones?
Yes. It's importent to sort when a someone doesn't like something not because it's bad, but because of he's own taste. Besides that, there's allways haters. Since turn based strategy is a genre for very specific players, it may appear some people disliking the game because it doesn't have huge grafics or whatever...

3.7) How autonomous are you when developing ? Would you rather discuss intensively changes and not start coding until you know what you want to do or would you rather code a proof of concept to "see how it turn out", taking the risk of having it thrown away if it doesn't match what the project want
I learned how to programme alone. In the begining I had a lot of ideas, but it was hard to start coding because I was afraid to fail. Now, I start coding to see whats the result. If it fails I'll do it again. It will never be thrown away. We allways lean something by trying.

4) Project

4.1) Did you select a project from our list? If that is the case, what project did you select? What do you want to especially concentrate on?
I have chosen the project from your list. The project is to develop a SpriteSheet System because of the excessive assets the game has. It can be done by separating the SpriteSheet in sections like a chess board, where each section represents a cursor, animation frame,etc. The code also gets cleaner, since the SpriteSheet is a reusable object and the developer only needs to load, for example, spritesheet1.png instead of pic1.png, pic2.png,...

4.2) If you have invented your own project, please describe the project and the scope.

4.3) Why did you choose this project?
I like to build this kind of tools for GameDev. I already did something similiar but much simpler. I am confortable doing this, but not a specialist so this is a very good oportunity to explore a project like this.

4.4) Include an estimated timeline for your work on the project. Don't forget to mention special things like "I booked holidays between A and B" and "I got an exam at ABC and won't be doing much then".
I only can start on 4rd July. Until then I'll have exams, works and presentations. Since 4th of July to the rest of the month and August, I'm free. I'll only go on holidays in the end of the project.

4.5) Include as much technical detail about your implementation as you can
Since the game uses SDL, it can also be coded directly with OpenGL and that may be important. The idea is to join the assets in a .png image instead of a .png image for every animation frame, cursor... For example, we have a character that is 32x32 pixels. This character has only one animation with 4 frames. We create a SpriteSheet with 64x64. In the code, the first frame will be in the position 0x0, the secound frame in position 32x0, 3rd in 0x32 and 4th in 32x32. My TicTacToe uses something similiar. You can take a look here of the Board.h here:
https://bitbucket.org/CodinGree/tictactoe/src

4.6) What do you expect to gain from this project?
First of all, experience and a good time. Since I want to be a Game Developer, this project on my CV would be Great.

4.7) What would make you stay in the Wesnoth community after the conclusion of SOC?
If I keep having ideas to improve the game and time for it, I'll much likely stay.

5) Practical considerations

5.1) Are you familiar with any of the following tools or languages?

Git (used for all commits): I use git with BitBucket
C++ (language used for all the normal source code): C++ is my main and favorite language.
STL, Boost, Sdl (C++ libraries used by Wesnoth): Never used none. I used SFML and a bit of OpenGL.
Python (optional, mainly used for tools): I know python and I'm confortable with it.
build environments (eg cmake/scons): Never did nothing similiar.
WML (the wesnoth specific scenario language): I'm not familiar with it.
Lua (used in combination with WML to create scenarios): Also not familiar with it.

5.2) Which tools do you normally use for development? Why do you use them?
I use eclipse for Java and Python (PyDev). In Linux I also use eclipse for C/C++. In Windows I use Visual C++ for C++. I think Visual C++ is the best C++ IDE. Since it's windows only, I use eclipse for linux. Eclipse is the 2nd best IDE in my opinion.

5.3) What programming languages are you fluent in?
I'm fluent in C++ and Python. I only know a bit of C# and I've been learning Java. It's been a year or two since I don't programme in C.

Dragonofair0/GSoC2014 project idea

2014-03-12T23:21:06Z

Timotei21:

{{SoC2014Student}}
[[Category:SoC_Ideas_SDL2]]

==ATTENTION==
'''This page is a work in progress'''

==Description==
<h4>SDL2 Project Proposal</h4>
'''TODO:''' Write a small (1-4 sentences) description of your proposal here.

'''TODO:''' Add more first-level sections to detail your proposal

==IRC==
dragonofair0

==Questionnaire==
[[SoC_Information_for_Google#Does your organization have an application template you would like to see students use?|SoC Information for Google]]

SoC Ideas Unify SP and MP 2014

2014-03-12T23:19:38Z

Timotei21: Fix category dpl

{{SoC2014Idea}}

==Description==
===Game Engine: Unify SP and MP===
Page for the idea: [[SoC_Ideas_Unify_SP_and_MP_2014]]

Wesnoth has lots of user made content, but some of it works only for either singleplayer or multiplayer. To solve this, some of the engine's singleplayer and multiplayer code paths need to be unified and extended.

{{#dpl:
|resultsheader=''There are %PAGES% submitted student proposals for this idea''
|oneresultheader=''There is 1 submitted student proposal for this idea''
|suppresserrors=true
|noresultsheader=''There are no submitted student proposals for this idea''
|category=Summer of Code 2014 Student Page&SoC_Ideas_Unify_SP_and_MP_2014
|notcategory=SoC 2014 Not Submitted To Google
|include=#Description
|nottitlematch=SoC2014_Template_of_Student_page
|mode=userformat
|format=,, See [[%PAGE%|%TITLE%]] for more information. ,
}}

==Additional Information==

Last year's [[SoC2013_thunderstruck_MP_Campaign_Support|GSoC project]] made it possible to use the same configuration files for both singleplayer and multiplayer campaigns. However, there is still some WML content which is not available for both singleplayer and multiplayer due to being handled by different code paths.

The goal of this project is to unify singleplayer and multiplayer code paths which are responsible for handling configuration files. This would lead to being able to use multiplayer eras and modifications in singleplayer too. As a result of this, some GUI dialogs would have to be created in order for players to be able to use this new functionality.

==Whom to ask about this==
thunderstruck on IRC.

SoC Ideas UMCD 2014

2014-03-12T23:19:29Z

Timotei21: Fix category dpl

{{SoC2014Idea}}

==Description==
===UMCD===
Page of the idea: [[SoC_Ideas_UMCD_2014]]
Improving and completing the new add-ons server, '''UMCD''' (User-made Content Daemon).

{{#dpl:
|resultsheader=''There are %PAGES% submitted student proposals for this idea''
|oneresultheader=''There is 1 submitted student proposal for this idea''
|suppresserrors=true
|noresultsheader=''There are no submitted student proposals for this idea''
|category=Summer of Code 2014 Student Page&SoC_Ideas_UMCD_2014
|notcategory=SoC 2014 Not Submitted To Google
|include=#Description
|nottitlematch=SoC2014_Template_of_Student_page
|mode=userformat
|format=,, See [[%PAGE%|%TITLE%]] for more information. ,
}}

==Additional Information==

The current add-ons server used in production ('''campaignd''') is old and monolithic, so it would be problematic to extend it. That is why we started working on a new add-ons server during the last summer for GSoC ([[User:Trademark/GSoC_2013/Addon_Server:_Create_a_new_and_shiny_one|see last year's proposal here]]). If you are interested, and before starting anything, please come to see us.

===Goals===

* The '''main goal''' of this summer project is to finish the basics of the server. This means that every action on add-ons should be implemented (create, update, delete, retrieve, update password, ...). It also means that you should update the client accordingly.
* '''Secondary goal''': Resolution of add-on dependencies.
* '''Additional goals''':
** Synchronization of translations with [[WesCamp]].
** Support for gettext on the client side (translation of server responses).

There is also a side project of a networking library based on Boost.Asio that we will use in UMCD. It could be great to design the add-ons server such that the basic add-on framework could be re-used in other open-source projects (the requirements for an add-ons server are often the same).

===Where to start===

* First you should subscribe to the [https://mail.gna.org/listinfo/wesnoth-dev/ Wesnoth developers mailing list].
* Download and build [https://github.com/ptal/neev NEEV]. Since you'll need to install and build Boost, it's important to build this library first (Wesnoth depends on Boost).
* Obtain a clone of the [[WesnothRepository|Wesnoth source repository]], and [[CompilingWesnoth|compile it]].
* See the official [[UMCD]] page, and compile the UMCD server.
* Before starting anything, send a mail or ask on IRC, since the UMCD page isn't updated with the latest information.

===Are you the person?===

We expect you to be motivated, especially if you are not familiar with the tools we are using. Nevertheless, we would like you to have some familiarity with C++11 or at least C++. If you don't know C++ but you are interested, ask us and we'll give you some references to learn C++ (but you will need to spend a lot of time learning, so be warned). Classic skills in software engineering and SQL are a plus. A love for designing and writing clean code is highly advisable.

===Resources===

* [https://github.com/wesnoth/wesnoth-old/ Wesnoth repository], in particular, the branch '''asio_umcd'''.
* [[UMCD|UMCD page]] (not updated, be careful).
* [http://www.boost.org/ Boost C++ libraries], in particular, [http://www.boost.org/libs/asio Boost.Asio].
* [https://github.com/rbock/sqlpp11 SQLPP11 library].
* [https://github.com/ptal/neev Neev library].

==Whom to ask about this==
* trademark on IRC or by mail <ptalbot@hyc.io> (contact me first by mail, I could miss you on IRC)
* mordante on IRC

SoC Ideas SpriteSheets2014

2014-03-12T23:19:13Z

Timotei21: Fix category dpl

{{SoC2014Idea}}

==Description==
===SpriteSheet===
Page for the idea: [[SoC_Ideas_SpriteSheets2014]]

Wesnoth uses thousands of images, each of them stored in separate files.
It would be more efficient to store multiple images in a single file. In order
to make that possible, the Wesnoth engine needs to be adapted to allow this change.

{{#dpl:
|resultsheader=''There are %PAGES% submitted student proposals for this idea''
|oneresultheader=''There is 1 submitted student proposal for this idea''
|suppresserrors=true
|noresultsheader=''There are no submitted student proposals for this idea''
|category=Summer of Code 2014 Student Page&SoC_Ideas_SpriteSheets2014
|notcategory=SoC 2014 Not Submitted To Google
|include=#Description
|nottitlematch=SoC2014_Template_of_Student_page
|mode=userformat
|format=,, See [[%PAGE%|%TITLE%]] for more information. ,
}}

==Additional Information==

Currently, all the Wesnoth unit animations are based on thousands of small png
images, each image representing the unit in a single pose. For terrains the
situation is the same, it has a base image with a lot of transitions to other
terrains, which are now stored as seperate images.

In a sprite sheet approach, each unit is represented by a single, huge, image
where all the unit images are put on a mosaïc pattern and the game knows where
to look for a given image.

The advantage of having a large image with all positions is that it's more
efficient in memory. Also one large file is more effecient on the harddisk and
faster to load than a lot of smaller files. So the change to spritesheets will
have a lot of advantages. Also several Wesnoth artists prefer using sprite
sheets over multiple single images.

This project involves changing the Wesnoth Markup Language (WML)* definition
for images to specify a sub image in a sprite sheet and change the image loading
code of the engine. Creating tools to transform existing images to a sprite sheet
can be an optional objective.

Regarding the implementation the student is free to come up with his/her own
solution and discuss that with the developers during the application period.

*) WML is a XML like language, used to describe the data/content of Wesnoth.

==Whom to ask about this==

mordante on IRC.

SoC Ideas SDL2

2014-03-12T23:15:59Z

Timotei21:

{{SoC2014Idea}}

==Description==
===SDL2===
Page for the idea: [[SoC_Ideas_SDL2]]

The Wesnoth project uses the [http://www.libsdl.org/ SDL] library. Last year, a new major version (2.0) of SDL was released. This version of the library has better support for mobile devices like the Android and the iPhone. This project involves helping porting Wesnoth from SDL 1.2 to 2.0.

{{#dpl:
|resultsheader=''There are %PAGES% submitted student proposals for this idea''
|oneresultheader=''There is 1 submitted student proposal for this idea''
|suppresserrors=true
|noresultsheader=''There are no submitted student proposals for this idea''
|category=Summer of Code 2014 Student Page&SoC_Ideas_SDL2
|notcategory=SoC 2014 Not Submitted To Google
|include=#Description
|nottitlematch=SoC2014_Template_of_Student_page
|mode=userformat
|format=,, See [[%PAGE%|%TITLE%]] for more information. ,
}}

==Additional Information==

The transition from SDL 1.2 to 2.0 is a large project and a lot of work
needs to be done:
* The event handling has changed, so the event and input handling in Wesnoth needs to be changed.
* With SDL 1.2 we are using [http://wiki.libsdl.org/CategorySurface surface-based drawing]. With the transition to 2.0, we want use [http://wiki.libsdl.org/CategoryRender accelerated drawing].

The SDL transition is too large for one GSoC project. During the application period
the student will discuss which part of the transition he or she wants to work on
during the summer.

==Whom to ask about this==

mordante on IRC

SoC Ideas Multiplayer Data Analysis

2014-03-12T23:15:40Z

Timotei21:

{{SoC2014Idea}}

==Description==
===Improve the automated collection and display of multiplayer game data===
Page for the idea: [[SoC_Ideas_Multiplayer_Data_Analysis]]

Multiplayer games are currently [http://replays.wesnoth.org/ archived]. This includes lots of interesting and potentially useful data, including recruits, deaths, number of turns and other things. The only way to access this information currently is parsing the WML one save file at a time. Additionally, which side(s) won the game is only recorded in some cases. We would like to record which side(s) won or lost (for as many games as possible) and then display useful information about these games for balancing and feedback purposes.

{{#dpl:
|resultsheader=''There are %PAGES% submitted student proposals for this idea''
|oneresultheader=''There is 1 submitted student proposal for this idea''
|suppresserrors=true
|noresultsheader=''There are no submitted student proposals for this idea''
|category=Summer of Code 2014 Student Page&SoC_Ideas_Multiplayer_Data_Analysis
|notcategory=SoC 2014 Not Submitted To Google
|include=#Description
|nottitlematch=SoC2014_Template_of_Student_page
|mode=userformat
|format=,, See [[%PAGE%|%TITLE%]] for more information. ,
}}

==Additional Information==

The primary use for this would be for multiplayer balancing, both for developers and for authors of UMC. This breaks down into 3 parts.

# '''Implement some way in the Wesnoth client to select a winning side (when it is not otherwise obvious).'''
#*Alter how multiplayer games end in such a way that they must either declare a winning side or have the players select a "continue later" option. Thought needs to be put into how to handle this to include different types of games (regular duels as well as custom scenarios that might end with special conditions). This will allow much of the game data that is already collected to be used more directly for analysis. Many games will no doubt never finish "successfully" due to network disconnections or savegames that are never reloaded, but if most players simply declare a winning side via some interface at the end of the game we should get many good data points. User Made Content (UMC) would also provide good data if the [end_level] tag is correctly implemented.
# '''Implement a replay data analyzation tool that processes replays and save what it finds out in a database.'''
#*Store in a database as much data useful to analysis as is currently possible. Savegames are stored in [[SavefileWML|WML]], which can be parsed by C++, Python and Perl. Some highlights of very useful things:
#** By era, which factions win the most and on which maps.
#** Which side(s) win the most on which maps.
#** Which eras and/or maps see the most games, and their various full-game completion rate.
#** If possible, what difficulty (if applicable to MP campaign or UMC) was selected for the game.
# '''Implement some frontend to query/visualize the data in the database.'''
#*While the first two parts are most important, if time allows it would be great to create a medium to display and filter the data (preferably web-based). Allow for filtering of many different variable with an eye toward being able to expend and add display variables in the future.

'''FAQ'''

'''''Q: Where in the code the data saving takes place?'''''

A: src/server/game.cpp: game::save_replay()

'''''Q: How will I open up the archived replays for data analysis?'''''

A: Using a WML parser you'd go through the replay like the game proper and collect data you think is useful (storing it in the database).

'''''Q: Where would the data analyzation tool live?'''''

A: The analyzation tool would probably be run on the server where also wesnothd runs but it's an independent process, since wesnothd just saves the replay data it has no real idea what's in it.

==Whom to ask about this==

Soliton, happygrue (IRC is preferable)

SoC2014 lipkab SDL2

2014-03-12T23:14:25Z

Timotei21: Fix the category

{{SoC2014Student}}
[[Category:SoC_Ideas_SDL2]]

=Description=
<h4>lipkab - SDL2 transition</h4>
I propose to help with the SDL2 transition.

I'd like to work on implementing hardware accelerated rendering for Wesnoth and enabling it for the map/unit rendering system.

=IRC=
lipkab

=Questionnaire=
'''1) Basics'''

'''1.1) Write a small introduction to yourself.'''

'''1.2) State your preferred email address.'''

lipkab zoho com

'''1.3) If you have chosen a nick for IRC and Wesnoth forums, what is it?'''

lipkab and lipk, respectively.

'''1.4) Why do you want to participate in summer of code?'''

I have a number of reasons:
* Do something useful during the summer holiday.
* Get a nice reference in my CV.
* Earn money.

'''1.5) What are you studying, subject, level and school?'''

I'm doing my second year on Computer Science BSc at the Pázmány Péter University (Faculty for Information Technology). Well, in fact, I'm formally a Molecular Bionics student, however, in practice I take CS courses and next year I'll be able to officially switch majors.

'''1.6) What country are you from, at what time are you most likely to be able to join IRC?'''

I'm Hungarian, I usually join IRC at CET nights on weekdays and at unpredictable times during weekends/holidays.

'''1.7) Do you have other commitments for the summer period ? Do you plan to take any vacations ? If yes, when.'''

I don't have other commitments. TODO: vacations?

'''2) Experience'''

'''2.1) What programs/software have you worked on before?'''

I have written a large number of small programs over the years as school work, or practice. As for bigger ones, I've been contributing to Wesnoth since 2012, and I produced a visual editor for Apertium's transfer rule format during last year's GSoC. That project is put on hold, though, since the concept (converting Apertium's declarative semantic to procedural) made further development very difficult. I'm semi-working on a replacement program for Visruled designed with a slightly different approach to avoid the structural problems of the former.

'''2.2) Have you developed software in a team environment before? (As opposed to hacking on something on your own)'''

If Wesnoth development is considered a team environment, yes...

'''2.3) Have you participated to the Google Summer of Code before? As a mentor or a student? In what project? Were you successful? If not, why?'''

I successfully participated in GSoC 2013 as a student, see 2.1 for details.

'''2.4) Are you already involved with any open source development projects? If yes, please describe the project and the scope of your involvement.'''

I worked with the Apertium folks during last summer and I remained more or less active in the project maintaining and developing the software component I worked on during GSoC (again, see 2.1). I'm also a semi-active Wesnoth developer, my contributions include:
* New storyscreen background WML (was required for the new bigmaps)
* Multiplayer features (modifications, custom add-on options, dependencies)
* MP interface redesign (in collaboration with thunderstruck and Coffee)
* Various bugfixes and PRs

'''2.5) Gaming experience - Are you a gamer?'''

'''2.5.1) What type of gamer are you?'''

I don't consider myself a gamer, although there're a few games I can play quite a lot of with.

'''2.5.2) What type of games?'''

I prefer brain-working ones like strategy or puzzle games. Some of my favorites are Trine 2, Civilization V and Splice. I also like LEGO games!

'''2.5.3) What type of opponents do you prefer?'''

Ones that are challenging to beat but can be beated, so roughly the same skill level.

'''2.5.4) Are you more interested in story or gameplay?'''

As above, I mostly play with strategy and puzzle games and there gameplay definitely weighs more than the plot. That being said, I do appreciate an interesting and thoughtful story.

'''2.5.5) Have you played Wesnoth? If so, tell us roughly for how long and whether you lean towards single player or multiplayer.'''

I've been playing Wesnoth for roughly 3 years now. I was an SP player initially, but nowadays I play MP almost exclusively partly because I've run out of good campaigns and partly for the greater challenge.

'''2.6) If you have contributed any patches to Wesnoth, please list them below. You can also list patches that have been submitted but not committed yet and patches that have not been specifically written for GSoC. If you have gained commit access to our repository (during the evaluation period or earlier) please state so.'''

I have commit access since 2012. I made approximately 100 commits since then, see 2.4 for an overview on their scope.

'''3) Communication skills'''

'''3.1) Though most of our developers are not native English speakers, English is the project's working language. Describe your fluency level in written English.'''

I had no problem communicating with the team in the last 3 years :)

'''3.2) What spoken languages are you fluent in?'''

Hungarian (native) and English. I'd like to believe that I'm also capable of communicating in French.

'''3.3) Are you good at interacting with other players? Our developer community is friendly, but the player community can be a bit rough.'''

I can get along with sane people with different opinions reasonably well but I'm not good at handling idiots.

'''3.4) Do you give constructive advice?'''

Well, at least I try to.

'''3.5) Do you receive advice well?'''

I usually listen to and consider any advice but I tend to be rather insistant on my own ideas.

'''3.6) Are you good at sorting useful criticisms from useless ones?'''

I believe so, although I have gotten very little feedback on my contributions for both Wesnoth and Apertium and none of my other works were subject to critique from a wider audience.

'''3.7) How autonomous are you when developing ? Would you rather discuss intensively changes and not start coding until you know what you want to do or would you rather code a proof of concept to "see how it turn out", taking the risk of having it thrown away if it doesn't match what the project want.'''

That depends on how confident I'm about what I'm doing and also the impacts of a possible failure. I'm much more careful when risking wasting other people's time than my own.

'''4) Project'''

'''4.1) Did you select a project from our list? If that is the case, what project did you select? What do you want to especially concentrate on?'''

I've chosen the SDL2 transition project. I'd like to concentrate on revamping the rendering system to make use of SDL2's hardware acceleration facilities.

'''4.2) If you have invented your own project, please describe the project and the scope.'''

-

'''4.3) Why did you choose this project?'''

I've been playing with the idea of porting Wesnoth to SDL2 for a long time. ...

'''4.4) Include an estimated timeline for your work on the project. Don't forget to mention special things like "I booked holidays between A and B" and "I got an exam at ABC and won't be doing much then".'''

'''4.5) Include as much technical detail about your implementation as you can'''

The first step of the project is to implement a wrapper class for SDL_Texture, which supports rotating, clipping and scaling the object. Since these operations (SDL_RenderCopyEx, SDL_SetScale) don't require the actual texture data to be modified in any way, multiple instances of the texture class can share a single SDL_Texture. A texture's pixels can't be accessed directly, thus we may also want to keep a copy of the surface the texture was created from in the class, in case a modified image is needed later.

The second task is to enable access to hardware accelerated facilities through the usual global objects. This includes an SDL_Renderer available through CVideo and texture loading via the image class. Both changes should be straightforward.

The third task is to deploy the texture class in the storyscreen code. The storyscreen's implementation is relatively self-contained and well documented so it's an ideal place to try out new features. Furthermore, it involves scaling large pictures which is currently one of the performance bottlenecks of Wesnoth and hopefully will be resolved by enabling hardware acceleration.

TODO: write something on display and game_display.

'''4.6) What do you expect to gain from this project?'''

A deeper understanding of both SDL2 and Wesnoth's rendering and event handling system. Plus a T-shirt.

'''4.7) What would make you stay in the Wesnoth community after the conclusion of SOC?'''

My affiliation with Wesnoth didn't begin with GSoC, so I don't expect it to end with it.

'''5) Practical considerations'''

'''5.1) Are you familiar with any of the following tools or languages?'''
* Git (used for all commits) ''yes''
* C++ (language used for all the normal source code) ''yes''
* STL, Boost, Sdl (C++ libraries used by Wesnoth) ''SDL, STL: yes, Boost: somewhat''
* Python (optional, mainly used for tools) ''at a basic level only''
* build environments (eg cmake/scons) ''yes''
* WML (the wesnoth specific scenario language) ''yes''
* Lua (used in combination with WML to create scenarios) ''yes''

'''5.2) Which tools do you normally use for development? Why do you use them?'''

I use Vim/GVim for smaller projects because of the almost perfect code completion and error detecting features I can get from YCM (a clang integration plugin). For bigger and/or Qt related stuff I use Qt Creator, which I like in particular for its friendly debugger interface and code navigation capabilities.

'''5.3) What programming languages are you fluent in?'''

C++, Java, Lua.

'''5.4) Would you mind talking with your mentor on telephone / internet phone? We would like to have a backup way for communications for the case that somehow emails and IRC do fail. If you are willing to do so, please do list a phone number (including international code) so that we are able to contact you. You should probably *only* add this number in the application for you submit to google since the info in the wiki is available in public. We will *not* make any use of your number unless some case of "there is no way to contact you" does arise!'''

SoC2014 Template of Student page

2014-03-12T23:13:07Z

Timotei21: /* Description */

{{SoC2014Student}}
[[Category:SoC_Ideas_Your_Own_Ideas2014]]

==ATTENTION==
* To copy this template page to your own new page, enter the desired URL for the new page in your browser's address bar, e.g. <code><nowiki>http://wiki.wesnoth.org/New_Page</nowiki></code>. (See also http://www.mediawiki.org/wiki/Help:Starting_a_new_page)
* Go into editing mode on this template page (http://wiki.wesnoth.org/index.php?title=SoC2014_Template_of_Student_page&action=edit) and copy the contents to your new page. '''DO NOT ACTUALLY EDIT ANYTHING IN THIS TEMPLATE!'''

==Description==
<h4>'''TODO:''' Copy this page and write "your name - proposal title" in this h4 section</h4>
'''TODO:''' Write a small (1-4 sentences) description of your proposal here.

'''TODO:''' Add more first-level sections to detail your proposal

'''TODO:''' Set the proper Category in the top of the page (<nowiki>[[Category:XYZ]]</nowiki>), to match the one you'd like to apply for, from the list on the main summer of code page (e.g.: <nowiki>[[Category:SoC_Ideas_AI_Global_strategy]]</nowiki>). Otherwise your idea will be marked as a new one.

==IRC==
'''TODO:''' Put '''only''' your IRC nickname in there. In case of alternate nicks, separate with commas.

Example contents for this section (without the quotes): "user" "user1, user2"

==Questionnaire==
'''TODO:''' fill out the questionnaire, on your copy of this page. The questions are provided in the [[SoC_Information_for_Google#Does your organization have an application template you would like to see students use?|SoC Information for Google]] page.

SoC2014 Template of Student page

2014-03-12T23:11:24Z

Timotei21: Add instructions related to category modification

{{SoC2014Student}}
[[Category:SoC_Ideas_Your_Own_Ideas2014]]

==ATTENTION==
* To copy this template page to your own new page, enter the desired URL for the new page in your browser's address bar, e.g. <code><nowiki>http://wiki.wesnoth.org/New_Page</nowiki></code>. (See also http://www.mediawiki.org/wiki/Help:Starting_a_new_page)
* Go into editing mode on this template page (http://wiki.wesnoth.org/index.php?title=SoC2014_Template_of_Student_page&action=edit) and copy the contents to your new page. '''DO NOT ACTUALLY EDIT ANYTHING IN THIS TEMPLATE!'''

==Description==
<h4>'''TODO:''' Copy this page and write "your name - proposal title" in this h4 section</h4>
'''TODO:''' Write a small (1-4 sentences) description of your proposal here.

'''TODO:''' Add more first-level sections to detail your proposal

'''TODO:''' Set the propert Category in the top of the page ([[Category:XXX]]), to match the one you'd like to apply for, from the list on the main summer of code page (e.g.: [[Category:SoC_Ideas_AI_Global_strategy]]). Otherwise your idea will be marked as a new one.

==IRC==
'''TODO:''' Put '''only''' your IRC nickname in there. In case of alternate nicks, separate with commas.

Example contents for this section (without the quotes): "user" "user1, user2"

==Questionnaire==
'''TODO:''' fill out the questionnaire, on your copy of this page. The questions are provided in the [[SoC_Information_for_Google#Does your organization have an application template you would like to see students use?|SoC Information for Google]] page.

SoC2014 Template of Student page

2014-03-12T23:04:08Z

Timotei21:

{{SoC2014Student}}
[[Category:Summer of Code 2014 Student Page]]

==ATTENTION==
* To copy this template page to your own new page, enter the desired URL for the new page in your browser's address bar, e.g. <code><nowiki>http://wiki.wesnoth.org/New_Page</nowiki></code>. (See also http://www.mediawiki.org/wiki/Help:Starting_a_new_page)
* Go into editing mode on this template page (http://wiki.wesnoth.org/index.php?title=SoC2014_Template_of_Student_page&action=edit) and copy the contents to your new page. '''DO NOT ACTUALLY EDIT ANYTHING IN THIS TEMPLATE!'''

==Description==
<h4>'''TODO:''' Copy this page and write "your name - proposal title" in this h4 section</h4>
'''TODO:''' Write a small (1-4 sentences) description of your proposal here.

'''TODO:''' Add more first-level sections to detail your proposal

==IRC==
'''TODO:''' Put '''only''' your IRC nickname in there. In case of alternate nicks, separate with commas.

Example contents for this section (without the quotes): "user" "user1, user2"

==Questionnaire==
'''TODO:''' fill out the questionnaire, on your copy of this page. The questions are provided in the [[SoC_Information_for_Google#Does your organization have an application template you would like to see students use?|SoC Information for Google]] page.

SummerOfCodeIdeas

2014-02-03T20:20:15Z

Timotei21: Remove Sirp as he's not active anymore.

{{SoC2014}}

= I want to be one of your Google Summer of Code students, what should I do... =

Welcome!
Here is a quick list of things to do at this time:

* '''MOST IMPORTANT''' Submit your application to Google till March 21st.
* '''MOST IMPORTANT''' Join the irc channel (#wesnoth-dev on irc.freenode.net) and talk about your project and your appilication. We will not give formal interviews, but we will clearly favor people we have learned to know during the selection process (basically communication via IRC is mandatory for our project! it is the main way of "every day communication" for Wesnoth. For the same reason, it's also a good idea to regularly read the [http://www.wesnoth.org/irclogs/2014/ IRC logs].).

* '''VERY IMPORTANT''' Create the wiki page about your idea (Make a copy of the student proposal page template: [[SoC2014 Template of Student page]]):
** Fill the questionnaire.
** Detail your idea as much as possible, look at other students pages, and please give timeline, milestones and studies you've done
* If you haven't done so yet, create an account on gna.org (required for committing later on)
* If you haven't done so yet, create an account on the wesnoth forum, and tell an admin of the forum or leader of the group on the IRC channel to mark it as a GSoC Student account (admins/group leaders are: Boucman, Crab, fendrin/Fabi, Ivanovic, Mordante/SkeletonCrew, Noy, shadowm/shadowmaster, Soliton)
* Though not mandatory, it is highly advisable to go to the [[EasyCoding]] and [[NotSoEasyCoding]] pages and implement one of these ideas (or any idea of similar scope) so we have an idea how you work. Be sure to use your gna account when submitting these patches so we know who it is coming from. You can also implement some features from our feature request database at gna. When you implement something, also list it on your own page with a reference to the patch. This should give you a good idea what the Wesnoth sourcecode is like and will provide a good start to getting used to our coding style, too. You can also start working on your project and submit patches/prototypes related to it

* For working on Wesnoth you have to be able to compile trunk. To do so you should have a look at the [[WesnothRepository|page about the repository]] and afterwards [[CompilingWesnoth|compile Wesnoth]].

= Information about our Project =
The information we provided google with about our project can be looked up at the site [[SoC Information for Google]].

Also see the [[DeveloperResources]] link (from the [[Project]] page).

= People to bug on IRC =
We have prepared a list of people with their "area of competence". This is to give you an idea on which areas those people can be of help for you. Of course you should always just ask in the IRC chan, but those are the most likely ones to answer questions in the respective area. And here is the list:

[[SoC People to bug on IRC]]

= List of Ideas for the Project (Suggestions from wesnoth developers) =

{| border=1
| NOTE: this list of ideas is automatically generated from the 'description' section of pages in ''Summer of Code 2014 Idea'' category. DO NOT TRY TO EDIT THIS LIST BY HAND - IT WON'T WORK. INSTEAD, CREATE A NEW PAGE WITH THE 'Soc Ideas2014 Template' template.
|-
| NOTE: to add a student page, create a new page based on copy the student proposal page template: [[SoC2014 Template of Student page]]):
|}

{{#dpl:
|noresultsheader=''No ideas yet. Why not create one?'' 
|category=Summer of Code 2014 Idea
|include=#Description
|mode=userformat
|format=,, ,
|nottitlematch=SoC_Ideas2014_Template
}}

=Student proposals not submitted to google=
{{#dpl:
|resultsheader=''There are %PAGES% student proposals which were not submitted to google'' 
|oneresultheader=''There is 1 student proposal which was not submitted to google'' 
|suppresserrors=true
|noresultsheader=''All the proposals were submitted to google'' 
|category=Summer of Code 2014 Student Page
|nottitlematch=SoC2014 Template of Student page
|include=#IRC, #SoC Application
|includenotmatch= ,/google/s
|mode=userformat
|format=,,[[%PAGE%|%TITLE%]] ,
}}

=Student proposals submitted both to wiki and google=
(marked by hand, so if your proposal is not there, don't panic, check google's site instead and ping us, if necessary)
{{#dpl:
|resultsheader=''There are %PAGES% student proposals which were submitted both to wiki and to google'' 
|oneresultheader=''There is 1 student proposal which was submitted both to wiki and to google'' 
|suppresserrors=true
|noresultsheader=''All the proposals were submitted to google'' 
|category=Summer of Code 2014 Student Page
|nottitlematch=SoC2014 Template of Student page
|include=#IRC, #SoC Application
|includematch= ,/Submitted to google/s
|mode=userformat
|format=,,[[%PAGE%|%TITLE%]] ,
}}
=Result from Google acceptance=
List of proposals accepted by Google would be available on April 21st

Template:SoC2014Student

2014-02-03T20:16:40Z

Timotei21: SoC 2014

<includeonly>
{{SoC2014}}
</includeonly>

{| border=3 align="center" cellpadding="20" cellspacing="0"
|align="center" | '''This is a Summer of Code 2014 student page'''
|}
 

<includeonly>
[[Category:Summer of Code 2014 Student Page]]
</includeonly>

SoC2014 Template of Student page

2014-02-03T20:16:20Z

Timotei21: SoC 2014

{{SoC2014Student}}
[[Category:SoC_Ideas_Your_Own_Ideas2014]]

=ATTENTION=
'''DO NOT EDIT THIS PAGE, SoC2014_Template_of_Student_Page, - MAKE A COPY!'''

=Description=
<h4>TODO: Copy this page and write "your name - proposal title" in this h4 section </h4>
TODO: Write a small (1-4 sentences) description of your proposal here.

TODO: Add more first-level sections to detail your proposal

=IRC=
put ONLY your irc nickname in there. in case of alternate nicks, separate by ,

Example content of this section: "user" "user1, user2" (without the quotes)

=Questionnaire=
TODO: fill out the questionnaire, on your copy of this page. Question are here : [[SoC_Information_for_Google#Does your organization have an application template you would like to see students use?]]

Template:SoC2014 NoCategory

2014-02-03T20:15:16Z

Timotei21: SoC 2014

{| border=3 align="center" cellpadding="20" cellspacing="0"
|align="center" | '''This page is related to Summer of Code 2014'''
|-
|align="center" | [[SummerOfCodeIdeas|See the list of Summer of Code 2014 Ideas]]
|}

Template:SoC2014

2014-02-03T20:14:56Z

Timotei21: Add the SoC2014 template page

{{SoC2014 NoCategory}}
<noinclude>
note: edit [[Template:SoC2014 NoCategory]] to edit the above header.
</noinclude>
<includeonly>
[[Category:Summer of Code 2014]]
</includeonly>

SummerOfCodeIdeas

2014-02-03T20:14:31Z

Timotei21: Update for SoC 2014

{{SoC2014}}

= I want to be one of your Google Summer of Code students, what should I do... =

Welcome!
Here is a quick list of things to do at this time:

* '''MOST IMPORTANT''' Submit your application to Google till March 21st.
* '''MOST IMPORTANT''' Join the irc channel (#wesnoth-dev on irc.freenode.net) and talk about your project and your appilication. We will not give formal interviews, but we will clearly favor people we have learned to know during the selection process (basically communication via IRC is mandatory for our project! it is the main way of "every day communication" for Wesnoth. For the same reason, it's also a good idea to regularly read the [http://www.wesnoth.org/irclogs/2014/ IRC logs].).

* '''VERY IMPORTANT''' Create the wiki page about your idea (Make a copy of the student proposal page template: [[SoC2014 Template of Student page]]):
** Fill the questionnaire.
** Detail your idea as much as possible, look at other students pages, and please give timeline, milestones and studies you've done
* If you haven't done so yet, create an account on gna.org (required for committing later on)
* If you haven't done so yet, create an account on the wesnoth forum, and tell an admin of the forum or leader of the group on the IRC channel to mark it as a GSoC Student account (admins/group leaders are: Boucman, Crab, fendrin/Fabi, Ivanovic, Mordante/SkeletonCrew, Noy, shadowm/shadowmaster, Sirp/Dave, Soliton)
* Though not mandatory, it is highly advisable to go to the [[EasyCoding]] and [[NotSoEasyCoding]] pages and implement one of these ideas (or any idea of similar scope) so we have an idea how you work. Be sure to use your gna account when submitting these patches so we know who it is coming from. You can also implement some features from our feature request database at gna. When you implement something, also list it on your own page with a reference to the patch. This should give you a good idea what the Wesnoth sourcecode is like and will provide a good start to getting used to our coding style, too. You can also start working on your project and submit patches/prototypes related to it

* For working on Wesnoth you have to be able to compile trunk. To do so you should have a look at the [[WesnothRepository|page about the repository]] and afterwards [[CompilingWesnoth|compile Wesnoth]].

= Information about our Project =
The information we provided google with about our project can be looked up at the site [[SoC Information for Google]].

Also see the [[DeveloperResources]] link (from the [[Project]] page).

= People to bug on IRC =
We have prepared a list of people with their "area of competence". This is to give you an idea on which areas those people can be of help for you. Of course you should always just ask in the IRC chan, but those are the most likely ones to answer questions in the respective area. And here is the list:

[[SoC People to bug on IRC]]

= List of Ideas for the Project (Suggestions from wesnoth developers) =

{| border=1
| NOTE: this list of ideas is automatically generated from the 'description' section of pages in ''Summer of Code 2014 Idea'' category. DO NOT TRY TO EDIT THIS LIST BY HAND - IT WON'T WORK. INSTEAD, CREATE A NEW PAGE WITH THE 'Soc Ideas2014 Template' template.
|-
| NOTE: to add a student page, create a new page based on copy the student proposal page template: [[SoC2014 Template of Student page]]):
|}

{{#dpl:
|noresultsheader=''No ideas yet. Why not create one?'' 
|category=Summer of Code 2014 Idea
|include=#Description
|mode=userformat
|format=,, ,
|nottitlematch=SoC_Ideas2014_Template
}}

=Student proposals not submitted to google=
{{#dpl:
|resultsheader=''There are %PAGES% student proposals which were not submitted to google'' 
|oneresultheader=''There is 1 student proposal which was not submitted to google'' 
|suppresserrors=true
|noresultsheader=''All the proposals were submitted to google'' 
|category=Summer of Code 2014 Student Page
|nottitlematch=SoC2014 Template of Student page
|include=#IRC, #SoC Application
|includenotmatch= ,/google/s
|mode=userformat
|format=,,[[%PAGE%|%TITLE%]] ,
}}

=Student proposals submitted both to wiki and google=
(marked by hand, so if your proposal is not there, don't panic, check google's site instead and ping us, if necessary)
{{#dpl:
|resultsheader=''There are %PAGES% student proposals which were submitted both to wiki and to google'' 
|oneresultheader=''There is 1 student proposal which was submitted both to wiki and to google'' 
|suppresserrors=true
|noresultsheader=''All the proposals were submitted to google'' 
|category=Summer of Code 2014 Student Page
|nottitlematch=SoC2014 Template of Student page
|include=#IRC, #SoC Application
|includematch= ,/Submitted to google/s
|mode=userformat
|format=,,[[%PAGE%|%TITLE%]] ,
}}
=Result from Google acceptance=
List of proposals accepted by Google would be available on April 21st

Fosdem2014

2014-02-02T13:17:14Z

Timotei21: fix the links to previous fosdem pages

== General information ==
This page is meant to somehow coordinate the small Wesconf taking place at FOSDEM 2014. That is everyone attending should please list him/herself in the list of arrivals and stuff like this. FOSDEM 2014 will take place at the first weekend in Febuary 2014, on Saturday 1st and Sunday 2nd.

* Fosdem - http://fosdem.org/2014/

== Wesnoth Hacking Room ==

Wesnoth will not have a room of its own (though there will be the open source game dev devroom on Saturday where hopefully many Wesnoth devs will participate). Instead we will use one of the "general hacking rooms". So far it is not sure which room it will be, if we do it like the last three years, it will be room number 115 in the building AW1 (okay, new booklet is out, now it is AW1.124). Last year this was the smaller of the two hacking rooms and we had no real problem with conquering (and holding) the first row in this room. There were not too many power outlets, so this year at least Ivanovic will bring one multi-outlet power strip plus some extension cable (5m or something like this). Mordante will (hopefully) also bring a multi-outlet power strip and a 20m extension cable. There is no wired network, everything wireless (and sometimes rather/very unstable!). Beside this you should bring laptops since there are no computers available for hacking.

Short version:
AW1 - Room 117 (at least on Sunday)

== Discussions and Results ==
We usually discuss all sorts of things at FOSDEM, this section is basically a (really short) summary of things that were discussed including their results. First are the discussions that were done "in plenum" with basically all attendees around. At the bottom is an area meant for discussions that were held in sub groups that not all devs might be aware of that were around.

Below you can find a list of things we discussed and that were done during FOSDEM.

===GSOC 2014===
Discussion if we want to participate in GSOC 2014. First question were possible mentors. Here is a list of the people who were around and somehow willing / able to take on students:

Willing to mentor a "full student":
* Fendrin
* AI
* Trademark

Willing to mentor a student with some other (mentors) support:
* Crab
* Mordante
* Thunderstruck

Proposed candidates to mentor who were not around to oppose:
* Shadowm
* mattsc
* timotei

Basic decision was that we would like to try to participate in GSoC. Now we "just" need to find ideas. Proposals:
* Eclipse UMC plugin (adjustments to new editor feature) (fendrin)
* Add-On server related tasks (Trademark)
* AI tasks
* Game engine and MP campaign support improvements (e.g. interface cleanup)
* Work on the ingame help
* AddOns for the editor (fendrin)
* Work on things helping the ladder community (competitive gameplay) without creating bad competitiveness in our MP server
* Better support for "extra resources" (to harvest / collect) to be usable for UMC creators in addition to the existing gold
* Check old project list for usable stuff

More ideas are always welcome. The details will need to be written and more discussion should take place on the ML, in the forums and in IRC.

===SDL2 / OpenGL===
Does the migration to SDL2 make sense? Reason against is that Debian stable does not support it (yet) but it is in testing. Mobile ports like iPhone / Android significantly benefit from it. Gamepad support is also improved. Valve hired the person who started SDL and is heavily pushing for it, too.

It will be a lot of work to really make it work. One interesting question is if we directly want to move our rendering engine for OpenGL. When moving to OpenGL we will probably have to touch the rendering engine anyway.

Moving to OpenGL will create even more work overall, but since it was talked about for ages this would be a good option to finally get to it. Yes, the early builds will not be as perfect as they could be, but it should be good enough for a start... Mordante already stated that he would be interested to look into it.

The switch to OpenGL also is a great time where we can clean up some ancient parts of the code. E.g. we still have OS2, AmigaOS and BeOS related ifdefs in our code. Those which are no longer supported should be removed. If we find further ones, those should also be removed. Thanks to version control things can still be restored/reimplemented once the ports get active again.

===Next stable release===
We want to participate in GSoC. This means we need to handle things a little differently regarding string and feature freeze. The proposal is as follows:
# Get the last string and feature changes into git master until Saturday, February 22nd.
# On February 23rd: release of "first beta" and branch off from master to "1.12 series branch".
# Stabilization for 2 month in this 1.12 branch, in parallel normal development going on in master (but devs should focus on bugfixes where possible while Mordante breaks master with libsdl2/OpenGL changes)
# Release of 1.12 at the end of April / beginning of May.

===Add-On Server===
The add-on servers content list is a mess right now. It is really difficult to find the "good" content vs the bad/broken content.

Possible solutions:
* Connection to some forum thread where "polling" takes place.
* Make it a "database" separate to the add-on server in which "votes" can be stored. Possible votes:
** "I like it"
** "I dislike it"
** "It is broken"
** "It is inappropriate"
** "Star based rating"
* separate add-on servers, one for known good content, one for new / experimental (probably not good because the experimental server will get almost no visits)
* add a flag to known good add-ons showing them as "recommended by the team" ("team" e.g. based on trusted forum users)

How to handle "outdated" votes. Votes / comments could be weighted based on age of the vote.

What we need to do next is decide which steps we should take and what would make most sense. Looking at the current list of add-ons at the server we could use some better ways to handle things because otherwise there is just too much to find good content "fast". We can't expect users to first visit 30 forum threads to find the decent add-ons.

===Mapformat===
Proposal to drop the following from the format of the map_data tag:
* usage=
* border_size=

The reason is that border_size is assumed to be 1 for mainline, otherwise some parts will break. Usage is always map, so there is no need to separate it. For cases where "=mask" a different WML tag is used already. This proposed change basically means that the wesnoth map editor will no longer write the tag. If the lines exist, the engine will just ignore them as it basically does right now.

===Server infrastructure===
The old server costs more than $1500 a year. It is only used for email right now. This is too much which is why the contract will be terminated. All services which are still left on the old machine will be lost unless someone ports them. AI already mentioned in IRC that he can work on migrating the mail setup.

===GUI / input handling===
The ingame help (unit descriptions) suck right now. it neither works well on large screens nor on small ones. The portraits use a lot of space (they are gorgeous!) and improved placement could improve this dialog. While changing something there we should directly consider moving to GUI2. This would mean the helpbrowser needs to be converted to GUI2.

Add-Ons should be able to add/modify things in the helpbrowser. This e.g. means that changed unit properties should somehow be reflected nicely in the sidebar and the help or the help entries should at least be marked that they feature the "base unit" / information and not the changed one. Mainline already does some stuff there, but it is a more pressing need for Add-Ons where the unit modifications can be changing many more things.

What about the "final" complete move to GUI2? The problem is that we either need to clone Mordante or find more people able to help with it and really cooperate on it. What is missing right now are improved listboxes and dynamic content is problematic. Besides tab-support is completely missing. Radio buttons are "sort of implemented" but it should be possible to easily implement them for real as listboxes. Once the foundation is laid many dialogs need to be converted. Replacing theme WML by GUI2 elements is still far away and a huge tasks which requires special widgets.

Besides it is not trivial to change the UI. Other systems like Qt or GTK often offer graphical editors to define the UI setup to ease the creation of the interface definition. Afterwards textual changes are still possible but often not required.

Overall work on GUI2 should probably be handled after the work on SDL2 / OpenGL because rendering is heavily influencing GUI2. If we decide to move to SDL2 / OpenGL it make sense to first get this done and then continue work on the GUI2.

===SOCI / Add-On Server (Deamon)===
The add-on server could be a 'side project' not directly integrated in the Wesnoth codebase. It still needs to be able to run on our own server which uses Debian stable. Trademark would like to use C++11 for the add-on server. This would be a reason for splitting it from the game but we still have the problem that we need to add some extra / more recent libs if C++11 was used. Right now the add-on server is not reusable for other projects which is a reason for keeping it in our base. The question is basically how well we can separate the add-on server from the game and if there would really be a different user for the system.

It might be a good idea to use the add-on server as a testbed for C++11. This would be the start of using it in Wesnoth but would first give us an idea about how the code looks and how well it works. We will need to think about how to move existing code and if to move "mainline" code over to C++11 (plus when).

The conclusion was that we can keep the add-on server in our server for the moment. If we really find it is reusable for other projects we can still move it outside of the wesnoth repository. We just need to make sure to keep it "separated" somehow in our codebase. But splitting it is not the main goal.

Trademark will complete this entry later on after further discussion.

===How to improve communication with 'external'===
People agreed that it would make sense to e.g. have some kind of "devblog". The question is who is going to write content. Probably everyone with commit access should be allowed to write something. If someone without commit access wants to write something, we should provide some focal points who would then publish it as "3rd party" post. Every developer should be encouraged to write posts about important things (like groundbreaking changes). It would be great if we had someone review the posts to ensure "valid English" is used. This would be best handled by a native English speaker (with writing skills) since we are talking about our external appearance. Maybe we can find someone on the forums who would like to help with this?

===Datamining for content feedback===
Fendrin mentioned that it might make sense to get back the old campaign stats system. The agreement was that if we reactivate this, we should start with a small dataset like "turns to win, loses, wins". The related problems here are the visualization of the data as well the question how many people will make use of the data. If many use it and we got a good way to show it we could extend upon it.

It should be possible to develop it for a current session since e.g. UMC developer or mainline developer will do lots of save-loading. Data privacy concerns enforce that we only collect anonymous data and can easily opt-out.

===Bugtracker / single login===
Currently the bugtracker is still at gna.org. This is not well integrated with our repository. It is possible to get the data out of gna. Crab already has done so and was able to basically get such an export working. Afterwards it should be possible to migrate to a different system. This was not tried yet because Crab did not know where to put it.

A proposal is to export it to redmine and host the bugtracker ourselves on Baldras. On the longterm we might think about creating some single login. Right now Jenkins is already using the github credentials. On the other hand the forum login is already shared with the multiplayer server. Currently we host wiki, forum and mp server. It would be desirable to have some single login available. A concern is the data safety with the wiki. What should not be shared is login credentials that work with the wiki and login credentials that allow login to the server itself via SSH.

The question is how we want to handle github, Jenkins and the bugtracker. Here it might make sense to use the github credentials.

This would result in two sets of credentials per (average) developer:
* github, Jenkins, bugtracker (currently discussed: Redmine)
* forum, wiki, mp server, (maybe) add-on server (if concept changes)

What would be an option for this list is to allow users use their forum credentials to login to the bugtracker (if this is technically possible and not conflicting with using github credentials).

Server administrators would in addition have an SSH login to our server. Access to the server is still to be handled by the main server admin(s).

We will need someone to volunteer help setup parts in this and get things together so that everything works nicely.

===Culture of discussion===
Several of us have the impression that the mood has become a lot more aggressive and negative. This does not only affect the forums with "non developers" but also the IRC chan. This leads to a reduced motivation and a barrier to implementing required changes. The impression also is that some developers join the discussions without first trying to understand what the topic is and providing productive feedback. One example for this is the git move. We had a long discussion and decided to move to sourceforge. Someone came up with "uhm, we could recontact the github folks" and then suddenly, without further discussion, we switch to github with results like a missing commit email list. This can lead to hurt feelings resulting in people reconsidering if they want to spend their time for the project.

The question here is how we can work together in a more constructive way? We will always come to points where we disagree on a topic and can't find a consensus. It is probably a bad idea to just fork the project and have two games as a result which do extremely similar things. It is especially important that nobody feels threatened with things like "we could remove your commit privileges if you don't give in". As far as we over here are aware we are all peers with no clearly defined "management infrastructure" which will always have the last word. In the past we sometimes asked Dave for help in situations where reaching a consensus was not possible but we should face that he is no longer active in the project.

So do we perhaps need to find and define someone as "decision leader" in case we end in a stalemate? This would *only* be valid for case where a stalemate is reached otherwise and the position would not be based on the tasks handled in the project (e.g. releases, administration, coding, artwork, ...). This can only make sense if we discuss things on a technical level wherever possible. Since we are a game it is hard to keep out the social perspective among our users, but we should not base it on the social interactions between developers.

In general it might be a good idea to come back to discussing larger changes in the open upfront. Here we need to make sure to keep the discussion open and not directly have everyone else jump in shutting down any attempt based on "we have always done it this way" or "I don't like it because I don't like it because I don't like it ...".

== Group Picture ==
No group picture was taken during FOSDEM 2014.

== Previous Years ==
* [http://www.wesnoth.org/wiki/Fosdem2013 FOSDEM 2013 wiki page]
* [http://www.wesnoth.org/wiki/Fosdem2012 FOSDEM 2012 wiki page]
* [http://www.wesnoth.org/wiki/Fosdem2011 FOSDEM 2011 wiki page]
* [http://www.wesnoth.org/wiki/Fosdem2010 FOSDEM 2010 wiki page]
* [http://www.wesnoth.org/wiki/Fosdem2009 FOSDEM 2009 wiki page]
* [http://www.wesnoth.org/wiki/Fosdem2008 2008 wiki page], [http://www.wesnoth.org/forum/viewtopic.php?p=283649#p283649 Forum topic (with group photo)], [https://mail.gna.org/public/wesnoth-dev/2008-02/msg00078.html Summary of FOSDEM 2008 results]

[[Category:Development]]
[[Category:Wesconf]]

GSoC 2011 Sytyi

2013-10-14T11:13:36Z

Timotei21:

{{SoC2011Student_2|Sytyi|SoC_Ideas_Schema_Validation2011}}
== Description ==
<h4>Sytyi - WML Validator</h4>
The main idea of WML Validator is grammar based validator on C++ generating '''USER-FRIENDLY''' error messages in gcc style.

==IRC==
Sytyi
== Contacts ==
'''IRC:''' Sytyi 
'''E-mail:''' nsytyi[at]gmail.com 
'''Skype''': azcure 
'''ICQ:''' four-zero-six-one-four-four-one-seven-four 

== Proposal Summary ==
I want to write a grammar based validator. One tool will prepare schema file containing all tags, keys and possible values from annotated source. Validator will read schema file on the beginning of the work and then, while parsing, just compare is this value allowed in this place.

Main idea is the hierarchical structure. Data storing allows to check key value, just by comparing with possible values. Also some simple types as string, integer, boolean can be possible too.

There are two problems:
# Tags with different specific but one name. I think hierarchy will solve this problem but make another one. Each tag will have
# Generally used tags like [action], [event], [filter]. They will be organized in global list. And list tags will have they mentioned. With this, hierarchy is broken a little, but it is still not graph in the widely understanding.

I also want to include Schema Generator in build system.
I suppose, SG to update schema file, not to "delete-and-again" generation. It is possible cause of using hierarchy tag structure and annotations.
WIP proof-on-concept SG example here https://gna.org/patch/?2636

== Format of annotations and schema file ==
See [[WML_Annotation_Format]] for details.

== How It All Work? ==
After a patch the developer runs SchemaGeneratorTool to regenerate schema file. I want to include the special build target in building system, trying to avoid the whole regenerating, only current updates.
Also see [[ValidationDesign]]

If somebody want to validate his WML document he runs ValidatorTool, and receives Error Messages like
source-file-name:lineno:column: In file %filename
source-file-name:lineno:column: in toplevel tag [scenario]
source-file-name:lineno:column: Mandatory key "id" is misssing
source-file-name:lineno:column: in tag [side]
source-file-name:lineno:column: Mandatory key "side" is misssing
source-file-name:lineno:column: Unknown value in key "controller" %wrong_value found, but %value_list possible

== Build System ==
I want to include Schema generating tool to build systems. This is not preference idea, only an add-on part. I want to make schema file refreshable (one source file was changed and only that part of schema will be updated), not "delete-and-again", but there are a few problems. If a tag or a key is removed from the source, how th SGT know about it? I think two ways: one to add source files names to schema file (this can be a little help to developer, trying to fix some bugs in code ), and second: to add special annotation to deleted keys.

== Timeline ==
8.04 - 22.05 Getting into the project time 
Improving annotations list. Getting as close as possible to WML documents. Studying how parser works.

23.05 - 30.06 Schema generating tool 
I have exams in this period of time, and max number of exams can be 5, so I can't plan much more. And I even have no timeline of exams, it will be available only in June.
#23.05 - 15.06 Annotation parsing part. 
#16.06 - 30.06 Schema generating part. 

1.07 - 15.08 Document validating tool 
# 1.07 - 10.07 Hierarchy structures.
# 11.07 - 25.07 Document parsing part.
# 26.07 - 5.08 Validation.
# 6.08 - 10.08 Data structures refactoring. (If nesessary).
# 10.08 - 15.08 Errors messages generating part.
# 15.08 - 20.08 Testing. Fixing bugs.

16.08 - 31.08 Afterwork 
#Testing 
#Fixing bugs 
#Documentation 

<If any time left> 
Improving build-systems integration, making more error types.

In far future 
Maybe a validator for unpreprocessed WML.

== Stages ==

{| border="1"
! ID
! PART OF
! NAME
! PRIORITY
! LAST FINISH TIME
! STATUS
|-
| 0
|
| Proof-of-concept patch
| GREATEST
| 15.04
| IN PROCESS
|-
|
|
| MILESTONE = "PREPARE"
| GREAT
| 23.05
|
|-
| 1
| PREPARE
| annotate a part of existing code
| IMPORTANT
| 23.05
| 90%
|-
| 2
| PREPARE
| improve annotations list due to nessesarity. view stage 2
| VERY IMPORTANT
| 23.05
| 90%
|-
| 3
| PREPARE
| write documentation and examples of annotations in wiki
| BASIC
| 23.05
| 90%
|-
|
|
| MILESTONE = SCHEMA GENERATOR
| GREAT
| 30.06
|
|-
| 1
| SG
| IMPLEMENTATION working mainstream source to SG
| BASIC
| 20.06
| 90% NEED REVISION
|-
| 2
| SG
| [[WML_Annotation_Format|DOCUMENTATION]] including extended examples of annotations, algorithm describing, and list of used regexes
| BASIC
| 30.06
| 60%
|-
| 3
| SG
| global tags support
| BASIC
| 30.06
| 100%
|-
|
|
| MILESTONE = VALIDATOR
| GREAT
| 15.08
|
|-
| 1
| VALIDATOR
| parsing schema file. Build wml tags tree
| BASIC
| 10.07
| 100%
|-
| 2
| VALIDATOR
| parsing wml file part. Using /src/serialisation/ (Optionally)
| BASIC
| 25.07
| NEED DISCUSSION
|-
| 3
| VALIDATOR
| checking against tree.
| BASIC
| 5.08
| 10%
|-
| 4
| VALIDATOR
| generating gcc-style errors implementation
| BASIC
| 15.08
| 5%
|-
| 5
| VALIDATOR
| working tool
| BASIC
| 15.08
|
|-
| 6
| VALIDATOR
| documentation about data containers, hierarchy, algorithms and input/output specification.
| BASIC
| 25.08
|
|-
|
| SG
| BUILD system support
| ADDITIONAL
|
| NEED DISCUSSION
|-
|
| SG
| refreshable schema file support
| ADDITIONAL
| NOT NEEDED
|
|-
|
| SG
| extend error messages
| ADDITIONAL
|
|
|-
|}

BASIC PRIORITY means that milestone without that stage just cannot be mentioned
The milestones after 30.06 schould be improved with more information, non mainstream milestones and so one. It's a bit hard nowadays. The more work - the more problems I explore.

== Patches and commits ==
No one at this moment of time.

==Answers to those questions==
<h3>Basics</h3>

Write a small introduction to yourself. 
Hello. My name is Nick Sytyi . I study Computer Engineering at the Chernigiv Technological University. I want to participate in Google Summer of Code and gain expierence in C++ and game development. I like this project and I want to encahnce it.

1.2) State your preferred email address. 
nsytyi@gmail.com

1.3) If you have chosen a nick for IRC and Wesnoth forums, what is it? 
IRC: Sytyi 
Wesnoth forums: none for now
Wesnoth wiki: Sytyi 
GNA: sytyi 

1.4) Why do you want to participate in summer of code? 
I would like to try some serious work. I want to grow in C++ development, open source, team work and game development experience.
I think the experience I gain here, will help me in future.
I hope I come in project for long period of my life, because it is my dream (to develop a game) since when I was child.

1.5) What are you studying, subject, level and school? 
Computer Engineering, 3rd year Faculty of Electronic Informational Technologies, Chernigiv Technological University, Ukraine.

1.6) If you have contributed any patches to Wesnoth, please list them below. You can also list patches that have been submitted but not committed yet and patches that have not been specifically written for Wesnoth. If you have gained commit access to our SVN (during the evaluation period or earlier) please state so. 

No patches for now. Maybe the situation will change for better.

<h3>Experience</h3>
good knowledge of C++, Java, computer science concepts, small experience of programming translators, olympiad projects with MCS-51 and AVR stends (I know it is insignificant but it gave me experience in quick, well synchronized C programs).

2.1) What programs/software have you worked on before? 
Mostly, I'am working on website development using Java EE. Also, I've done little C++ projects writing simple data manipulating programs.

2.2) Have you developed software in a team environment before? (As opposed to hacking on something on your own) 
Yes. Our university has command projects, and now I am a team leader for a simple course work So I was to learn SVN features.

2.3) Have you participated to the Google Summer of Code before? As a mentor or a student? In what project? Were you successful? If not, why? 
I haven't participated in the GSoC before. This is my first chance to participate.

2.4) Open Source 

2.4.1) Are you already involved with any open source development projects? If yes, please describe the project and the scope of your involvement. 

I use Ubuntu, Mozilla, Eclipse, Qt , but Wesnoth is the first open source project I am involved with.

2.5) Gaming experience - Are you a gamer? 
Yes, I am a gamer )

2.5.1) What type of gamer are you? 
Slow strategic gamer.

2.5.2) What type of games? 
I prefer turn-based strategy games or RPG with good story.

2.5.3) What type of opponents do you prefer? 
I can’t say I play good. So I prefer good opponents which sometimes teach me some tricks. When I’m beaten, I analyze, why this occurred.

2.5.4) Are you more interested in story or gameplay? 
Story is more interesting for me. But if gameplay is very booooring ………….

2.5.5) Have you played Wesnoth? If so, tell us roughly for how long and whether you lean towards single player or multiplayer.
We do not plan to favor Wesnoth players as such, but some particular projects require a good feeling for the game which is hard to get without having played intensively. 
I have heard about Wesnoth first time at 18 March. It interested me, and sometimes, when I need a rest, I play a little.

<h3>Communication skills</h3>

3.1) Though most of our developers are not native English speakers, English is the project's working language. Describe your fluency level in written English. 
I can read and write English with few mistakes.

3.2) Are you good at interacting with other players? Our developer community is friendly, but the player community can be a bit rough. 
I just ignore rough statements in address. In a team I takes the second role.

3.3) Do you give constructive advice? 
Maybe. Sometimes.

3.4) Do you receive advice well? 
Yes

3.5) Are you good at sorting useful criticisms from useless ones? 
Yes

<h3>Project</h3>

4.1) Did you select a project from our list? If that is the case, what project did you select? What do you want to especially concentrate on? 
Yes. It is interesting to make tools for non-programmers content developers. I want to concentrate on grammar of WML. And if I have free time after all of this, maybe a simple WML GUI or including WML validation into existing GUI’s.

4.2) If you have invented your own project, please describe the project and the scope. 

4.3) Why did you choose this project? 
When I studied Google list of participating organizations, I read about your game first, I played a little, and then I want to enchance project.
I am interesting in translations. WML validation seemed to me a perfect task to study the main project and a perfect task for a starter not confident in his abilities.

4.4) Include an estimated timeline for your work on the project. Don't forget to mention special things like "I booked holidays between A and B" and "I got an exam at ABC and won't be doing much then". 
I'll have 4 or 5 exams in June, but I hope to pass 3 of them out by auto. 
3-4 days in archaelogic expedition near 15 of August. 
Two times 3-4 days on bike down the river in July. I can not say current time now, it depends on the last exam and my friends. More possible it will be after stipendy at 25 of each month 

4.5) Include as much technical detail about your implementation as you can 
I want to write two tools. One to generate Schema file from the annotated source. and another to validate WML documents using schema. Tags are organized in a hierarchical structure. 
4.6) What do you expect to gain from this project? 
I expect to gain experience in game development and maybe a continious work with Wesnoth.

4.7) What would make you stay in the Wesnoth community after the conclusion of SOC? 
Willing to “upgrade” myself. To know more. To work with interesting people on the interesting tasks.

<h3>Practical considerations</h3>

5.1) Are you familiar with any of the following tools or languages? 

* Subversion (used for all commits) Yes. 
* C++ (language used for all the normal source code)Yes STL. QT. 
* Python (optional, mainly used for tools) no. 
* build environments (eg cmake/autotools/scons) 'make' - yes, 'scons' no. 'autotools' - no 
I don't know LUA and i'm studying WML now. 
5.2) Which tools do you normally use for development? Why do you use them? 
Eclipse under Windows and Ubuntu. Qt. Notepad.

5.3) What programming languages are you fluent in? 
I have a little practice in Java (1 years of experience) and C/C++ (2 years of experience)
I know a bit of sh/javascript/pascal/c

5.4) What spoken languages are you fluent in? 
I can speak in Ukrainian (native), in Russian (native), English.

5.5) At what hours are you awake and when will you be able to be in IRC (please specify in UTC) 
I'm in UTC+3 timezone in summer. I am normally awake from +11 UTC to +02 UTC, and most of that time I'm at home or some anywhere with wi-fi, so I'm able to be in IRC.

5.6) Would you mind talking with your mentor on telephone / internet phone? We would like to have a backup way for communications for the case that somehow emails and IRC do fail. 
Skype : azcure

== Grammar ==
I wrote grammar cause of misunderstood. So it does not influence the main idea, etc. But it may be useful to some people.

Grammar needs some improvements in types of key values, but the main work is done. If you see any mistake here, please contact me 
EBNF form for unpreprocessed WML http://en.wikipedia.org/wiki/EBNF 

Document = [ Header ], { StmntList } ;
StmntList = Statement, EOL, { StmntList } ;
Statement = { ( Tag | MacroCall | MacroDefine | TextDomain | PreprocIf ) } ;
Tag = TagStart { ( Tag | Key | MacroCall | MacroDefine | TextDomain | PreprocIf ) }, TagEnd ;
Key = Name, { Name} ,"=", KeyValue, { KeyValue }, EOL;
MacroCall = "{", Name," ",{ " " }, MacroValue {, MacroValue} , "}"
MacroDefine = DEFINE, Name, MacroVar {, MacroVar} , StmntList, "ENDDEF";
TextDomain = "#textdomain ", Name ;
PreprocIf = (IFBegin, StmntList, [IFElse, StmntList,] IFEnd) | (Undef, MacroName);
TagStart = "[",[ "+" ], TagName , "]" ;
TagEnd = "[/", TagName ,"]" ;
(* Can TagName contain uppercase? *)
TagName = LowerCaseLetter | "_", { LowerCaseLetter | Special | "_"};
KeyValue = ( Name | Substitution | Strings );
Substitution = "$", (Name | Formula) ;
Formula = "(", Name, ")" ;
MacroVar = Name;
IFBegin = "#ifdef " | "#ifhave " | "#ifndef " | "#ifnhave " | "#ifver " | "#ifnver " ;
IFElse = "#else " ;
IFEnd = "#endif" ;
DEFINE = "#define " ;
ENDDEF = "#enddef" ;
Name = Letter, { Letter };
Identifier = Letter, { Letter | Digit | Special };
Strings = ( String | TranslatedString ), { "+", ( String | TranslatedString ) };
String = '"', { ( Letter | Digit | Symbols) },'"';
TranslatedString = "_", String;
Letter = (UpperCaseLetter | LowerCaseletter | "_" );
UpperCaseLetter = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z" ;
LowerCaseLetter = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" ;
Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;
Sign = "+" | "-" ;
WhiteSpace = " " | "\t" , { " " | "\t" } ;
Special = "-" | ":" ;
EOL = { "\r" }, "\n" , { "\r"|"\n" }

EBNF form for preprocessed WML 

Document = [ Header ], { StmntList } ;
StmntList = Statement, EOL, { StmntList } ;
Statement = { ( Tag | TextDomain ) } ;
Tag = TagStart { ( Tag | Key ) }, TagEnd ;
Key = Name, { Name} ,"=", KeyValue, { KeyValue }, EOL;
TextDomain = "#textdomain ", Name ;
TagStart = "[",[ "+" ], TagName , "]" ;
TagEnd = "[/", TagName ,"]" ;
(* Can TagName contain uppercase? *)
TagName = LowerCaseLetter | "_", { LowerCaseLetter | Special | "_"};
KeyValue = ( Name | Substitution | Strings );
Substitution = "$", (Name | Formula) ;
Formula = "(", Name, ")" ;
Name = Letter, { Letter };
Identifier = Letter, { Letter | Digit | Special };
Strings = ( String | TranslatedString ), { "+", ( String | TranslatedString ) };
String = '"', { ( Letter | Digit | Symbols) },'"';
TranslatedString = "_", String;
Letter = (UpperCaseLetter | LowerCaseletter | "_" );
UpperCaseLetter = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z" ;
LowerCaseLetter = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" ;
Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;
Sign = "+" | "-" ;
WhiteSpace = " " | "\t" , { " " | "\t" } ;
Special = "-" | ":" ;
EOL = { "\r" }, "\n" , { "\r"|"\n" }

[[Category:Summer of Code]]

=SoC Application=
[http://www.google-melange.com/gsoc/proposal/review/google/gsoc2011/nicksytyi/1 - Battle for Wesnoth - Google Summer of Code Application]

PreprocessorRef

2012-07-12T18:58:58Z

Timotei21: Misc fixes

{{WML Tags}}
== Overview ==

Wesnoth loads just one configuration file directly: '''data/_main.cfg'''. However the '''WML preprocessor''' allows to include more files. Whenever a WML file is read by Wesnoth, it is passed through the preprocessor.

The preprocessor can interpret a simple language of string expansions known as ''macros''. A macro should always be defined '''before''' the place where it needs to be used.

The preprocessor is applied recursively, so included files will be parsed for macros, and after macro expansion will be parsed for macros again, and so on. As a result, you should not write a recursive macro that references itself, because it will cause errors (but, alas, not necessarily error messages).

== Preprocessor directives ==

The following directives are used to create and use ''macros'', i.e. shortcuts which reduce repetition of information. See [http://www.wesnoth.org/macro-reference.xhtml the macro reference] for the list of predefined core macros.

The preprocessor has changed several times, so don't expect old Wesnoth versions to behave exactly the same as the current stable and development series.

'''Note:''' In multiplayer scenarios, these directives will appear to work only for the host and not for other clients. This is because the preprocessor is run only on the host, and the clients receive the resultant WML from the server. It's particularly important to keep this in mind before using preprocessor conditionals.

=== #define ===

'''Syntax: #define ''symbol'' [''parameters''] ''<newline>'' ''substitution'' #enddef'''

All subsequent occurences of '''{''symbol'' [''arguments'']}''' (see below) will be replaced by the contents of the ''substitution'' block, with all occurrences of any parameter {''parameter''} within ''substitution'' replaced by the corresponding value in ''arguments''. For example, the ENEMY_UNIT macro for the [[#Macro inclusions|macro inclusion]] example below could be defined as follows:

#define ENEMY_UNIT TYPE X Y
## the ordering above is important, since the preprocessor does not distinguish
## data into different types; only the ordering is used to determine which
## arguments apply to which parameters.
[unit]
type={TYPE} ## the unit will be of type TYPE, so different
## instantiations
## of this macro can create different units.
x={X}
y={Y}
side=2 ## the unit will be an enemy, regardless of the parameter
## values. This reduces "repetition of information",
## since it is no longer necessary to specify
## each created unit as an enemy.
[/unit]
#enddef

(See [[SingleUnitWML]] for further information on creating units using WML.)

=== #undef ===

'''Syntax:''' '''#undef ''symbol'' '''

Removes the previous definition of the macro named ''symbol''.

=== Inclusion directive {} ===

This directive can be used to include macros, single files or sets of files from a target directory.

==== File/directory inclusions ====

'''Syntax: {''path''}'''

Includes the file with the specified ''path'', which will in turn run the preprocessor on it and perform any required substitutions or inclusions within it. The ''path'' may not contain ''..'' or the inclusion will be skipped.

The exact location in which the ''path'' will be resolved will depend on its prefix:

* '''{''path''}''': If ''path'' isn't a known macro (see below), the game will assume it's a relative path to a file in the main game '''data/''' directory and include it.
* '''{~''path''}''': As above, but instead of the game data directory, the path is resolved relative to the user '''data/''' directory, where user made add-ons can normally be found.
* '''{./''path''}''': The path is resolved relative to the location of the current file containing this inclusion.

Information for locating the user data and game data directories can be found in [[EditingWesnoth]].

Forward slashes ('''/''') should '''always''' be used as the path delimiter, even if your platform uses a different symbol such as colons (''':''') or backslashes ('''\''')! It is also very important to respect the '''actual letter case''' used to name files and directories for compatibility with case-sensitive filesystems on Unix-based operating systems.

When ''path'' points to a directory instead of a file, the preprocessor will include all files found within with the '''.cfg''' extension, in alphabetical order; files without this extension (such as '''.map''' or '''.png''' files) are ignored.

Some directories are handled in a special fashion according to their contents:

* If there's a file named '''_main.cfg''' in the target directory, only that file will be included and preprocessed. It may include other files from its own directory or subdirectories within it, of course. This is used for managing WML directories as self-contained packages, like user made add-ons.
* If there are files named '''_main.cfg''' in subdirectories of the target and there isn't one in the target itself, they will be all preprocessed. Given the following layout:
dir/
dir/a/_main.cfg
dir/a/other.cfg
dir/b/_main.cfg
dir/b/other.cfg
dir/other.cfg
Using '''{dir}''' will cause dir/a/_main.cfg, dir/b/_main.cfg and dir/other.cfg to be included.
* If there's a file named '''_final.cfg''' but no '''_main.cfg''', the file is guaranteed to be included and processed ''after'' all the other files in the directory.
* If there's a file named '''_initial.cfg''' but no '''_main.cfg''', the file is guaranteed to be included and processed ''before'' all the other files in the directory.

==== Macro inclusions ====

'''Syntax: {''symbol'' [''arguments'']}'''

If the macro named ''symbol'' is defined, the preprocessor will replace this instruction by the expression ''symbol'' was previously defined as, using ''arguments'' as parameters. The number of arguments must be exactly the same as in the original definition or an error will occur.

You can create multiple word arguments by using parentheses to delimit the contents. For example, in '''{ENEMY_UNIT Wolf Rider 18 24}''' the four words will be interpreted as separate arguments and cause the preprocessor to fail since the macro was defined above with only three; instead, you should use '''{ENEMY_UNIT (Wolf Rider) 18 24}'''.

Using the name of an existing macro as the name of a macro argument is possible, but the argument will always take precedence over the original macro:

#define VARIABLE
#enddef
#define MACRO VARIABLE
{VARIABLE} # is calling for the argument, not for the macro above
#enddef

=== #ifdef and #ifndef ===

Unlike the other preprocessor directives, '''#ifdef''' and '''#ifndef''' are not mere conveniences. They are often necessary to distinguish between different gameplay modes or difficulties (see [[#Built-in macros|Built-in macros]] below).

'''Syntax:''' '''#ifdef ''symbol'' ''substitution-if-defined'' [#else ''substitution-if-not-defined'' ] #endif'''

If ''symbol'' has been defined with '''#define''' or as a built-in macro, the whole block will be replaced by ''substitution-if-stored''. If not, it will be replaced by ''substitution-if-not-stored'' if it is available.

'''#ifndef''' is the exact opposite of '''#ifdef''', reversing the logic:

'''Syntax:''' '''#ifndef ''symbol'' ''substitution-if-not-stored'' [#else ''substitution-if-stored''] #endif'''

=== #ifhave and #ifnhave ===

'''Syntax:''' '''#ifhave ''path'' ''substitution-if-path-exists'' [#else ''substitution-if-path-does-not-exist''] #endif'''

Checks for the existence of a file. Uses the same relative paths as include directives (see below).

Example:

#ifhave ~add-ons/My_Addon/_main.cfg
{MY_ADDON_MACROS}
#endif

'''#ifnhave''' does the opposite of '''#ifhave''':

'''Syntax:''' '''#ifnhave ''path'' ''substitution-if-path-does-not-exist'' [#else ''substitution-if-path-exists''] #endif'''

=== #ifver and #ifnver ===

'''Syntax:''' '''#ifver ''symbol'' ''operator'' ''version-number'' ''<newline>'' ''substitution-if-condition-met'' [#else ''substitution-if-condition-not-met''] #endif'''

Compares a version number defined in a macro against an argument for conditional block inclusions, like ''#ifdef'' and ''#ifhave''. ''operator'' is one of ''=='' (equal), ''!='' (not equal), ''<'' (less), ''<='' (less or equal), ''>'' (greater), ''>='' (greater or equal). The specified ''symbol'' should have been previously defined as plain text without more macro inclusions within it, and it must not require any arguments.

Example:
#ifver WESNOTH_VERSION >= 1.9.7+svn
[message]
speaker=narrator
message= _ "I’m on Wesnoth 1.9.7+svn, 1.9.8 or later!"
[/message]
#else
#ifver WESNOTH_VERSION == 1.9.7
[message]
speaker=narrator
message= _ "I’m on Wesnoth 1.9.7, and I’ll include some workaround code for bug #9001!"
[/message]
#endif
#endif

'''#ifnver''' does the opposite of '''#ifver''':

'''Syntax:''' '''#ifnver ''symbol'' ''operator'' ''version-number'' ''<newline>'' ''substitution-if-condition-not-met'' [#else ''substitution-if-condition-met''] #endif'''

== Built-in macros ==

The following macros are automatically defined with empty contents (unless specified otherwise) by the game engine depending on the configuration or gameplay mode.

* A campaign define symbol (see ''define'' in [[CampaignWML]]): defined when playing a single-player campaign.
* A campaign difficulty level, usually '''EASY''', '''NORMAL''' or '''HARD''' (see ''difficulties'' in [[CampaignWML]]): defined according to the chosen difficulty when starting a single-player campaign, also stored in saved games.
* '''MULTIPLAYER''': defined when in multiplayer mode.
* '''TUTORIAL''': defined when playing the tutorial campaign.
* '''EDITOR''': defined when running the built-in map editor.
* '''DEBUG_MODE''': defined when the game has been launched in debug mode (i.e. with '''-d''' or '''--debug''' in the command line).
* '''APPLE''': defined while processing the main game data when running on Mac OS X.
* '''WESNOTH_VERSION''': defined containing just the game version number when running the WML preprocessor.

== Command-line preprocessor ==

'''Syntax: --preprocess ''<source file/directory>'' ''<target directory>'' '''

Or the short form:

'''Syntax: -p ''<source file/directory>'' ''<target directory>'' '''

You can specify a list of predefined defines with:

'''Syntax: --preprocess-defines=DEFINE1,DEFINE2,etc'''

comma separated list of defines to be used by '--preprocess' command. If 'SKIP_CORE' is in the define list the data/core won't be preprocessed.

The command will preprocess first the common config files in the main game ''data/'' directory, and afterwards the specified ones. You can specify a single file to be preprocessed (if you want to preprocess multiple separate files, you'll need to run a different command line for each one), or an entire directory, which will be preprocessed according to the rules used by the inclusion directive above.

The resulted preprocessed files will be written in the target directory. There will be two types of files: .cfg files --- the normal ones, and .plain files containing line markers and textdomain changes.

If by chance, the simple macro define doesn't suffice, you can use:

'''Syntax: --preprocess-input-macros <file>'''

To import an existing file that contains macros, and they will be available in the defines database before processing the specified files.

There is also the possibility to export the preprocessed defines/macro list with:

'''Syntax: --preprocess-output-macros [<target file>]'''

This file could be fed to the 'input-macros' argument next time you run it. For example, a scenario would be: parsing just the core first time, and for the intended target files, you would add SKIP_CORE but import the generated macros file - that will be faster than preprocessing the core again. If the target file is not specified, the output file will be _MACROS_.cfg in the target directory of the preprocess's command.

If ''file/directory'' and ''target directory'' are not absolute paths, they will be considered relative to the game's executable path.

Some examples:

* Preprocess the entire tutorial dir, and write the results in the ~/result folder:
-p ~/wesnoth/data/campaigns/tutorial ~/result
* Add the MULTIPLAYER define to the list and preprocess a scenario's config file:
-p ~/.wesnoth/data/add-ons/My_Campaign/scenarios/01_First_Scenario.cfg ~/result --preprocess-defines=MULTIPLAYER
* Add the MY_CAMPAIGN and HARD defines before preprocessing a campaign's files:
-p ~/.wesnoth/data/add-ons/My_Campaign ~/result --preprocess-defines=MY_CAMPAIGN,HARD

If you want a more detailed (and potentially overwhelming) log, you can simply add the switches '''--log-debug=all''' or '''--log-info=all''' to the command line, so you can see how things are preprocessed in detail.

== See Also ==

* [[SyntaxWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

Download

2012-01-29T19:25:02Z

Timotei21: /* UMC Editor */

{{Download/Translations}}
Welcome to the Battle for Wesnoth downloads page. The BFW project team only officially releases the source code. Binary packages are only provided by community volunteers and hosted here. Torrents are also unofficial.

If the latest binaries are not currently available for your OS, please check back in a few days to see if they have been placed here. Packagers have been informed of the release, please be patient. In the meantime, read the [[FAQ#A_new_version_is_out.2C_but_where_is_the_download_for_.5BWindows.2C_Mac_OS.2C_etc..5D.3F|FAQ]].

__NOTOC__
Jump to: [[Download#Stable_.281.10_branch.29|Stable Branch]] | [[Download#Stable_.28older_versions.29|Stable Branch (older versions)]] | [[Download#Development_.281.9_branch.29|Development Branch]]

== Stable (1.10 branch) ==
The stable files are meant to be used as a stable and rather balanced version of the game. Each version of the 1.10 branch is compatible to each other.

Version 1.10.0 is the latest stable version. This version is recommended for most players since the 1.10 online multiplayer community is very large and user-made campaign server has a robust content selection.

==== Source code ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.0/wesnoth-1.10.tar.bz2/download Current Version] (1.10.0, 324.2 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.9.14/wesnoth-1.9.14.tar.bz2/download Previous Version] (1.9.14, 323.6 MB)

* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== MS Windows ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.0/wesnoth-1.10-win32.exe/download Current Version] (1.10.0, 298.2 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.9.14/wesnoth-1.9.14-win32.exe/download Previous Version] (1.9.14, 298.1 MB)

==== Mac OS X (10.4+) ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.0/Wesnoth_1.10.dmg/download Current Version (for OSX 10.5+)] (1.10.0, 326.3 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.9.14/Wesnoth_1.9.14.dmg/download Previous Version (for OSX 10.5+)] (1.9.14, 325.4 MB)

==== GNU/Linux ====
* There are binaries for many different GNU/Linux Distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your Distribution.

==== OpenPandora ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.0/wesnoth-1.10-1.pnd/download Current Version] (1.10.0-1, 316.7 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.9.14/wesnoth-1.9.14-1.pnd/download Previous Version] (1.9.14-1, 316.3 MB)

==== Miscellaneous ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.0/wesnoth-1.10.tar.bz2.md5/download md5sum for current source code]
* [http://www.wesnoth.org/wiki/Download_Xdeltas#Stable_Version_1.10.x Xdelta for the source code]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]

== Stable (older versions) ==
Several operating systems do not offer a binary of the latest stable release. Here is a list of the latest known (stable version) binaries for various systems. For those older versions there often is no (official) multiplayer or addon server available anymore.

==== AmigaOS4 ====
* [http://www.amigasoft.net/pages/games/download/Wesnoth186.lha.lzh Older Version] (1.8.6, 300MB)

==== (Open)Solaris ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.4/wesnoth-1.4.5/wesnoth-solaris-i386-1.4.5.pkg.bz2/download Older Version] (1.4.5, 145.6 MB), not compatible with 1.6.x

==== OS/2 & eComStation ====
* [http://download.smedley.info/wesnoth-1.4.5-os2-20080828.zip Older Version] (1.4.5, 160 MB), not compatible with 1.6.x

==== RISC OS ====
*[http://www.riscos.info/packages/arm/Games/wesnoth_1.4.5-1.zip Older version] (1.4.5-1, 140MB), not compatible with 1.6.x

==== Syllable ====
* [http://downloads.syllable.org/Syllable/i586/applications/contributed/Battle-for-Wesnoth/Battle-for-Wesnoth-1.2.6.application Older Version] (1.2.6, 60.8 MB), not compatible with 1.6.x

== Development (1.9 branch) ==
Version 1.9.x is the latest development version, boasting updated graphics and new exciting features. However, there may be occasional bugs or performance problems in the development versions since heavy changes are taking place all the time. For balanced and stable gaming, it is recommended you use the latest version of the 1.8.x branch. This version is recommended for coders and campaign developers, as well as those who want to preview the future of Wesnoth. People familiar with SVN and compiling can follow the latest development by checking [[WesnothSVN]].

At this moment the successor of 1.9.x is available: 1.10.x. Please have a look above for this version of the game.

==== Source code ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.0/wesnoth-1.10.tar.bz2/download Current Version] (1.10.0, 324.2 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.9.14/wesnoth-1.9.14.tar.bz2/download Previous Version] (1.9.14, 323.6 MB)

* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== MS Windows ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.0/wesnoth-1.10-win32.exe/download Current Version] (1.10.0, 298.2 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.9.14/wesnoth-1.9.14-win32.exe/download Previous Version] (1.9.14, 298.1 MB)

==== Mac OS X (10.4+) ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.0/Wesnoth_1.10.dmg/download Current Version (for OSX 10.5+)] (1.10.0, 326.3 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.9.14/Wesnoth_1.9.14.dmg/download Previous Version (for OSX 10.5+)] (1.9.14, 325.4 MB)

==== GNU/Linux ====
* There are binaries for many different GNU/Linux Distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your Distribution.

==== OpenPandora ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.0/wesnoth-1.10-1.pnd/download Current Version] (1.10.0-1, 316.7 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.9.14/wesnoth-1.9.14-1.pnd/download Previous Version] (1.9.14-1, 316.3 MB)

==== Miscellaneous ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.0/wesnoth-1.10.tar.bz2.md5/download md5sum for current source code]
* [http://www.wesnoth.org/wiki/Download_Xdeltas#Development_Version_1.9.x Xdelta for the source code]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]
* [http://sourceforge.net/projects/wesnoth/files/unofficial/Mac%20Compile%20Stuff/wesnoth_compile_mac_1.9.zip/download MacCompileStuff for 1.9]

== License ==
''Main article: [[Wesnoth:Copyrights]]

This program is free software; you can redistribute it and/or modify it under the terms of the [http://www.fsf.org/copyleft/gpl.html GNU General Public License version 2], as published by the [http://www.fsf.org Free Software Foundation].
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

== UMC Editor ==
This is available with Wesnoth 1.9.x and greater (including Wesnoth 1.10.x).
Details and installation steps can be found at: http://eclipse.wesnoth.org

== See also ==
* [http://changelog.wesnoth.org Changelog]
* [[WesnothBinaries| More binaries]]
* [[WesnothSVN]] - bleeding edge version from SVN

[[Category:Building and Installing]]

Download

2012-01-29T19:24:05Z

Timotei21: /* UMC Editor */

{{Download/Translations}}
Welcome to the Battle for Wesnoth downloads page. The BFW project team only officially releases the source code. Binary packages are only provided by community volunteers and hosted here. Torrents are also unofficial.

If the latest binaries are not currently available for your OS, please check back in a few days to see if they have been placed here. Packagers have been informed of the release, please be patient. In the meantime, read the [[FAQ#A_new_version_is_out.2C_but_where_is_the_download_for_.5BWindows.2C_Mac_OS.2C_etc..5D.3F|FAQ]].

__NOTOC__
Jump to: [[Download#Stable_.281.10_branch.29|Stable Branch]] | [[Download#Stable_.28older_versions.29|Stable Branch (older versions)]] | [[Download#Development_.281.9_branch.29|Development Branch]]

== Stable (1.10 branch) ==
The stable files are meant to be used as a stable and rather balanced version of the game. Each version of the 1.10 branch is compatible to each other.

Version 1.10.0 is the latest stable version. This version is recommended for most players since the 1.10 online multiplayer community is very large and user-made campaign server has a robust content selection.

==== Source code ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.0/wesnoth-1.10.tar.bz2/download Current Version] (1.10.0, 324.2 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.9.14/wesnoth-1.9.14.tar.bz2/download Previous Version] (1.9.14, 323.6 MB)

* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== MS Windows ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.0/wesnoth-1.10-win32.exe/download Current Version] (1.10.0, 298.2 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.9.14/wesnoth-1.9.14-win32.exe/download Previous Version] (1.9.14, 298.1 MB)

==== Mac OS X (10.4+) ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.0/Wesnoth_1.10.dmg/download Current Version (for OSX 10.5+)] (1.10.0, 326.3 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.9.14/Wesnoth_1.9.14.dmg/download Previous Version (for OSX 10.5+)] (1.9.14, 325.4 MB)

==== GNU/Linux ====
* There are binaries for many different GNU/Linux Distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your Distribution.

==== OpenPandora ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.0/wesnoth-1.10-1.pnd/download Current Version] (1.10.0-1, 316.7 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.9.14/wesnoth-1.9.14-1.pnd/download Previous Version] (1.9.14-1, 316.3 MB)

==== Miscellaneous ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.0/wesnoth-1.10.tar.bz2.md5/download md5sum for current source code]
* [http://www.wesnoth.org/wiki/Download_Xdeltas#Stable_Version_1.10.x Xdelta for the source code]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]

== Stable (older versions) ==
Several operating systems do not offer a binary of the latest stable release. Here is a list of the latest known (stable version) binaries for various systems. For those older versions there often is no (official) multiplayer or addon server available anymore.

==== AmigaOS4 ====
* [http://www.amigasoft.net/pages/games/download/Wesnoth186.lha.lzh Older Version] (1.8.6, 300MB)

==== (Open)Solaris ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.4/wesnoth-1.4.5/wesnoth-solaris-i386-1.4.5.pkg.bz2/download Older Version] (1.4.5, 145.6 MB), not compatible with 1.6.x

==== OS/2 & eComStation ====
* [http://download.smedley.info/wesnoth-1.4.5-os2-20080828.zip Older Version] (1.4.5, 160 MB), not compatible with 1.6.x

==== RISC OS ====
*[http://www.riscos.info/packages/arm/Games/wesnoth_1.4.5-1.zip Older version] (1.4.5-1, 140MB), not compatible with 1.6.x

==== Syllable ====
* [http://downloads.syllable.org/Syllable/i586/applications/contributed/Battle-for-Wesnoth/Battle-for-Wesnoth-1.2.6.application Older Version] (1.2.6, 60.8 MB), not compatible with 1.6.x

== Development (1.9 branch) ==
Version 1.9.x is the latest development version, boasting updated graphics and new exciting features. However, there may be occasional bugs or performance problems in the development versions since heavy changes are taking place all the time. For balanced and stable gaming, it is recommended you use the latest version of the 1.8.x branch. This version is recommended for coders and campaign developers, as well as those who want to preview the future of Wesnoth. People familiar with SVN and compiling can follow the latest development by checking [[WesnothSVN]].

At this moment the successor of 1.9.x is available: 1.10.x. Please have a look above for this version of the game.

==== Source code ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.0/wesnoth-1.10.tar.bz2/download Current Version] (1.10.0, 324.2 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.9.14/wesnoth-1.9.14.tar.bz2/download Previous Version] (1.9.14, 323.6 MB)

* [[CompilingWesnoth|Compiling Guide]] - how to compile the source code

==== MS Windows ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.0/wesnoth-1.10-win32.exe/download Current Version] (1.10.0, 298.2 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.9.14/wesnoth-1.9.14-win32.exe/download Previous Version] (1.9.14, 298.1 MB)

==== Mac OS X (10.4+) ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.0/Wesnoth_1.10.dmg/download Current Version (for OSX 10.5+)] (1.10.0, 326.3 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.9.14/Wesnoth_1.9.14.dmg/download Previous Version (for OSX 10.5+)] (1.9.14, 325.4 MB)

==== GNU/Linux ====
* There are binaries for many different GNU/Linux Distributions. Not all are always up to date with the current release. Please have a look at the [[WesnothBinariesLinux|Linux binary page]] for more information about the binaries for your Distribution.

==== OpenPandora ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.0/wesnoth-1.10-1.pnd/download Current Version] (1.10.0-1, 316.7 MB)
* [http://sourceforge.net/projects/wesnoth/files/wesnoth/wesnoth-1.9.14/wesnoth-1.9.14-1.pnd/download Previous Version] (1.9.14-1, 316.3 MB)

==== Miscellaneous ====
* [http://sourceforge.net/projects/wesnoth/files/wesnoth-1.10/wesnoth-1.10.0/wesnoth-1.10.tar.bz2.md5/download md5sum for current source code]
* [http://www.wesnoth.org/wiki/Download_Xdeltas#Development_Version_1.9.x Xdelta for the source code]
* [http://sourceforge.net/projects/wesnoth/files/ SourceForge page for current and all previous versions]
* [http://sourceforge.net/projects/wesnoth/files/unofficial/Mac%20Compile%20Stuff/wesnoth_compile_mac_1.9.zip/download MacCompileStuff for 1.9]

== License ==
''Main article: [[Wesnoth:Copyrights]]

This program is free software; you can redistribute it and/or modify it under the terms of the [http://www.fsf.org/copyleft/gpl.html GNU General Public License version 2], as published by the [http://www.fsf.org Free Software Foundation].
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

== UMC Editor ==
This is available just with Wesnoth 1.9.x and Wesnoth 1.10.x.
Details and installation steps can be found at: http://eclipse.wesnoth.org

== See also ==
* [http://changelog.wesnoth.org Changelog]
* [[WesnothBinaries| More binaries]]
* [[WesnothSVN]] - bleeding edge version from SVN

[[Category:Building and Installing]]

PreprocessorRef

2012-01-27T07:53:55Z

Timotei21: Update the preprocess command line

{{WML Tags}}
== Overview ==

Wesnoth loads just one configuration file directly: '''data/_main.cfg'''. However the '''WML preprocessor''' allows to include more files. Whenever a WML file is read by Wesnoth, it is passed through the preprocessor.

The preprocessor can interpret a simple language of string expansions known as ''macros''. A macro should always be defined '''before''' the place where it needs to be used.

The preprocessor is applied recursively, so included files will be parsed for macros, and after macro expansion will be parsed for macros again, and so on. As a result, you should not write a recursive macro that references itself, because it will cause errors (but, alas, not necessarily error messages).

== Preprocessor directives ==

The following directives are used to create and use ''macros'', i.e. shortcuts which reduce repetition of information. See [http://www.wesnoth.org/macro-reference.xhtml the macro reference] for the list of predefined core macros.

The preprocessor has changed several times, so don't expect old Wesnoth versions to behave exactly the same as the current stable and development series.

'''Note:''' In multiplayer scenarios, these directives will appear to work only for the host and not for other clients. This is because the preprocessor is run only on the host, and the clients receive the resultant WML from the server. It's particularly important to keep this in mind before using preprocessor conditionals.

=== #define ===

'''Syntax: #define ''symbol'' [''parameters''] ''<newline>'' ''substitution'' #enddef'''

All subsequent occurences of '''{''symbol'' [''arguments'']}''' (see below) will be replaced by the contents of the ''substitution'' block, with all occurrences of any parameter {''parameter''} within ''substitution'' replaced by the corresponding value in ''arguments''. For example, the ENEMY_UNIT macro for the [[#Macro inclusions|macro inclusion]] example below could be defined as follows:

#define ENEMY_UNIT TYPE X Y
## the ordering above is important, since the preprocessor does not distinguish
## data into different types; only the ordering is used to determine which
## arguments apply to which parameters.
[unit]
type={TYPE} ## the unit will be of type TYPE, so different
## instantiations
## of this macro can create different units.
x={X}
y={Y}
side=2 ## the unit will be an enemy, regardless of the parameter
## values. This reduces "repetition of information",
## since it is no longer necessary to specify
## each created unit as an enemy.
[/unit]
#enddef

(See [[SingleUnitWML]] for further information on creating units using WML.)

=== #undef ===

'''Syntax:''' '''#undef ''symbol'' '''

Removes the previous definition of the macro named ''symbol''.

=== Inclusion directive {} ===

This directive can be used to include macros, single files or sets of files from a target directory.

==== File/directory inclusions ====

'''Syntax: {''path''}'''

Includes the file with the specified ''path'', which will in turn run the preprocessor on it and perform any required substitutions or inclusions within it. The ''path'' may not contain ''..'' or the inclusion will be skipped.

The exact location in which the ''path'' will be resolved will depend on its prefix:

* '''{''path''}''': If ''path'' isn't a known macro (see below), the game will assume it's a relative path to a file in the main game '''data/''' directory and include it.
* '''{~''path''}''': As above, but instead of the game data directory, the path is resolved relative to the user '''data/''' directory, where user made add-ons can normally be found.
* '''{./''path''}''': The path is resolved relative to the location of the current file containing this inclusion.

Information for locating the user data and game data directories can be found in [[EditingWesnoth]].

Forward slashes ('''/''') should '''always''' be used as the path delimiter, even if your platform uses a different symbol such as colons (''':''') or backslashes ('''\''')! It is also very important to respect the '''actual letter case''' used to name files and directories for compatibility with case-sensitive filesystems on Unix-based operating systems.

When ''path'' points to a directory instead of a file, the preprocessor will include all files under it, except subdirectories, in alphabetical order. Some files are handled in a special fashion:

* If there's a file named '''_main.cfg''' in the target directory, only that file will be included and preprocessed. It may include other files from its own directory or subdirectories within it, of course. This is used for managing WML directories as self-contained packages, like user made add-ons.
* If there are files named '''_main.cfg''' in subdirectories of the target and there isn't one in the target itself, they will be all preprocessed. Given the following layout:
dir/
dir/a/_main.cfg
dir/a/other.cfg
dir/b/_main.cfg
dir/b/other.cfg
dir/other.cfg
Using '''{dir}''' will cause dir/a/_main.cfg, dir/b/_main.cfg and dir/other.cfg to be included.
* If there's a file named '''_final.cfg''' but no '''_main.cfg''', the file is guaranteed to be included and processed ''after'' all the other files in the directory.
* If there's a file named '''_initial.cfg''' but no '''_main.cfg''', the file is guaranteed to be included and processed ''before'' all the other files in the directory.

==== Macro inclusions ====

'''Syntax: {''symbol'' [''arguments'']}'''

If the macro named ''symbol'' is defined, the preprocessor will replace this instruction by the expression ''symbol'' was previously defined as, using ''arguments'' as parameters. The number of arguments must be exactly the same as in the original definition or an error will occur.

You can create multiple word arguments by using parentheses to delimit the contents. For example, in '''{ENEMY_UNIT Wolf Rider 18 24}''' the four words will be interpreted as separate arguments and cause the preprocessor to fail since the macro was defined above with only three; instead, you should use '''{ENEMY_UNIT (Wolf Rider) 18 24}'''.

Using the name of an existing macro as the name of a macro argument is possible, but the argument will always take precedence over the original macro:

#define VARIABLE
#enddef
#define MACRO VARIABLE
{VARIABLE} # is calling for the argument, not for the macro above
#enddef

=== #ifdef and #ifndef ===

Unlike the other preprocessor directives, '''#ifdef''' and '''#ifndef''' are not mere conveniences. They are often necessary to distinguish between different gameplay modes or difficulties (see [[#Built-in macros|Built-in macros]] below).

'''Syntax:''' '''#ifdef ''symbol'' ''substitution-if-defined'' [#else ''substitution-if-not-defined'' ] #endif'''

If ''symbol'' has been defined with '''#define''' or as a built-in macro, the whole block will be replaced by ''substitution-if-stored''. If not, it will be replaced by ''substitution-if-not-stored'' if it is available.

'''#ifndef''' is the exact opposite of '''#ifdef''', reversing the logic:

'''Syntax:''' '''#ifndef ''symbol'' ''substitution-if-not-stored'' [#else ''substitution-if-stored''] #endif'''

=== #ifhave and #ifnhave ===

{{DevFeature1.9}}

'''Syntax:''' '''#ifhave ''path'' ''substitution-if-path-exists'' [#else ''substitution-if-path-does-not-exist''] #endif'''

Checks for the existence of a file. Uses the same relative paths as include directives (see below).

Example:

#ifhave ~add-ons/My_Addon/_main.cfg
{MY_ADDON_MACROS}
#endif

'''#ifnhave''' does the opposite of '''#ifhave''':

'''Syntax:''' '''#ifnhave ''path'' ''substitution-if-path-does-not-exist'' [#else ''substitution-if-path-exists''] #endif'''

=== #ifver and #ifnver ===

{{DevFeature1.9}}

'''Syntax:''' '''#ifver ''symbol'' ''operator'' ''version-number'' ''<newline>'' ''substitution-if-condition-met'' [#else ''substitution-if-condition-not-met''] #endif'''

Compares a version number defined in a macro against an argument for conditional block inclusions, like ''#ifdef'' and ''#ifhave''. ''operator'' is one of ''=='' (equal), ''!='' (not equal), ''<'' (less), ''<='' (less or equal), ''>'' (greater), ''>='' (greater or equal). The specified ''symbol'' should have been previously defined as plain text without more macro inclusions within it, and it must not require any arguments.

Example:
#ifver WESNOTH_VERSION >= 1.9.7+svn
[message]
speaker=narrator
message= _ "I’m on Wesnoth 1.9.7+svn, 1.9.8 or later!"
[/message]
#else
#ifver WESNOTH_VERSION == 1.9.7
[message]
speaker=narrator
message= _ "I’m on Wesnoth 1.9.7, and I’ll include some workaround code for bug #9001!"
[/message]
#endif
#endif

'''#ifnver''' does the opposite of '''#ifver''':

'''Syntax:''' '''#ifnver ''symbol'' ''operator'' ''version-number'' ''<newline>'' ''substitution-if-condition-not-met'' [#else ''substitution-if-condition-met''] #endif'''

== Built-in macros ==

The following macros are automatically defined with empty contents (unless specified otherwise) by the game engine depending on the configuration or gameplay mode.

* A campaign define symbol (see ''define'' in [[CampaignWML]]): defined when playing a single-player campaign.
* A campaign difficulty level, usually '''EASY''', '''NORMAL''' or '''HARD''' (see ''difficulties'' in [[CampaignWML]]): defined according to the chosen difficulty when starting a single-player campaign, also stored in saved games.
* '''MULTIPLAYER''': defined when in multiplayer mode.
* '''TUTORIAL''': defined when playing the tutorial campaign.
* '''EDITOR''': defined when running the built-in map editor.
* '''DEBUG_MODE''': defined when the game has been launched in debug mode (i.e. with '''-d''' or '''--debug''' in the command line).
* '''APPLE''': defined while processing the main game data when running on Mac OS X.
* '''WESNOTH_VERSION''' {{DevFeature1.9}}: defined containing just the game version number when running the WML preprocessor on 1.9.5 and later. Due to a bug, this isn't defined when using the command-line version unless using 1.9.10 and later.

== Command-line preprocessor ==

{{DevFeature1.9}}

Since Wesnoth 1.9.0, there is a new command line option available:

'''Syntax: --preprocess ''<source file/directory>'' ''<target directory>'' '''

Or the short form:

'''Syntax: -p ''<source file/directory>'' ''<target directory>'' '''

You can specify a list of predefined defines with:

'''Syntax: --preprocess-defines=DEFINE1,DEFINE2,etc'''

comma separated list of defines to be used by '--preprocess' command. If 'SKIP_CORE' is in the define list the data/core won't be preprocessed."

The command will preprocess first the common config files in the main game ''data/'' directory, and afterwards the specified ones. You can specify a single file to be preprocessed (if you want to preprocess multiple separate files, you'll need to run a different command line for each one), or an entire directory, which will be preprocessed according to the rules used by the inclusion directive above.

The resulted preprocessed files will be written in the target directory. There will be two types of files: .cfg files --- the normal ones, and .plain files containing line markers and textdomain changes.

If by chance, the simple macro define doesn't suffice, you can use:

'''Syntax: --preprocess-input-macros <file>'''

To import an existing file that contains macros, and they will be available in the defines database before processing the specified files.

There is also the possibility to export the preprocessed defines/macro list with:

'''Syntax: --preprocess-output-macros <target file>'''

This file could be fed to the 'input-macros' argument next time you run it. For example, a scenario would be: parsing just the core first time, and for the intended target files, you would add SKIP_CORE but import the generated macros file - that will be faster than preprocessing the core again.

If ''file/directory'' and ''target directory'' are not absolute paths, they will be considered relative to the game's executable path.

Some examples:

* Preprocess the entire tutorial dir, and write the results in the ~/result folder:
-p ~/wesnoth/data/campaigns/tutorial ~/result
* Add the MULTIPLAYER define to the list and preprocess a scenario's config file:
-p ~/.wesnoth/data/add-ons/My_Campaign/scenarios/01_First_Scenario.cfg ~/result --preprocess-defines=MULTIPLAYER
* Add the MY_CAMPAIGN and HARD defines before preprocessing a campaign's files:
-p ~/.wesnoth/data/add-ons/My_Campaign ~/result --preprocess-defines=MY_CAMPAIGN,HARD

If you want a more detailed (and potentially overwhelming) log, you can simply add the switches '''--log-debug=all''' or '''--log-info=all''' to the command line, so you can see how things are preprocessed in detail.

== See Also ==

* [[SyntaxWML]]
* [[ReferenceWML]]

[[Category: WML Reference]]

User:Timotei21/Questionaire

2011-12-26T07:23:41Z

Timotei21: /* Questionnaire */

=Questionnaire=
<h3>Basics</h3>

<h4>Write a small introduction to yourself.</h4>
My name is Timotei , 21 years old and I'm from Cluj, Romania. I'm one of the best students in my year, and I've decided to participate in another GSoC. I'm also very passionate about programming, doing it my spare time and also having fun with other people/my friends.

<h4>State your preferred email address.</h4>
user:

<h4>If you have chosen a nick for IRC and Wesnoth forums, what is it?</h4>
timotei,timotei21 - IRC, timotei - forums

<h4>Why do you want to participate in summer of code?</h4>
I have participated last year and it was an '''awesome''' experience. I've learn a lot of new things, and I've made friends as well. Provided that, I shall go again for a GSoC experience. Also, another reason would be the one that I really wish to finish the work started last summer, so the eclipse plugin will be polished and much stable, so it can become "de facto" for developing UMC content. Since the summer will be holiday for me, GSoC will help me use the holiday at its fully extend, by flipping bits not burgers :P, and the stipend will be very good to have.

<h4>What are you studying, subject, level and school? </h4>
I'm currently 2st year undergraduate at the Technical University of Cluj-Napoca, Computer Science.

<h4>What country are you from, at what time are you most likely to be able to join IRC?</h4>
I'm from Romania, Eastern Europe (Timezone: UTC +2). Usually I'm available for about 2-8 hours a day, but in the day-time - I better sleep in the night, so I can start earlier the next day. In general, based on my current schedule I'll be available: Monday: 18-22 UTC+2, Tuesday: 8 - 22 UTC+2, Wednesday: 16 - 22 UTC+2, Thursday: 16 - 22 UTC+2, Friday-Sunday: 8-22 UTC+2.

<h4>Do you have other commitments for the summer period? Do you plan to take any vacations? If yes, when.</h4>
Like every student, I'll have exams in the following period: 30.05-19.06.2010, that's 3 weeks. So in that period the time for development will be slowed down a lot, to almost none - depends a lot of the time I need to dedicate for each exam. Because of that, I will start the work faster than the official time, so I can recover the "lost" time.

<h3>Experience</h3>

<h4>What programs/software have you worked on before?</h4>
<ul><li>InfoCenter - application for aiding high-school students in learning the C++ language. This is the biggest project I have ever worked on. (technologies and tools used in development: Visual Studio, C#, SVN, XML, MS Access Database, ReSharper)
</li>
<li>Lineage 2 Launcher & Server – application for launching and updating the “Lineage 2” game from a web server, registration on the server for new users. The game was used to connect to my custom “Lineage 2 MMORPG” server (the server was developed in java by an existing open-source community - l2jserver). I modified the server adding new features, fixing bugs and making my own version of game play, not seen on other servers. ( technologies and tools used: Java, Eclipse, SVN – server; C#/.NET/MySQL - launcher)</li>
<li>vLessons – prototype application for a future e-learning application. (Project done as an assignment for courses; technologies and tools used: SQLite, QTCreator, C++)</li>
<li>Y! Detector – prototype application that scans a specified Yahoo! Messenger user for being offline/invisible, and retrieving his/her avatar from the Yahoo servers. (technologies and tools: VS, C#) </li>
<li>Websites – built many custom websites for friends, companies and my high-school.</li>
<li>XNA Game – I have worked on a XNA game with a friend, for participating in the Game Design competition at Imagine Cup; Dream-build-play contest and IGF (Independent Games Festival). (website: http://awkwardgames.wordpress.com/shade/)</li>
<li>Pure Assembly Game - I have made a simple 16-bit assembly game, space invaders, just for fun an experiencing with assembly. Code: http://dl.dropbox.com/u/462510/portofolio/spaceinvaders/spacein.asm | Compiled exe runnable in DosBox: http://dl.dropbox.com/u/462510/portofolio/spaceinvaders/SPACEIN.EXE</li>
<li>Battle for Wesnoth - I have created the eclipse UMC plugin as part of Google Summer of Code 2010, a fabulous tool that helps the UMC Creators to create/develop faster new addons or edit the current ones. The tools'homepage is: www.eclipse.wesnoth.org</li>
</ul>

<h4> Have you developed software in a team environment before? (As opposed to hacking on something on your own)</h4>
Yes. For the XNA Game I've worked with another friend. For an AI project, I've worked with 2 friends. Both times we used SVN to synchronize our modifications. I have also worked with another colleague for a school project. Currently I'm working with another 3 friends on a software solution for the ImagineCup competition.

<h4>Have you participated to the Google Summer of Code before? As a mentor or a student? In what project? Were you successful? If not, why?</h4>
Yes. I have participated to GSoC last year, in 2010, as a student. My mentor was fendrin and I have worked on the Eclipse UMC plugin. The project was successful, although I haven't really finished all task I proposed.

<h4>Are you already involved with any open source development projects? If yes, please describe the project and the scope of your involvement.</h4>
Yes I am. I am developer for Battle For Wesnoth, maintainer for the Eclipse UMC Plugin. I usually fix bugs and add new features (depends on my time if that allows it). Also, about 4 years ago I worked on an open-source project (http://l2jserver.com | http://l2jfree.com) with some friends, modifing the existing files, adding new features and fixing existing bugs, so we could make our own version of the server (if you want you can take a look at an older .diff file here: http://wesnoth.pastebin.com/bGyJ87eY - this was written when my experience/coding style wasn't so good)

<h4>Gaming experience - Are you a gamer?</h4>
I like a lot playing games, especially indie ones. My first contact with video games was with a NES console. After that it followed the PC, starting with very low power configurations but increasing to better ones. So, there were games that I played in low graphics mode, but that didn't stop me from playing them. The gameplay was almost everything.

<h5>What type of gamer are you?</h5>
There are games at which I'm a master, but there are some games in which I am really bad. I know well the DoTa game - a map for Warcraft3 - I was the best in my high-school, and I play racing games in general. I go mainly for gameplay/story rather than for the graphics. In the last months I played minecraft.

<h5>What type of games? </h5>
Sorted by "I like more": Mmorpg/Indie/racing/rpg/adventure/shooters. I played too many games to enumerate them, but some of my favorites: Lineage 2, World of Warcraft, Braid, World of Goo, Warcraft3 (Dota), Need for Speed, Unreal Tournament 3, Minecraft.

<h5>What type of opponents do you prefer? </h5>
If it's AI, then I prefer an adaptive one, growing in the difficulty as the game progresses. If it's human, I like all types, including campers because even this type of opponent is good, because it forces you to develop new strategies to try take it down.

<h5>Are you more interested in story or gameplay? </h5>
It depends a lot on the mood and game type. In a fast-paced game (fighting/race/etc) I would like the gameplay to be very good. If It's an adventure for example, I would like it to have a good story.

<h5>Have you played Wesnoth? If so, tell us roughly for how long and whether you lean towards single player or multiplayer. </h5>
Yes. I have played some parts of the campaigns. I also played on Gambit's multiplayer map "Breaking Ground" - I'd still play that because I won't get bored. I like better the multiplayer ones since they engage more people and it's more fun.

<h4>If you have contributed any patches to Wesnoth, please list them below. You can also list patches that have been submitted but not committed yet and patches that have not been specifically written for GSoC. If you have gained commit access to our SVN (during the evaluation period or earlier) please state so. </h4>
Yes. I have contributed with some patches before last GSoC. After that, till now I have commit access on the SVN.

<h3>Communication skills </h3>

<h4>Though most of our developers are not native English speakers, English is the project's working language. Describe your fluency level in written English.</h4>
My writing in English is pretty good because I speak sometimes with other peoples, which are not Romanian. Also I spent a week with some students that came in Romania from U.S.; when I was Game Master on the L2Server I had to talk in English and try to understand every "variance" of the standard English, so I think I could understand most of the terms. Also, since when I was involved with wesnoth since last year, I can say that both my spoken and written english have improved - thanks especially to Espreon and shadowmaster who kept correcting me on each mispelled/wrong word.

<h4>What spoken languages are you fluent in?</h4>
Romanian and English.

<h4>Are you good at interacting with other players? Our developer community is friendly, but the player community can be a bit rough.</h4>
I'm a very "enduring" when receiving harsh criticisms and I am well-tempered. Is it very hard to upset me. Also I know how to separate feedback (constructive criticism) and useless criticisms.

<h4>Do you give constructive advice? </h4>
Yes. Usually I tend to help people in their problems more than necessary, just to be sure of it, by providing feedback and ideas.

<h4>Do you receive advice well? </h4>
Yes.

<h4>Are you good at sorting useful criticisms from useless ones?</h4>
Yes.

<h4>How autonomous are you when developing ? Would you rather discuss intensively changes and not start coding until you know what you want to do or would you rather code a proof of concept to "see how it turn out", taking the risk of having it thrown away if it doesn't match what the project want</h4>
Somehow between. It depends a lot of my knowledge in that area. If I have enough spare time to try it and know what I have/want to do, I'll do it, providing some results to support my changes. Otherwise, I would wait for the dev guys confirmation.

<h3>Project</h3>

<h4>Did you select a project from our list? If that is the case, what project did you select? What do you want to especially concentrate on?</h4>
I want to work on improving the Eclipse UMC Plugin. Idea's page is: http://wiki.wesnoth.org/SoC_Ideas_Eclipse_Plugin2011. I want to focus on getting the plugin more stable so it can be used even on slower PCs.

<h4>If you have invented your own project, please describe the project and the scope.</h4>
I haven't invented one.

<h4>Why did you choose this project?</h4>
I chose this project because I've worked on it last summer. I know my way around and this GSoC year will give me the opportunity to finish the plugin so it can be properly used by all UMC Authors, like a tool they won't want to stop using. Of course, since the eclipse framework is written in java, the performance might won't be so good on slower PCs,but, depending on the plugin's tools/available options, it may replace even the emacs WML mode, or other tools used currently for writing UMC.

<h4>Include an estimated timeline for your work on the project. Don't forget to mention special things like "I booked holidays between A and B" and "I got an exam at ABC and won't be doing much then".</h4>
See [[SummerofCode2011_Timotei21#Timeline|Timeline]]

<h4>Include as much technical detail about your implementation as you can</h4>
See [[SummerofCode2011_Timotei21#Proposal_Summary|Proposal Summary]]

<h4>What do you expect to gain from this project?</h4>
The thing I'm expecting now, is that the wesnoth community will use the plugin after the 1.9.x branch is getting stable. Aside from this, I'm expecting consolidate my java/eclipse framework knowledge and my coding skills performance-wise.

<h4>What would make you stay in the Wesnoth community after the conclusion of SOC? </h4>
The people I'm working with, the friends made during the "coding" period. If there is need to enhance the plugin I did, I will continue to improve it. The knowledge I gathered directly or indirectly from other wesnoth members was very beneficial for me. Thus, I'm gonna continue being (as times allows me) a maintainer for the eclipse plugin, and if there is the need, to get my hands on other wesnoth's areas too.

<h4>Practical considerations</h4>

<h4>Are you familiar with any of the following tools or languages?</h4>
* Subversion (used for all commits)
Yes. I used subversion for many projects. Right now I prefer using git svn wrapper instead of svn command line/tortoise svn.
* C++ (language used for all the normal source code)
Yes. I've worked with C/C++ for 3 years for different projects and programming contests.
* STL, Boost, SDL (C++ libraries used by Wesnoth)
STL: Only used small parts from it.
Boost: Didn't used it but I know what it offers.
SDL: No.
* Python (optional, mainly used for tools)
No, but I've written some scattered bits of code.
* build environments (eg cmake/autotools/scons)
CMake, Ant - basic usage.
* WML (the wesnoth specific scenario language)
I know just its syntax and some tags/attributes.
* Lua (used in combination with WML to create scenarios)
No. But wishing a lot to learn it.

<h4>Which tools do you normally use for development? Why do you use them?</h4>
I use Visual Studio(C#,C/C++), Expression Studio(C#, WPF), Eclipse(java, php) and (g)vim for short and fast C/C++ programs/scripts. Visual Studio is IMHO the best IDE alongside with Eclipse. The only thing why I didn't move completely from VS to Eclipse, is the enhanced debugger of VS and the very low support for C# in eclipse. Lately, I've started using gvim for more and more tasks that involve writing text. Also, for projects that need more than 2-3 days of development, I use a local git for keeping the changes.

<h4>What programming languages are you fluent in?</h4>
C#, C/C++, Java, Assembly

<h4>Would you mind talking with your mentor on telephone / internet phone? We would like to have a backup way for communications for the case that somehow emails and IRC do fail. If you are willing to do so, please do list a phone number (including international code) so that we are able to contact you. You should probably *only* add this number in the application for you submit to google since the info in the wiki is available in public. We will *not* make any use of your number unless some case of "there is no way to contact you" does arise!</h4>
I won't mind. Even though I think it won't be needed, I will provide the telephone number in the application sent to google.

SummerofCode2011 Timotei21

2011-08-19T16:58:57Z

Timotei21: /* Tasks */

{{SoC2011Student_2|timotei|SoC_Ideas_Eclipse_Plugin2011}}

=Description=
<h4>timotei - Improving the Eclipse Plugin</h4>
I aim at improving the plugin, so it will become the tool used by all UMC Authors. That is, UMC Authors will get rid of the lot of different tools they use for different tasks (for example the Emacs WMLMode/other plugins for different text editors), and instead use one single unified Tool that will speed up the development. My target is to make this plugin a complete and very stable suite for all umc tasks that don't need specialized software - like a graphics editor, so I'd like to have this oportunity to finish it in the good sense.

=Contacts=
==IRC==
timotei

==Other==
Forum: timotei 
gna.org: timotei

=SoC Application=
[http://www.google-melange.com/gsoc/proposal/review/google/gsoc2011/timoteidolean/1 Battle for Wesnoth - Google Summer of Code Application]

=Proposal Summary=
Page Last Updated: {{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}} 

In the following lines I will give details on how I'm planning to implement some of the required tasks, and also add some new ones.

The ''Notes'' sections are aimed for personal guideliness. They are took from my todo list.

==Multiple Wesnoth installations==
Having multiple wesnoth setups, and working with them at the same time would be nice to be done from inside the plugin.
For that, there will be a new preferences page. The page will look something like this:
http://dl.dropbox.com/u/462510/personal/soc/installations_management.PNG

There will be buttons that add/remove/edit a certain wesnoth installation. When adding/editing an installation, a new page like the current one (in which we set the paths), will be shown. The user will be able to name it and specify the version (I could automatically get the version by invoking ''wesnoth --version'').
The current page for setting the paths will act as a default installation.

After we have configured the paths, the user can chose the installation to which the (new) projects are bound, by opening the project properties. There will be a wesnoth-related page, where the user will be able to chose to what installation the project binds. With that, every command that uses the paths, won't use the single current paths, but the ones assigned to each project. This project properties page will open new ways for adding new

There would be a problem in case the project will be migrated between 2 different plugin's versions. For example, in one place we would have defined "1.9.4svn" but on the other there would be "trunk".

We can solve this in 3 ways:

# Alert the user that the installation doesn't bind, and let him chose the current matching installation for his plugin.
# Default automatically to the current plugin's default installation.
# "Hardcode" the version, so that there may be defined just installations like: 1.8.0, 1.9.3. With this we lose some flexibility, but we could use this as base version for new installations, so for example, a user can have two 1.9.3 installations. Provided this, we have again a possible problem, which can be solved again by 1. or 2., but this time, trying to match the base version first.

With this feature, the user won't need to restart the plugin at all, switching workspaces.

Regarding the technical PoV, all paths will be stored using eclipse's preferences system, by appending an unique id of each installation to each path in that set.

''Note'':
Add the NO_TERRAIN_GFX preprocess option checkbox to the project properties rather than being a global one.

==Enhance the Content Assist(CA) feature==
The CA framework is very extensible but it lacks proper contexts for providing the content.
I was thinking of trying to accomplish the generating of CA list either by using a config file, in case something like that can be used or writing directly the code that does that.

Another factor that is involved in a better auto-complete, is the ''schema.cfg'' the plugin bases on. Depending on whether the schema is worked on during this summer of code, I'll need to redo a bit the parser of the schema, in case the format/semantics change.

===Project files dependecy tree===
In order for the CA to work better - and maybe other areas would benefit from this - we will need to build a project files tree. With that tree, we can see how a certain declared macro/variable will affect subsequent related files and also their scope. Basically, we can see the relation from a file to anothers.

This tree will be (re)built in 2 situations:
# A file is added/removed/changed it's name
# A full rebuild is triggered (for example, the project is added for the first time in the workspace)

The tree will be built by the WML parser's rules:
# files are processed in the alphabetically order
# _initial.cfg is the first processed before anything else.
# _final.cfg is the last processed after anything else.
# if there is a _main.cfg in the directory, it is the only one processed.

Since the current ''WesnothProjectBuilder'' doesn't take in account the previous rules, I will create my own method of visiting each folder's children in the correct order. This method will look close to wesnoth's one, namely ''get_files_from_in_dir()'' found in ''src/filesystem.cpp:93''.

For a very fast lookup, as a data structure we will use a Hashtable, which has as the key the local project path to the file, and as a value a custom structure, which has the previous/next/parent/son properties, used to traverse the tree. The previous/next go on the same tree level, while the parent/son go up/down in the tree. I will use this instead of a tree, because this will give us access to info about a file, faster, in O(1) compared to a breadth-first search which has O(V+E) - where V is number of vertices and E number of edges.

Talking with Crab about this, he alerted me about a little possible problem with current aproach:
<Crab_> a note about 'The tree will be built by the WML parser's rules: ' - don't forget that you can (conditionally) include files/dirs from a file.
<Crab_> so, if we have 'ai/ais/zzz' which, say, defines a macro, it might get included by campaigns/bbb/scenarios/some_scenario.cfg , even if it is not inside /campaigns/bbb/scenarios

For that we have 2 cases:
{~file/dir path}
or
{file/dir path}

The paths are simply discarded if the current project's directory name is not found in the path.

Currently the so called "Tree" will be actually just a List or a single path tree. For the first iteration of this project, I won't tackle the advanced macro usage that might direct the flow based on defines (this will be optional if there will be time in GSoC, or if not, after GSoC, since I plan to remain active developer to maintain the plugin/enhance it furthermore). So, for example (taken from LoW):

#ifdef CAMPAIGN_LOW

{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#endif

#ifdef MULTIPLAYER

#define EASY
#enddef
{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#undef EASY
...
#endif

With current way to do this we will just take "blindly" all included directories/files without taking in consideration the #define flow control.

If we are at LoW, the following tree(list) will be created on its project:

_main.cfg -> utils/*.cfg -> scenarios/*.cfg -> units/*.cfg

Each file in the dependency tree, will have associated a number. For more details on why this and how it's done, read the Scoping section.

===Scoping===
In order for the plugin to know more about the semnatics, it should have the posibility to represent scopes. The scopes will be used mainly for variables and macros.

The Scoping is a delicate problem, because there are some tricky situations that might interfere with the scoping. I choosed to represent scoping in the following way:

Scoping is everything just about order relations. That is, we will compare numbers when dealing with scoping. With that we move the "problem" upper, to the "Dependency tree". We won't use filenames/paths because:

* The filename might change, but the order index may not. So, not having to update the index helps us.
* Number comparison is faster than string comparison.

So, from now on we'll talk in terms of indexes instead of filenames for scoping.

So, we are working with numbers. But there is still a lil' problem. What happens, when we remove/need to add a new file in the current tree, in the middle of existing 2? We would need to update all subsequent files's indexes. That would not be so ok performance wise.

To counter this problem we will not use consecutive numbers, but rather have a certain step between numbers. The step might be configured inside the plugin based on real statistics (for example, trying to see the number of cfg files per project. Taking a big number, like 1000 won't really hurt). For example, we could take the step 50. That means we would have the following tree for LoW:

0 50 100
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

instead of:
0 1 2
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

So, when it's the case of insertion, we insert the new node at the ''middle'' of the current "distance". That way we may insert/delete files *without* breaking the order, and our scoping will still work.

There is another problem it rised in my head: how do we know when to put the number as the next step (the previous number + step) or add it in the middle? Well, since every project will surely do a '''Full Build''', we'll use that oportunity to create the initial tree. Afterwards we will just insert files based on the halving of the distance between 2 indices.

The scoping will be represented by a simple structure, consisting of start index and offset and end index and offset.

===Content Assist Config(CAC) Files===
The CAC files will provide values that are default/available to config files from the wesnoth engine itself. There will be several files that define the values based on their context. This will allow a very great flexibility editing the CA list.

A CAC file will be just a simple text file, that has on each line one (or more) value(s) depending on the context.

* The ''cac/variables.txt'' will contain variables available. The list is currently available at [http://wiki.wesnoth.org/VariablesWML#Automatically_stored_variables]. For example the file could look like:
$side_number
$turn_number
...

* The ''cac/events.txt'' will contain the game events. The list is availabe at: [http://wiki.wesnoth.org/EventWML#Predefined_.27name.27_Key_Values]. Since the events that have spaces in their names can replace that with an underscore '_', the file will contain the underscore instead space variants also.



===Variables===
The variables are either defined by user or defined by default by the wesnoth engine. User's variables will be parsed from each processed file by the WesnothProjectBuilder, using the WMLSaxHandler. The default variables will be parsed and added from the CAC file. (cac/variables.txt)

Variables definitions can be triggered using the VARIABLE macro:
{VARIABLE var_name "value"}
or the [set_variable] tag:
[set_variable]
name=my_var
value="value"
[/set_variable]

The ''ConfigFile'' class in the ''org.wesnoth.wml.core'' already has a list of variables. The ''Variable'' class has some fields that allow its identification. We will build that list when we parse each file, adding each variable found by the previous defined triggers.
When the content assist finds the '$' character, it will supply the user + default variables gathered so far.

Since the variables can be cleared, thus they have scope, the ''Variable'' class needs to be refactorted, so it can represent the scope aswell. The scoping was settled before.

===Name Collisions===
I've considered that we should store the variables per project, like we currently do with macros. This will minimize the memory we need, rather than storing variables on each file - like we do currently. With this, I've discovered it's innevitable to have ''collisions''. That is, have the same variable name on multiple files.

To solve this problem, each variable/macro structure, will not have just a single scope, but rather a list of scopes.

===Events===
Besides the default event names, supplied by the wesnoth engine, there can be created custom ones, wich will be triggered with [fire_event]. As usual the default events names will be available in the cac/events.txt file.

The events defined by the user will be parsed from the ''name'' attribute of the [event] tag.

===Attributes===
All attributes are currently got from the schema.cfg

===Attributes Values===
All attributes values should be parsed based on the schema.cfg.

===Macros===
The support for macros is already built in, but it needs a way to let them have scope. That is, when an #undef is found, the certain macro would not be available to subsequent files unless redeclared. This will be done with the aid of the dependency tree and scoping. The collisions will be solved like I said at the variables section

===Support for custom luaWML tags===
The lua can create new WML Tags. It would be nice that the plugin suggest those aswell besides the ''schema.cfg''. The lua will be easily parsed, since there is a simple pattern for creating new tags:
wesnoth.wml_actions.<tag name>(cfg)

The parser will just run over the lua code/file, over each line, trying to match the 'function *wesnoth.wml_actions.*' pattern. If it finds something, it will add the tag name to the list of tags. There is also a small thing we might have missed. The user could use a shorthand notation for the actions namespace, so when searching for the pattern, I will add to the 'pattern to match' list, the respective variable when searching for new WML Tags.

Thus, like the ''wml-tags.lua'' from the data/lua uses:
local wml_actions = wesnoth.wml_actions

the 'to match' list will contain: 'function *wesnoth.wml_actions.*' and 'function *wml_actions.*', thus finding other tags too.

Going further more, for an ''optional'' enhancement, I could also search that function to see if it needs/has some extra attributes. The attributes can be found by:
* function's parameter (usually cfg) is asked for a property. For example:
function wml_actions.terrain(cfg)
local terrain = cfg.terrain or helper.wml_error("[terrain] missing required terrain= attribute")
cfg = helper.shallow_literal(cfg)
cfg.terrain = nil
for i, loc in ipairs(wesnoth.get_locations(cfg)) do
wesnoth.set_terrain(loc[1], loc[2], terrain, cfg.layer, cfg.replace_if_failed)
end
end

Here we need the attributes ''terrain'', ''layer'' and ''replace_if_failed''.

* ''get_child'' call:
function wml_actions.message(cfg)
local show_if = helper.get_child(cfg, "show_if")
if not show_if or wesnoth.eval_conditional(show_if) then
engine_message(cfg)
end
end

Here we need to have the attribute ''show_if''.

==Automatic/headless building==
The eclipse plugins can be automatically built from command line, provided there is the eclipse sdk and the eclipse delta pack on the builder's machine. The plugin can also use Buckminster tool to automate the building of the plugin.

''Notes''
Add all plugin's files *inside* a folder to prevent cluttering the directory where it's extracted

More info at:
* http://wiki.eclipse.org/PDE/Build
* http://wiki.bioclipse.net/index.php?title=How_to_build_plugins_headless
* http://help.eclipse.org/galileo/index.jsp?topic=/org.eclipse.pde.doc.user/guide/intro/pde_overview.htm
* http://www.eclipse.org/articles/Article-PDE-Automation/automation.html

==Standalone app auto-update==
The current standalone application doesn't offer the same eclipse's update system. I will add it, so anytime there is a new version of the plugin, it can be updated with a single click by the user, without the needing to download a new standalone app again.

==Documentation==
===External documentation===
The current existing readme will be split in 2 manuals: User Manual and Developer Manual (Don't forget to add images where relevant).

The user manual will contain:
* Prerequisites and Installing the prerequisites
Note: don't forget to mention the MINIMUM eclipse/java version needed to run
* Installing the plugin / standalone version
* Using the plugin
* Plugin features
* Step-by-step use cases
** Setupping the workspace
** Creating a new project and running it in the game
** Importing existing projects
** Using the WML Editor
** Updating the plugin
* Frequently Asked Questions

The developer manual will contain:
* Prerequisites and Installing the prerequisites
* Adding the plugin's projects in the
* Compiling and Running the plugin
* Deploying the plugin and standalone app

===Internal documentation===
The Eclipse infrastructure has features for letting the developer embed help into the application, depending on the current context. After I will write the external documentation, I will work on adding internal documentation aswell. Some of it already comes from the external one.

* Plugin welcome page
* Eclipse Help (When pressing Help->Help contents)
* Wizards help

==Plugin polishing==
This are some tasks needed to be done in order to get the plugin more stable and more usable than it's currently. Some of the tasks are taken from my todo list. New tasks will be added through the project advancing when improvements to actual code /user interaction can be done, so this list is not final.

# Don't copy a project that belongs to data/campaigns to the user addons's directory. This can be done by looking at the path when creating a new project. (This is prevented by not spawning a ''build.xml'' file in the campaigns's directory)
# Enhance the logging so it can help debugging other's problem much easier. I could split the current log in 2:
## Commands executed by the plugin
## Other information like parsed information/statuses
# Enhance the integration with the eclipse platform by adding the "Wesnoth" related wizards directly to the "New" menu.
# Allow users to import a directory as a wesnoth project. Under the hood it will either open the wesnoth project (if there is any .project files in it) or create a new empty project on it.
# Allow the user to clear it's current plugin's settings just with a simple button.
# Wesnoth Project Explorer - Add error markers just like the Java Explorer has
# Refactor the current way of getting the macro list. Currently if there is no _main.cfg practically the _MACROS_.cfg file is not built resulting in no MACRO suggestions.
# Create a view filter to hide the Project ''_AutoLinked_CFGExternalFiles_'' which is created for opening the external config files (external meaning outside the current workspace).
# Fix the F3 navigation when the map's location is specified withing " ", as a string.

===New parsing method (optional)===
The current parsing method involves a lot of Wesnoth preprocessor/wmlparser.py. This is doing somehow the parsing job double. This is because the xtext framework already does 1 pass over the files when added to the project. My plan is to see if I can reuse the already built AST(Abstract Syntax Tree) and the parse tree, to use those values instead of additional preprocessing/wmlparsing, and use the latter only when really needed.

Using the xtext's model will greatly fasten the "build" time of each project and it will be *much* simpler to work with, since the framework already provides exceptions recovering (that is, when the code is not well formed according to the grammar) and based on the defined grammar the respective tokens. So, for example instead using 2 another external processes, we could just iterate over each WMLTag and get it's WMLKeys and parse their individual values.

If this idea works, I will add it on the Plugin polishing tasks.

==Other ideas==
===Addons management===
There will be a new Addons management view. It will behave much like the in-game addon manager, but it will be more handy since the user doesn't need to start the game for that (and also wait till the cache refreshes after downloading it). This view will be based on the python script from '''data/tools/wesnoth_addon_manager''', like it does currently for uploading the project as an addon.

The view will let the user see the list/details for each of the addons currently on the server. There will be also a filter based on what addon server to use (trunk/1.8/1.9/etc)

The user will be able to just right click on an addon and download it to it's user data folder. Optionally a new project will be created, based on the just downloaded addon.



===Unit testing===
====Grammar====
For a better wml handling with in the editor, I will create a Testing class for the current grammar. The class will do testing on all *.cfgs in the data directory. That way after modifing something in the grammar we will be able to see how many errors we have introduced/eliminated. This will greatly help the developing of a better grammar that can hold all current WML formats.

''Notes'':
optionally rework the grammar and try to use a custom lexer/parser in order to benefit from the preprocessor, injecting the valid tokens. This would help the cases when the current grammar doesn't work:
{name} = value
or unclosed tags

====Parsing and getting information from files====
I will create some basic (or taken from existing campaigns) config files that will be parsed in order to check if the correct behaviour - correct information is extracted from the files.

This will check for extracting the:
scenario name
campaign name
next_scenario
first_scenario
variables
macros

=Timeline=
The GSOC period is between 24th May and 20th August. But since I have exams for 3 weeks (during 30.05-19.06.2011), I will start working on the plugin before the 24th of May, to recover some of the lost time. Also, my ImagineCup team made it to the national phase - that is in 5,6,7 May. That means till that time I will not be able to do so much work, so I'll make the timeline according with the starting of work on 9 May.

Here is a table with key periods of the time spent on this project.
{| border="1"
|'''Period''' || '''Actions'''
|-
| 26 April || Get accepted
|-
| 26 April - 8 May || Busy working on ImagineCup project for the national phase. Little or no work done.
|-
| 9 May - 15 May || Allow headless build of the plugin
|-
| 16 May - 22 May || Add Support for multiple installations
|-
| 23 May - 28 May || Add the auto-update feature for the standalone app
|-
| 30 May - 19 June || Exams
|-
| 20 June - 24 June || Create the external documentation
|-
| 25 June - 16 July || Enhance Content Assist
|-
| 15 July || Mid-term evaluations deadline
|-
| 17 July - 24 July || Addons management view
|-
| 25 July - 30 July || Unit tests
|-
| 1 August - 14 August || Do the Plugin polishing tasks
|-
| 15 August || Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc.
|-
| 15 August - 17 August || Create the internal documentation.
|-
| 18 August - 22 August || Buffer half-week. This will be used in case some tasks fell a bit outside their proposed time.
|-
| 22 August || Firm 'pencils down' date. Mentors, students and organization administrators can begin submitting final evaluations to Google.
|}

=Tasks=
This is a list of the "atomic" tasks that need to be done, based on the project part. Since the big tasks are split into smaller task, the progress will be seen better and any problems that arise with the timeline will be seen faster. I will update this table based on my current progress.

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Headless build ||Research about what system to use for automatic building of the plugin || Done
|-
| Headless build || Implement the chosen system for the wesnoth plugin|| Done
|-
| Multiple installations || Implement the preferences pages || Done
|-
| Multiple installations || Implement the logic for saving and loading the installation's paths on the disk || Done
|-
| Multiple installations || Implement the project preferences page || Done
|-
| Multiple installations || Rewrite the current mechanisms that use the paths to use the ones based on the project. || Done
|-
| Auto-update || Implement the auto-update feature. || Done
|-
| Documentation || Write the User Manual || Done
|-
| Documentation || Write the Developer Manual || Done
|-
| Documentation || Write the internal documentation || Done
|-
| Enhance Content Assist || Project dependency tree || In progress
|-
| Enhance Content Assist || Content assist files || Done
|-
| Enhance Content Assist || Variables || Done
|-
| Enhance Content Assist || Events || Done
|-
| Enhance Content Assist || Lua tags || Done
|-
| Addon management || Create the GUI of the view || Done
|-
| Addon management || Create the view's logic || Done
|-
| Unit testing || Tests for the grammar || Done
|-
| Unit testing || Tests for parsing the config files || Done
|-
| Plugin Polishing || Task 1 || Done
|-
| Plugin Polishing || Task 2 || Done
|-
| Plugin Polishing || Task 3 || Done
|-
| Plugin Polishing || Task 4 || Done
|-
| Plugin Polishing || Task 5 || Done
|-
| Plugin Polishing || Task 6 || Done
|-
| Plugin Polishing || Task 7|| Done
|-
| Plugin Polishing || Task 8 || Done
|-
| Plugin Polishing || Task 9 || Done
|}

Optional tasks will be dealt with if the time allows it:

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Enhance Content Assist || Project dependency tree with multiple paths based on defines || None
|-
| Enhance Content Assist || Lua tags attributes || Done
|-
| Grammar || Enhance the grammar to support the 2 current unsupported syntax constructs || None
|-
| Documentation || Implement a simple WML project from start to end using Help's built-in cheat sheets tutorial || None
|}

=Questionnaire=
The questionnaire can be found here: http://wiki.wesnoth.org/User:Timotei21/Questionaire

FAQ

2011-08-08T15:29:03Z

Timotei21: mention the eclipse plugin

{{FAQ/Translations}}
== General ==

===What is Battle for Wesnoth?===
Battle for Wesnoth is a turn-based tactical strategy game with a high fantasy theme, featuring both single-player, and online/hotseat multiplayer combat.

===What license is the game distributed under?===
The project is distributed under the [http://www.fsf.org/copyleft/gpl.html GPL]. All contributors retain copyright on the portions of the project that they contribute. For more information, see [[Wesnoth:Copyrights]].

===How to get informed about new releases?===
Check the front page of the website.

===A new version is out, but where is the download for [Windows, Mac OS X, etc.]?===
The packages provided, other than the source code tarball, are '''not''' part of the official project. The BfW team only releases the game's source code. Binary executables or applications are always contributed by community volunteers. If not for these volunteers, there would never be any downloads for us to enjoy. The volunteers compile the game and upload it on their own time, and sometimes they cannot do this in a timely fashion (or at all, at times). Although there are usual packagers designated for each operating system, there are times when other members of the community are asked to step in and contribute when the usual people cannot.

Every time a new version is released, the usual volunteers are notified by the project leaders. '''Please refrain from making forum posts asking where your download is''' because it doesn't help anything - the packagers already know, and they will get to it as soon as they can. In the past, the Windows and Mac communities have come together to produce home-grown unofficial builds for the community to use, and the renewed interest in community and learning how to compile is generally a good thing.

===Why doesn't Wesnoth have my favorite feature?===
Because we are building this game for ourselves, to suit our own preferences. We're not building the game for you, in large part because this is our hobby, not our job; whether you like it or not is immaterial to us.
You may wonder, then, what the point is of soliciting ideas, as we do on the forum. We, the developers, have certainly come up with many good ideas on our own, but our players often do as well, and generally ones we don't think of ourselves. If a player comes up with an idea we like, we might implement it. Not because they asked for it, but because of its own merits as an addition to our game.

The beautiful thing about the license our game is distributed under, as compared to closed-source, commercial games, is that if you want that feature badly enough, you can take the code and art of our game and modify it yourself; you are free to re-use any work in Wesnoth, as long as you follow the rules of the [http://www.fsf.org/copyleft/gpl.html GPL]. From this, you can build a game exactly the way that you like. Just don't expect us to build that game for you. Building this game is our hobby, not our profession, and you did not pay us to make it; rather, we are the ones who have paid for it, in time and labor.

===Do you want help making this game? How can I help?===
Yes, we want your help. Whether you're a programmer, artist, musician, writer, translator, level designer, playtester, or just have some great suggestions, you're welcome to contribute. How? You can:
* join the [http://www.wesnoth.org/wiki/Project project]
* share your opinions at the [http://www.wesnoth.org/forum/ Forum]
* talk with us on [[Support#IRC|IRC]]
* [[ReportingBugs|report]] bugs you find with Wesnoth and its mainline content
* update the wiki
* play against other players via the [[GettingStarted#Multiplayer|Multiplayer]] menu
* vote for Wesnoth at your favorite gaming web site
* spread the word!

=== What are the system requirements? ===
'''outdated!'''
We are not completely certain, but an x86 running at 400 MHz with 128 MB RAM should be adequate for versions 1.0.2 and below. For versions 1.1 and up we recommend a computer with at least 1 GHz and 512 MB RAM if you run KDE or Gnome as Windowmanager (The game itself needs about 100 MB RAM). Slower machines will have trouble scrolling large maps or processing AI turns with many units. See the [http://www.wesnoth.org/forum/viewtopic.php?t=7384 forum thread] about minimum and recommended system requirements.

=== I'm bored; how do I speed the game up? ===

There are several preferences you can change to shorten the time that the AI takes to make its moves. "Accelerated Speed" will make units move and fight faster. "Skip AI Moves" will not show the AI's units moving from hex to hex. Finally, you can turn off all combat animations via the "Show Combat" option on the Advanced tab.

=== My computer is too slow; how do I speed the game up? ===

First, turn off the music and sound effects. Turning off the color cursors will make your cursor respond faster. If scrolling the map is slow, run the game in "Full Screen" mode, not in a window. Turn off combat, map, and standing unit animations via the "Show Combat", "Animate Map" and "Unit Standing Animations" options on the Advanced tab in the game Preferences. You can try turning off halos and combat results, but this might make gameplay more difficult.
For some tips on tweaking the startup, see [[CustomizingStartup]].

== Gameplay and Controls ==

=== How do I learn to play? ===

If you just want to jump right in, start the game and play the tutorial. If you like reading documentation, see [[WesnothManual]]. At any time while playing, you can select help from the menu button (or hit F1). The online help is quite extensive and provides information on terrains, weapons, traits, abilities, units and a good overview of how to play.

=== My unit leveled up but didn't improve. What happened? ===

This is called "After Maximum Level Advancement" or AMLA for short. While most level 0, 1, and 2 units can advance, some cannot. However, some level 3 units can advance to level 4, or even 5. You can see whether a unit can advance further by right clicking and selecting "description."

After a unit reaches the highest level it can get, every time it reaches a new experience threshold (which increases with each advancement) it gains 3 hitpoints and is restored to a state of full health. This is a minor bonus so that experience gained by maxed out units is not altogether wasted. It is generally better to give experience to lower level units, rather than continue to advance units that have reached their maximum level.

=== I tried to trap an enemy with several weak units, but it still escaped. What happened? ===

Most units exert a zone of control (or ZoC). If an enemy moves into one of the six adjacent hexes, the zone of control will prevent it from moving any farther. However some weak units are level 0, meaning they are so weak that they do not have a ZoC. You can still surround an enemy unit entirely with level 0 units to keep it from escaping, but if there is any gap in your ranks, it could escape.

Also, some units have the "skirmish" ability, which allows them to ignore ZoCs.

=== How can I see where an enemy unit can move next turn? ===

During your turn you can click on an enemy unit. Wesnoth will highlight all the hexes the unit can move to in the next turn. This is useful when trying to arrange your units to block an enemy's movement.

=== There's too much luck in this game! ===

Sooner or later, you will become frustrated when your archmage with four 70% attacks misses all four times. This does not mean that the AI is cheating or the random number generator is futzed. It means you are noticing random negative events more than positive ones. During the development of the game, many mathematicians have done sophisticated statistical analysis of the combat system. Likewise, programmers have examined the random number generator. No flaws have been found, so streaks of "bad" and "good" luck should just be accepted as part of having randomness in Wesnoth. A more detailed rational and discussion of the role that randomness plays in Wesnoth can be found [http://www.wesnoth.org/forum/viewtopic.php?f=6&t=21317&start=0&st=0&sk=t&sd=a here].

Since Wesnoth is GPLed, it is possible that a new development team will someday "fork" the source and produce a version more like Heroes of Might & Magic, with less or no randomness. Until then, don't charge with your horsemen against troll rocklobbers at night...

=== The (random unit) is overpowered/underpowered! ===

The development team has spent years tweaking the units in the game. Each unit has had its gold cost, attack types, combat damage, defensive values, resistances, upgrade paths, and other stats carefully scrutinized and loudly discussed in the forum. However, the game code and the units were being modified right up until the 1.0 release, so some unbalanced units may have slipped through.

If you have evidence to back up your claim, search the forum for past discussions about this unit, and then try posting.

=== The (random scenario) is too hard/easy! ===

See above answer about random units.

=== What do the different difficulty levels do? ===

That depends on the scenario. Usually, the opponent will get more money and be able to recruit higher-level units at higher difficulty levels, and you will have fewer turns available.

== Maps, Scenarios and Campaigns ==

=== How do I beat scenario _______ ? ===

If you are stuck on a scenario in a campaign, you'll probably find a walkthrough at [[MainlineCampaigns]]. Or check out the "Strategies and Tips" forum at http://www.wesnoth.org/forum/viewforum.php?f=3

=== How do I download user campaigns? ===
Choose "Campaigns" in the main Wesnoth menu. Then scroll down to the bottom and choose "Get More Campaigns..." or since 1.1.5 there is a "Get add-ons" button in the main menu. This connects you to the campaign server. In the campaign server you can view a list of all available campaigns and download them, as well as posting or deleting your own campaigns.

If you are behind a firewall you may not be able to connect to the campaign server. In this case try to download the campaign directly from the campaign server through the web interface at http://wolff.to/campaigns/list.html. If you know how to change your firewall settings, then you should open port 15003 (version 1.1.1 and up) or port 15002 (versions 1.1.0 and lower). For added security, you can restrict traffic over those ports to the campaign server's IP address (currently 88.191.12.200).

=== Are there any tools to help me create maps and scenarios? ===
Yes, the game includes a built-in map editor, that you can use to build the terrain maps for your scenarios.

Unfortunately, there's no simple solution for creating the rest of what constitutes a complete scenario or campaign, which is the [[ReferenceWML|WML]] code. There have been some abandoned attempts at creating complete scenario editors such as [[CampGen]], but they are no longer maintained, nor do they work with the latest stable versions of the game.

You should take a look at the [[Create]] section for information and guides that can help you build your own scenario or campaign. Taking a look at how existing content works is also a good idea.

=== What are the .cfg files and how can I edit them? ===

The .cfg files are plain text files, saved with the file extension ".cfg". You can create and edit them using normal text editors; just save the files in correct format.

Please note that some Windows programs like to add a ".txt" extension, so the file is instead of "my_scenario.cfg" saved as "my_scenario.cfg.txt". And then the Windows Explorer will hide the ".txt" extension by default, so you may not notice it.

'''Notepad''': After you create a document, click "File", "Save as..." and select "Save as type: All files". To open the document, click "File", "Open..." and select "Files of type: All files (*.*)". If you open someone else's document, and the end-of-line symbols are displayed as small rectangles, you have to use another editor.

'''WordPad''': After you create a document, click "File", "Save as..." and select "Save as type: Text Document". After the document is saved, close WordPad and remove the ".txt" extension from file. To open the document, click "File", "Open..." and select "Files of type: All documents (*.*)".

Starting with the 1.9.x branch, there is a new IDE for helping User Made Content Authors to easily develop Wesnoth Add-ons. The website and details can be found at: http://eclipse.wesnoth.org

=== I already created an add-on and published it on the server. How can I get translations for the campaign? ===
Just have a look at [[WesCamp]]. This project is the easiest way to get translations for your campaign. All the info you need you can find at [[WesCamp]].

===How do I place an object or unit on my map with the map editor?===
You can't. You need to make a scenario file. There are more details on the [[BuildingMaps|maps]] page.

== Multiplayer ==

===How do I connect to a multiplayer server, when I sit behind a restrictive firewall?===

You have to open outgoing TCP port 15000 - 14997 (depending on the version you use) to play multiplayer games over the internet on the official servers.

===How to find players for multiplayer game?===
Hang around for a while on multiplayer servers and you might find someone to play with. If you observe other people playing you will get informed when someone joins the servers. Maybe you find someone willing to play in the [[Support#IRC|IRC]] channel dedicated to Wesnoth, #wesnoth at irc.freenode.net.

===How to save and load a multiplayer game===

Save the game. Give it a good name, so that you can find it among the other saved games.

Create new game. (Give it a name like "private game for X and Y", so that other players will not try joining it, and you do not have to explain or kick them.) The first item in the map/scenario list is "Saved games", select this. Choose the saved game. Wait for the other player(s) to connect. Start the game.

===How can I make my computer into a dedicated Wesnoth server?===

To setup a dedicated Wesnoth server, you have to compile the game with the "--enable-server" flag, and after you install, simply run wesnothd from the console. This will start the server, listening on TCP port 15000. To compile the server only you can use the flags "--disable-game --enable-server". If you aren't using a linux or mac operating system, there are a few ways you can compile on Windows... [[CompilingWesnoth/CrossCompiling|here is one way]].

'''Note:''' Packages for Wesnoth 1.4 and later include wesnothd by default since it's required by the "Host a network game" option from the Multiplayer menu, which is the preferred option for temporarily hosting a server instance to play in a LAN or privately through the Internet.

===Which versions of Wesnoth can play together?===

You only need to make sure you are using the same minor version number (6 in "1.6.x", 8 in "1.8.x" and so on) corresponding to stable branch releases. If you are using a development release (odd minor version numbers), you must be using exactly the same version number as other clients, to avoid out-of-sync (OOS) issues in multiplayer.

If you are using user-made eras or MP scenarios, all players should make sure they are using the same, latest version of the add-on.

== Translations ==

===Where can I find more information about translating Wesnoth?===
See [[WesnothTranslations]] for a list of currently maintained projects, and methods for contacting their maintainers and volunteering for help, and instructions for starting your own translation if it isn't included in the game already. [http://gettext.wesnoth.org] shows the current progress translations for different game development and stable branches, mainline campaigns and user-made add-ons.

== Other Questions You Have ==

The best way to get answers to less-frequently asked questions is by visiting the official [http://forums.wesnoth.org Battle for Wesnoth forums]. There are plenty of people willing to help. Make sure you read ALL of the forum sticky notes and announcements before posting!

[[Category:Troubleshooting and Bugs]]

SummerofCode2011 Timotei21

2011-08-06T15:22:41Z

Timotei21: update progress

{{SoC2011Student_2|timotei|SoC_Ideas_Eclipse_Plugin2011}}

=Description=
<h4>timotei - Improving the Eclipse Plugin</h4>
I aim at improving the plugin, so it will become the tool used by all UMC Authors. That is, UMC Authors will get rid of the lot of different tools they use for different tasks (for example the Emacs WMLMode/other plugins for different text editors), and instead use one single unified Tool that will speed up the development. My target is to make this plugin a complete and very stable suite for all umc tasks that don't need specialized software - like a graphics editor, so I'd like to have this oportunity to finish it in the good sense.

=Contacts=
==IRC==
timotei

==Other==
Forum: timotei 
gna.org: timotei

=SoC Application=
[http://www.google-melange.com/gsoc/proposal/review/google/gsoc2011/timoteidolean/1 Battle for Wesnoth - Google Summer of Code Application]

=Proposal Summary=
Page Last Updated: {{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}} 

In the following lines I will give details on how I'm planning to implement some of the required tasks, and also add some new ones.

The ''Notes'' sections are aimed for personal guideliness. They are took from my todo list.

==Multiple Wesnoth installations==
Having multiple wesnoth setups, and working with them at the same time would be nice to be done from inside the plugin.
For that, there will be a new preferences page. The page will look something like this:
http://dl.dropbox.com/u/462510/personal/soc/installations_management.PNG

There will be buttons that add/remove/edit a certain wesnoth installation. When adding/editing an installation, a new page like the current one (in which we set the paths), will be shown. The user will be able to name it and specify the version (I could automatically get the version by invoking ''wesnoth --version'').
The current page for setting the paths will act as a default installation.

After we have configured the paths, the user can chose the installation to which the (new) projects are bound, by opening the project properties. There will be a wesnoth-related page, where the user will be able to chose to what installation the project binds. With that, every command that uses the paths, won't use the single current paths, but the ones assigned to each project. This project properties page will open new ways for adding new

There would be a problem in case the project will be migrated between 2 different plugin's versions. For example, in one place we would have defined "1.9.4svn" but on the other there would be "trunk".

We can solve this in 3 ways:

# Alert the user that the installation doesn't bind, and let him chose the current matching installation for his plugin.
# Default automatically to the current plugin's default installation.
# "Hardcode" the version, so that there may be defined just installations like: 1.8.0, 1.9.3. With this we lose some flexibility, but we could use this as base version for new installations, so for example, a user can have two 1.9.3 installations. Provided this, we have again a possible problem, which can be solved again by 1. or 2., but this time, trying to match the base version first.

With this feature, the user won't need to restart the plugin at all, switching workspaces.

Regarding the technical PoV, all paths will be stored using eclipse's preferences system, by appending an unique id of each installation to each path in that set.

''Note'':
Add the NO_TERRAIN_GFX preprocess option checkbox to the project properties rather than being a global one.

==Enhance the Content Assist(CA) feature==
The CA framework is very extensible but it lacks proper contexts for providing the content.
I was thinking of trying to accomplish the generating of CA list either by using a config file, in case something like that can be used or writing directly the code that does that.

Another factor that is involved in a better auto-complete, is the ''schema.cfg'' the plugin bases on. Depending on whether the schema is worked on during this summer of code, I'll need to redo a bit the parser of the schema, in case the format/semantics change.

===Project files dependecy tree===
In order for the CA to work better - and maybe other areas would benefit from this - we will need to build a project files tree. With that tree, we can see how a certain declared macro/variable will affect subsequent related files and also their scope. Basically, we can see the relation from a file to anothers.

This tree will be (re)built in 2 situations:
# A file is added/removed/changed it's name
# A full rebuild is triggered (for example, the project is added for the first time in the workspace)

The tree will be built by the WML parser's rules:
# files are processed in the alphabetically order
# _initial.cfg is the first processed before anything else.
# _final.cfg is the last processed after anything else.
# if there is a _main.cfg in the directory, it is the only one processed.

Since the current ''WesnothProjectBuilder'' doesn't take in account the previous rules, I will create my own method of visiting each folder's children in the correct order. This method will look close to wesnoth's one, namely ''get_files_from_in_dir()'' found in ''src/filesystem.cpp:93''.

For a very fast lookup, as a data structure we will use a Hashtable, which has as the key the local project path to the file, and as a value a custom structure, which has the previous/next/parent/son properties, used to traverse the tree. The previous/next go on the same tree level, while the parent/son go up/down in the tree. I will use this instead of a tree, because this will give us access to info about a file, faster, in O(1) compared to a breadth-first search which has O(V+E) - where V is number of vertices and E number of edges.

Talking with Crab about this, he alerted me about a little possible problem with current aproach:
<Crab_> a note about 'The tree will be built by the WML parser's rules: ' - don't forget that you can (conditionally) include files/dirs from a file.
<Crab_> so, if we have 'ai/ais/zzz' which, say, defines a macro, it might get included by campaigns/bbb/scenarios/some_scenario.cfg , even if it is not inside /campaigns/bbb/scenarios

For that we have 2 cases:
{~file/dir path}
or
{file/dir path}

The paths are simply discarded if the current project's directory name is not found in the path.

Currently the so called "Tree" will be actually just a List or a single path tree. For the first iteration of this project, I won't tackle the advanced macro usage that might direct the flow based on defines (this will be optional if there will be time in GSoC, or if not, after GSoC, since I plan to remain active developer to maintain the plugin/enhance it furthermore). So, for example (taken from LoW):

#ifdef CAMPAIGN_LOW

{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#endif

#ifdef MULTIPLAYER

#define EASY
#enddef
{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#undef EASY
...
#endif

With current way to do this we will just take "blindly" all included directories/files without taking in consideration the #define flow control.

If we are at LoW, the following tree(list) will be created on its project:

_main.cfg -> utils/*.cfg -> scenarios/*.cfg -> units/*.cfg

Each file in the dependency tree, will have associated a number. For more details on why this and how it's done, read the Scoping section.

===Scoping===
In order for the plugin to know more about the semnatics, it should have the posibility to represent scopes. The scopes will be used mainly for variables and macros.

The Scoping is a delicate problem, because there are some tricky situations that might interfere with the scoping. I choosed to represent scoping in the following way:

Scoping is everything just about order relations. That is, we will compare numbers when dealing with scoping. With that we move the "problem" upper, to the "Dependency tree". We won't use filenames/paths because:

* The filename might change, but the order index may not. So, not having to update the index helps us.
* Number comparison is faster than string comparison.

So, from now on we'll talk in terms of indexes instead of filenames for scoping.

So, we are working with numbers. But there is still a lil' problem. What happens, when we remove/need to add a new file in the current tree, in the middle of existing 2? We would need to update all subsequent files's indexes. That would not be so ok performance wise.

To counter this problem we will not use consecutive numbers, but rather have a certain step between numbers. The step might be configured inside the plugin based on real statistics (for example, trying to see the number of cfg files per project. Taking a big number, like 1000 won't really hurt). For example, we could take the step 50. That means we would have the following tree for LoW:

0 50 100
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

instead of:
0 1 2
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

So, when it's the case of insertion, we insert the new node at the ''middle'' of the current "distance". That way we may insert/delete files *without* breaking the order, and our scoping will still work.

There is another problem it rised in my head: how do we know when to put the number as the next step (the previous number + step) or add it in the middle? Well, since every project will surely do a '''Full Build''', we'll use that oportunity to create the initial tree. Afterwards we will just insert files based on the halving of the distance between 2 indices.

The scoping will be represented by a simple structure, consisting of start index and offset and end index and offset.

===Content Assist Config(CAC) Files===
The CAC files will provide values that are default/available to config files from the wesnoth engine itself. There will be several files that define the values based on their context. This will allow a very great flexibility editing the CA list.

A CAC file will be just a simple text file, that has on each line one (or more) value(s) depending on the context.

* The ''cac/variables.txt'' will contain variables available. The list is currently available at [http://wiki.wesnoth.org/VariablesWML#Automatically_stored_variables]. For example the file could look like:
$side_number
$turn_number
...

* The ''cac/events.txt'' will contain the game events. The list is availabe at: [http://wiki.wesnoth.org/EventWML#Predefined_.27name.27_Key_Values]. Since the events that have spaces in their names can replace that with an underscore '_', the file will contain the underscore instead space variants also.



===Variables===
The variables are either defined by user or defined by default by the wesnoth engine. User's variables will be parsed from each processed file by the WesnothProjectBuilder, using the WMLSaxHandler. The default variables will be parsed and added from the CAC file. (cac/variables.txt)

Variables definitions can be triggered using the VARIABLE macro:
{VARIABLE var_name "value"}
or the [set_variable] tag:
[set_variable]
name=my_var
value="value"
[/set_variable]

The ''ConfigFile'' class in the ''org.wesnoth.wml.core'' already has a list of variables. The ''Variable'' class has some fields that allow its identification. We will build that list when we parse each file, adding each variable found by the previous defined triggers.
When the content assist finds the '$' character, it will supply the user + default variables gathered so far.

Since the variables can be cleared, thus they have scope, the ''Variable'' class needs to be refactorted, so it can represent the scope aswell. The scoping was settled before.

===Name Collisions===
I've considered that we should store the variables per project, like we currently do with macros. This will minimize the memory we need, rather than storing variables on each file - like we do currently. With this, I've discovered it's innevitable to have ''collisions''. That is, have the same variable name on multiple files.

To solve this problem, each variable/macro structure, will not have just a single scope, but rather a list of scopes.

===Events===
Besides the default event names, supplied by the wesnoth engine, there can be created custom ones, wich will be triggered with [fire_event]. As usual the default events names will be available in the cac/events.txt file.

The events defined by the user will be parsed from the ''name'' attribute of the [event] tag.

===Attributes===
All attributes are currently got from the schema.cfg

===Attributes Values===
All attributes values should be parsed based on the schema.cfg.

===Macros===
The support for macros is already built in, but it needs a way to let them have scope. That is, when an #undef is found, the certain macro would not be available to subsequent files unless redeclared. This will be done with the aid of the dependency tree and scoping. The collisions will be solved like I said at the variables section

===Support for custom luaWML tags===
The lua can create new WML Tags. It would be nice that the plugin suggest those aswell besides the ''schema.cfg''. The lua will be easily parsed, since there is a simple pattern for creating new tags:
wesnoth.wml_actions.<tag name>(cfg)

The parser will just run over the lua code/file, over each line, trying to match the 'function *wesnoth.wml_actions.*' pattern. If it finds something, it will add the tag name to the list of tags. There is also a small thing we might have missed. The user could use a shorthand notation for the actions namespace, so when searching for the pattern, I will add to the 'pattern to match' list, the respective variable when searching for new WML Tags.

Thus, like the ''wml-tags.lua'' from the data/lua uses:
local wml_actions = wesnoth.wml_actions

the 'to match' list will contain: 'function *wesnoth.wml_actions.*' and 'function *wml_actions.*', thus finding other tags too.

Going further more, for an ''optional'' enhancement, I could also search that function to see if it needs/has some extra attributes. The attributes can be found by:
* function's parameter (usually cfg) is asked for a property. For example:
function wml_actions.terrain(cfg)
local terrain = cfg.terrain or helper.wml_error("[terrain] missing required terrain= attribute")
cfg = helper.shallow_literal(cfg)
cfg.terrain = nil
for i, loc in ipairs(wesnoth.get_locations(cfg)) do
wesnoth.set_terrain(loc[1], loc[2], terrain, cfg.layer, cfg.replace_if_failed)
end
end

Here we need the attributes ''terrain'', ''layer'' and ''replace_if_failed''.

* ''get_child'' call:
function wml_actions.message(cfg)
local show_if = helper.get_child(cfg, "show_if")
if not show_if or wesnoth.eval_conditional(show_if) then
engine_message(cfg)
end
end

Here we need to have the attribute ''show_if''.

==Automatic/headless building==
The eclipse plugins can be automatically built from command line, provided there is the eclipse sdk and the eclipse delta pack on the builder's machine. The plugin can also use Buckminster tool to automate the building of the plugin.

''Notes''
Add all plugin's files *inside* a folder to prevent cluttering the directory where it's extracted

More info at:
* http://wiki.eclipse.org/PDE/Build
* http://wiki.bioclipse.net/index.php?title=How_to_build_plugins_headless
* http://help.eclipse.org/galileo/index.jsp?topic=/org.eclipse.pde.doc.user/guide/intro/pde_overview.htm
* http://www.eclipse.org/articles/Article-PDE-Automation/automation.html

==Standalone app auto-update==
The current standalone application doesn't offer the same eclipse's update system. I will add it, so anytime there is a new version of the plugin, it can be updated with a single click by the user, without the needing to download a new standalone app again.

==Documentation==
===External documentation===
The current existing readme will be split in 2 manuals: User Manual and Developer Manual (Don't forget to add images where relevant).

The user manual will contain:
* Prerequisites and Installing the prerequisites
Note: don't forget to mention the MINIMUM eclipse/java version needed to run
* Installing the plugin / standalone version
* Using the plugin
* Plugin features
* Step-by-step use cases
** Setupping the workspace
** Creating a new project and running it in the game
** Importing existing projects
** Using the WML Editor
** Updating the plugin
* Frequently Asked Questions

The developer manual will contain:
* Prerequisites and Installing the prerequisites
* Adding the plugin's projects in the
* Compiling and Running the plugin
* Deploying the plugin and standalone app

===Internal documentation===
The Eclipse infrastructure has features for letting the developer embed help into the application, depending on the current context. After I will write the external documentation, I will work on adding internal documentation aswell. Some of it already comes from the external one.

* Plugin welcome page
* Eclipse Help (When pressing Help->Help contents)
* Wizards help

==Plugin polishing==
This are some tasks needed to be done in order to get the plugin more stable and more usable than it's currently. Some of the tasks are taken from my todo list. New tasks will be added through the project advancing when improvements to actual code /user interaction can be done, so this list is not final.

# Don't copy a project that belongs to data/campaigns to the user addons's directory. This can be done by looking at the path when creating a new project. (This is prevented by not spawning a ''build.xml'' file in the campaigns's directory)
# Enhance the logging so it can help debugging other's problem much easier. I could split the current log in 2:
## Commands executed by the plugin
## Other information like parsed information/statuses
# Enhance the integration with the eclipse platform by adding the "Wesnoth" related wizards directly to the "New" menu.
# Allow users to import a directory as a wesnoth project. Under the hood it will either open the wesnoth project (if there is any .project files in it) or create a new empty project on it.
# Allow the user to clear it's current plugin's settings just with a simple button.
# Wesnoth Project Explorer - Add error markers just like the Java Explorer has
# Refactor the current way of getting the macro list. Currently if there is no _main.cfg practically the _MACROS_.cfg file is not built resulting in no MACRO suggestions.
# Create a view filter to hide the Project ''_AutoLinked_CFGExternalFiles_'' which is created for opening the external config files (external meaning outside the current workspace).
# Fix the F3 navigation when the map's location is specified withing " ", as a string.

===New parsing method (optional)===
The current parsing method involves a lot of Wesnoth preprocessor/wmlparser.py. This is doing somehow the parsing job double. This is because the xtext framework already does 1 pass over the files when added to the project. My plan is to see if I can reuse the already built AST(Abstract Syntax Tree) and the parse tree, to use those values instead of additional preprocessing/wmlparsing, and use the latter only when really needed.

Using the xtext's model will greatly fasten the "build" time of each project and it will be *much* simpler to work with, since the framework already provides exceptions recovering (that is, when the code is not well formed according to the grammar) and based on the defined grammar the respective tokens. So, for example instead using 2 another external processes, we could just iterate over each WMLTag and get it's WMLKeys and parse their individual values.

If this idea works, I will add it on the Plugin polishing tasks.

==Other ideas==
===Addons management===
There will be a new Addons management view. It will behave much like the in-game addon manager, but it will be more handy since the user doesn't need to start the game for that (and also wait till the cache refreshes after downloading it). This view will be based on the python script from '''data/tools/wesnoth_addon_manager''', like it does currently for uploading the project as an addon.

The view will let the user see the list/details for each of the addons currently on the server. There will be also a filter based on what addon server to use (trunk/1.8/1.9/etc)

The user will be able to just right click on an addon and download it to it's user data folder. Optionally a new project will be created, based on the just downloaded addon.



===Unit testing===
====Grammar====
For a better wml handling with in the editor, I will create a Testing class for the current grammar. The class will do testing on all *.cfgs in the data directory. That way after modifing something in the grammar we will be able to see how many errors we have introduced/eliminated. This will greatly help the developing of a better grammar that can hold all current WML formats.

''Notes'':
optionally rework the grammar and try to use a custom lexer/parser in order to benefit from the preprocessor, injecting the valid tokens. This would help the cases when the current grammar doesn't work:
{name} = value
or unclosed tags

====Parsing and getting information from files====
I will create some basic (or taken from existing campaigns) config files that will be parsed in order to check if the correct behaviour - correct information is extracted from the files.

This will check for extracting the:
scenario name
campaign name
next_scenario
first_scenario
variables
macros

=Timeline=
The GSOC period is between 24th May and 20th August. But since I have exams for 3 weeks (during 30.05-19.06.2011), I will start working on the plugin before the 24th of May, to recover some of the lost time. Also, my ImagineCup team made it to the national phase - that is in 5,6,7 May. That means till that time I will not be able to do so much work, so I'll make the timeline according with the starting of work on 9 May.

Here is a table with key periods of the time spent on this project.
{| border="1"
|'''Period''' || '''Actions'''
|-
| 26 April || Get accepted
|-
| 26 April - 8 May || Busy working on ImagineCup project for the national phase. Little or no work done.
|-
| 9 May - 15 May || Allow headless build of the plugin
|-
| 16 May - 22 May || Add Support for multiple installations
|-
| 23 May - 28 May || Add the auto-update feature for the standalone app
|-
| 30 May - 19 June || Exams
|-
| 20 June - 24 June || Create the external documentation
|-
| 25 June - 16 July || Enhance Content Assist
|-
| 15 July || Mid-term evaluations deadline
|-
| 17 July - 24 July || Addons management view
|-
| 25 July - 30 July || Unit tests
|-
| 1 August - 14 August || Do the Plugin polishing tasks
|-
| 15 August || Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc.
|-
| 15 August - 17 August || Create the internal documentation.
|-
| 18 August - 22 August || Buffer half-week. This will be used in case some tasks fell a bit outside their proposed time.
|-
| 22 August || Firm 'pencils down' date. Mentors, students and organization administrators can begin submitting final evaluations to Google.
|}

=Tasks=
This is a list of the "atomic" tasks that need to be done, based on the project part. Since the big tasks are split into smaller task, the progress will be seen better and any problems that arise with the timeline will be seen faster. I will update this table based on my current progress.

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Headless build ||Research about what system to use for automatic building of the plugin || Done
|-
| Headless build || Implement the chosen system for the wesnoth plugin|| Done
|-
| Multiple installations || Implement the preferences pages || Done
|-
| Multiple installations || Implement the logic for saving and loading the installation's paths on the disk || Done
|-
| Multiple installations || Implement the project preferences page || Done
|-
| Multiple installations || Rewrite the current mechanisms that use the paths to use the ones based on the project. || Done
|-
| Auto-update || Implement the auto-update feature. || Done
|-
| Documentation || Write the User Manual || Done
|-
| Documentation || Write the Developer Manual || Done
|-
| Documentation || Write the internal documentation || Done
|-
| Enhance Content Assist || Project dependency tree || In progress
|-
| Enhance Content Assist || Content assist files || Done
|-
| Enhance Content Assist || Variables || Done
|-
| Enhance Content Assist || Events || Done
|-
| Enhance Content Assist || Lua tags || Done
|-
| Addon management || Create the GUI of the view || Done
|-
| Addon management || Create the view's logic || Done
|-
| Unit testing || Tests for the grammar || Done
|-
| Unit testing || Tests for parsing the config files || Done
|-
| Plugin Polishing || Task 1 || Done
|-
| Plugin Polishing || Task 2 || Done
|-
| Plugin Polishing || Task 3 || Done
|-
| Plugin Polishing || Task 4 || Done
|-
| Plugin Polishing || Task 5 || Done
|-
| Plugin Polishing || Task 6 || In progress
|-
| Plugin Polishing || Task 7|| Done
|-
| Plugin Polishing || Task 8 || Done
|-
| Plugin Polishing || Task 9 || Done
|}

Optional tasks will be dealt with if the time allows it:

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Enhance Content Assist || Project dependency tree with multiple paths based on defines || None
|-
| Enhance Content Assist || Lua tags attributes || Done
|-
| Grammar || Enhance the grammar to support the 2 current unsupported syntax constructs || None
|-
| Documentation || Implement a simple WML project from start to end using Help's built-in cheat sheets tutorial || None
|}

=Questionnaire=
The questionnaire can be found here: http://wiki.wesnoth.org/User:Timotei21/Questionaire

SummerofCode2011 Timotei21

2011-08-02T07:08:21Z

Timotei21: update progress

{{SoC2011Student_2|timotei|SoC_Ideas_Eclipse_Plugin2011}}

=Description=
<h4>timotei - Improving the Eclipse Plugin</h4>
I aim at improving the plugin, so it will become the tool used by all UMC Authors. That is, UMC Authors will get rid of the lot of different tools they use for different tasks (for example the Emacs WMLMode/other plugins for different text editors), and instead use one single unified Tool that will speed up the development. My target is to make this plugin a complete and very stable suite for all umc tasks that don't need specialized software - like a graphics editor, so I'd like to have this oportunity to finish it in the good sense.

=Contacts=
==IRC==
timotei

==Other==
Forum: timotei 
gna.org: timotei

=SoC Application=
[http://www.google-melange.com/gsoc/proposal/review/google/gsoc2011/timoteidolean/1 Battle for Wesnoth - Google Summer of Code Application]

=Proposal Summary=
Page Last Updated: {{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}} 

In the following lines I will give details on how I'm planning to implement some of the required tasks, and also add some new ones.

The ''Notes'' sections are aimed for personal guideliness. They are took from my todo list.

==Multiple Wesnoth installations==
Having multiple wesnoth setups, and working with them at the same time would be nice to be done from inside the plugin.
For that, there will be a new preferences page. The page will look something like this:
http://dl.dropbox.com/u/462510/personal/soc/installations_management.PNG

There will be buttons that add/remove/edit a certain wesnoth installation. When adding/editing an installation, a new page like the current one (in which we set the paths), will be shown. The user will be able to name it and specify the version (I could automatically get the version by invoking ''wesnoth --version'').
The current page for setting the paths will act as a default installation.

After we have configured the paths, the user can chose the installation to which the (new) projects are bound, by opening the project properties. There will be a wesnoth-related page, where the user will be able to chose to what installation the project binds. With that, every command that uses the paths, won't use the single current paths, but the ones assigned to each project. This project properties page will open new ways for adding new

There would be a problem in case the project will be migrated between 2 different plugin's versions. For example, in one place we would have defined "1.9.4svn" but on the other there would be "trunk".

We can solve this in 3 ways:

# Alert the user that the installation doesn't bind, and let him chose the current matching installation for his plugin.
# Default automatically to the current plugin's default installation.
# "Hardcode" the version, so that there may be defined just installations like: 1.8.0, 1.9.3. With this we lose some flexibility, but we could use this as base version for new installations, so for example, a user can have two 1.9.3 installations. Provided this, we have again a possible problem, which can be solved again by 1. or 2., but this time, trying to match the base version first.

With this feature, the user won't need to restart the plugin at all, switching workspaces.

Regarding the technical PoV, all paths will be stored using eclipse's preferences system, by appending an unique id of each installation to each path in that set.

''Note'':
Add the NO_TERRAIN_GFX preprocess option checkbox to the project properties rather than being a global one.

==Enhance the Content Assist(CA) feature==
The CA framework is very extensible but it lacks proper contexts for providing the content.
I was thinking of trying to accomplish the generating of CA list either by using a config file, in case something like that can be used or writing directly the code that does that.

Another factor that is involved in a better auto-complete, is the ''schema.cfg'' the plugin bases on. Depending on whether the schema is worked on during this summer of code, I'll need to redo a bit the parser of the schema, in case the format/semantics change.

===Project files dependecy tree===
In order for the CA to work better - and maybe other areas would benefit from this - we will need to build a project files tree. With that tree, we can see how a certain declared macro/variable will affect subsequent related files and also their scope. Basically, we can see the relation from a file to anothers.

This tree will be (re)built in 2 situations:
# A file is added/removed/changed it's name
# A full rebuild is triggered (for example, the project is added for the first time in the workspace)

The tree will be built by the WML parser's rules:
# files are processed in the alphabetically order
# _initial.cfg is the first processed before anything else.
# _final.cfg is the last processed after anything else.
# if there is a _main.cfg in the directory, it is the only one processed.

Since the current ''WesnothProjectBuilder'' doesn't take in account the previous rules, I will create my own method of visiting each folder's children in the correct order. This method will look close to wesnoth's one, namely ''get_files_from_in_dir()'' found in ''src/filesystem.cpp:93''.

For a very fast lookup, as a data structure we will use a Hashtable, which has as the key the local project path to the file, and as a value a custom structure, which has the previous/next/parent/son properties, used to traverse the tree. The previous/next go on the same tree level, while the parent/son go up/down in the tree. I will use this instead of a tree, because this will give us access to info about a file, faster, in O(1) compared to a breadth-first search which has O(V+E) - where V is number of vertices and E number of edges.

Talking with Crab about this, he alerted me about a little possible problem with current aproach:
<Crab_> a note about 'The tree will be built by the WML parser's rules: ' - don't forget that you can (conditionally) include files/dirs from a file.
<Crab_> so, if we have 'ai/ais/zzz' which, say, defines a macro, it might get included by campaigns/bbb/scenarios/some_scenario.cfg , even if it is not inside /campaigns/bbb/scenarios

For that we have 2 cases:
{~file/dir path}
or
{file/dir path}

The paths are simply discarded if the current project's directory name is not found in the path.

Currently the so called "Tree" will be actually just a List or a single path tree. For the first iteration of this project, I won't tackle the advanced macro usage that might direct the flow based on defines (this will be optional if there will be time in GSoC, or if not, after GSoC, since I plan to remain active developer to maintain the plugin/enhance it furthermore). So, for example (taken from LoW):

#ifdef CAMPAIGN_LOW

{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#endif

#ifdef MULTIPLAYER

#define EASY
#enddef
{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#undef EASY
...
#endif

With current way to do this we will just take "blindly" all included directories/files without taking in consideration the #define flow control.

If we are at LoW, the following tree(list) will be created on its project:

_main.cfg -> utils/*.cfg -> scenarios/*.cfg -> units/*.cfg

Each file in the dependency tree, will have associated a number. For more details on why this and how it's done, read the Scoping section.

===Scoping===
In order for the plugin to know more about the semnatics, it should have the posibility to represent scopes. The scopes will be used mainly for variables and macros.

The Scoping is a delicate problem, because there are some tricky situations that might interfere with the scoping. I choosed to represent scoping in the following way:

Scoping is everything just about order relations. That is, we will compare numbers when dealing with scoping. With that we move the "problem" upper, to the "Dependency tree". We won't use filenames/paths because:

* The filename might change, but the order index may not. So, not having to update the index helps us.
* Number comparison is faster than string comparison.

So, from now on we'll talk in terms of indexes instead of filenames for scoping.

So, we are working with numbers. But there is still a lil' problem. What happens, when we remove/need to add a new file in the current tree, in the middle of existing 2? We would need to update all subsequent files's indexes. That would not be so ok performance wise.

To counter this problem we will not use consecutive numbers, but rather have a certain step between numbers. The step might be configured inside the plugin based on real statistics (for example, trying to see the number of cfg files per project. Taking a big number, like 1000 won't really hurt). For example, we could take the step 50. That means we would have the following tree for LoW:

0 50 100
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

instead of:
0 1 2
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

So, when it's the case of insertion, we insert the new node at the ''middle'' of the current "distance". That way we may insert/delete files *without* breaking the order, and our scoping will still work.

There is another problem it rised in my head: how do we know when to put the number as the next step (the previous number + step) or add it in the middle? Well, since every project will surely do a '''Full Build''', we'll use that oportunity to create the initial tree. Afterwards we will just insert files based on the halving of the distance between 2 indices.

The scoping will be represented by a simple structure, consisting of start index and offset and end index and offset.

===Content Assist Config(CAC) Files===
The CAC files will provide values that are default/available to config files from the wesnoth engine itself. There will be several files that define the values based on their context. This will allow a very great flexibility editing the CA list.

A CAC file will be just a simple text file, that has on each line one (or more) value(s) depending on the context.

* The ''cac/variables.txt'' will contain variables available. The list is currently available at [http://wiki.wesnoth.org/VariablesWML#Automatically_stored_variables]. For example the file could look like:
$side_number
$turn_number
...

* The ''cac/events.txt'' will contain the game events. The list is availabe at: [http://wiki.wesnoth.org/EventWML#Predefined_.27name.27_Key_Values]. Since the events that have spaces in their names can replace that with an underscore '_', the file will contain the underscore instead space variants also.



===Variables===
The variables are either defined by user or defined by default by the wesnoth engine. User's variables will be parsed from each processed file by the WesnothProjectBuilder, using the WMLSaxHandler. The default variables will be parsed and added from the CAC file. (cac/variables.txt)

Variables definitions can be triggered using the VARIABLE macro:
{VARIABLE var_name "value"}
or the [set_variable] tag:
[set_variable]
name=my_var
value="value"
[/set_variable]

The ''ConfigFile'' class in the ''org.wesnoth.wml.core'' already has a list of variables. The ''Variable'' class has some fields that allow its identification. We will build that list when we parse each file, adding each variable found by the previous defined triggers.
When the content assist finds the '$' character, it will supply the user + default variables gathered so far.

Since the variables can be cleared, thus they have scope, the ''Variable'' class needs to be refactorted, so it can represent the scope aswell. The scoping was settled before.

===Name Collisions===
I've considered that we should store the variables per project, like we currently do with macros. This will minimize the memory we need, rather than storing variables on each file - like we do currently. With this, I've discovered it's innevitable to have ''collisions''. That is, have the same variable name on multiple files.

To solve this problem, each variable/macro structure, will not have just a single scope, but rather a list of scopes.

===Events===
Besides the default event names, supplied by the wesnoth engine, there can be created custom ones, wich will be triggered with [fire_event]. As usual the default events names will be available in the cac/events.txt file.

The events defined by the user will be parsed from the ''name'' attribute of the [event] tag.

===Attributes===
All attributes are currently got from the schema.cfg

===Attributes Values===
All attributes values should be parsed based on the schema.cfg.

===Macros===
The support for macros is already built in, but it needs a way to let them have scope. That is, when an #undef is found, the certain macro would not be available to subsequent files unless redeclared. This will be done with the aid of the dependency tree and scoping. The collisions will be solved like I said at the variables section

===Support for custom luaWML tags===
The lua can create new WML Tags. It would be nice that the plugin suggest those aswell besides the ''schema.cfg''. The lua will be easily parsed, since there is a simple pattern for creating new tags:
wesnoth.wml_actions.<tag name>(cfg)

The parser will just run over the lua code/file, over each line, trying to match the 'function *wesnoth.wml_actions.*' pattern. If it finds something, it will add the tag name to the list of tags. There is also a small thing we might have missed. The user could use a shorthand notation for the actions namespace, so when searching for the pattern, I will add to the 'pattern to match' list, the respective variable when searching for new WML Tags.

Thus, like the ''wml-tags.lua'' from the data/lua uses:
local wml_actions = wesnoth.wml_actions

the 'to match' list will contain: 'function *wesnoth.wml_actions.*' and 'function *wml_actions.*', thus finding other tags too.

Going further more, for an ''optional'' enhancement, I could also search that function to see if it needs/has some extra attributes. The attributes can be found by:
* function's parameter (usually cfg) is asked for a property. For example:
function wml_actions.terrain(cfg)
local terrain = cfg.terrain or helper.wml_error("[terrain] missing required terrain= attribute")
cfg = helper.shallow_literal(cfg)
cfg.terrain = nil
for i, loc in ipairs(wesnoth.get_locations(cfg)) do
wesnoth.set_terrain(loc[1], loc[2], terrain, cfg.layer, cfg.replace_if_failed)
end
end

Here we need the attributes ''terrain'', ''layer'' and ''replace_if_failed''.

* ''get_child'' call:
function wml_actions.message(cfg)
local show_if = helper.get_child(cfg, "show_if")
if not show_if or wesnoth.eval_conditional(show_if) then
engine_message(cfg)
end
end

Here we need to have the attribute ''show_if''.

==Automatic/headless building==
The eclipse plugins can be automatically built from command line, provided there is the eclipse sdk and the eclipse delta pack on the builder's machine. The plugin can also use Buckminster tool to automate the building of the plugin.

''Notes''
Add all plugin's files *inside* a folder to prevent cluttering the directory where it's extracted

More info at:
* http://wiki.eclipse.org/PDE/Build
* http://wiki.bioclipse.net/index.php?title=How_to_build_plugins_headless
* http://help.eclipse.org/galileo/index.jsp?topic=/org.eclipse.pde.doc.user/guide/intro/pde_overview.htm
* http://www.eclipse.org/articles/Article-PDE-Automation/automation.html

==Standalone app auto-update==
The current standalone application doesn't offer the same eclipse's update system. I will add it, so anytime there is a new version of the plugin, it can be updated with a single click by the user, without the needing to download a new standalone app again.

==Documentation==
===External documentation===
The current existing readme will be split in 2 manuals: User Manual and Developer Manual (Don't forget to add images where relevant).

The user manual will contain:
* Prerequisites and Installing the prerequisites
Note: don't forget to mention the MINIMUM eclipse/java version needed to run
* Installing the plugin / standalone version
* Using the plugin
* Plugin features
* Step-by-step use cases
** Setupping the workspace
** Creating a new project and running it in the game
** Importing existing projects
** Using the WML Editor
** Updating the plugin
* Frequently Asked Questions

The developer manual will contain:
* Prerequisites and Installing the prerequisites
* Adding the plugin's projects in the
* Compiling and Running the plugin
* Deploying the plugin and standalone app

===Internal documentation===
The Eclipse infrastructure has features for letting the developer embed help into the application, depending on the current context. After I will write the external documentation, I will work on adding internal documentation aswell. Some of it already comes from the external one.

* Plugin welcome page
* Eclipse Help (When pressing Help->Help contents)
* Wizards help

==Plugin polishing==
This are some tasks needed to be done in order to get the plugin more stable and more usable than it's currently. Some of the tasks are taken from my todo list. New tasks will be added through the project advancing when improvements to actual code /user interaction can be done, so this list is not final.

# Don't copy a project that belongs to data/campaigns to the user addons's directory. This can be done by looking at the path when creating a new project. (This is prevented by not spawning a ''build.xml'' file in the campaigns's directory)
# Enhance the logging so it can help debugging other's problem much easier. I could split the current log in 2:
## Commands executed by the plugin
## Other information like parsed information/statuses
# Enhance the integration with the eclipse platform by adding the "Wesnoth" related wizards directly to the "New" menu.
# Allow users to import a directory as a wesnoth project. Under the hood it will either open the wesnoth project (if there is any .project files in it) or create a new empty project on it.
# Allow the user to clear it's current plugin's settings just with a simple button.
# Wesnoth Project Explorer - Add error markers just like the Java Explorer has
# Refactor the current way of getting the macro list. Currently if there is no _main.cfg practically the _MACROS_.cfg file is not built resulting in no MACRO suggestions.
# Create a view filter to hide the Project ''_AutoLinked_CFGExternalFiles_'' which is created for opening the external config files (external meaning outside the current workspace).
# Fix the F3 navigation when the map's location is specified withing " ", as a string.

===New parsing method (optional)===
The current parsing method involves a lot of Wesnoth preprocessor/wmlparser.py. This is doing somehow the parsing job double. This is because the xtext framework already does 1 pass over the files when added to the project. My plan is to see if I can reuse the already built AST(Abstract Syntax Tree) and the parse tree, to use those values instead of additional preprocessing/wmlparsing, and use the latter only when really needed.

Using the xtext's model will greatly fasten the "build" time of each project and it will be *much* simpler to work with, since the framework already provides exceptions recovering (that is, when the code is not well formed according to the grammar) and based on the defined grammar the respective tokens. So, for example instead using 2 another external processes, we could just iterate over each WMLTag and get it's WMLKeys and parse their individual values.

If this idea works, I will add it on the Plugin polishing tasks.

==Other ideas==
===Addons management===
There will be a new Addons management view. It will behave much like the in-game addon manager, but it will be more handy since the user doesn't need to start the game for that (and also wait till the cache refreshes after downloading it). This view will be based on the python script from '''data/tools/wesnoth_addon_manager''', like it does currently for uploading the project as an addon.

The view will let the user see the list/details for each of the addons currently on the server. There will be also a filter based on what addon server to use (trunk/1.8/1.9/etc)

The user will be able to just right click on an addon and download it to it's user data folder. Optionally a new project will be created, based on the just downloaded addon.



===Unit testing===
====Grammar====
For a better wml handling with in the editor, I will create a Testing class for the current grammar. The class will do testing on all *.cfgs in the data directory. That way after modifing something in the grammar we will be able to see how many errors we have introduced/eliminated. This will greatly help the developing of a better grammar that can hold all current WML formats.

''Notes'':
optionally rework the grammar and try to use a custom lexer/parser in order to benefit from the preprocessor, injecting the valid tokens. This would help the cases when the current grammar doesn't work:
{name} = value
or unclosed tags

====Parsing and getting information from files====
I will create some basic (or taken from existing campaigns) config files that will be parsed in order to check if the correct behaviour - correct information is extracted from the files.

This will check for extracting the:
scenario name
campaign name
next_scenario
first_scenario
variables
macros

=Timeline=
The GSOC period is between 24th May and 20th August. But since I have exams for 3 weeks (during 30.05-19.06.2011), I will start working on the plugin before the 24th of May, to recover some of the lost time. Also, my ImagineCup team made it to the national phase - that is in 5,6,7 May. That means till that time I will not be able to do so much work, so I'll make the timeline according with the starting of work on 9 May.

Here is a table with key periods of the time spent on this project.
{| border="1"
|'''Period''' || '''Actions'''
|-
| 26 April || Get accepted
|-
| 26 April - 8 May || Busy working on ImagineCup project for the national phase. Little or no work done.
|-
| 9 May - 15 May || Allow headless build of the plugin
|-
| 16 May - 22 May || Add Support for multiple installations
|-
| 23 May - 28 May || Add the auto-update feature for the standalone app
|-
| 30 May - 19 June || Exams
|-
| 20 June - 24 June || Create the external documentation
|-
| 25 June - 16 July || Enhance Content Assist
|-
| 15 July || Mid-term evaluations deadline
|-
| 17 July - 24 July || Addons management view
|-
| 25 July - 30 July || Unit tests
|-
| 1 August - 14 August || Do the Plugin polishing tasks
|-
| 15 August || Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc.
|-
| 15 August - 17 August || Create the internal documentation.
|-
| 18 August - 22 August || Buffer half-week. This will be used in case some tasks fell a bit outside their proposed time.
|-
| 22 August || Firm 'pencils down' date. Mentors, students and organization administrators can begin submitting final evaluations to Google.
|}

=Tasks=
This is a list of the "atomic" tasks that need to be done, based on the project part. Since the big tasks are split into smaller task, the progress will be seen better and any problems that arise with the timeline will be seen faster. I will update this table based on my current progress.

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Headless build ||Research about what system to use for automatic building of the plugin || Done
|-
| Headless build || Implement the chosen system for the wesnoth plugin|| Done
|-
| Multiple installations || Implement the preferences pages || Done
|-
| Multiple installations || Implement the logic for saving and loading the installation's paths on the disk || Done
|-
| Multiple installations || Implement the project preferences page || Done
|-
| Multiple installations || Rewrite the current mechanisms that use the paths to use the ones based on the project. || Done
|-
| Auto-update || Implement the auto-update feature. || In progress
|-
| Documentation || Write the User Manual || Done
|-
| Documentation || Write the Developer Manual || Done
|-
| Documentation || Write the internal documentation || Done
|-
| Enhance Content Assist || Project dependency tree || In progress
|-
| Enhance Content Assist || Content assist files || Done
|-
| Enhance Content Assist || Variables || Done
|-
| Enhance Content Assist || Events || In progress
|-
| Enhance Content Assist || Lua tags || Done
|-
| Addon management || Create the GUI of the view || Done
|-
| Addon management || Create the view's logic || Done
|-
| Unit testing || Tests for the grammar || Done
|-
| Unit testing || Tests for parsing the config files || Done
|-
| Plugin Polishing || Task 1 || Done
|-
| Plugin Polishing || Task 2 || Done
|-
| Plugin Polishing || Task 3 || Done
|-
| Plugin Polishing || Task 4 || Done
|-
| Plugin Polishing || Task 5 || Done
|-
| Plugin Polishing || Task 6 || In progress
|-
| Plugin Polishing || Task 7|| Done
|-
| Plugin Polishing || Task 8 || Done
|-
| Plugin Polishing || Task 9 || Done
|}

Optional tasks will be dealt with if the time allows it:

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Enhance Content Assist || Project dependency tree with multiple paths based on defines || None
|-
| Enhance Content Assist || Lua tags attributes || Done
|-
| Grammar || Enhance the grammar to support the 2 current unsupported syntax constructs || None
|-
| Documentation || Implement a simple WML project from start to end using Help's built-in cheat sheets tutorial || None
|}

=Questionnaire=
The questionnaire can be found here: http://wiki.wesnoth.org/User:Timotei21/Questionaire

SummerofCode2011 Timotei21

2011-07-31T10:16:54Z

Timotei21: update progress

{{SoC2011Student_2|timotei|SoC_Ideas_Eclipse_Plugin2011}}

=Description=
<h4>timotei - Improving the Eclipse Plugin</h4>
I aim at improving the plugin, so it will become the tool used by all UMC Authors. That is, UMC Authors will get rid of the lot of different tools they use for different tasks (for example the Emacs WMLMode/other plugins for different text editors), and instead use one single unified Tool that will speed up the development. My target is to make this plugin a complete and very stable suite for all umc tasks that don't need specialized software - like a graphics editor, so I'd like to have this oportunity to finish it in the good sense.

=Contacts=
==IRC==
timotei

==Other==
Forum: timotei 
gna.org: timotei

=SoC Application=
[http://www.google-melange.com/gsoc/proposal/review/google/gsoc2011/timoteidolean/1 Battle for Wesnoth - Google Summer of Code Application]

=Proposal Summary=
Page Last Updated: {{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}} 

In the following lines I will give details on how I'm planning to implement some of the required tasks, and also add some new ones.

The ''Notes'' sections are aimed for personal guideliness. They are took from my todo list.

==Multiple Wesnoth installations==
Having multiple wesnoth setups, and working with them at the same time would be nice to be done from inside the plugin.
For that, there will be a new preferences page. The page will look something like this:
http://dl.dropbox.com/u/462510/personal/soc/installations_management.PNG

There will be buttons that add/remove/edit a certain wesnoth installation. When adding/editing an installation, a new page like the current one (in which we set the paths), will be shown. The user will be able to name it and specify the version (I could automatically get the version by invoking ''wesnoth --version'').
The current page for setting the paths will act as a default installation.

After we have configured the paths, the user can chose the installation to which the (new) projects are bound, by opening the project properties. There will be a wesnoth-related page, where the user will be able to chose to what installation the project binds. With that, every command that uses the paths, won't use the single current paths, but the ones assigned to each project. This project properties page will open new ways for adding new

There would be a problem in case the project will be migrated between 2 different plugin's versions. For example, in one place we would have defined "1.9.4svn" but on the other there would be "trunk".

We can solve this in 3 ways:

# Alert the user that the installation doesn't bind, and let him chose the current matching installation for his plugin.
# Default automatically to the current plugin's default installation.
# "Hardcode" the version, so that there may be defined just installations like: 1.8.0, 1.9.3. With this we lose some flexibility, but we could use this as base version for new installations, so for example, a user can have two 1.9.3 installations. Provided this, we have again a possible problem, which can be solved again by 1. or 2., but this time, trying to match the base version first.

With this feature, the user won't need to restart the plugin at all, switching workspaces.

Regarding the technical PoV, all paths will be stored using eclipse's preferences system, by appending an unique id of each installation to each path in that set.

''Note'':
Add the NO_TERRAIN_GFX preprocess option checkbox to the project properties rather than being a global one.

==Enhance the Content Assist(CA) feature==
The CA framework is very extensible but it lacks proper contexts for providing the content.
I was thinking of trying to accomplish the generating of CA list either by using a config file, in case something like that can be used or writing directly the code that does that.

Another factor that is involved in a better auto-complete, is the ''schema.cfg'' the plugin bases on. Depending on whether the schema is worked on during this summer of code, I'll need to redo a bit the parser of the schema, in case the format/semantics change.

===Project files dependecy tree===
In order for the CA to work better - and maybe other areas would benefit from this - we will need to build a project files tree. With that tree, we can see how a certain declared macro/variable will affect subsequent related files and also their scope. Basically, we can see the relation from a file to anothers.

This tree will be (re)built in 2 situations:
# A file is added/removed/changed it's name
# A full rebuild is triggered (for example, the project is added for the first time in the workspace)

The tree will be built by the WML parser's rules:
# files are processed in the alphabetically order
# _initial.cfg is the first processed before anything else.
# _final.cfg is the last processed after anything else.
# if there is a _main.cfg in the directory, it is the only one processed.

Since the current ''WesnothProjectBuilder'' doesn't take in account the previous rules, I will create my own method of visiting each folder's children in the correct order. This method will look close to wesnoth's one, namely ''get_files_from_in_dir()'' found in ''src/filesystem.cpp:93''.

For a very fast lookup, as a data structure we will use a Hashtable, which has as the key the local project path to the file, and as a value a custom structure, which has the previous/next/parent/son properties, used to traverse the tree. The previous/next go on the same tree level, while the parent/son go up/down in the tree. I will use this instead of a tree, because this will give us access to info about a file, faster, in O(1) compared to a breadth-first search which has O(V+E) - where V is number of vertices and E number of edges.

Talking with Crab about this, he alerted me about a little possible problem with current aproach:
<Crab_> a note about 'The tree will be built by the WML parser's rules: ' - don't forget that you can (conditionally) include files/dirs from a file.
<Crab_> so, if we have 'ai/ais/zzz' which, say, defines a macro, it might get included by campaigns/bbb/scenarios/some_scenario.cfg , even if it is not inside /campaigns/bbb/scenarios

For that we have 2 cases:
{~file/dir path}
or
{file/dir path}

The paths are simply discarded if the current project's directory name is not found in the path.

Currently the so called "Tree" will be actually just a List or a single path tree. For the first iteration of this project, I won't tackle the advanced macro usage that might direct the flow based on defines (this will be optional if there will be time in GSoC, or if not, after GSoC, since I plan to remain active developer to maintain the plugin/enhance it furthermore). So, for example (taken from LoW):

#ifdef CAMPAIGN_LOW

{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#endif

#ifdef MULTIPLAYER

#define EASY
#enddef
{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#undef EASY
...
#endif

With current way to do this we will just take "blindly" all included directories/files without taking in consideration the #define flow control.

If we are at LoW, the following tree(list) will be created on its project:

_main.cfg -> utils/*.cfg -> scenarios/*.cfg -> units/*.cfg

Each file in the dependency tree, will have associated a number. For more details on why this and how it's done, read the Scoping section.

===Scoping===
In order for the plugin to know more about the semnatics, it should have the posibility to represent scopes. The scopes will be used mainly for variables and macros.

The Scoping is a delicate problem, because there are some tricky situations that might interfere with the scoping. I choosed to represent scoping in the following way:

Scoping is everything just about order relations. That is, we will compare numbers when dealing with scoping. With that we move the "problem" upper, to the "Dependency tree". We won't use filenames/paths because:

* The filename might change, but the order index may not. So, not having to update the index helps us.
* Number comparison is faster than string comparison.

So, from now on we'll talk in terms of indexes instead of filenames for scoping.

So, we are working with numbers. But there is still a lil' problem. What happens, when we remove/need to add a new file in the current tree, in the middle of existing 2? We would need to update all subsequent files's indexes. That would not be so ok performance wise.

To counter this problem we will not use consecutive numbers, but rather have a certain step between numbers. The step might be configured inside the plugin based on real statistics (for example, trying to see the number of cfg files per project. Taking a big number, like 1000 won't really hurt). For example, we could take the step 50. That means we would have the following tree for LoW:

0 50 100
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

instead of:
0 1 2
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

So, when it's the case of insertion, we insert the new node at the ''middle'' of the current "distance". That way we may insert/delete files *without* breaking the order, and our scoping will still work.

There is another problem it rised in my head: how do we know when to put the number as the next step (the previous number + step) or add it in the middle? Well, since every project will surely do a '''Full Build''', we'll use that oportunity to create the initial tree. Afterwards we will just insert files based on the halving of the distance between 2 indices.

The scoping will be represented by a simple structure, consisting of start index and offset and end index and offset.

===Content Assist Config(CAC) Files===
The CAC files will provide values that are default/available to config files from the wesnoth engine itself. There will be several files that define the values based on their context. This will allow a very great flexibility editing the CA list.

A CAC file will be just a simple text file, that has on each line one (or more) value(s) depending on the context.

* The ''cac/variables.txt'' will contain variables available. The list is currently available at [http://wiki.wesnoth.org/VariablesWML#Automatically_stored_variables]. For example the file could look like:
$side_number
$turn_number
...

* The ''cac/events.txt'' will contain the game events. The list is availabe at: [http://wiki.wesnoth.org/EventWML#Predefined_.27name.27_Key_Values]. Since the events that have spaces in their names can replace that with an underscore '_', the file will contain the underscore instead space variants also.



===Variables===
The variables are either defined by user or defined by default by the wesnoth engine. User's variables will be parsed from each processed file by the WesnothProjectBuilder, using the WMLSaxHandler. The default variables will be parsed and added from the CAC file. (cac/variables.txt)

Variables definitions can be triggered using the VARIABLE macro:
{VARIABLE var_name "value"}
or the [set_variable] tag:
[set_variable]
name=my_var
value="value"
[/set_variable]

The ''ConfigFile'' class in the ''org.wesnoth.wml.core'' already has a list of variables. The ''Variable'' class has some fields that allow its identification. We will build that list when we parse each file, adding each variable found by the previous defined triggers.
When the content assist finds the '$' character, it will supply the user + default variables gathered so far.

Since the variables can be cleared, thus they have scope, the ''Variable'' class needs to be refactorted, so it can represent the scope aswell. The scoping was settled before.

===Name Collisions===
I've considered that we should store the variables per project, like we currently do with macros. This will minimize the memory we need, rather than storing variables on each file - like we do currently. With this, I've discovered it's innevitable to have ''collisions''. That is, have the same variable name on multiple files.

To solve this problem, each variable/macro structure, will not have just a single scope, but rather a list of scopes.

===Events===
Besides the default event names, supplied by the wesnoth engine, there can be created custom ones, wich will be triggered with [fire_event]. As usual the default events names will be available in the cac/events.txt file.

The events defined by the user will be parsed from the ''name'' attribute of the [event] tag.

===Attributes===
All attributes are currently got from the schema.cfg

===Attributes Values===
All attributes values should be parsed based on the schema.cfg.

===Macros===
The support for macros is already built in, but it needs a way to let them have scope. That is, when an #undef is found, the certain macro would not be available to subsequent files unless redeclared. This will be done with the aid of the dependency tree and scoping. The collisions will be solved like I said at the variables section

===Support for custom luaWML tags===
The lua can create new WML Tags. It would be nice that the plugin suggest those aswell besides the ''schema.cfg''. The lua will be easily parsed, since there is a simple pattern for creating new tags:
wesnoth.wml_actions.<tag name>(cfg)

The parser will just run over the lua code/file, over each line, trying to match the 'function *wesnoth.wml_actions.*' pattern. If it finds something, it will add the tag name to the list of tags. There is also a small thing we might have missed. The user could use a shorthand notation for the actions namespace, so when searching for the pattern, I will add to the 'pattern to match' list, the respective variable when searching for new WML Tags.

Thus, like the ''wml-tags.lua'' from the data/lua uses:
local wml_actions = wesnoth.wml_actions

the 'to match' list will contain: 'function *wesnoth.wml_actions.*' and 'function *wml_actions.*', thus finding other tags too.

Going further more, for an ''optional'' enhancement, I could also search that function to see if it needs/has some extra attributes. The attributes can be found by:
* function's parameter (usually cfg) is asked for a property. For example:
function wml_actions.terrain(cfg)
local terrain = cfg.terrain or helper.wml_error("[terrain] missing required terrain= attribute")
cfg = helper.shallow_literal(cfg)
cfg.terrain = nil
for i, loc in ipairs(wesnoth.get_locations(cfg)) do
wesnoth.set_terrain(loc[1], loc[2], terrain, cfg.layer, cfg.replace_if_failed)
end
end

Here we need the attributes ''terrain'', ''layer'' and ''replace_if_failed''.

* ''get_child'' call:
function wml_actions.message(cfg)
local show_if = helper.get_child(cfg, "show_if")
if not show_if or wesnoth.eval_conditional(show_if) then
engine_message(cfg)
end
end

Here we need to have the attribute ''show_if''.

==Automatic/headless building==
The eclipse plugins can be automatically built from command line, provided there is the eclipse sdk and the eclipse delta pack on the builder's machine. The plugin can also use Buckminster tool to automate the building of the plugin.

''Notes''
Add all plugin's files *inside* a folder to prevent cluttering the directory where it's extracted

More info at:
* http://wiki.eclipse.org/PDE/Build
* http://wiki.bioclipse.net/index.php?title=How_to_build_plugins_headless
* http://help.eclipse.org/galileo/index.jsp?topic=/org.eclipse.pde.doc.user/guide/intro/pde_overview.htm
* http://www.eclipse.org/articles/Article-PDE-Automation/automation.html

==Standalone app auto-update==
The current standalone application doesn't offer the same eclipse's update system. I will add it, so anytime there is a new version of the plugin, it can be updated with a single click by the user, without the needing to download a new standalone app again.

==Documentation==
===External documentation===
The current existing readme will be split in 2 manuals: User Manual and Developer Manual (Don't forget to add images where relevant).

The user manual will contain:
* Prerequisites and Installing the prerequisites
Note: don't forget to mention the MINIMUM eclipse/java version needed to run
* Installing the plugin / standalone version
* Using the plugin
* Plugin features
* Step-by-step use cases
** Setupping the workspace
** Creating a new project and running it in the game
** Importing existing projects
** Using the WML Editor
** Updating the plugin
* Frequently Asked Questions

The developer manual will contain:
* Prerequisites and Installing the prerequisites
* Adding the plugin's projects in the
* Compiling and Running the plugin
* Deploying the plugin and standalone app

===Internal documentation===
The Eclipse infrastructure has features for letting the developer embed help into the application, depending on the current context. After I will write the external documentation, I will work on adding internal documentation aswell. Some of it already comes from the external one.

* Plugin welcome page
* Eclipse Help (When pressing Help->Help contents)
* Wizards help

==Plugin polishing==
This are some tasks needed to be done in order to get the plugin more stable and more usable than it's currently. Some of the tasks are taken from my todo list. New tasks will be added through the project advancing when improvements to actual code /user interaction can be done, so this list is not final.

# Don't copy a project that belongs to data/campaigns to the user addons's directory. This can be done by looking at the path when creating a new project. (This is prevented by not spawning a ''build.xml'' file in the campaigns's directory)
# Enhance the logging so it can help debugging other's problem much easier. I could split the current log in 2:
## Commands executed by the plugin
## Other information like parsed information/statuses
# Enhance the integration with the eclipse platform by adding the "Wesnoth" related wizards directly to the "New" menu.
# Allow users to import a directory as a wesnoth project. Under the hood it will either open the wesnoth project (if there is any .project files in it) or create a new empty project on it.
# Allow the user to clear it's current plugin's settings just with a simple button.
# Wesnoth Project Explorer - Add error markers just like the Java Explorer has
# Refactor the current way of getting the macro list. Currently if there is no _main.cfg practically the _MACROS_.cfg file is not built resulting in no MACRO suggestions.
# Create a view filter to hide the Project ''_AutoLinked_CFGExternalFiles_'' which is created for opening the external config files (external meaning outside the current workspace).
# Fix the F3 navigation when the map's location is specified withing " ", as a string.

===New parsing method (optional)===
The current parsing method involves a lot of Wesnoth preprocessor/wmlparser.py. This is doing somehow the parsing job double. This is because the xtext framework already does 1 pass over the files when added to the project. My plan is to see if I can reuse the already built AST(Abstract Syntax Tree) and the parse tree, to use those values instead of additional preprocessing/wmlparsing, and use the latter only when really needed.

Using the xtext's model will greatly fasten the "build" time of each project and it will be *much* simpler to work with, since the framework already provides exceptions recovering (that is, when the code is not well formed according to the grammar) and based on the defined grammar the respective tokens. So, for example instead using 2 another external processes, we could just iterate over each WMLTag and get it's WMLKeys and parse their individual values.

If this idea works, I will add it on the Plugin polishing tasks.

==Other ideas==
===Addons management===
There will be a new Addons management view. It will behave much like the in-game addon manager, but it will be more handy since the user doesn't need to start the game for that (and also wait till the cache refreshes after downloading it). This view will be based on the python script from '''data/tools/wesnoth_addon_manager''', like it does currently for uploading the project as an addon.

The view will let the user see the list/details for each of the addons currently on the server. There will be also a filter based on what addon server to use (trunk/1.8/1.9/etc)

The user will be able to just right click on an addon and download it to it's user data folder. Optionally a new project will be created, based on the just downloaded addon.



===Unit testing===
====Grammar====
For a better wml handling with in the editor, I will create a Testing class for the current grammar. The class will do testing on all *.cfgs in the data directory. That way after modifing something in the grammar we will be able to see how many errors we have introduced/eliminated. This will greatly help the developing of a better grammar that can hold all current WML formats.

''Notes'':
optionally rework the grammar and try to use a custom lexer/parser in order to benefit from the preprocessor, injecting the valid tokens. This would help the cases when the current grammar doesn't work:
{name} = value
or unclosed tags

====Parsing and getting information from files====
I will create some basic (or taken from existing campaigns) config files that will be parsed in order to check if the correct behaviour - correct information is extracted from the files.

This will check for extracting the:
scenario name
campaign name
next_scenario
first_scenario
variables
macros

=Timeline=
The GSOC period is between 24th May and 20th August. But since I have exams for 3 weeks (during 30.05-19.06.2011), I will start working on the plugin before the 24th of May, to recover some of the lost time. Also, my ImagineCup team made it to the national phase - that is in 5,6,7 May. That means till that time I will not be able to do so much work, so I'll make the timeline according with the starting of work on 9 May.

Here is a table with key periods of the time spent on this project.
{| border="1"
|'''Period''' || '''Actions'''
|-
| 26 April || Get accepted
|-
| 26 April - 8 May || Busy working on ImagineCup project for the national phase. Little or no work done.
|-
| 9 May - 15 May || Allow headless build of the plugin
|-
| 16 May - 22 May || Add Support for multiple installations
|-
| 23 May - 28 May || Add the auto-update feature for the standalone app
|-
| 30 May - 19 June || Exams
|-
| 20 June - 24 June || Create the external documentation
|-
| 25 June - 16 July || Enhance Content Assist
|-
| 15 July || Mid-term evaluations deadline
|-
| 17 July - 24 July || Addons management view
|-
| 25 July - 30 July || Unit tests
|-
| 1 August - 14 August || Do the Plugin polishing tasks
|-
| 15 August || Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc.
|-
| 15 August - 17 August || Create the internal documentation.
|-
| 18 August - 22 August || Buffer half-week. This will be used in case some tasks fell a bit outside their proposed time.
|-
| 22 August || Firm 'pencils down' date. Mentors, students and organization administrators can begin submitting final evaluations to Google.
|}

=Tasks=
This is a list of the "atomic" tasks that need to be done, based on the project part. Since the big tasks are split into smaller task, the progress will be seen better and any problems that arise with the timeline will be seen faster. I will update this table based on my current progress.

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Headless build ||Research about what system to use for automatic building of the plugin || Done
|-
| Headless build || Implement the chosen system for the wesnoth plugin|| Done
|-
| Multiple installations || Implement the preferences pages || Done
|-
| Multiple installations || Implement the logic for saving and loading the installation's paths on the disk || Done
|-
| Multiple installations || Implement the project preferences page || Done
|-
| Multiple installations || Rewrite the current mechanisms that use the paths to use the ones based on the project. || Done
|-
| Auto-update || Implement the auto-update feature. || In progress
|-
| Documentation || Write the User Manual || Done
|-
| Documentation || Write the Developer Manual || Done
|-
| Documentation || Write the internal documentation || Done
|-
| Enhance Content Assist || Project dependency tree || In progress
|-
| Enhance Content Assist || Content assist files || Done
|-
| Enhance Content Assist || Variables || Done
|-
| Enhance Content Assist || Events || In progress
|-
| Enhance Content Assist || Lua tags || Done
|-
| Addon management || Create the GUI of the view || Done
|-
| Addon management || Create the view's logic || Done
|-
| Unit testing || Tests for the grammar || Done
|-
| Unit testing || Tests for parsing the config files || Done
|-
| Plugin Polishing || Task 1 || Done
|-
| Plugin Polishing || Task 2 || Done
|-
| Plugin Polishing || Task 3 || Done
|-
| Plugin Polishing || Task 4 || Done
|-
| Plugin Polishing || Task 5 || Done
|-
| Plugin Polishing || Task 6 || Done
|-
| Plugin Polishing || Task 7|| Done
|-
| Plugin Polishing || Task 8 || In progress
|-
| Plugin Polishing || Task 9 || In progress
|}

Optional tasks will be dealt with if the time allows it:

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Enhance Content Assist || Project dependency tree with multiple paths based on defines || None
|-
| Enhance Content Assist || Lua tags attributes || Done
|-
| Grammar || Enhance the grammar to support the 2 current unsupported syntax constructs || None
|-
| Documentation || Implement a simple WML project from start to end using Help's built-in cheat sheets tutorial || None
|}

=Questionnaire=
The questionnaire can be found here: http://wiki.wesnoth.org/User:Timotei21/Questionaire

SummerofCode2011 Timotei21

2011-07-26T19:00:03Z

Timotei21: update progress

{{SoC2011Student_2|timotei|SoC_Ideas_Eclipse_Plugin2011}}

=Description=
<h4>timotei - Improving the Eclipse Plugin</h4>
I aim at improving the plugin, so it will become the tool used by all UMC Authors. That is, UMC Authors will get rid of the lot of different tools they use for different tasks (for example the Emacs WMLMode/other plugins for different text editors), and instead use one single unified Tool that will speed up the development. My target is to make this plugin a complete and very stable suite for all umc tasks that don't need specialized software - like a graphics editor, so I'd like to have this oportunity to finish it in the good sense.

=Contacts=
==IRC==
timotei

==Other==
Forum: timotei 
gna.org: timotei

=SoC Application=
[http://www.google-melange.com/gsoc/proposal/review/google/gsoc2011/timoteidolean/1 Battle for Wesnoth - Google Summer of Code Application]

=Proposal Summary=
Page Last Updated: {{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}} 

In the following lines I will give details on how I'm planning to implement some of the required tasks, and also add some new ones.

The ''Notes'' sections are aimed for personal guideliness. They are took from my todo list.

==Multiple Wesnoth installations==
Having multiple wesnoth setups, and working with them at the same time would be nice to be done from inside the plugin.
For that, there will be a new preferences page. The page will look something like this:
http://dl.dropbox.com/u/462510/personal/soc/installations_management.PNG

There will be buttons that add/remove/edit a certain wesnoth installation. When adding/editing an installation, a new page like the current one (in which we set the paths), will be shown. The user will be able to name it and specify the version (I could automatically get the version by invoking ''wesnoth --version'').
The current page for setting the paths will act as a default installation.

After we have configured the paths, the user can chose the installation to which the (new) projects are bound, by opening the project properties. There will be a wesnoth-related page, where the user will be able to chose to what installation the project binds. With that, every command that uses the paths, won't use the single current paths, but the ones assigned to each project. This project properties page will open new ways for adding new

There would be a problem in case the project will be migrated between 2 different plugin's versions. For example, in one place we would have defined "1.9.4svn" but on the other there would be "trunk".

We can solve this in 3 ways:

# Alert the user that the installation doesn't bind, and let him chose the current matching installation for his plugin.
# Default automatically to the current plugin's default installation.
# "Hardcode" the version, so that there may be defined just installations like: 1.8.0, 1.9.3. With this we lose some flexibility, but we could use this as base version for new installations, so for example, a user can have two 1.9.3 installations. Provided this, we have again a possible problem, which can be solved again by 1. or 2., but this time, trying to match the base version first.

With this feature, the user won't need to restart the plugin at all, switching workspaces.

Regarding the technical PoV, all paths will be stored using eclipse's preferences system, by appending an unique id of each installation to each path in that set.

''Note'':
Add the NO_TERRAIN_GFX preprocess option checkbox to the project properties rather than being a global one.

==Enhance the Content Assist(CA) feature==
The CA framework is very extensible but it lacks proper contexts for providing the content.
I was thinking of trying to accomplish the generating of CA list either by using a config file, in case something like that can be used or writing directly the code that does that.

Another factor that is involved in a better auto-complete, is the ''schema.cfg'' the plugin bases on. Depending on whether the schema is worked on during this summer of code, I'll need to redo a bit the parser of the schema, in case the format/semantics change.

===Project files dependecy tree===
In order for the CA to work better - and maybe other areas would benefit from this - we will need to build a project files tree. With that tree, we can see how a certain declared macro/variable will affect subsequent related files and also their scope. Basically, we can see the relation from a file to anothers.

This tree will be (re)built in 2 situations:
# A file is added/removed/changed it's name
# A full rebuild is triggered (for example, the project is added for the first time in the workspace)

The tree will be built by the WML parser's rules:
# files are processed in the alphabetically order
# _initial.cfg is the first processed before anything else.
# _final.cfg is the last processed after anything else.
# if there is a _main.cfg in the directory, it is the only one processed.

Since the current ''WesnothProjectBuilder'' doesn't take in account the previous rules, I will create my own method of visiting each folder's children in the correct order. This method will look close to wesnoth's one, namely ''get_files_from_in_dir()'' found in ''src/filesystem.cpp:93''.

For a very fast lookup, as a data structure we will use a Hashtable, which has as the key the local project path to the file, and as a value a custom structure, which has the previous/next/parent/son properties, used to traverse the tree. The previous/next go on the same tree level, while the parent/son go up/down in the tree. I will use this instead of a tree, because this will give us access to info about a file, faster, in O(1) compared to a breadth-first search which has O(V+E) - where V is number of vertices and E number of edges.

Talking with Crab about this, he alerted me about a little possible problem with current aproach:
<Crab_> a note about 'The tree will be built by the WML parser's rules: ' - don't forget that you can (conditionally) include files/dirs from a file.
<Crab_> so, if we have 'ai/ais/zzz' which, say, defines a macro, it might get included by campaigns/bbb/scenarios/some_scenario.cfg , even if it is not inside /campaigns/bbb/scenarios

For that we have 2 cases:
{~file/dir path}
or
{file/dir path}

The paths are simply discarded if the current project's directory name is not found in the path.

Currently the so called "Tree" will be actually just a List or a single path tree. For the first iteration of this project, I won't tackle the advanced macro usage that might direct the flow based on defines (this will be optional if there will be time in GSoC, or if not, after GSoC, since I plan to remain active developer to maintain the plugin/enhance it furthermore). So, for example (taken from LoW):

#ifdef CAMPAIGN_LOW

{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#endif

#ifdef MULTIPLAYER

#define EASY
#enddef
{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#undef EASY
...
#endif

With current way to do this we will just take "blindly" all included directories/files without taking in consideration the #define flow control.

If we are at LoW, the following tree(list) will be created on its project:

_main.cfg -> utils/*.cfg -> scenarios/*.cfg -> units/*.cfg

Each file in the dependency tree, will have associated a number. For more details on why this and how it's done, read the Scoping section.

===Scoping===
In order for the plugin to know more about the semnatics, it should have the posibility to represent scopes. The scopes will be used mainly for variables and macros.

The Scoping is a delicate problem, because there are some tricky situations that might interfere with the scoping. I choosed to represent scoping in the following way:

Scoping is everything just about order relations. That is, we will compare numbers when dealing with scoping. With that we move the "problem" upper, to the "Dependency tree". We won't use filenames/paths because:

* The filename might change, but the order index may not. So, not having to update the index helps us.
* Number comparison is faster than string comparison.

So, from now on we'll talk in terms of indexes instead of filenames for scoping.

So, we are working with numbers. But there is still a lil' problem. What happens, when we remove/need to add a new file in the current tree, in the middle of existing 2? We would need to update all subsequent files's indexes. That would not be so ok performance wise.

To counter this problem we will not use consecutive numbers, but rather have a certain step between numbers. The step might be configured inside the plugin based on real statistics (for example, trying to see the number of cfg files per project. Taking a big number, like 1000 won't really hurt). For example, we could take the step 50. That means we would have the following tree for LoW:

0 50 100
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

instead of:
0 1 2
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

So, when it's the case of insertion, we insert the new node at the ''middle'' of the current "distance". That way we may insert/delete files *without* breaking the order, and our scoping will still work.

There is another problem it rised in my head: how do we know when to put the number as the next step (the previous number + step) or add it in the middle? Well, since every project will surely do a '''Full Build''', we'll use that oportunity to create the initial tree. Afterwards we will just insert files based on the halving of the distance between 2 indices.

The scoping will be represented by a simple structure, consisting of start index and offset and end index and offset.

===Content Assist Config(CAC) Files===
The CAC files will provide values that are default/available to config files from the wesnoth engine itself. There will be several files that define the values based on their context. This will allow a very great flexibility editing the CA list.

A CAC file will be just a simple text file, that has on each line one (or more) value(s) depending on the context.

* The ''cac/variables.txt'' will contain variables available. The list is currently available at [http://wiki.wesnoth.org/VariablesWML#Automatically_stored_variables]. For example the file could look like:
$side_number
$turn_number
...

* The ''cac/events.txt'' will contain the game events. The list is availabe at: [http://wiki.wesnoth.org/EventWML#Predefined_.27name.27_Key_Values]. Since the events that have spaces in their names can replace that with an underscore '_', the file will contain the underscore instead space variants also.



===Variables===
The variables are either defined by user or defined by default by the wesnoth engine. User's variables will be parsed from each processed file by the WesnothProjectBuilder, using the WMLSaxHandler. The default variables will be parsed and added from the CAC file. (cac/variables.txt)

Variables definitions can be triggered using the VARIABLE macro:
{VARIABLE var_name "value"}
or the [set_variable] tag:
[set_variable]
name=my_var
value="value"
[/set_variable]

The ''ConfigFile'' class in the ''org.wesnoth.wml.core'' already has a list of variables. The ''Variable'' class has some fields that allow its identification. We will build that list when we parse each file, adding each variable found by the previous defined triggers.
When the content assist finds the '$' character, it will supply the user + default variables gathered so far.

Since the variables can be cleared, thus they have scope, the ''Variable'' class needs to be refactorted, so it can represent the scope aswell. The scoping was settled before.

===Name Collisions===
I've considered that we should store the variables per project, like we currently do with macros. This will minimize the memory we need, rather than storing variables on each file - like we do currently. With this, I've discovered it's innevitable to have ''collisions''. That is, have the same variable name on multiple files.

To solve this problem, each variable/macro structure, will not have just a single scope, but rather a list of scopes.

===Events===
Besides the default event names, supplied by the wesnoth engine, there can be created custom ones, wich will be triggered with [fire_event]. As usual the default events names will be available in the cac/events.txt file.

The events defined by the user will be parsed from the ''name'' attribute of the [event] tag.

===Attributes===
All attributes are currently got from the schema.cfg

===Attributes Values===
All attributes values should be parsed based on the schema.cfg.

===Macros===
The support for macros is already built in, but it needs a way to let them have scope. That is, when an #undef is found, the certain macro would not be available to subsequent files unless redeclared. This will be done with the aid of the dependency tree and scoping. The collisions will be solved like I said at the variables section

===Support for custom luaWML tags===
The lua can create new WML Tags. It would be nice that the plugin suggest those aswell besides the ''schema.cfg''. The lua will be easily parsed, since there is a simple pattern for creating new tags:
wesnoth.wml_actions.<tag name>(cfg)

The parser will just run over the lua code/file, over each line, trying to match the 'function *wesnoth.wml_actions.*' pattern. If it finds something, it will add the tag name to the list of tags. There is also a small thing we might have missed. The user could use a shorthand notation for the actions namespace, so when searching for the pattern, I will add to the 'pattern to match' list, the respective variable when searching for new WML Tags.

Thus, like the ''wml-tags.lua'' from the data/lua uses:
local wml_actions = wesnoth.wml_actions

the 'to match' list will contain: 'function *wesnoth.wml_actions.*' and 'function *wml_actions.*', thus finding other tags too.

Going further more, for an ''optional'' enhancement, I could also search that function to see if it needs/has some extra attributes. The attributes can be found by:
* function's parameter (usually cfg) is asked for a property. For example:
function wml_actions.terrain(cfg)
local terrain = cfg.terrain or helper.wml_error("[terrain] missing required terrain= attribute")
cfg = helper.shallow_literal(cfg)
cfg.terrain = nil
for i, loc in ipairs(wesnoth.get_locations(cfg)) do
wesnoth.set_terrain(loc[1], loc[2], terrain, cfg.layer, cfg.replace_if_failed)
end
end

Here we need the attributes ''terrain'', ''layer'' and ''replace_if_failed''.

* ''get_child'' call:
function wml_actions.message(cfg)
local show_if = helper.get_child(cfg, "show_if")
if not show_if or wesnoth.eval_conditional(show_if) then
engine_message(cfg)
end
end

Here we need to have the attribute ''show_if''.

==Automatic/headless building==
The eclipse plugins can be automatically built from command line, provided there is the eclipse sdk and the eclipse delta pack on the builder's machine. The plugin can also use Buckminster tool to automate the building of the plugin.

''Notes''
Add all plugin's files *inside* a folder to prevent cluttering the directory where it's extracted

More info at:
* http://wiki.eclipse.org/PDE/Build
* http://wiki.bioclipse.net/index.php?title=How_to_build_plugins_headless
* http://help.eclipse.org/galileo/index.jsp?topic=/org.eclipse.pde.doc.user/guide/intro/pde_overview.htm
* http://www.eclipse.org/articles/Article-PDE-Automation/automation.html

==Standalone app auto-update==
The current standalone application doesn't offer the same eclipse's update system. I will add it, so anytime there is a new version of the plugin, it can be updated with a single click by the user, without the needing to download a new standalone app again.

==Documentation==
===External documentation===
The current existing readme will be split in 2 manuals: User Manual and Developer Manual (Don't forget to add images where relevant).

The user manual will contain:
* Prerequisites and Installing the prerequisites
Note: don't forget to mention the MINIMUM eclipse/java version needed to run
* Installing the plugin / standalone version
* Using the plugin
* Plugin features
* Step-by-step use cases
** Setupping the workspace
** Creating a new project and running it in the game
** Importing existing projects
** Using the WML Editor
** Updating the plugin
* Frequently Asked Questions

The developer manual will contain:
* Prerequisites and Installing the prerequisites
* Adding the plugin's projects in the
* Compiling and Running the plugin
* Deploying the plugin and standalone app

===Internal documentation===
The Eclipse infrastructure has features for letting the developer embed help into the application, depending on the current context. After I will write the external documentation, I will work on adding internal documentation aswell. Some of it already comes from the external one.

* Plugin welcome page
* Eclipse Help (When pressing Help->Help contents)
* Wizards help

==Plugin polishing==
This are some tasks needed to be done in order to get the plugin more stable and more usable than it's currently. Some of the tasks are taken from my todo list. New tasks will be added through the project advancing when improvements to actual code /user interaction can be done, so this list is not final.

# Don't copy a project that belongs to data/campaigns to the user addons's directory. This can be done by looking at the path when creating a new project. (This is prevented by not spawning a ''build.xml'' file in the campaigns's directory)
# Enhance the logging so it can help debugging other's problem much easier. I could split the current log in 2:
## Commands executed by the plugin
## Other information like parsed information/statuses
# Enhance the integration with the eclipse platform by adding the "Wesnoth" related wizards directly to the "New" menu.
# Allow users to import a directory as a wesnoth project. Under the hood it will either open the wesnoth project (if there is any .project files in it) or create a new empty project on it.
# Allow the user to clear it's current plugin's settings just with a simple button.
# Wesnoth Project Explorer - Add error markers just like the Java Explorer has
# Refactor the current way of getting the macro list. Currently if there is no _main.cfg practically the _MACROS_.cfg file is not built resulting in no MACRO suggestions.
# Create a view filter to hide the Project ''_AutoLinked_CFGExternalFiles_'' which is created for opening the external config files (external meaning outside the current workspace).
# Fix the F3 navigation when the map's location is specified withing " ", as a string.

===New parsing method (optional)===
The current parsing method involves a lot of Wesnoth preprocessor/wmlparser.py. This is doing somehow the parsing job double. This is because the xtext framework already does 1 pass over the files when added to the project. My plan is to see if I can reuse the already built AST(Abstract Syntax Tree) and the parse tree, to use those values instead of additional preprocessing/wmlparsing, and use the latter only when really needed.

Using the xtext's model will greatly fasten the "build" time of each project and it will be *much* simpler to work with, since the framework already provides exceptions recovering (that is, when the code is not well formed according to the grammar) and based on the defined grammar the respective tokens. So, for example instead using 2 another external processes, we could just iterate over each WMLTag and get it's WMLKeys and parse their individual values.

If this idea works, I will add it on the Plugin polishing tasks.

==Other ideas==
===Addons management===
There will be a new Addons management view. It will behave much like the in-game addon manager, but it will be more handy since the user doesn't need to start the game for that (and also wait till the cache refreshes after downloading it). This view will be based on the python script from '''data/tools/wesnoth_addon_manager''', like it does currently for uploading the project as an addon.

The view will let the user see the list/details for each of the addons currently on the server. There will be also a filter based on what addon server to use (trunk/1.8/1.9/etc)

The user will be able to just right click on an addon and download it to it's user data folder. Optionally a new project will be created, based on the just downloaded addon.



===Unit testing===
====Grammar====
For a better wml handling with in the editor, I will create a Testing class for the current grammar. The class will do testing on all *.cfgs in the data directory. That way after modifing something in the grammar we will be able to see how many errors we have introduced/eliminated. This will greatly help the developing of a better grammar that can hold all current WML formats.

''Notes'':
optionally rework the grammar and try to use a custom lexer/parser in order to benefit from the preprocessor, injecting the valid tokens. This would help the cases when the current grammar doesn't work:
{name} = value
or unclosed tags

====Parsing and getting information from files====
I will create some basic (or taken from existing campaigns) config files that will be parsed in order to check if the correct behaviour - correct information is extracted from the files.

This will check for extracting the:
scenario name
campaign name
next_scenario
first_scenario
variables
macros

=Timeline=
The GSOC period is between 24th May and 20th August. But since I have exams for 3 weeks (during 30.05-19.06.2011), I will start working on the plugin before the 24th of May, to recover some of the lost time. Also, my ImagineCup team made it to the national phase - that is in 5,6,7 May. That means till that time I will not be able to do so much work, so I'll make the timeline according with the starting of work on 9 May.

Here is a table with key periods of the time spent on this project.
{| border="1"
|'''Period''' || '''Actions'''
|-
| 26 April || Get accepted
|-
| 26 April - 8 May || Busy working on ImagineCup project for the national phase. Little or no work done.
|-
| 9 May - 15 May || Allow headless build of the plugin
|-
| 16 May - 22 May || Add Support for multiple installations
|-
| 23 May - 28 May || Add the auto-update feature for the standalone app
|-
| 30 May - 19 June || Exams
|-
| 20 June - 24 June || Create the external documentation
|-
| 25 June - 16 July || Enhance Content Assist
|-
| 15 July || Mid-term evaluations deadline
|-
| 17 July - 24 July || Addons management view
|-
| 25 July - 30 July || Unit tests
|-
| 1 August - 14 August || Do the Plugin polishing tasks
|-
| 15 August || Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc.
|-
| 15 August - 17 August || Create the internal documentation.
|-
| 18 August - 22 August || Buffer half-week. This will be used in case some tasks fell a bit outside their proposed time.
|-
| 22 August || Firm 'pencils down' date. Mentors, students and organization administrators can begin submitting final evaluations to Google.
|}

=Tasks=
This is a list of the "atomic" tasks that need to be done, based on the project part. Since the big tasks are split into smaller task, the progress will be seen better and any problems that arise with the timeline will be seen faster. I will update this table based on my current progress.

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Headless build ||Research about what system to use for automatic building of the plugin || Done
|-
| Headless build || Implement the chosen system for the wesnoth plugin|| Done
|-
| Multiple installations || Implement the preferences pages || Done
|-
| Multiple installations || Implement the logic for saving and loading the installation's paths on the disk || Done
|-
| Multiple installations || Implement the project preferences page || Done
|-
| Multiple installations || Rewrite the current mechanisms that use the paths to use the ones based on the project. || Done
|-
| Auto-update || Implement the auto-update feature. || In progress
|-
| Documentation || Write the User Manual || Done
|-
| Documentation || Write the Developer Manual || Done
|-
| Documentation || Write the internal documentation || Done
|-
| Enhance Content Assist || Project dependency tree || In progress
|-
| Enhance Content Assist || Content assist files || Done
|-
| Enhance Content Assist || Variables || Done
|-
| Enhance Content Assist || Events || In progress
|-
| Enhance Content Assist || Lua tags || Done
|-
| Addon management || Create the GUI of the view || Done
|-
| Addon management || Create the view's logic || Done
|-
| Unit testing || Tests for the grammar || Done
|-
| Unit testing || Tests for parsing the config files || Done
|-
| Plugin Polishing || Task 1 || In progress
|-
| Plugin Polishing || Task 2 || Done
|-
| Plugin Polishing || Task 3 || None
|-
| Plugin Polishing || Task 4 || None
|-
| Plugin Polishing || Task 5 || None
|-
| Plugin Polishing || Task 6 || None
|-
| Plugin Polishing || Task 7|| Done
|-
| Plugin Polishing || Task 8 || None
|-
| Plugin Polishing || Task 9 || None
|}

Optional tasks will be dealt with if the time allows it:

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Enhance Content Assist || Project dependency tree with multiple paths based on defines || None
|-
| Enhance Content Assist || Lua tags attributes || Done
|-
| Grammar || Enhance the grammar to support the 2 current unsupported syntax constructs || None
|-
| Documentation || Implement a simple WML project from start to end using Help's built-in cheat sheets tutorial || None
|}

=Questionnaire=
The questionnaire can be found here: http://wiki.wesnoth.org/User:Timotei21/Questionaire

SummerofCode2011 Timotei21

2011-07-26T08:15:48Z

Timotei21: update progress

{{SoC2011Student_2|timotei|SoC_Ideas_Eclipse_Plugin2011}}

=Description=
<h4>timotei - Improving the Eclipse Plugin</h4>
I aim at improving the plugin, so it will become the tool used by all UMC Authors. That is, UMC Authors will get rid of the lot of different tools they use for different tasks (for example the Emacs WMLMode/other plugins for different text editors), and instead use one single unified Tool that will speed up the development. My target is to make this plugin a complete and very stable suite for all umc tasks that don't need specialized software - like a graphics editor, so I'd like to have this oportunity to finish it in the good sense.

=Contacts=
==IRC==
timotei

==Other==
Forum: timotei 
gna.org: timotei

=SoC Application=
[http://www.google-melange.com/gsoc/proposal/review/google/gsoc2011/timoteidolean/1 Battle for Wesnoth - Google Summer of Code Application]

=Proposal Summary=
Page Last Updated: {{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}} 

In the following lines I will give details on how I'm planning to implement some of the required tasks, and also add some new ones.

The ''Notes'' sections are aimed for personal guideliness. They are took from my todo list.

==Multiple Wesnoth installations==
Having multiple wesnoth setups, and working with them at the same time would be nice to be done from inside the plugin.
For that, there will be a new preferences page. The page will look something like this:
http://dl.dropbox.com/u/462510/personal/soc/installations_management.PNG

There will be buttons that add/remove/edit a certain wesnoth installation. When adding/editing an installation, a new page like the current one (in which we set the paths), will be shown. The user will be able to name it and specify the version (I could automatically get the version by invoking ''wesnoth --version'').
The current page for setting the paths will act as a default installation.

After we have configured the paths, the user can chose the installation to which the (new) projects are bound, by opening the project properties. There will be a wesnoth-related page, where the user will be able to chose to what installation the project binds. With that, every command that uses the paths, won't use the single current paths, but the ones assigned to each project. This project properties page will open new ways for adding new

There would be a problem in case the project will be migrated between 2 different plugin's versions. For example, in one place we would have defined "1.9.4svn" but on the other there would be "trunk".

We can solve this in 3 ways:

# Alert the user that the installation doesn't bind, and let him chose the current matching installation for his plugin.
# Default automatically to the current plugin's default installation.
# "Hardcode" the version, so that there may be defined just installations like: 1.8.0, 1.9.3. With this we lose some flexibility, but we could use this as base version for new installations, so for example, a user can have two 1.9.3 installations. Provided this, we have again a possible problem, which can be solved again by 1. or 2., but this time, trying to match the base version first.

With this feature, the user won't need to restart the plugin at all, switching workspaces.

Regarding the technical PoV, all paths will be stored using eclipse's preferences system, by appending an unique id of each installation to each path in that set.

''Note'':
Add the NO_TERRAIN_GFX preprocess option checkbox to the project properties rather than being a global one.

==Enhance the Content Assist(CA) feature==
The CA framework is very extensible but it lacks proper contexts for providing the content.
I was thinking of trying to accomplish the generating of CA list either by using a config file, in case something like that can be used or writing directly the code that does that.

Another factor that is involved in a better auto-complete, is the ''schema.cfg'' the plugin bases on. Depending on whether the schema is worked on during this summer of code, I'll need to redo a bit the parser of the schema, in case the format/semantics change.

===Project files dependecy tree===
In order for the CA to work better - and maybe other areas would benefit from this - we will need to build a project files tree. With that tree, we can see how a certain declared macro/variable will affect subsequent related files and also their scope. Basically, we can see the relation from a file to anothers.

This tree will be (re)built in 2 situations:
# A file is added/removed/changed it's name
# A full rebuild is triggered (for example, the project is added for the first time in the workspace)

The tree will be built by the WML parser's rules:
# files are processed in the alphabetically order
# _initial.cfg is the first processed before anything else.
# _final.cfg is the last processed after anything else.
# if there is a _main.cfg in the directory, it is the only one processed.

Since the current ''WesnothProjectBuilder'' doesn't take in account the previous rules, I will create my own method of visiting each folder's children in the correct order. This method will look close to wesnoth's one, namely ''get_files_from_in_dir()'' found in ''src/filesystem.cpp:93''.

For a very fast lookup, as a data structure we will use a Hashtable, which has as the key the local project path to the file, and as a value a custom structure, which has the previous/next/parent/son properties, used to traverse the tree. The previous/next go on the same tree level, while the parent/son go up/down in the tree. I will use this instead of a tree, because this will give us access to info about a file, faster, in O(1) compared to a breadth-first search which has O(V+E) - where V is number of vertices and E number of edges.

Talking with Crab about this, he alerted me about a little possible problem with current aproach:
<Crab_> a note about 'The tree will be built by the WML parser's rules: ' - don't forget that you can (conditionally) include files/dirs from a file.
<Crab_> so, if we have 'ai/ais/zzz' which, say, defines a macro, it might get included by campaigns/bbb/scenarios/some_scenario.cfg , even if it is not inside /campaigns/bbb/scenarios

For that we have 2 cases:
{~file/dir path}
or
{file/dir path}

The paths are simply discarded if the current project's directory name is not found in the path.

Currently the so called "Tree" will be actually just a List or a single path tree. For the first iteration of this project, I won't tackle the advanced macro usage that might direct the flow based on defines (this will be optional if there will be time in GSoC, or if not, after GSoC, since I plan to remain active developer to maintain the plugin/enhance it furthermore). So, for example (taken from LoW):

#ifdef CAMPAIGN_LOW

{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#endif

#ifdef MULTIPLAYER

#define EASY
#enddef
{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#undef EASY
...
#endif

With current way to do this we will just take "blindly" all included directories/files without taking in consideration the #define flow control.

If we are at LoW, the following tree(list) will be created on its project:

_main.cfg -> utils/*.cfg -> scenarios/*.cfg -> units/*.cfg

Each file in the dependency tree, will have associated a number. For more details on why this and how it's done, read the Scoping section.

===Scoping===
In order for the plugin to know more about the semnatics, it should have the posibility to represent scopes. The scopes will be used mainly for variables and macros.

The Scoping is a delicate problem, because there are some tricky situations that might interfere with the scoping. I choosed to represent scoping in the following way:

Scoping is everything just about order relations. That is, we will compare numbers when dealing with scoping. With that we move the "problem" upper, to the "Dependency tree". We won't use filenames/paths because:

* The filename might change, but the order index may not. So, not having to update the index helps us.
* Number comparison is faster than string comparison.

So, from now on we'll talk in terms of indexes instead of filenames for scoping.

So, we are working with numbers. But there is still a lil' problem. What happens, when we remove/need to add a new file in the current tree, in the middle of existing 2? We would need to update all subsequent files's indexes. That would not be so ok performance wise.

To counter this problem we will not use consecutive numbers, but rather have a certain step between numbers. The step might be configured inside the plugin based on real statistics (for example, trying to see the number of cfg files per project. Taking a big number, like 1000 won't really hurt). For example, we could take the step 50. That means we would have the following tree for LoW:

0 50 100
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

instead of:
0 1 2
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

So, when it's the case of insertion, we insert the new node at the ''middle'' of the current "distance". That way we may insert/delete files *without* breaking the order, and our scoping will still work.

There is another problem it rised in my head: how do we know when to put the number as the next step (the previous number + step) or add it in the middle? Well, since every project will surely do a '''Full Build''', we'll use that oportunity to create the initial tree. Afterwards we will just insert files based on the halving of the distance between 2 indices.

The scoping will be represented by a simple structure, consisting of start index and offset and end index and offset.

===Content Assist Config(CAC) Files===
The CAC files will provide values that are default/available to config files from the wesnoth engine itself. There will be several files that define the values based on their context. This will allow a very great flexibility editing the CA list.

A CAC file will be just a simple text file, that has on each line one (or more) value(s) depending on the context.

* The ''cac/variables.txt'' will contain variables available. The list is currently available at [http://wiki.wesnoth.org/VariablesWML#Automatically_stored_variables]. For example the file could look like:
$side_number
$turn_number
...

* The ''cac/events.txt'' will contain the game events. The list is availabe at: [http://wiki.wesnoth.org/EventWML#Predefined_.27name.27_Key_Values]. Since the events that have spaces in their names can replace that with an underscore '_', the file will contain the underscore instead space variants also.



===Variables===
The variables are either defined by user or defined by default by the wesnoth engine. User's variables will be parsed from each processed file by the WesnothProjectBuilder, using the WMLSaxHandler. The default variables will be parsed and added from the CAC file. (cac/variables.txt)

Variables definitions can be triggered using the VARIABLE macro:
{VARIABLE var_name "value"}
or the [set_variable] tag:
[set_variable]
name=my_var
value="value"
[/set_variable]

The ''ConfigFile'' class in the ''org.wesnoth.wml.core'' already has a list of variables. The ''Variable'' class has some fields that allow its identification. We will build that list when we parse each file, adding each variable found by the previous defined triggers.
When the content assist finds the '$' character, it will supply the user + default variables gathered so far.

Since the variables can be cleared, thus they have scope, the ''Variable'' class needs to be refactorted, so it can represent the scope aswell. The scoping was settled before.

===Name Collisions===
I've considered that we should store the variables per project, like we currently do with macros. This will minimize the memory we need, rather than storing variables on each file - like we do currently. With this, I've discovered it's innevitable to have ''collisions''. That is, have the same variable name on multiple files.

To solve this problem, each variable/macro structure, will not have just a single scope, but rather a list of scopes.

===Events===
Besides the default event names, supplied by the wesnoth engine, there can be created custom ones, wich will be triggered with [fire_event]. As usual the default events names will be available in the cac/events.txt file.

The events defined by the user will be parsed from the ''name'' attribute of the [event] tag.

===Attributes===
All attributes are currently got from the schema.cfg

===Attributes Values===
All attributes values should be parsed based on the schema.cfg.

===Macros===
The support for macros is already built in, but it needs a way to let them have scope. That is, when an #undef is found, the certain macro would not be available to subsequent files unless redeclared. This will be done with the aid of the dependency tree and scoping. The collisions will be solved like I said at the variables section

===Support for custom luaWML tags===
The lua can create new WML Tags. It would be nice that the plugin suggest those aswell besides the ''schema.cfg''. The lua will be easily parsed, since there is a simple pattern for creating new tags:
wesnoth.wml_actions.<tag name>(cfg)

The parser will just run over the lua code/file, over each line, trying to match the 'function *wesnoth.wml_actions.*' pattern. If it finds something, it will add the tag name to the list of tags. There is also a small thing we might have missed. The user could use a shorthand notation for the actions namespace, so when searching for the pattern, I will add to the 'pattern to match' list, the respective variable when searching for new WML Tags.

Thus, like the ''wml-tags.lua'' from the data/lua uses:
local wml_actions = wesnoth.wml_actions

the 'to match' list will contain: 'function *wesnoth.wml_actions.*' and 'function *wml_actions.*', thus finding other tags too.

Going further more, for an ''optional'' enhancement, I could also search that function to see if it needs/has some extra attributes. The attributes can be found by:
* function's parameter (usually cfg) is asked for a property. For example:
function wml_actions.terrain(cfg)
local terrain = cfg.terrain or helper.wml_error("[terrain] missing required terrain= attribute")
cfg = helper.shallow_literal(cfg)
cfg.terrain = nil
for i, loc in ipairs(wesnoth.get_locations(cfg)) do
wesnoth.set_terrain(loc[1], loc[2], terrain, cfg.layer, cfg.replace_if_failed)
end
end

Here we need the attributes ''terrain'', ''layer'' and ''replace_if_failed''.

* ''get_child'' call:
function wml_actions.message(cfg)
local show_if = helper.get_child(cfg, "show_if")
if not show_if or wesnoth.eval_conditional(show_if) then
engine_message(cfg)
end
end

Here we need to have the attribute ''show_if''.

==Automatic/headless building==
The eclipse plugins can be automatically built from command line, provided there is the eclipse sdk and the eclipse delta pack on the builder's machine. The plugin can also use Buckminster tool to automate the building of the plugin.

''Notes''
Add all plugin's files *inside* a folder to prevent cluttering the directory where it's extracted

More info at:
* http://wiki.eclipse.org/PDE/Build
* http://wiki.bioclipse.net/index.php?title=How_to_build_plugins_headless
* http://help.eclipse.org/galileo/index.jsp?topic=/org.eclipse.pde.doc.user/guide/intro/pde_overview.htm
* http://www.eclipse.org/articles/Article-PDE-Automation/automation.html

==Standalone app auto-update==
The current standalone application doesn't offer the same eclipse's update system. I will add it, so anytime there is a new version of the plugin, it can be updated with a single click by the user, without the needing to download a new standalone app again.

==Documentation==
===External documentation===
The current existing readme will be split in 2 manuals: User Manual and Developer Manual (Don't forget to add images where relevant).

The user manual will contain:
* Prerequisites and Installing the prerequisites
Note: don't forget to mention the MINIMUM eclipse/java version needed to run
* Installing the plugin / standalone version
* Using the plugin
* Plugin features
* Step-by-step use cases
** Setupping the workspace
** Creating a new project and running it in the game
** Importing existing projects
** Using the WML Editor
** Updating the plugin
* Frequently Asked Questions

The developer manual will contain:
* Prerequisites and Installing the prerequisites
* Adding the plugin's projects in the
* Compiling and Running the plugin
* Deploying the plugin and standalone app

===Internal documentation===
The Eclipse infrastructure has features for letting the developer embed help into the application, depending on the current context. After I will write the external documentation, I will work on adding internal documentation aswell. Some of it already comes from the external one.

* Plugin welcome page
* Eclipse Help (When pressing Help->Help contents)
* Wizards help

==Plugin polishing==
This are some tasks needed to be done in order to get the plugin more stable and more usable than it's currently. Some of the tasks are taken from my todo list. New tasks will be added through the project advancing when improvements to actual code /user interaction can be done, so this list is not final.

# Don't copy a project that belongs to data/campaigns to the user addons's directory. This can be done by looking at the path when creating a new project. (This is prevented by not spawning a ''build.xml'' file in the campaigns's directory)
# Enhance the logging so it can help debugging other's problem much easier. I could split the current log in 2:
## Commands executed by the plugin
## Other information like parsed information/statuses
# Enhance the integration with the eclipse platform by adding the "Wesnoth" related wizards directly to the "New" menu.
# Allow users to import a directory as a wesnoth project. Under the hood it will either open the wesnoth project (if there is any .project files in it) or create a new empty project on it.
# Allow the user to clear it's current plugin's settings just with a simple button.
# Wesnoth Project Explorer - Add error markers just like the Java Explorer has
# Refactor the current way of getting the macro list. Currently if there is no _main.cfg practically the _MACROS_.cfg file is not built resulting in no MACRO suggestions.
# Create a view filter to hide the Project ''_AutoLinked_CFGExternalFiles_'' which is created for opening the external config files (external meaning outside the current workspace).
# Fix the F3 navigation when the map's location is specified withing " ", as a string.

===New parsing method (optional)===
The current parsing method involves a lot of Wesnoth preprocessor/wmlparser.py. This is doing somehow the parsing job double. This is because the xtext framework already does 1 pass over the files when added to the project. My plan is to see if I can reuse the already built AST(Abstract Syntax Tree) and the parse tree, to use those values instead of additional preprocessing/wmlparsing, and use the latter only when really needed.

Using the xtext's model will greatly fasten the "build" time of each project and it will be *much* simpler to work with, since the framework already provides exceptions recovering (that is, when the code is not well formed according to the grammar) and based on the defined grammar the respective tokens. So, for example instead using 2 another external processes, we could just iterate over each WMLTag and get it's WMLKeys and parse their individual values.

If this idea works, I will add it on the Plugin polishing tasks.

==Other ideas==
===Addons management===
There will be a new Addons management view. It will behave much like the in-game addon manager, but it will be more handy since the user doesn't need to start the game for that (and also wait till the cache refreshes after downloading it). This view will be based on the python script from '''data/tools/wesnoth_addon_manager''', like it does currently for uploading the project as an addon.

The view will let the user see the list/details for each of the addons currently on the server. There will be also a filter based on what addon server to use (trunk/1.8/1.9/etc)

The user will be able to just right click on an addon and download it to it's user data folder. Optionally a new project will be created, based on the just downloaded addon.



===Unit testing===
====Grammar====
For a better wml handling with in the editor, I will create a Testing class for the current grammar. The class will do testing on all *.cfgs in the data directory. That way after modifing something in the grammar we will be able to see how many errors we have introduced/eliminated. This will greatly help the developing of a better grammar that can hold all current WML formats.

''Notes'':
optionally rework the grammar and try to use a custom lexer/parser in order to benefit from the preprocessor, injecting the valid tokens. This would help the cases when the current grammar doesn't work:
{name} = value
or unclosed tags

====Parsing and getting information from files====
I will create some basic (or taken from existing campaigns) config files that will be parsed in order to check if the correct behaviour - correct information is extracted from the files.

This will check for extracting the:
scenario name
campaign name
next_scenario
first_scenario
variables
macros

=Timeline=
The GSOC period is between 24th May and 20th August. But since I have exams for 3 weeks (during 30.05-19.06.2011), I will start working on the plugin before the 24th of May, to recover some of the lost time. Also, my ImagineCup team made it to the national phase - that is in 5,6,7 May. That means till that time I will not be able to do so much work, so I'll make the timeline according with the starting of work on 9 May.

Here is a table with key periods of the time spent on this project.
{| border="1"
|'''Period''' || '''Actions'''
|-
| 26 April || Get accepted
|-
| 26 April - 8 May || Busy working on ImagineCup project for the national phase. Little or no work done.
|-
| 9 May - 15 May || Allow headless build of the plugin
|-
| 16 May - 22 May || Add Support for multiple installations
|-
| 23 May - 28 May || Add the auto-update feature for the standalone app
|-
| 30 May - 19 June || Exams
|-
| 20 June - 24 June || Create the external documentation
|-
| 25 June - 16 July || Enhance Content Assist
|-
| 15 July || Mid-term evaluations deadline
|-
| 17 July - 24 July || Addons management view
|-
| 25 July - 30 July || Unit tests
|-
| 1 August - 14 August || Do the Plugin polishing tasks
|-
| 15 August || Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc.
|-
| 15 August - 17 August || Create the internal documentation.
|-
| 18 August - 22 August || Buffer half-week. This will be used in case some tasks fell a bit outside their proposed time.
|-
| 22 August || Firm 'pencils down' date. Mentors, students and organization administrators can begin submitting final evaluations to Google.
|}

=Tasks=
This is a list of the "atomic" tasks that need to be done, based on the project part. Since the big tasks are split into smaller task, the progress will be seen better and any problems that arise with the timeline will be seen faster. I will update this table based on my current progress.

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Headless build ||Research about what system to use for automatic building of the plugin || Done
|-
| Headless build || Implement the chosen system for the wesnoth plugin|| Done
|-
| Multiple installations || Implement the preferences pages || Done
|-
| Multiple installations || Implement the logic for saving and loading the installation's paths on the disk || Done
|-
| Multiple installations || Implement the project preferences page || Done
|-
| Multiple installations || Rewrite the current mechanisms that use the paths to use the ones based on the project. || Done
|-
| Auto-update || Implement the auto-update feature. || In progress
|-
| Documentation || Write the User Manual || Done
|-
| Documentation || Write the Developer Manual || Done
|-
| Documentation || Write the internal documentation || Done
|-
| Enhance Content Assist || Project dependency tree || In progress
|-
| Enhance Content Assist || Content assist files || Done
|-
| Enhance Content Assist || Variables || Done
|-
| Enhance Content Assist || Events || In progress
|-
| Enhance Content Assist || Lua tags || Done
|-
| Addon management || Create the GUI of the view || Done
|-
| Addon management || Create the view's logic || Done
|-
| Unit testing || Tests for the grammar || Done
|-
| Unit testing || Tests for parsing the config files || Done
|-
| Plugin Polishing || Task 1 || None
|-
| Plugin Polishing || Task 2 || None
|-
| Plugin Polishing || Task 3 || None
|-
| Plugin Polishing || Task 4 || None
|-
| Plugin Polishing || Task 5 || None
|-
| Plugin Polishing || Task 6 || None
|-
| Plugin Polishing || Task 7|| None
|-
| Plugin Polishing || Task 8 || None
|-
| Plugin Polishing || Task 9 || None
|}

Optional tasks will be dealt with if the time allows it:

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Enhance Content Assist || Project dependency tree with multiple paths based on defines || None
|-
| Enhance Content Assist || Lua tags attributes || Done
|-
| Grammar || Enhance the grammar to support the 2 current unsupported syntax constructs || None
|-
| Documentation || Implement a simple WML project from start to end using Help's built-in cheat sheets tutorial || None
|}

=Questionnaire=
The questionnaire can be found here: http://wiki.wesnoth.org/User:Timotei21/Questionaire

SummerofCode2011 Timotei21

2011-07-23T09:20:59Z

Timotei21: update progress

{{SoC2011Student_2|timotei|SoC_Ideas_Eclipse_Plugin2011}}

=Description=
<h4>timotei - Improving the Eclipse Plugin</h4>
I aim at improving the plugin, so it will become the tool used by all UMC Authors. That is, UMC Authors will get rid of the lot of different tools they use for different tasks (for example the Emacs WMLMode/other plugins for different text editors), and instead use one single unified Tool that will speed up the development. My target is to make this plugin a complete and very stable suite for all umc tasks that don't need specialized software - like a graphics editor, so I'd like to have this oportunity to finish it in the good sense.

=Contacts=
==IRC==
timotei

==Other==
Forum: timotei 
gna.org: timotei

=SoC Application=
[http://www.google-melange.com/gsoc/proposal/review/google/gsoc2011/timoteidolean/1 Battle for Wesnoth - Google Summer of Code Application]

=Proposal Summary=
Page Last Updated: {{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}} 

In the following lines I will give details on how I'm planning to implement some of the required tasks, and also add some new ones.

The ''Notes'' sections are aimed for personal guideliness. They are took from my todo list.

==Multiple Wesnoth installations==
Having multiple wesnoth setups, and working with them at the same time would be nice to be done from inside the plugin.
For that, there will be a new preferences page. The page will look something like this:
http://dl.dropbox.com/u/462510/personal/soc/installations_management.PNG

There will be buttons that add/remove/edit a certain wesnoth installation. When adding/editing an installation, a new page like the current one (in which we set the paths), will be shown. The user will be able to name it and specify the version (I could automatically get the version by invoking ''wesnoth --version'').
The current page for setting the paths will act as a default installation.

After we have configured the paths, the user can chose the installation to which the (new) projects are bound, by opening the project properties. There will be a wesnoth-related page, where the user will be able to chose to what installation the project binds. With that, every command that uses the paths, won't use the single current paths, but the ones assigned to each project. This project properties page will open new ways for adding new

There would be a problem in case the project will be migrated between 2 different plugin's versions. For example, in one place we would have defined "1.9.4svn" but on the other there would be "trunk".

We can solve this in 3 ways:

# Alert the user that the installation doesn't bind, and let him chose the current matching installation for his plugin.
# Default automatically to the current plugin's default installation.
# "Hardcode" the version, so that there may be defined just installations like: 1.8.0, 1.9.3. With this we lose some flexibility, but we could use this as base version for new installations, so for example, a user can have two 1.9.3 installations. Provided this, we have again a possible problem, which can be solved again by 1. or 2., but this time, trying to match the base version first.

With this feature, the user won't need to restart the plugin at all, switching workspaces.

Regarding the technical PoV, all paths will be stored using eclipse's preferences system, by appending an unique id of each installation to each path in that set.

''Note'':
Add the NO_TERRAIN_GFX preprocess option checkbox to the project properties rather than being a global one.

==Enhance the Content Assist(CA) feature==
The CA framework is very extensible but it lacks proper contexts for providing the content.
I was thinking of trying to accomplish the generating of CA list either by using a config file, in case something like that can be used or writing directly the code that does that.

Another factor that is involved in a better auto-complete, is the ''schema.cfg'' the plugin bases on. Depending on whether the schema is worked on during this summer of code, I'll need to redo a bit the parser of the schema, in case the format/semantics change.

===Project files dependecy tree===
In order for the CA to work better - and maybe other areas would benefit from this - we will need to build a project files tree. With that tree, we can see how a certain declared macro/variable will affect subsequent related files and also their scope. Basically, we can see the relation from a file to anothers.

This tree will be (re)built in 2 situations:
# A file is added/removed/changed it's name
# A full rebuild is triggered (for example, the project is added for the first time in the workspace)

The tree will be built by the WML parser's rules:
# files are processed in the alphabetically order
# _initial.cfg is the first processed before anything else.
# _final.cfg is the last processed after anything else.
# if there is a _main.cfg in the directory, it is the only one processed.

Since the current ''WesnothProjectBuilder'' doesn't take in account the previous rules, I will create my own method of visiting each folder's children in the correct order. This method will look close to wesnoth's one, namely ''get_files_from_in_dir()'' found in ''src/filesystem.cpp:93''.

For a very fast lookup, as a data structure we will use a Hashtable, which has as the key the local project path to the file, and as a value a custom structure, which has the previous/next/parent/son properties, used to traverse the tree. The previous/next go on the same tree level, while the parent/son go up/down in the tree. I will use this instead of a tree, because this will give us access to info about a file, faster, in O(1) compared to a breadth-first search which has O(V+E) - where V is number of vertices and E number of edges.

Talking with Crab about this, he alerted me about a little possible problem with current aproach:
<Crab_> a note about 'The tree will be built by the WML parser's rules: ' - don't forget that you can (conditionally) include files/dirs from a file.
<Crab_> so, if we have 'ai/ais/zzz' which, say, defines a macro, it might get included by campaigns/bbb/scenarios/some_scenario.cfg , even if it is not inside /campaigns/bbb/scenarios

For that we have 2 cases:
{~file/dir path}
or
{file/dir path}

The paths are simply discarded if the current project's directory name is not found in the path.

Currently the so called "Tree" will be actually just a List or a single path tree. For the first iteration of this project, I won't tackle the advanced macro usage that might direct the flow based on defines (this will be optional if there will be time in GSoC, or if not, after GSoC, since I plan to remain active developer to maintain the plugin/enhance it furthermore). So, for example (taken from LoW):

#ifdef CAMPAIGN_LOW

{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#endif

#ifdef MULTIPLAYER

#define EASY
#enddef
{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#undef EASY
...
#endif

With current way to do this we will just take "blindly" all included directories/files without taking in consideration the #define flow control.

If we are at LoW, the following tree(list) will be created on its project:

_main.cfg -> utils/*.cfg -> scenarios/*.cfg -> units/*.cfg

Each file in the dependency tree, will have associated a number. For more details on why this and how it's done, read the Scoping section.

===Scoping===
In order for the plugin to know more about the semnatics, it should have the posibility to represent scopes. The scopes will be used mainly for variables and macros.

The Scoping is a delicate problem, because there are some tricky situations that might interfere with the scoping. I choosed to represent scoping in the following way:

Scoping is everything just about order relations. That is, we will compare numbers when dealing with scoping. With that we move the "problem" upper, to the "Dependency tree". We won't use filenames/paths because:

* The filename might change, but the order index may not. So, not having to update the index helps us.
* Number comparison is faster than string comparison.

So, from now on we'll talk in terms of indexes instead of filenames for scoping.

So, we are working with numbers. But there is still a lil' problem. What happens, when we remove/need to add a new file in the current tree, in the middle of existing 2? We would need to update all subsequent files's indexes. That would not be so ok performance wise.

To counter this problem we will not use consecutive numbers, but rather have a certain step between numbers. The step might be configured inside the plugin based on real statistics (for example, trying to see the number of cfg files per project. Taking a big number, like 1000 won't really hurt). For example, we could take the step 50. That means we would have the following tree for LoW:

0 50 100
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

instead of:
0 1 2
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

So, when it's the case of insertion, we insert the new node at the ''middle'' of the current "distance". That way we may insert/delete files *without* breaking the order, and our scoping will still work.

There is another problem it rised in my head: how do we know when to put the number as the next step (the previous number + step) or add it in the middle? Well, since every project will surely do a '''Full Build''', we'll use that oportunity to create the initial tree. Afterwards we will just insert files based on the halving of the distance between 2 indices.

The scoping will be represented by a simple structure, consisting of start index and offset and end index and offset.

===Content Assist Config(CAC) Files===
The CAC files will provide values that are default/available to config files from the wesnoth engine itself. There will be several files that define the values based on their context. This will allow a very great flexibility editing the CA list.

A CAC file will be just a simple text file, that has on each line one (or more) value(s) depending on the context.

* The ''cac/variables.txt'' will contain variables available. The list is currently available at [http://wiki.wesnoth.org/VariablesWML#Automatically_stored_variables]. For example the file could look like:
$side_number
$turn_number
...

* The ''cac/events.txt'' will contain the game events. The list is availabe at: [http://wiki.wesnoth.org/EventWML#Predefined_.27name.27_Key_Values]. Since the events that have spaces in their names can replace that with an underscore '_', the file will contain the underscore instead space variants also.



===Variables===
The variables are either defined by user or defined by default by the wesnoth engine. User's variables will be parsed from each processed file by the WesnothProjectBuilder, using the WMLSaxHandler. The default variables will be parsed and added from the CAC file. (cac/variables.txt)

Variables definitions can be triggered using the VARIABLE macro:
{VARIABLE var_name "value"}
or the [set_variable] tag:
[set_variable]
name=my_var
value="value"
[/set_variable]

The ''ConfigFile'' class in the ''org.wesnoth.wml.core'' already has a list of variables. The ''Variable'' class has some fields that allow its identification. We will build that list when we parse each file, adding each variable found by the previous defined triggers.
When the content assist finds the '$' character, it will supply the user + default variables gathered so far.

Since the variables can be cleared, thus they have scope, the ''Variable'' class needs to be refactorted, so it can represent the scope aswell. The scoping was settled before.

===Name Collisions===
I've considered that we should store the variables per project, like we currently do with macros. This will minimize the memory we need, rather than storing variables on each file - like we do currently. With this, I've discovered it's innevitable to have ''collisions''. That is, have the same variable name on multiple files.

To solve this problem, each variable/macro structure, will not have just a single scope, but rather a list of scopes.

===Events===
Besides the default event names, supplied by the wesnoth engine, there can be created custom ones, wich will be triggered with [fire_event]. As usual the default events names will be available in the cac/events.txt file.

The events defined by the user will be parsed from the ''name'' attribute of the [event] tag.

===Attributes===
All attributes are currently got from the schema.cfg

===Attributes Values===
All attributes values should be parsed based on the schema.cfg.

===Macros===
The support for macros is already built in, but it needs a way to let them have scope. That is, when an #undef is found, the certain macro would not be available to subsequent files unless redeclared. This will be done with the aid of the dependency tree and scoping. The collisions will be solved like I said at the variables section

===Support for custom luaWML tags===
The lua can create new WML Tags. It would be nice that the plugin suggest those aswell besides the ''schema.cfg''. The lua will be easily parsed, since there is a simple pattern for creating new tags:
wesnoth.wml_actions.<tag name>(cfg)

The parser will just run over the lua code/file, over each line, trying to match the 'function *wesnoth.wml_actions.*' pattern. If it finds something, it will add the tag name to the list of tags. There is also a small thing we might have missed. The user could use a shorthand notation for the actions namespace, so when searching for the pattern, I will add to the 'pattern to match' list, the respective variable when searching for new WML Tags.

Thus, like the ''wml-tags.lua'' from the data/lua uses:
local wml_actions = wesnoth.wml_actions

the 'to match' list will contain: 'function *wesnoth.wml_actions.*' and 'function *wml_actions.*', thus finding other tags too.

Going further more, for an ''optional'' enhancement, I could also search that function to see if it needs/has some extra attributes. The attributes can be found by:
* function's parameter (usually cfg) is asked for a property. For example:
function wml_actions.terrain(cfg)
local terrain = cfg.terrain or helper.wml_error("[terrain] missing required terrain= attribute")
cfg = helper.shallow_literal(cfg)
cfg.terrain = nil
for i, loc in ipairs(wesnoth.get_locations(cfg)) do
wesnoth.set_terrain(loc[1], loc[2], terrain, cfg.layer, cfg.replace_if_failed)
end
end

Here we need the attributes ''terrain'', ''layer'' and ''replace_if_failed''.

* ''get_child'' call:
function wml_actions.message(cfg)
local show_if = helper.get_child(cfg, "show_if")
if not show_if or wesnoth.eval_conditional(show_if) then
engine_message(cfg)
end
end

Here we need to have the attribute ''show_if''.

==Automatic/headless building==
The eclipse plugins can be automatically built from command line, provided there is the eclipse sdk and the eclipse delta pack on the builder's machine. The plugin can also use Buckminster tool to automate the building of the plugin.

''Notes''
Add all plugin's files *inside* a folder to prevent cluttering the directory where it's extracted

More info at:
* http://wiki.eclipse.org/PDE/Build
* http://wiki.bioclipse.net/index.php?title=How_to_build_plugins_headless
* http://help.eclipse.org/galileo/index.jsp?topic=/org.eclipse.pde.doc.user/guide/intro/pde_overview.htm
* http://www.eclipse.org/articles/Article-PDE-Automation/automation.html

==Standalone app auto-update==
The current standalone application doesn't offer the same eclipse's update system. I will add it, so anytime there is a new version of the plugin, it can be updated with a single click by the user, without the needing to download a new standalone app again.

==Documentation==
===External documentation===
The current existing readme will be split in 2 manuals: User Manual and Developer Manual (Don't forget to add images where relevant).

The user manual will contain:
* Prerequisites and Installing the prerequisites
Note: don't forget to mention the MINIMUM eclipse/java version needed to run
* Installing the plugin / standalone version
* Using the plugin
* Plugin features
* Step-by-step use cases
** Setupping the workspace
** Creating a new project and running it in the game
** Importing existing projects
** Using the WML Editor
** Updating the plugin
* Frequently Asked Questions

The developer manual will contain:
* Prerequisites and Installing the prerequisites
* Adding the plugin's projects in the
* Compiling and Running the plugin
* Deploying the plugin and standalone app

===Internal documentation===
The Eclipse infrastructure has features for letting the developer embed help into the application, depending on the current context. After I will write the external documentation, I will work on adding internal documentation aswell. Some of it already comes from the external one.

* Plugin welcome page
* Eclipse Help (When pressing Help->Help contents)
* Wizards help

==Plugin polishing==
This are some tasks needed to be done in order to get the plugin more stable and more usable than it's currently. Some of the tasks are taken from my todo list. New tasks will be added through the project advancing when improvements to actual code /user interaction can be done, so this list is not final.

# Don't copy a project that belongs to data/campaigns to the user addons's directory. This can be done by looking at the path when creating a new project. (This is prevented by not spawning a ''build.xml'' file in the campaigns's directory)
# Enhance the logging so it can help debugging other's problem much easier. I could split the current log in 2:
## Commands executed by the plugin
## Other information like parsed information/statuses
# Enhance the integration with the eclipse platform by adding the "Wesnoth" related wizards directly to the "New" menu.
# Allow users to import a directory as a wesnoth project. Under the hood it will either open the wesnoth project (if there is any .project files in it) or create a new empty project on it.
# Allow the user to clear it's current plugin's settings just with a simple button.
# Wesnoth Project Explorer - Add error markers just like the Java Explorer has
# Refactor the current way of getting the macro list. Currently if there is no _main.cfg practically the _MACROS_.cfg file is not built resulting in no MACRO suggestions.
# Create a view filter to hide the Project ''_AutoLinked_CFGExternalFiles_'' which is created for opening the external config files (external meaning outside the current workspace).
# Fix the F3 navigation when the map's location is specified withing " ", as a string.

===New parsing method (optional)===
The current parsing method involves a lot of Wesnoth preprocessor/wmlparser.py. This is doing somehow the parsing job double. This is because the xtext framework already does 1 pass over the files when added to the project. My plan is to see if I can reuse the already built AST(Abstract Syntax Tree) and the parse tree, to use those values instead of additional preprocessing/wmlparsing, and use the latter only when really needed.

Using the xtext's model will greatly fasten the "build" time of each project and it will be *much* simpler to work with, since the framework already provides exceptions recovering (that is, when the code is not well formed according to the grammar) and based on the defined grammar the respective tokens. So, for example instead using 2 another external processes, we could just iterate over each WMLTag and get it's WMLKeys and parse their individual values.

If this idea works, I will add it on the Plugin polishing tasks.

==Other ideas==
===Addons management===
There will be a new Addons management view. It will behave much like the in-game addon manager, but it will be more handy since the user doesn't need to start the game for that (and also wait till the cache refreshes after downloading it). This view will be based on the python script from '''data/tools/wesnoth_addon_manager''', like it does currently for uploading the project as an addon.

The view will let the user see the list/details for each of the addons currently on the server. There will be also a filter based on what addon server to use (trunk/1.8/1.9/etc)

The user will be able to just right click on an addon and download it to it's user data folder. Optionally a new project will be created, based on the just downloaded addon.



===Unit testing===
====Grammar====
For a better wml handling with in the editor, I will create a Testing class for the current grammar. The class will do testing on all *.cfgs in the data directory. That way after modifing something in the grammar we will be able to see how many errors we have introduced/eliminated. This will greatly help the developing of a better grammar that can hold all current WML formats.

''Notes'':
optionally rework the grammar and try to use a custom lexer/parser in order to benefit from the preprocessor, injecting the valid tokens. This would help the cases when the current grammar doesn't work:
{name} = value
or unclosed tags

====Parsing and getting information from files====
I will create some basic (or taken from existing campaigns) config files that will be parsed in order to check if the correct behaviour - correct information is extracted from the files.

This will check for extracting the:
scenario name
campaign name
next_scenario
first_scenario
variables
macros

=Timeline=
The GSOC period is between 24th May and 20th August. But since I have exams for 3 weeks (during 30.05-19.06.2011), I will start working on the plugin before the 24th of May, to recover some of the lost time. Also, my ImagineCup team made it to the national phase - that is in 5,6,7 May. That means till that time I will not be able to do so much work, so I'll make the timeline according with the starting of work on 9 May.

Here is a table with key periods of the time spent on this project.
{| border="1"
|'''Period''' || '''Actions'''
|-
| 26 April || Get accepted
|-
| 26 April - 8 May || Busy working on ImagineCup project for the national phase. Little or no work done.
|-
| 9 May - 15 May || Allow headless build of the plugin
|-
| 16 May - 22 May || Add Support for multiple installations
|-
| 23 May - 28 May || Add the auto-update feature for the standalone app
|-
| 30 May - 19 June || Exams
|-
| 20 June - 24 June || Create the external documentation
|-
| 25 June - 16 July || Enhance Content Assist
|-
| 15 July || Mid-term evaluations deadline
|-
| 17 July - 24 July || Addons management view
|-
| 25 July - 30 July || Unit tests
|-
| 1 August - 14 August || Do the Plugin polishing tasks
|-
| 15 August || Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc.
|-
| 15 August - 17 August || Create the internal documentation.
|-
| 18 August - 22 August || Buffer half-week. This will be used in case some tasks fell a bit outside their proposed time.
|-
| 22 August || Firm 'pencils down' date. Mentors, students and organization administrators can begin submitting final evaluations to Google.
|}

=Tasks=
This is a list of the "atomic" tasks that need to be done, based on the project part. Since the big tasks are split into smaller task, the progress will be seen better and any problems that arise with the timeline will be seen faster. I will update this table based on my current progress.

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Headless build ||Research about what system to use for automatic building of the plugin || Done
|-
| Headless build || Implement the chosen system for the wesnoth plugin|| Done
|-
| Multiple installations || Implement the preferences pages || Done
|-
| Multiple installations || Implement the logic for saving and loading the installation's paths on the disk || Done
|-
| Multiple installations || Implement the project preferences page || Done
|-
| Multiple installations || Rewrite the current mechanisms that use the paths to use the ones based on the project. || Done
|-
| Auto-update || Implement the auto-update feature. || In progress
|-
| Documentation || Write the User Manual || Done
|-
| Documentation || Write the Developer Manual || Done
|-
| Documentation || Write the internal documentation || Done
|-
| Enhance Content Assist || Project dependency tree || In progress
|-
| Enhance Content Assist || Content assist files || Done
|-
| Enhance Content Assist || Variables || Done
|-
| Enhance Content Assist || Events || In progress
|-
| Enhance Content Assist || Lua tags || Done
|-
| Addon management || Create the GUI of the view || Done
|-
| Addon management || Create the view's logic || Done
|-
| Unit testing || Tests for the grammar || None
|-
| Unit testing || Tests for parsing the config files || None
|-
| Plugin Polishing || Task 1 || None
|-
| Plugin Polishing || Task 2 || None
|-
| Plugin Polishing || Task 3 || None
|-
| Plugin Polishing || Task 4 || None
|-
| Plugin Polishing || Task 5 || None
|-
| Plugin Polishing || Task 6 || None
|-
| Plugin Polishing || Task 7|| None
|-
| Plugin Polishing || Task 8 || None
|-
| Plugin Polishing || Task 9 || None
|}

Optional tasks will be dealt with if the time allows it:

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Enhance Content Assist || Project dependency tree with multiple paths based on defines || None
|-
| Enhance Content Assist || Lua tags attributes || Done
|-
| Grammar || Enhance the grammar to support the 2 current unsupported syntax constructs || None
|-
| Documentation || Implement a simple WML project from start to end using Help's built-in cheat sheets tutorial || None
|}

=Questionnaire=
The questionnaire can be found here: http://wiki.wesnoth.org/User:Timotei21/Questionaire

SummerofCode2011 Timotei21

2011-07-14T08:20:22Z

Timotei21: update progress

{{SoC2011Student_2|timotei|SoC_Ideas_Eclipse_Plugin2011}}

=Description=
<h4>timotei - Improving the Eclipse Plugin</h4>
I aim at improving the plugin, so it will become the tool used by all UMC Authors. That is, UMC Authors will get rid of the lot of different tools they use for different tasks (for example the Emacs WMLMode/other plugins for different text editors), and instead use one single unified Tool that will speed up the development. My target is to make this plugin a complete and very stable suite for all umc tasks that don't need specialized software - like a graphics editor, so I'd like to have this oportunity to finish it in the good sense.

=Contacts=
==IRC==
timotei

==Other==
Forum: timotei 
gna.org: timotei

=SoC Application=
[http://www.google-melange.com/gsoc/proposal/review/google/gsoc2011/timoteidolean/1 Battle for Wesnoth - Google Summer of Code Application]

=Proposal Summary=
Page Last Updated: {{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}} 

In the following lines I will give details on how I'm planning to implement some of the required tasks, and also add some new ones.

The ''Notes'' sections are aimed for personal guideliness. They are took from my todo list.

==Multiple Wesnoth installations==
Having multiple wesnoth setups, and working with them at the same time would be nice to be done from inside the plugin.
For that, there will be a new preferences page. The page will look something like this:
http://dl.dropbox.com/u/462510/personal/soc/installations_management.PNG

There will be buttons that add/remove/edit a certain wesnoth installation. When adding/editing an installation, a new page like the current one (in which we set the paths), will be shown. The user will be able to name it and specify the version (I could automatically get the version by invoking ''wesnoth --version'').
The current page for setting the paths will act as a default installation.

After we have configured the paths, the user can chose the installation to which the (new) projects are bound, by opening the project properties. There will be a wesnoth-related page, where the user will be able to chose to what installation the project binds. With that, every command that uses the paths, won't use the single current paths, but the ones assigned to each project. This project properties page will open new ways for adding new

There would be a problem in case the project will be migrated between 2 different plugin's versions. For example, in one place we would have defined "1.9.4svn" but on the other there would be "trunk".

We can solve this in 3 ways:

# Alert the user that the installation doesn't bind, and let him chose the current matching installation for his plugin.
# Default automatically to the current plugin's default installation.
# "Hardcode" the version, so that there may be defined just installations like: 1.8.0, 1.9.3. With this we lose some flexibility, but we could use this as base version for new installations, so for example, a user can have two 1.9.3 installations. Provided this, we have again a possible problem, which can be solved again by 1. or 2., but this time, trying to match the base version first.

With this feature, the user won't need to restart the plugin at all, switching workspaces.

Regarding the technical PoV, all paths will be stored using eclipse's preferences system, by appending an unique id of each installation to each path in that set.

''Note'':
Add the NO_TERRAIN_GFX preprocess option checkbox to the project properties rather than being a global one.

==Enhance the Content Assist(CA) feature==
The CA framework is very extensible but it lacks proper contexts for providing the content.
I was thinking of trying to accomplish the generating of CA list either by using a config file, in case something like that can be used or writing directly the code that does that.

Another factor that is involved in a better auto-complete, is the ''schema.cfg'' the plugin bases on. Depending on whether the schema is worked on during this summer of code, I'll need to redo a bit the parser of the schema, in case the format/semantics change.

===Project files dependecy tree===
In order for the CA to work better - and maybe other areas would benefit from this - we will need to build a project files tree. With that tree, we can see how a certain declared macro/variable will affect subsequent related files and also their scope. Basically, we can see the relation from a file to anothers.

This tree will be (re)built in 2 situations:
# A file is added/removed/changed it's name
# A full rebuild is triggered (for example, the project is added for the first time in the workspace)

The tree will be built by the WML parser's rules:
# files are processed in the alphabetically order
# _initial.cfg is the first processed before anything else.
# _final.cfg is the last processed after anything else.
# if there is a _main.cfg in the directory, it is the only one processed.

Since the current ''WesnothProjectBuilder'' doesn't take in account the previous rules, I will create my own method of visiting each folder's children in the correct order. This method will look close to wesnoth's one, namely ''get_files_from_in_dir()'' found in ''src/filesystem.cpp:93''.

For a very fast lookup, as a data structure we will use a Hashtable, which has as the key the local project path to the file, and as a value a custom structure, which has the previous/next/parent/son properties, used to traverse the tree. The previous/next go on the same tree level, while the parent/son go up/down in the tree. I will use this instead of a tree, because this will give us access to info about a file, faster, in O(1) compared to a breadth-first search which has O(V+E) - where V is number of vertices and E number of edges.

Talking with Crab about this, he alerted me about a little possible problem with current aproach:
<Crab_> a note about 'The tree will be built by the WML parser's rules: ' - don't forget that you can (conditionally) include files/dirs from a file.
<Crab_> so, if we have 'ai/ais/zzz' which, say, defines a macro, it might get included by campaigns/bbb/scenarios/some_scenario.cfg , even if it is not inside /campaigns/bbb/scenarios

For that we have 2 cases:
{~file/dir path}
or
{file/dir path}

The paths are simply discarded if the current project's directory name is not found in the path.

Currently the so called "Tree" will be actually just a List or a single path tree. For the first iteration of this project, I won't tackle the advanced macro usage that might direct the flow based on defines (this will be optional if there will be time in GSoC, or if not, after GSoC, since I plan to remain active developer to maintain the plugin/enhance it furthermore). So, for example (taken from LoW):

#ifdef CAMPAIGN_LOW

{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#endif

#ifdef MULTIPLAYER

#define EASY
#enddef
{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#undef EASY
...
#endif

With current way to do this we will just take "blindly" all included directories/files without taking in consideration the #define flow control.

If we are at LoW, the following tree(list) will be created on its project:

_main.cfg -> utils/*.cfg -> scenarios/*.cfg -> units/*.cfg

Each file in the dependency tree, will have associated a number. For more details on why this and how it's done, read the Scoping section.

===Scoping===
In order for the plugin to know more about the semnatics, it should have the posibility to represent scopes. The scopes will be used mainly for variables and macros.

The Scoping is a delicate problem, because there are some tricky situations that might interfere with the scoping. I choosed to represent scoping in the following way:

Scoping is everything just about order relations. That is, we will compare numbers when dealing with scoping. With that we move the "problem" upper, to the "Dependency tree". We won't use filenames/paths because:

* The filename might change, but the order index may not. So, not having to update the index helps us.
* Number comparison is faster than string comparison.

So, from now on we'll talk in terms of indexes instead of filenames for scoping.

So, we are working with numbers. But there is still a lil' problem. What happens, when we remove/need to add a new file in the current tree, in the middle of existing 2? We would need to update all subsequent files's indexes. That would not be so ok performance wise.

To counter this problem we will not use consecutive numbers, but rather have a certain step between numbers. The step might be configured inside the plugin based on real statistics (for example, trying to see the number of cfg files per project. Taking a big number, like 1000 won't really hurt). For example, we could take the step 50. That means we would have the following tree for LoW:

0 50 100
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

instead of:
0 1 2
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

So, when it's the case of insertion, we insert the new node at the ''middle'' of the current "distance". That way we may insert/delete files *without* breaking the order, and our scoping will still work.

There is another problem it rised in my head: how do we know when to put the number as the next step (the previous number + step) or add it in the middle? Well, since every project will surely do a '''Full Build''', we'll use that oportunity to create the initial tree. Afterwards we will just insert files based on the halving of the distance between 2 indices.

The scoping will be represented by a simple structure, consisting of start index and offset and end index and offset.

===Content Assist Config(CAC) Files===
The CAC files will provide values that are default/available to config files from the wesnoth engine itself. There will be several files that define the values based on their context. This will allow a very great flexibility editing the CA list.

A CAC file will be just a simple text file, that has on each line one (or more) value(s) depending on the context.

* The ''cac/variables.txt'' will contain variables available. The list is currently available at [http://wiki.wesnoth.org/VariablesWML#Automatically_stored_variables]. For example the file could look like:
$side_number
$turn_number
...

* The ''cac/events.txt'' will contain the game events. The list is availabe at: [http://wiki.wesnoth.org/EventWML#Predefined_.27name.27_Key_Values]. Since the events that have spaces in their names can replace that with an underscore '_', the file will contain the underscore instead space variants also.



===Variables===
The variables are either defined by user or defined by default by the wesnoth engine. User's variables will be parsed from each processed file by the WesnothProjectBuilder, using the WMLSaxHandler. The default variables will be parsed and added from the CAC file. (cac/variables.txt)

Variables definitions can be triggered using the VARIABLE macro:
{VARIABLE var_name "value"}
or the [set_variable] tag:
[set_variable]
name=my_var
value="value"
[/set_variable]

The ''ConfigFile'' class in the ''org.wesnoth.wml.core'' already has a list of variables. The ''Variable'' class has some fields that allow its identification. We will build that list when we parse each file, adding each variable found by the previous defined triggers.
When the content assist finds the '$' character, it will supply the user + default variables gathered so far.

Since the variables can be cleared, thus they have scope, the ''Variable'' class needs to be refactorted, so it can represent the scope aswell. The scoping was settled before.

===Name Collisions===
I've considered that we should store the variables per project, like we currently do with macros. This will minimize the memory we need, rather than storing variables on each file - like we do currently. With this, I've discovered it's innevitable to have ''collisions''. That is, have the same variable name on multiple files.

To solve this problem, each variable/macro structure, will not have just a single scope, but rather a list of scopes.

===Events===
Besides the default event names, supplied by the wesnoth engine, there can be created custom ones, wich will be triggered with [fire_event]. As usual the default events names will be available in the cac/events.txt file.

The events defined by the user will be parsed from the ''name'' attribute of the [event] tag.

===Attributes===
All attributes are currently got from the schema.cfg

===Attributes Values===
All attributes values should be parsed based on the schema.cfg.

===Macros===
The support for macros is already built in, but it needs a way to let them have scope. That is, when an #undef is found, the certain macro would not be available to subsequent files unless redeclared. This will be done with the aid of the dependency tree and scoping. The collisions will be solved like I said at the variables section

===Support for custom luaWML tags===
The lua can create new WML Tags. It would be nice that the plugin suggest those aswell besides the ''schema.cfg''. The lua will be easily parsed, since there is a simple pattern for creating new tags:
wesnoth.wml_actions.<tag name>(cfg)

The parser will just run over the lua code/file, over each line, trying to match the 'function *wesnoth.wml_actions.*' pattern. If it finds something, it will add the tag name to the list of tags. There is also a small thing we might have missed. The user could use a shorthand notation for the actions namespace, so when searching for the pattern, I will add to the 'pattern to match' list, the respective variable when searching for new WML Tags.

Thus, like the ''wml-tags.lua'' from the data/lua uses:
local wml_actions = wesnoth.wml_actions

the 'to match' list will contain: 'function *wesnoth.wml_actions.*' and 'function *wml_actions.*', thus finding other tags too.

Going further more, for an ''optional'' enhancement, I could also search that function to see if it needs/has some extra attributes. The attributes can be found by:
* function's parameter (usually cfg) is asked for a property. For example:
function wml_actions.terrain(cfg)
local terrain = cfg.terrain or helper.wml_error("[terrain] missing required terrain= attribute")
cfg = helper.shallow_literal(cfg)
cfg.terrain = nil
for i, loc in ipairs(wesnoth.get_locations(cfg)) do
wesnoth.set_terrain(loc[1], loc[2], terrain, cfg.layer, cfg.replace_if_failed)
end
end

Here we need the attributes ''terrain'', ''layer'' and ''replace_if_failed''.

* ''get_child'' call:
function wml_actions.message(cfg)
local show_if = helper.get_child(cfg, "show_if")
if not show_if or wesnoth.eval_conditional(show_if) then
engine_message(cfg)
end
end

Here we need to have the attribute ''show_if''.

==Automatic/headless building==
The eclipse plugins can be automatically built from command line, provided there is the eclipse sdk and the eclipse delta pack on the builder's machine. The plugin can also use Buckminster tool to automate the building of the plugin.

''Notes''
Add all plugin's files *inside* a folder to prevent cluttering the directory where it's extracted

More info at:
* http://wiki.eclipse.org/PDE/Build
* http://wiki.bioclipse.net/index.php?title=How_to_build_plugins_headless
* http://help.eclipse.org/galileo/index.jsp?topic=/org.eclipse.pde.doc.user/guide/intro/pde_overview.htm
* http://www.eclipse.org/articles/Article-PDE-Automation/automation.html

==Standalone app auto-update==
The current standalone application doesn't offer the same eclipse's update system. I will add it, so anytime there is a new version of the plugin, it can be updated with a single click by the user, without the needing to download a new standalone app again.

==Documentation==
===External documentation===
The current existing readme will be split in 2 manuals: User Manual and Developer Manual (Don't forget to add images where relevant).

The user manual will contain:
* Prerequisites and Installing the prerequisites
Note: don't forget to mention the MINIMUM eclipse/java version needed to run
* Installing the plugin / standalone version
* Using the plugin
* Plugin features
* Step-by-step use cases
** Setupping the workspace
** Creating a new project and running it in the game
** Importing existing projects
** Using the WML Editor
** Updating the plugin
* Frequently Asked Questions

The developer manual will contain:
* Prerequisites and Installing the prerequisites
* Adding the plugin's projects in the
* Compiling and Running the plugin
* Deploying the plugin and standalone app

===Internal documentation===
The Eclipse infrastructure has features for letting the developer embed help into the application, depending on the current context. After I will write the external documentation, I will work on adding internal documentation aswell. Some of it already comes from the external one.

* Plugin welcome page
* Eclipse Help (When pressing Help->Help contents)
* Wizards help

==Plugin polishing==
This are some tasks needed to be done in order to get the plugin more stable and more usable than it's currently. Some of the tasks are taken from my todo list. New tasks will be added through the project advancing when improvements to actual code /user interaction can be done, so this list is not final.

# Don't copy a project that belongs to data/campaigns to the user addons's directory. This can be done by looking at the path when creating a new project. (This is prevented by not spawning a ''build.xml'' file in the campaigns's directory)
# Enhance the logging so it can help debugging other's problem much easier. I could split the current log in 2:
## Commands executed by the plugin
## Other information like parsed information/statuses
# Enhance the integration with the eclipse platform by adding the "Wesnoth" related wizards directly to the "New" menu.
# Allow users to import a directory as a wesnoth project. Under the hood it will either open the wesnoth project (if there is any .project files in it) or create a new empty project on it.
# Allow the user to clear it's current plugin's settings just with a simple button.
# Wesnoth Project Explorer - Add error markers just like the Java Explorer has
# Refactor the current way of getting the macro list. Currently if there is no _main.cfg practically the _MACROS_.cfg file is not built resulting in no MACRO suggestions.
# Create a view filter to hide the Project ''_AutoLinked_CFGExternalFiles_'' which is created for opening the external config files (external meaning outside the current workspace).
# Fix the F3 navigation when the map's location is specified withing " ", as a string.

===New parsing method (optional)===
The current parsing method involves a lot of Wesnoth preprocessor/wmlparser.py. This is doing somehow the parsing job double. This is because the xtext framework already does 1 pass over the files when added to the project. My plan is to see if I can reuse the already built AST(Abstract Syntax Tree) and the parse tree, to use those values instead of additional preprocessing/wmlparsing, and use the latter only when really needed.

Using the xtext's model will greatly fasten the "build" time of each project and it will be *much* simpler to work with, since the framework already provides exceptions recovering (that is, when the code is not well formed according to the grammar) and based on the defined grammar the respective tokens. So, for example instead using 2 another external processes, we could just iterate over each WMLTag and get it's WMLKeys and parse their individual values.

If this idea works, I will add it on the Plugin polishing tasks.

==Other ideas==
===Addons management===
There will be a new Addons management view. It will behave much like the in-game addon manager, but it will be more handy since the user doesn't need to start the game for that (and also wait till the cache refreshes after downloading it). This view will be based on the python script from '''data/tools/wesnoth_addon_manager''', like it does currently for uploading the project as an addon.

The view will let the user see the list/details for each of the addons currently on the server. There will be also a filter based on what addon server to use (trunk/1.8/1.9/etc)

The user will be able to just right click on an addon and download it to it's user data folder. Optionally a new project will be created, based on the just downloaded addon.



===Unit testing===
====Grammar====
For a better wml handling with in the editor, I will create a Testing class for the current grammar. The class will do testing on all *.cfgs in the data directory. That way after modifing something in the grammar we will be able to see how many errors we have introduced/eliminated. This will greatly help the developing of a better grammar that can hold all current WML formats.

''Notes'':
optionally rework the grammar and try to use a custom lexer/parser in order to benefit from the preprocessor, injecting the valid tokens. This would help the cases when the current grammar doesn't work:
{name} = value
or unclosed tags

====Parsing and getting information from files====
I will create some basic (or taken from existing campaigns) config files that will be parsed in order to check if the correct behaviour - correct information is extracted from the files.

This will check for extracting the:
scenario name
campaign name
next_scenario
first_scenario
variables
macros

=Timeline=
The GSOC period is between 24th May and 20th August. But since I have exams for 3 weeks (during 30.05-19.06.2011), I will start working on the plugin before the 24th of May, to recover some of the lost time. Also, my ImagineCup team made it to the national phase - that is in 5,6,7 May. That means till that time I will not be able to do so much work, so I'll make the timeline according with the starting of work on 9 May.

Here is a table with key periods of the time spent on this project.
{| border="1"
|'''Period''' || '''Actions'''
|-
| 26 April || Get accepted
|-
| 26 April - 8 May || Busy working on ImagineCup project for the national phase. Little or no work done.
|-
| 9 May - 15 May || Allow headless build of the plugin
|-
| 16 May - 22 May || Add Support for multiple installations
|-
| 23 May - 28 May || Add the auto-update feature for the standalone app
|-
| 30 May - 19 June || Exams
|-
| 20 June - 24 June || Create the external documentation
|-
| 25 June - 16 July || Enhance Content Assist
|-
| 15 July || Mid-term evaluations deadline
|-
| 17 July - 24 July || Addons management view
|-
| 25 July - 30 July || Unit tests
|-
| 1 August - 14 August || Do the Plugin polishing tasks
|-
| 15 August || Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc.
|-
| 15 August - 17 August || Create the internal documentation.
|-
| 18 August - 22 August || Buffer half-week. This will be used in case some tasks fell a bit outside their proposed time.
|-
| 22 August || Firm 'pencils down' date. Mentors, students and organization administrators can begin submitting final evaluations to Google.
|}

=Tasks=
This is a list of the "atomic" tasks that need to be done, based on the project part. Since the big tasks are split into smaller task, the progress will be seen better and any problems that arise with the timeline will be seen faster. I will update this table based on my current progress.

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Headless build ||Research about what system to use for automatic building of the plugin || Done
|-
| Headless build || Implement the chosen system for the wesnoth plugin|| Done
|-
| Multiple installations || Implement the preferences pages || Done
|-
| Multiple installations || Implement the logic for saving and loading the installation's paths on the disk || Done
|-
| Multiple installations || Implement the project preferences page || Done
|-
| Multiple installations || Rewrite the current mechanisms that use the paths to use the ones based on the project. || Done
|-
| Auto-update || Implement the auto-update feature. || In progress
|-
| Documentation || Write the User Manual || Done
|-
| Documentation || Write the Developer Manual || Done
|-
| Documentation || Write the internal documentation || Done
|-
| Enhance Content Assist || Project dependency tree || In progress
|-
| Enhance Content Assist || Content assist files || Done
|-
| Enhance Content Assist || Variables || In progress
|-
| Enhance Content Assist || Events || In progress
|-
| Enhance Content Assist || Lua tags || None
|-
| Addon management || Create the GUI of the view || Done
|-
| Addon management || Create the view's logic || Done
|-
| Unit testing || Tests for the grammar || None
|-
| Unit testing || Tests for parsing the config files || None
|-
| Plugin Polishing || Task 1 || None
|-
| Plugin Polishing || Task 2 || None
|-
| Plugin Polishing || Task 3 || None
|-
| Plugin Polishing || Task 4 || None
|-
| Plugin Polishing || Task 5 || None
|-
| Plugin Polishing || Task 6 || None
|-
| Plugin Polishing || Task 7|| None
|-
| Plugin Polishing || Task 8 || None
|-
| Plugin Polishing || Task 9 || None
|}

Optional tasks will be dealt with if the time allows it:

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Enhance Content Assist || Project dependency tree with multiple paths based on defines || None
|-
| Enhance Content Assist || Lua tags attributes || None
|-
| Grammar || Enhance the grammar to support the 2 current unsupported syntax constructs || None
|-
| Documentation || Implement a simple WML project from start to end using Help's built-in cheat sheets tutorial || None
|}

=Questionnaire=
The questionnaire can be found here: http://wiki.wesnoth.org/User:Timotei21/Questionaire

SummerofCode2011 Timotei21

2011-07-13T10:46:38Z

Timotei21: update progress

{{SoC2011Student_2|timotei|SoC_Ideas_Eclipse_Plugin2011}}

=Description=
<h4>timotei - Improving the Eclipse Plugin</h4>
I aim at improving the plugin, so it will become the tool used by all UMC Authors. That is, UMC Authors will get rid of the lot of different tools they use for different tasks (for example the Emacs WMLMode/other plugins for different text editors), and instead use one single unified Tool that will speed up the development. My target is to make this plugin a complete and very stable suite for all umc tasks that don't need specialized software - like a graphics editor, so I'd like to have this oportunity to finish it in the good sense.

=Contacts=
==IRC==
timotei

==Other==
Forum: timotei 
gna.org: timotei

=SoC Application=
[http://www.google-melange.com/gsoc/proposal/review/google/gsoc2011/timoteidolean/1 Battle for Wesnoth - Google Summer of Code Application]

=Proposal Summary=
Page Last Updated: {{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}} 

In the following lines I will give details on how I'm planning to implement some of the required tasks, and also add some new ones.

The ''Notes'' sections are aimed for personal guideliness. They are took from my todo list.

==Multiple Wesnoth installations==
Having multiple wesnoth setups, and working with them at the same time would be nice to be done from inside the plugin.
For that, there will be a new preferences page. The page will look something like this:
http://dl.dropbox.com/u/462510/personal/soc/installations_management.PNG

There will be buttons that add/remove/edit a certain wesnoth installation. When adding/editing an installation, a new page like the current one (in which we set the paths), will be shown. The user will be able to name it and specify the version (I could automatically get the version by invoking ''wesnoth --version'').
The current page for setting the paths will act as a default installation.

After we have configured the paths, the user can chose the installation to which the (new) projects are bound, by opening the project properties. There will be a wesnoth-related page, where the user will be able to chose to what installation the project binds. With that, every command that uses the paths, won't use the single current paths, but the ones assigned to each project. This project properties page will open new ways for adding new

There would be a problem in case the project will be migrated between 2 different plugin's versions. For example, in one place we would have defined "1.9.4svn" but on the other there would be "trunk".

We can solve this in 3 ways:

# Alert the user that the installation doesn't bind, and let him chose the current matching installation for his plugin.
# Default automatically to the current plugin's default installation.
# "Hardcode" the version, so that there may be defined just installations like: 1.8.0, 1.9.3. With this we lose some flexibility, but we could use this as base version for new installations, so for example, a user can have two 1.9.3 installations. Provided this, we have again a possible problem, which can be solved again by 1. or 2., but this time, trying to match the base version first.

With this feature, the user won't need to restart the plugin at all, switching workspaces.

Regarding the technical PoV, all paths will be stored using eclipse's preferences system, by appending an unique id of each installation to each path in that set.

''Note'':
Add the NO_TERRAIN_GFX preprocess option checkbox to the project properties rather than being a global one.

==Enhance the Content Assist(CA) feature==
The CA framework is very extensible but it lacks proper contexts for providing the content.
I was thinking of trying to accomplish the generating of CA list either by using a config file, in case something like that can be used or writing directly the code that does that.

Another factor that is involved in a better auto-complete, is the ''schema.cfg'' the plugin bases on. Depending on whether the schema is worked on during this summer of code, I'll need to redo a bit the parser of the schema, in case the format/semantics change.

===Project files dependecy tree===
In order for the CA to work better - and maybe other areas would benefit from this - we will need to build a project files tree. With that tree, we can see how a certain declared macro/variable will affect subsequent related files and also their scope. Basically, we can see the relation from a file to anothers.

This tree will be (re)built in 2 situations:
# A file is added/removed/changed it's name
# A full rebuild is triggered (for example, the project is added for the first time in the workspace)

The tree will be built by the WML parser's rules:
# files are processed in the alphabetically order
# _initial.cfg is the first processed before anything else.
# _final.cfg is the last processed after anything else.
# if there is a _main.cfg in the directory, it is the only one processed.

Since the current ''WesnothProjectBuilder'' doesn't take in account the previous rules, I will create my own method of visiting each folder's children in the correct order. This method will look close to wesnoth's one, namely ''get_files_from_in_dir()'' found in ''src/filesystem.cpp:93''.

For a very fast lookup, as a data structure we will use a Hashtable, which has as the key the local project path to the file, and as a value a custom structure, which has the previous/next/parent/son properties, used to traverse the tree. The previous/next go on the same tree level, while the parent/son go up/down in the tree. I will use this instead of a tree, because this will give us access to info about a file, faster, in O(1) compared to a breadth-first search which has O(V+E) - where V is number of vertices and E number of edges.

Talking with Crab about this, he alerted me about a little possible problem with current aproach:
<Crab_> a note about 'The tree will be built by the WML parser's rules: ' - don't forget that you can (conditionally) include files/dirs from a file.
<Crab_> so, if we have 'ai/ais/zzz' which, say, defines a macro, it might get included by campaigns/bbb/scenarios/some_scenario.cfg , even if it is not inside /campaigns/bbb/scenarios

For that we have 2 cases:
{~file/dir path}
or
{file/dir path}

The paths are simply discarded if the current project's directory name is not found in the path.

Currently the so called "Tree" will be actually just a List or a single path tree. For the first iteration of this project, I won't tackle the advanced macro usage that might direct the flow based on defines (this will be optional if there will be time in GSoC, or if not, after GSoC, since I plan to remain active developer to maintain the plugin/enhance it furthermore). So, for example (taken from LoW):

#ifdef CAMPAIGN_LOW

{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#endif

#ifdef MULTIPLAYER

#define EASY
#enddef
{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#undef EASY
...
#endif

With current way to do this we will just take "blindly" all included directories/files without taking in consideration the #define flow control.

If we are at LoW, the following tree(list) will be created on its project:

_main.cfg -> utils/*.cfg -> scenarios/*.cfg -> units/*.cfg

Each file in the dependency tree, will have associated a number. For more details on why this and how it's done, read the Scoping section.

===Scoping===
In order for the plugin to know more about the semnatics, it should have the posibility to represent scopes. The scopes will be used mainly for variables and macros.

The Scoping is a delicate problem, because there are some tricky situations that might interfere with the scoping. I choosed to represent scoping in the following way:

Scoping is everything just about order relations. That is, we will compare numbers when dealing with scoping. With that we move the "problem" upper, to the "Dependency tree". We won't use filenames/paths because:

* The filename might change, but the order index may not. So, not having to update the index helps us.
* Number comparison is faster than string comparison.

So, from now on we'll talk in terms of indexes instead of filenames for scoping.

So, we are working with numbers. But there is still a lil' problem. What happens, when we remove/need to add a new file in the current tree, in the middle of existing 2? We would need to update all subsequent files's indexes. That would not be so ok performance wise.

To counter this problem we will not use consecutive numbers, but rather have a certain step between numbers. The step might be configured inside the plugin based on real statistics (for example, trying to see the number of cfg files per project. Taking a big number, like 1000 won't really hurt). For example, we could take the step 50. That means we would have the following tree for LoW:

0 50 100
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

instead of:
0 1 2
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

So, when it's the case of insertion, we insert the new node at the ''middle'' of the current "distance". That way we may insert/delete files *without* breaking the order, and our scoping will still work.

There is another problem it rised in my head: how do we know when to put the number as the next step (the previous number + step) or add it in the middle? Well, since every project will surely do a '''Full Build''', we'll use that oportunity to create the initial tree. Afterwards we will just insert files based on the halving of the distance between 2 indices.

The scoping will be represented by a simple structure, consisting of start index and offset and end index and offset.

===Content Assist Config(CAC) Files===
The CAC files will provide values that are default/available to config files from the wesnoth engine itself. There will be several files that define the values based on their context. This will allow a very great flexibility editing the CA list.

A CAC file will be just a simple text file, that has on each line one (or more) value(s) depending on the context.

* The ''cac/variables.txt'' will contain variables available. The list is currently available at [http://wiki.wesnoth.org/VariablesWML#Automatically_stored_variables]. For example the file could look like:
$side_number
$turn_number
...

* The ''cac/events.txt'' will contain the game events. The list is availabe at: [http://wiki.wesnoth.org/EventWML#Predefined_.27name.27_Key_Values]. Since the events that have spaces in their names can replace that with an underscore '_', the file will contain the underscore instead space variants also.



===Variables===
The variables are either defined by user or defined by default by the wesnoth engine. User's variables will be parsed from each processed file by the WesnothProjectBuilder, using the WMLSaxHandler. The default variables will be parsed and added from the CAC file. (cac/variables.txt)

Variables definitions can be triggered using the VARIABLE macro:
{VARIABLE var_name "value"}
or the [set_variable] tag:
[set_variable]
name=my_var
value="value"
[/set_variable]

The ''ConfigFile'' class in the ''org.wesnoth.wml.core'' already has a list of variables. The ''Variable'' class has some fields that allow its identification. We will build that list when we parse each file, adding each variable found by the previous defined triggers.
When the content assist finds the '$' character, it will supply the user + default variables gathered so far.

Since the variables can be cleared, thus they have scope, the ''Variable'' class needs to be refactorted, so it can represent the scope aswell. The scoping was settled before.

===Name Collisions===
I've considered that we should store the variables per project, like we currently do with macros. This will minimize the memory we need, rather than storing variables on each file - like we do currently. With this, I've discovered it's innevitable to have ''collisions''. That is, have the same variable name on multiple files.

To solve this problem, each variable/macro structure, will not have just a single scope, but rather a list of scopes.

===Events===
Besides the default event names, supplied by the wesnoth engine, there can be created custom ones, wich will be triggered with [fire_event]. As usual the default events names will be available in the cac/events.txt file.

The events defined by the user will be parsed from the ''name'' attribute of the [event] tag.

===Attributes===
All attributes are currently got from the schema.cfg

===Attributes Values===
All attributes values should be parsed based on the schema.cfg.

===Macros===
The support for macros is already built in, but it needs a way to let them have scope. That is, when an #undef is found, the certain macro would not be available to subsequent files unless redeclared. This will be done with the aid of the dependency tree and scoping. The collisions will be solved like I said at the variables section

===Support for custom luaWML tags===
The lua can create new WML Tags. It would be nice that the plugin suggest those aswell besides the ''schema.cfg''. The lua will be easily parsed, since there is a simple pattern for creating new tags:
wesnoth.wml_actions.<tag name>(cfg)

The parser will just run over the lua code/file, over each line, trying to match the 'function *wesnoth.wml_actions.*' pattern. If it finds something, it will add the tag name to the list of tags. There is also a small thing we might have missed. The user could use a shorthand notation for the actions namespace, so when searching for the pattern, I will add to the 'pattern to match' list, the respective variable when searching for new WML Tags.

Thus, like the ''wml-tags.lua'' from the data/lua uses:
local wml_actions = wesnoth.wml_actions

the 'to match' list will contain: 'function *wesnoth.wml_actions.*' and 'function *wml_actions.*', thus finding other tags too.

Going further more, for an ''optional'' enhancement, I could also search that function to see if it needs/has some extra attributes. The attributes can be found by:
* function's parameter (usually cfg) is asked for a property. For example:
function wml_actions.terrain(cfg)
local terrain = cfg.terrain or helper.wml_error("[terrain] missing required terrain= attribute")
cfg = helper.shallow_literal(cfg)
cfg.terrain = nil
for i, loc in ipairs(wesnoth.get_locations(cfg)) do
wesnoth.set_terrain(loc[1], loc[2], terrain, cfg.layer, cfg.replace_if_failed)
end
end

Here we need the attributes ''terrain'', ''layer'' and ''replace_if_failed''.

* ''get_child'' call:
function wml_actions.message(cfg)
local show_if = helper.get_child(cfg, "show_if")
if not show_if or wesnoth.eval_conditional(show_if) then
engine_message(cfg)
end
end

Here we need to have the attribute ''show_if''.

==Automatic/headless building==
The eclipse plugins can be automatically built from command line, provided there is the eclipse sdk and the eclipse delta pack on the builder's machine. The plugin can also use Buckminster tool to automate the building of the plugin.

''Notes''
Add all plugin's files *inside* a folder to prevent cluttering the directory where it's extracted

More info at:
* http://wiki.eclipse.org/PDE/Build
* http://wiki.bioclipse.net/index.php?title=How_to_build_plugins_headless
* http://help.eclipse.org/galileo/index.jsp?topic=/org.eclipse.pde.doc.user/guide/intro/pde_overview.htm
* http://www.eclipse.org/articles/Article-PDE-Automation/automation.html

==Standalone app auto-update==
The current standalone application doesn't offer the same eclipse's update system. I will add it, so anytime there is a new version of the plugin, it can be updated with a single click by the user, without the needing to download a new standalone app again.

==Documentation==
===External documentation===
The current existing readme will be split in 2 manuals: User Manual and Developer Manual (Don't forget to add images where relevant).

The user manual will contain:
* Prerequisites and Installing the prerequisites
Note: don't forget to mention the MINIMUM eclipse/java version needed to run
* Installing the plugin / standalone version
* Using the plugin
* Plugin features
* Step-by-step use cases
** Setupping the workspace
** Creating a new project and running it in the game
** Importing existing projects
** Using the WML Editor
** Updating the plugin
* Frequently Asked Questions

The developer manual will contain:
* Prerequisites and Installing the prerequisites
* Adding the plugin's projects in the
* Compiling and Running the plugin
* Deploying the plugin and standalone app

===Internal documentation===
The Eclipse infrastructure has features for letting the developer embed help into the application, depending on the current context. After I will write the external documentation, I will work on adding internal documentation aswell. Some of it already comes from the external one.

* Plugin welcome page
* Eclipse Help (When pressing Help->Help contents)
* Wizards help

==Plugin polishing==
This are some tasks needed to be done in order to get the plugin more stable and more usable than it's currently. Some of the tasks are taken from my todo list. New tasks will be added through the project advancing when improvements to actual code /user interaction can be done, so this list is not final.

# Don't copy a project that belongs to data/campaigns to the user addons's directory. This can be done by looking at the path when creating a new project. (This is prevented by not spawning a ''build.xml'' file in the campaigns's directory)
# Enhance the logging so it can help debugging other's problem much easier. I could split the current log in 2:
## Commands executed by the plugin
## Other information like parsed information/statuses
# Enhance the integration with the eclipse platform by adding the "Wesnoth" related wizards directly to the "New" menu.
# Allow users to import a directory as a wesnoth project. Under the hood it will either open the wesnoth project (if there is any .project files in it) or create a new empty project on it.
# Allow the user to clear it's current plugin's settings just with a simple button.
# Wesnoth Project Explorer - Add error markers just like the Java Explorer has
# Refactor the current way of getting the macro list. Currently if there is no _main.cfg practically the _MACROS_.cfg file is not built resulting in no MACRO suggestions.
# Create a view filter to hide the Project ''_AutoLinked_CFGExternalFiles_'' which is created for opening the external config files (external meaning outside the current workspace).
# Fix the F3 navigation when the map's location is specified withing " ", as a string.

===New parsing method (optional)===
The current parsing method involves a lot of Wesnoth preprocessor/wmlparser.py. This is doing somehow the parsing job double. This is because the xtext framework already does 1 pass over the files when added to the project. My plan is to see if I can reuse the already built AST(Abstract Syntax Tree) and the parse tree, to use those values instead of additional preprocessing/wmlparsing, and use the latter only when really needed.

Using the xtext's model will greatly fasten the "build" time of each project and it will be *much* simpler to work with, since the framework already provides exceptions recovering (that is, when the code is not well formed according to the grammar) and based on the defined grammar the respective tokens. So, for example instead using 2 another external processes, we could just iterate over each WMLTag and get it's WMLKeys and parse their individual values.

If this idea works, I will add it on the Plugin polishing tasks.

==Other ideas==
===Addons management===
There will be a new Addons management view. It will behave much like the in-game addon manager, but it will be more handy since the user doesn't need to start the game for that (and also wait till the cache refreshes after downloading it). This view will be based on the python script from '''data/tools/wesnoth_addon_manager''', like it does currently for uploading the project as an addon.

The view will let the user see the list/details for each of the addons currently on the server. There will be also a filter based on what addon server to use (trunk/1.8/1.9/etc)

The user will be able to just right click on an addon and download it to it's user data folder. Optionally a new project will be created, based on the just downloaded addon.



===Unit testing===
====Grammar====
For a better wml handling with in the editor, I will create a Testing class for the current grammar. The class will do testing on all *.cfgs in the data directory. That way after modifing something in the grammar we will be able to see how many errors we have introduced/eliminated. This will greatly help the developing of a better grammar that can hold all current WML formats.

''Notes'':
optionally rework the grammar and try to use a custom lexer/parser in order to benefit from the preprocessor, injecting the valid tokens. This would help the cases when the current grammar doesn't work:
{name} = value
or unclosed tags

====Parsing and getting information from files====
I will create some basic (or taken from existing campaigns) config files that will be parsed in order to check if the correct behaviour - correct information is extracted from the files.

This will check for extracting the:
scenario name
campaign name
next_scenario
first_scenario
variables
macros

=Timeline=
The GSOC period is between 24th May and 20th August. But since I have exams for 3 weeks (during 30.05-19.06.2011), I will start working on the plugin before the 24th of May, to recover some of the lost time. Also, my ImagineCup team made it to the national phase - that is in 5,6,7 May. That means till that time I will not be able to do so much work, so I'll make the timeline according with the starting of work on 9 May.

Here is a table with key periods of the time spent on this project.
{| border="1"
|'''Period''' || '''Actions'''
|-
| 26 April || Get accepted
|-
| 26 April - 8 May || Busy working on ImagineCup project for the national phase. Little or no work done.
|-
| 9 May - 15 May || Allow headless build of the plugin
|-
| 16 May - 22 May || Add Support for multiple installations
|-
| 23 May - 28 May || Add the auto-update feature for the standalone app
|-
| 30 May - 19 June || Exams
|-
| 20 June - 24 June || Create the external documentation
|-
| 25 June - 16 July || Enhance Content Assist
|-
| 15 July || Mid-term evaluations deadline
|-
| 17 July - 24 July || Addons management view
|-
| 25 July - 30 July || Unit tests
|-
| 1 August - 14 August || Do the Plugin polishing tasks
|-
| 15 August || Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc.
|-
| 15 August - 17 August || Create the internal documentation.
|-
| 18 August - 22 August || Buffer half-week. This will be used in case some tasks fell a bit outside their proposed time.
|-
| 22 August || Firm 'pencils down' date. Mentors, students and organization administrators can begin submitting final evaluations to Google.
|}

=Tasks=
This is a list of the "atomic" tasks that need to be done, based on the project part. Since the big tasks are split into smaller task, the progress will be seen better and any problems that arise with the timeline will be seen faster. I will update this table based on my current progress.

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Headless build ||Research about what system to use for automatic building of the plugin || Done
|-
| Headless build || Implement the chosen system for the wesnoth plugin|| Done
|-
| Multiple installations || Implement the preferences pages || Done
|-
| Multiple installations || Implement the logic for saving and loading the installation's paths on the disk || Done
|-
| Multiple installations || Implement the project preferences page || Done
|-
| Multiple installations || Rewrite the current mechanisms that use the paths to use the ones based on the project. || Done
|-
| Auto-update || Implement the auto-update feature. || In progress
|-
| Documentation || Write the User Manual || Done
|-
| Documentation || Write the Developer Manual || Done
|-
| Documentation || Write the internal documentation || Done
|-
| Enhance Content Assist || Project dependency tree || In progress
|-
| Enhance Content Assist || Content assist files || In progress
|-
| Enhance Content Assist || Variables || In progress
|-
| Enhance Content Assist || Events || In progress
|-
| Enhance Content Assist || Lua tags || None
|-
| Addon management || Create the GUI of the view || Done
|-
| Addon management || Create the view's logic || Done
|-
| Unit testing || Tests for the grammar || None
|-
| Unit testing || Tests for parsing the config files || None
|-
| Plugin Polishing || Task 1 || None
|-
| Plugin Polishing || Task 2 || None
|-
| Plugin Polishing || Task 3 || None
|-
| Plugin Polishing || Task 4 || None
|-
| Plugin Polishing || Task 5 || None
|-
| Plugin Polishing || Task 6 || None
|-
| Plugin Polishing || Task 7|| None
|-
| Plugin Polishing || Task 8 || None
|-
| Plugin Polishing || Task 9 || None
|}

Optional tasks will be dealt with if the time allows it:

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Enhance Content Assist || Project dependency tree with multiple paths based on defines || None
|-
| Enhance Content Assist || Lua tags attributes || None
|-
| Grammar || Enhance the grammar to support the 2 current unsupported syntax constructs || None
|-
| Documentation || Implement a simple WML project from start to end using Help's built-in cheat sheets tutorial || None
|}

=Questionnaire=
The questionnaire can be found here: http://wiki.wesnoth.org/User:Timotei21/Questionaire

SummerofCode2011 Timotei21

2011-07-08T20:41:29Z

Timotei21: /* Tasks */

{{SoC2011Student_2|timotei|SoC_Ideas_Eclipse_Plugin2011}}

=Description=
<h4>timotei - Improving the Eclipse Plugin</h4>
I aim at improving the plugin, so it will become the tool used by all UMC Authors. That is, UMC Authors will get rid of the lot of different tools they use for different tasks (for example the Emacs WMLMode/other plugins for different text editors), and instead use one single unified Tool that will speed up the development. My target is to make this plugin a complete and very stable suite for all umc tasks that don't need specialized software - like a graphics editor, so I'd like to have this oportunity to finish it in the good sense.

=Contacts=
==IRC==
timotei

==Other==
Forum: timotei 
gna.org: timotei

=SoC Application=
[http://www.google-melange.com/gsoc/proposal/review/google/gsoc2011/timoteidolean/1 Battle for Wesnoth - Google Summer of Code Application]

=Proposal Summary=
Page Last Updated: {{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}} 

In the following lines I will give details on how I'm planning to implement some of the required tasks, and also add some new ones.

The ''Notes'' sections are aimed for personal guideliness. They are took from my todo list.

==Multiple Wesnoth installations==
Having multiple wesnoth setups, and working with them at the same time would be nice to be done from inside the plugin.
For that, there will be a new preferences page. The page will look something like this:
http://dl.dropbox.com/u/462510/personal/soc/installations_management.PNG

There will be buttons that add/remove/edit a certain wesnoth installation. When adding/editing an installation, a new page like the current one (in which we set the paths), will be shown. The user will be able to name it and specify the version (I could automatically get the version by invoking ''wesnoth --version'').
The current page for setting the paths will act as a default installation.

After we have configured the paths, the user can chose the installation to which the (new) projects are bound, by opening the project properties. There will be a wesnoth-related page, where the user will be able to chose to what installation the project binds. With that, every command that uses the paths, won't use the single current paths, but the ones assigned to each project. This project properties page will open new ways for adding new

There would be a problem in case the project will be migrated between 2 different plugin's versions. For example, in one place we would have defined "1.9.4svn" but on the other there would be "trunk".

We can solve this in 3 ways:

# Alert the user that the installation doesn't bind, and let him chose the current matching installation for his plugin.
# Default automatically to the current plugin's default installation.
# "Hardcode" the version, so that there may be defined just installations like: 1.8.0, 1.9.3. With this we lose some flexibility, but we could use this as base version for new installations, so for example, a user can have two 1.9.3 installations. Provided this, we have again a possible problem, which can be solved again by 1. or 2., but this time, trying to match the base version first.

With this feature, the user won't need to restart the plugin at all, switching workspaces.

Regarding the technical PoV, all paths will be stored using eclipse's preferences system, by appending an unique id of each installation to each path in that set.

''Note'':
Add the NO_TERRAIN_GFX preprocess option checkbox to the project properties rather than being a global one.

==Enhance the Content Assist(CA) feature==
The CA framework is very extensible but it lacks proper contexts for providing the content.
I was thinking of trying to accomplish the generating of CA list either by using a config file, in case something like that can be used or writing directly the code that does that.

Another factor that is involved in a better auto-complete, is the ''schema.cfg'' the plugin bases on. Depending on whether the schema is worked on during this summer of code, I'll need to redo a bit the parser of the schema, in case the format/semantics change.

===Project files dependecy tree===
In order for the CA to work better - and maybe other areas would benefit from this - we will need to build a project files tree. With that tree, we can see how a certain declared macro/variable will affect subsequent related files and also their scope. Basically, we can see the relation from a file to anothers.

This tree will be (re)built in 2 situations:
# A file is added/removed/changed it's name
# A full rebuild is triggered (for example, the project is added for the first time in the workspace)

The tree will be built by the WML parser's rules:
# files are processed in the alphabetically order
# _initial.cfg is the first processed before anything else.
# _final.cfg is the last processed after anything else.
# if there is a _main.cfg in the directory, it is the only one processed.

Since the current ''WesnothProjectBuilder'' doesn't take in account the previous rules, I will create my own method of visiting each folder's children in the correct order. This method will look close to wesnoth's one, namely ''get_files_from_in_dir()'' found in ''src/filesystem.cpp:93''.

For a very fast lookup, as a data structure we will use a Hashtable, which has as the key the local project path to the file, and as a value a custom structure, which has the previous/next/parent/son properties, used to traverse the tree. The previous/next go on the same tree level, while the parent/son go up/down in the tree. I will use this instead of a tree, because this will give us access to info about a file, faster, in O(1) compared to a breadth-first search which has O(V+E) - where V is number of vertices and E number of edges.

Talking with Crab about this, he alerted me about a little possible problem with current aproach:
<Crab_> a note about 'The tree will be built by the WML parser's rules: ' - don't forget that you can (conditionally) include files/dirs from a file.
<Crab_> so, if we have 'ai/ais/zzz' which, say, defines a macro, it might get included by campaigns/bbb/scenarios/some_scenario.cfg , even if it is not inside /campaigns/bbb/scenarios

For that we have 2 cases:
{~file/dir path}
or
{file/dir path}

The paths are simply discarded if the current project's directory name is not found in the path.

Currently the so called "Tree" will be actually just a List or a single path tree. For the first iteration of this project, I won't tackle the advanced macro usage that might direct the flow based on defines (this will be optional if there will be time in GSoC, or if not, after GSoC, since I plan to remain active developer to maintain the plugin/enhance it furthermore). So, for example (taken from LoW):

#ifdef CAMPAIGN_LOW

{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#endif

#ifdef MULTIPLAYER

#define EASY
#enddef
{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#undef EASY
...
#endif

With current way to do this we will just take "blindly" all included directories/files without taking in consideration the #define flow control.

If we are at LoW, the following tree(list) will be created on its project:

_main.cfg -> utils/*.cfg -> scenarios/*.cfg -> units/*.cfg

Each file in the dependency tree, will have associated a number. For more details on why this and how it's done, read the Scoping section.

===Scoping===
In order for the plugin to know more about the semnatics, it should have the posibility to represent scopes. The scopes will be used mainly for variables and macros.

The Scoping is a delicate problem, because there are some tricky situations that might interfere with the scoping. I choosed to represent scoping in the following way:

Scoping is everything just about order relations. That is, we will compare numbers when dealing with scoping. With that we move the "problem" upper, to the "Dependency tree". We won't use filenames/paths because:

* The filename might change, but the order index may not. So, not having to update the index helps us.
* Number comparison is faster than string comparison.

So, from now on we'll talk in terms of indexes instead of filenames for scoping.

So, we are working with numbers. But there is still a lil' problem. What happens, when we remove/need to add a new file in the current tree, in the middle of existing 2? We would need to update all subsequent files's indexes. That would not be so ok performance wise.

To counter this problem we will not use consecutive numbers, but rather have a certain step between numbers. The step might be configured inside the plugin based on real statistics (for example, trying to see the number of cfg files per project. Taking a big number, like 1000 won't really hurt). For example, we could take the step 50. That means we would have the following tree for LoW:

0 50 100
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

instead of:
0 1 2
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

So, when it's the case of insertion, we insert the new node at the ''middle'' of the current "distance". That way we may insert/delete files *without* breaking the order, and our scoping will still work.

There is another problem it rised in my head: how do we know when to put the number as the next step (the previous number + step) or add it in the middle? Well, since every project will surely do a '''Full Build''', we'll use that oportunity to create the initial tree. Afterwards we will just insert files based on the halving of the distance between 2 indices.

The scoping will be represented by a simple structure, consisting of start index and offset and end index and offset.

===Content Assist Config(CAC) Files===
The CAC files will provide values that are default/available to config files from the wesnoth engine itself. There will be several files that define the values based on their context. This will allow a very great flexibility editing the CA list.

A CAC file will be just a simple text file, that has on each line one (or more) value(s) depending on the context.

* The ''cac/variables.txt'' will contain variables available. The list is currently available at [http://wiki.wesnoth.org/VariablesWML#Automatically_stored_variables]. For example the file could look like:
$side_number
$turn_number
...

* The ''cac/events.txt'' will contain the game events. The list is availabe at: [http://wiki.wesnoth.org/EventWML#Predefined_.27name.27_Key_Values]. Since the events that have spaces in their names can replace that with an underscore '_', the file will contain the underscore instead space variants also.



===Variables===
The variables are either defined by user or defined by default by the wesnoth engine. User's variables will be parsed from each processed file by the WesnothProjectBuilder, using the WMLSaxHandler. The default variables will be parsed and added from the CAC file. (cac/variables.txt)

Variables definitions can be triggered using the VARIABLE macro:
{VARIABLE var_name "value"}
or the [set_variable] tag:
[set_variable]
name=my_var
value="value"
[/set_variable]

The ''ConfigFile'' class in the ''org.wesnoth.wml.core'' already has a list of variables. The ''Variable'' class has some fields that allow its identification. We will build that list when we parse each file, adding each variable found by the previous defined triggers.
When the content assist finds the '$' character, it will supply the user + default variables gathered so far.

Since the variables can be cleared, thus they have scope, the ''Variable'' class needs to be refactorted, so it can represent the scope aswell. The scoping was settled before.

===Name Collisions===
I've considered that we should store the variables per project, like we currently do with macros. This will minimize the memory we need, rather than storing variables on each file - like we do currently. With this, I've discovered it's innevitable to have ''collisions''. That is, have the same variable name on multiple files.

To solve this problem, each variable/macro structure, will not have just a single scope, but rather a list of scopes.

===Events===
Besides the default event names, supplied by the wesnoth engine, there can be created custom ones, wich will be triggered with [fire_event]. As usual the default events names will be available in the cac/events.txt file.

The events defined by the user will be parsed from the ''name'' attribute of the [event] tag.

===Attributes===
All attributes are currently got from the schema.cfg

===Attributes Values===
All attributes values should be parsed based on the schema.cfg.

===Macros===
The support for macros is already built in, but it needs a way to let them have scope. That is, when an #undef is found, the certain macro would not be available to subsequent files unless redeclared. This will be done with the aid of the dependency tree and scoping. The collisions will be solved like I said at the variables section

===Support for custom luaWML tags===
The lua can create new WML Tags. It would be nice that the plugin suggest those aswell besides the ''schema.cfg''. The lua will be easily parsed, since there is a simple pattern for creating new tags:
wesnoth.wml_actions.<tag name>(cfg)

The parser will just run over the lua code/file, over each line, trying to match the 'function *wesnoth.wml_actions.*' pattern. If it finds something, it will add the tag name to the list of tags. There is also a small thing we might have missed. The user could use a shorthand notation for the actions namespace, so when searching for the pattern, I will add to the 'pattern to match' list, the respective variable when searching for new WML Tags.

Thus, like the ''wml-tags.lua'' from the data/lua uses:
local wml_actions = wesnoth.wml_actions

the 'to match' list will contain: 'function *wesnoth.wml_actions.*' and 'function *wml_actions.*', thus finding other tags too.

Going further more, for an ''optional'' enhancement, I could also search that function to see if it needs/has some extra attributes. The attributes can be found by:
* function's parameter (usually cfg) is asked for a property. For example:
function wml_actions.terrain(cfg)
local terrain = cfg.terrain or helper.wml_error("[terrain] missing required terrain= attribute")
cfg = helper.shallow_literal(cfg)
cfg.terrain = nil
for i, loc in ipairs(wesnoth.get_locations(cfg)) do
wesnoth.set_terrain(loc[1], loc[2], terrain, cfg.layer, cfg.replace_if_failed)
end
end

Here we need the attributes ''terrain'', ''layer'' and ''replace_if_failed''.

* ''get_child'' call:
function wml_actions.message(cfg)
local show_if = helper.get_child(cfg, "show_if")
if not show_if or wesnoth.eval_conditional(show_if) then
engine_message(cfg)
end
end

Here we need to have the attribute ''show_if''.

==Automatic/headless building==
The eclipse plugins can be automatically built from command line, provided there is the eclipse sdk and the eclipse delta pack on the builder's machine. The plugin can also use Buckminster tool to automate the building of the plugin.

''Notes''
Add all plugin's files *inside* a folder to prevent cluttering the directory where it's extracted

More info at:
* http://wiki.eclipse.org/PDE/Build
* http://wiki.bioclipse.net/index.php?title=How_to_build_plugins_headless
* http://help.eclipse.org/galileo/index.jsp?topic=/org.eclipse.pde.doc.user/guide/intro/pde_overview.htm
* http://www.eclipse.org/articles/Article-PDE-Automation/automation.html

==Standalone app auto-update==
The current standalone application doesn't offer the same eclipse's update system. I will add it, so anytime there is a new version of the plugin, it can be updated with a single click by the user, without the needing to download a new standalone app again.

==Documentation==
===External documentation===
The current existing readme will be split in 2 manuals: User Manual and Developer Manual (Don't forget to add images where relevant).

The user manual will contain:
* Prerequisites and Installing the prerequisites
Note: don't forget to mention the MINIMUM eclipse/java version needed to run
* Installing the plugin / standalone version
* Using the plugin
* Plugin features
* Step-by-step use cases
** Setupping the workspace
** Creating a new project and running it in the game
** Importing existing projects
** Using the WML Editor
** Updating the plugin
* Frequently Asked Questions

The developer manual will contain:
* Prerequisites and Installing the prerequisites
* Adding the plugin's projects in the
* Compiling and Running the plugin
* Deploying the plugin and standalone app

===Internal documentation===
The Eclipse infrastructure has features for letting the developer embed help into the application, depending on the current context. After I will write the external documentation, I will work on adding internal documentation aswell. Some of it already comes from the external one.

* Plugin welcome page
* Eclipse Help (When pressing Help->Help contents)
* Wizards help

==Plugin polishing==
This are some tasks needed to be done in order to get the plugin more stable and more usable than it's currently. Some of the tasks are taken from my todo list. New tasks will be added through the project advancing when improvements to actual code /user interaction can be done, so this list is not final.

# Don't copy a project that belongs to data/campaigns to the user addons's directory. This can be done by looking at the path when creating a new project. (This is prevented by not spawning a ''build.xml'' file in the campaigns's directory)
# Enhance the logging so it can help debugging other's problem much easier. I could split the current log in 2:
## Commands executed by the plugin
## Other information like parsed information/statuses
# Enhance the integration with the eclipse platform by adding the "Wesnoth" related wizards directly to the "New" menu.
# Allow users to import a directory as a wesnoth project. Under the hood it will either open the wesnoth project (if there is any .project files in it) or create a new empty project on it.
# Allow the user to clear it's current plugin's settings just with a simple button.
# Wesnoth Project Explorer - Add error markers just like the Java Explorer has
# Refactor the current way of getting the macro list. Currently if there is no _main.cfg practically the _MACROS_.cfg file is not built resulting in no MACRO suggestions.
# Create a view filter to hide the Project ''_AutoLinked_CFGExternalFiles_'' which is created for opening the external config files (external meaning outside the current workspace).
# Fix the F3 navigation when the map's location is specified withing " ", as a string.

===New parsing method (optional)===
The current parsing method involves a lot of Wesnoth preprocessor/wmlparser.py. This is doing somehow the parsing job double. This is because the xtext framework already does 1 pass over the files when added to the project. My plan is to see if I can reuse the already built AST(Abstract Syntax Tree) and the parse tree, to use those values instead of additional preprocessing/wmlparsing, and use the latter only when really needed.

Using the xtext's model will greatly fasten the "build" time of each project and it will be *much* simpler to work with, since the framework already provides exceptions recovering (that is, when the code is not well formed according to the grammar) and based on the defined grammar the respective tokens. So, for example instead using 2 another external processes, we could just iterate over each WMLTag and get it's WMLKeys and parse their individual values.

If this idea works, I will add it on the Plugin polishing tasks.

==Other ideas==
===Addons management===
There will be a new Addons management view. It will behave much like the in-game addon manager, but it will be more handy since the user doesn't need to start the game for that (and also wait till the cache refreshes after downloading it). This view will be based on the python script from '''data/tools/wesnoth_addon_manager''', like it does currently for uploading the project as an addon.

The view will let the user see the list/details for each of the addons currently on the server. There will be also a filter based on what addon server to use (trunk/1.8/1.9/etc)

The user will be able to just right click on an addon and download it to it's user data folder. Optionally a new project will be created, based on the just downloaded addon.



===Unit testing===
====Grammar====
For a better wml handling with in the editor, I will create a Testing class for the current grammar. The class will do testing on all *.cfgs in the data directory. That way after modifing something in the grammar we will be able to see how many errors we have introduced/eliminated. This will greatly help the developing of a better grammar that can hold all current WML formats.

''Notes'':
optionally rework the grammar and try to use a custom lexer/parser in order to benefit from the preprocessor, injecting the valid tokens. This would help the cases when the current grammar doesn't work:
{name} = value
or unclosed tags

====Parsing and getting information from files====
I will create some basic (or taken from existing campaigns) config files that will be parsed in order to check if the correct behaviour - correct information is extracted from the files.

This will check for extracting the:
scenario name
campaign name
next_scenario
first_scenario
variables
macros

=Timeline=
The GSOC period is between 24th May and 20th August. But since I have exams for 3 weeks (during 30.05-19.06.2011), I will start working on the plugin before the 24th of May, to recover some of the lost time. Also, my ImagineCup team made it to the national phase - that is in 5,6,7 May. That means till that time I will not be able to do so much work, so I'll make the timeline according with the starting of work on 9 May.

Here is a table with key periods of the time spent on this project.
{| border="1"
|'''Period''' || '''Actions'''
|-
| 26 April || Get accepted
|-
| 26 April - 8 May || Busy working on ImagineCup project for the national phase. Little or no work done.
|-
| 9 May - 15 May || Allow headless build of the plugin
|-
| 16 May - 22 May || Add Support for multiple installations
|-
| 23 May - 28 May || Add the auto-update feature for the standalone app
|-
| 30 May - 19 June || Exams
|-
| 20 June - 24 June || Create the external documentation
|-
| 25 June - 16 July || Enhance Content Assist
|-
| 15 July || Mid-term evaluations deadline
|-
| 17 July - 24 July || Addons management view
|-
| 25 July - 30 July || Unit tests
|-
| 1 August - 14 August || Do the Plugin polishing tasks
|-
| 15 August || Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc.
|-
| 15 August - 17 August || Create the internal documentation.
|-
| 18 August - 22 August || Buffer half-week. This will be used in case some tasks fell a bit outside their proposed time.
|-
| 22 August || Firm 'pencils down' date. Mentors, students and organization administrators can begin submitting final evaluations to Google.
|}

=Tasks=
This is a list of the "atomic" tasks that need to be done, based on the project part. Since the big tasks are split into smaller task, the progress will be seen better and any problems that arise with the timeline will be seen faster. I will update this table based on my current progress.

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Headless build ||Research about what system to use for automatic building of the plugin || Done
|-
| Headless build || Implement the chosen system for the wesnoth plugin|| Done
|-
| Multiple installations || Implement the preferences pages || Done
|-
| Multiple installations || Implement the logic for saving and loading the installation's paths on the disk || Done
|-
| Multiple installations || Implement the project preferences page || Done
|-
| Multiple installations || Rewrite the current mechanisms that use the paths to use the ones based on the project. || Done
|-
| Auto-update || Implement the auto-update feature. || In progress
|-
| Documentation || Write the User Manual || Done
|-
| Documentation || Write the Developer Manual || Done
|-
| Documentation || Write the internal documentation || Done
|-
| Enhance Content Assist || Project dependency tree || In progress
|-
| Enhance Content Assist || Content assist files || None
|-
| Enhance Content Assist || Variables || None
|-
| Enhance Content Assist || Events || None
|-
| Enhance Content Assist || Lua tags || None
|-
| Addon management || Create the GUI of the view || Done
|-
| Addon management || Create the view's logic || Done
|-
| Unit testing || Tests for the grammar || None
|-
| Unit testing || Tests for parsing the config files || None
|-
| Plugin Polishing || Task 1 || None
|-
| Plugin Polishing || Task 2 || None
|-
| Plugin Polishing || Task 3 || None
|-
| Plugin Polishing || Task 4 || None
|-
| Plugin Polishing || Task 5 || None
|-
| Plugin Polishing || Task 6 || None
|-
| Plugin Polishing || Task 7|| None
|-
| Plugin Polishing || Task 8 || None
|-
| Plugin Polishing || Task 9 || None
|}

Optional tasks will be dealt with if the time allows it:

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Enhance Content Assist || Project dependency tree with multiple paths based on defines || None
|-
| Enhance Content Assist || Lua tags attributes || None
|-
| Grammar || Enhance the grammar to support the 2 current unsupported syntax constructs || None
|-
| Documentation || Implement a simple WML project from start to end using Help's built-in cheat sheets tutorial || None
|}

=Questionnaire=
The questionnaire can be found here: http://wiki.wesnoth.org/User:Timotei21/Questionaire

SummerofCode2011 Timotei21

2011-07-08T20:40:49Z

Timotei21: /* Plugin polishing */

{{SoC2011Student_2|timotei|SoC_Ideas_Eclipse_Plugin2011}}

=Description=
<h4>timotei - Improving the Eclipse Plugin</h4>
I aim at improving the plugin, so it will become the tool used by all UMC Authors. That is, UMC Authors will get rid of the lot of different tools they use for different tasks (for example the Emacs WMLMode/other plugins for different text editors), and instead use one single unified Tool that will speed up the development. My target is to make this plugin a complete and very stable suite for all umc tasks that don't need specialized software - like a graphics editor, so I'd like to have this oportunity to finish it in the good sense.

=Contacts=
==IRC==
timotei

==Other==
Forum: timotei 
gna.org: timotei

=SoC Application=
[http://www.google-melange.com/gsoc/proposal/review/google/gsoc2011/timoteidolean/1 Battle for Wesnoth - Google Summer of Code Application]

=Proposal Summary=
Page Last Updated: {{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}} 

In the following lines I will give details on how I'm planning to implement some of the required tasks, and also add some new ones.

The ''Notes'' sections are aimed for personal guideliness. They are took from my todo list.

==Multiple Wesnoth installations==
Having multiple wesnoth setups, and working with them at the same time would be nice to be done from inside the plugin.
For that, there will be a new preferences page. The page will look something like this:
http://dl.dropbox.com/u/462510/personal/soc/installations_management.PNG

There will be buttons that add/remove/edit a certain wesnoth installation. When adding/editing an installation, a new page like the current one (in which we set the paths), will be shown. The user will be able to name it and specify the version (I could automatically get the version by invoking ''wesnoth --version'').
The current page for setting the paths will act as a default installation.

After we have configured the paths, the user can chose the installation to which the (new) projects are bound, by opening the project properties. There will be a wesnoth-related page, where the user will be able to chose to what installation the project binds. With that, every command that uses the paths, won't use the single current paths, but the ones assigned to each project. This project properties page will open new ways for adding new

There would be a problem in case the project will be migrated between 2 different plugin's versions. For example, in one place we would have defined "1.9.4svn" but on the other there would be "trunk".

We can solve this in 3 ways:

# Alert the user that the installation doesn't bind, and let him chose the current matching installation for his plugin.
# Default automatically to the current plugin's default installation.
# "Hardcode" the version, so that there may be defined just installations like: 1.8.0, 1.9.3. With this we lose some flexibility, but we could use this as base version for new installations, so for example, a user can have two 1.9.3 installations. Provided this, we have again a possible problem, which can be solved again by 1. or 2., but this time, trying to match the base version first.

With this feature, the user won't need to restart the plugin at all, switching workspaces.

Regarding the technical PoV, all paths will be stored using eclipse's preferences system, by appending an unique id of each installation to each path in that set.

''Note'':
Add the NO_TERRAIN_GFX preprocess option checkbox to the project properties rather than being a global one.

==Enhance the Content Assist(CA) feature==
The CA framework is very extensible but it lacks proper contexts for providing the content.
I was thinking of trying to accomplish the generating of CA list either by using a config file, in case something like that can be used or writing directly the code that does that.

Another factor that is involved in a better auto-complete, is the ''schema.cfg'' the plugin bases on. Depending on whether the schema is worked on during this summer of code, I'll need to redo a bit the parser of the schema, in case the format/semantics change.

===Project files dependecy tree===
In order for the CA to work better - and maybe other areas would benefit from this - we will need to build a project files tree. With that tree, we can see how a certain declared macro/variable will affect subsequent related files and also their scope. Basically, we can see the relation from a file to anothers.

This tree will be (re)built in 2 situations:
# A file is added/removed/changed it's name
# A full rebuild is triggered (for example, the project is added for the first time in the workspace)

The tree will be built by the WML parser's rules:
# files are processed in the alphabetically order
# _initial.cfg is the first processed before anything else.
# _final.cfg is the last processed after anything else.
# if there is a _main.cfg in the directory, it is the only one processed.

Since the current ''WesnothProjectBuilder'' doesn't take in account the previous rules, I will create my own method of visiting each folder's children in the correct order. This method will look close to wesnoth's one, namely ''get_files_from_in_dir()'' found in ''src/filesystem.cpp:93''.

For a very fast lookup, as a data structure we will use a Hashtable, which has as the key the local project path to the file, and as a value a custom structure, which has the previous/next/parent/son properties, used to traverse the tree. The previous/next go on the same tree level, while the parent/son go up/down in the tree. I will use this instead of a tree, because this will give us access to info about a file, faster, in O(1) compared to a breadth-first search which has O(V+E) - where V is number of vertices and E number of edges.

Talking with Crab about this, he alerted me about a little possible problem with current aproach:
<Crab_> a note about 'The tree will be built by the WML parser's rules: ' - don't forget that you can (conditionally) include files/dirs from a file.
<Crab_> so, if we have 'ai/ais/zzz' which, say, defines a macro, it might get included by campaigns/bbb/scenarios/some_scenario.cfg , even if it is not inside /campaigns/bbb/scenarios

For that we have 2 cases:
{~file/dir path}
or
{file/dir path}

The paths are simply discarded if the current project's directory name is not found in the path.

Currently the so called "Tree" will be actually just a List or a single path tree. For the first iteration of this project, I won't tackle the advanced macro usage that might direct the flow based on defines (this will be optional if there will be time in GSoC, or if not, after GSoC, since I plan to remain active developer to maintain the plugin/enhance it furthermore). So, for example (taken from LoW):

#ifdef CAMPAIGN_LOW

{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#endif

#ifdef MULTIPLAYER

#define EASY
#enddef
{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#undef EASY
...
#endif

With current way to do this we will just take "blindly" all included directories/files without taking in consideration the #define flow control.

If we are at LoW, the following tree(list) will be created on its project:

_main.cfg -> utils/*.cfg -> scenarios/*.cfg -> units/*.cfg

Each file in the dependency tree, will have associated a number. For more details on why this and how it's done, read the Scoping section.

===Scoping===
In order for the plugin to know more about the semnatics, it should have the posibility to represent scopes. The scopes will be used mainly for variables and macros.

The Scoping is a delicate problem, because there are some tricky situations that might interfere with the scoping. I choosed to represent scoping in the following way:

Scoping is everything just about order relations. That is, we will compare numbers when dealing with scoping. With that we move the "problem" upper, to the "Dependency tree". We won't use filenames/paths because:

* The filename might change, but the order index may not. So, not having to update the index helps us.
* Number comparison is faster than string comparison.

So, from now on we'll talk in terms of indexes instead of filenames for scoping.

So, we are working with numbers. But there is still a lil' problem. What happens, when we remove/need to add a new file in the current tree, in the middle of existing 2? We would need to update all subsequent files's indexes. That would not be so ok performance wise.

To counter this problem we will not use consecutive numbers, but rather have a certain step between numbers. The step might be configured inside the plugin based on real statistics (for example, trying to see the number of cfg files per project. Taking a big number, like 1000 won't really hurt). For example, we could take the step 50. That means we would have the following tree for LoW:

0 50 100
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

instead of:
0 1 2
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

So, when it's the case of insertion, we insert the new node at the ''middle'' of the current "distance". That way we may insert/delete files *without* breaking the order, and our scoping will still work.

There is another problem it rised in my head: how do we know when to put the number as the next step (the previous number + step) or add it in the middle? Well, since every project will surely do a '''Full Build''', we'll use that oportunity to create the initial tree. Afterwards we will just insert files based on the halving of the distance between 2 indices.

The scoping will be represented by a simple structure, consisting of start index and offset and end index and offset.

===Content Assist Config(CAC) Files===
The CAC files will provide values that are default/available to config files from the wesnoth engine itself. There will be several files that define the values based on their context. This will allow a very great flexibility editing the CA list.

A CAC file will be just a simple text file, that has on each line one (or more) value(s) depending on the context.

* The ''cac/variables.txt'' will contain variables available. The list is currently available at [http://wiki.wesnoth.org/VariablesWML#Automatically_stored_variables]. For example the file could look like:
$side_number
$turn_number
...

* The ''cac/events.txt'' will contain the game events. The list is availabe at: [http://wiki.wesnoth.org/EventWML#Predefined_.27name.27_Key_Values]. Since the events that have spaces in their names can replace that with an underscore '_', the file will contain the underscore instead space variants also.



===Variables===
The variables are either defined by user or defined by default by the wesnoth engine. User's variables will be parsed from each processed file by the WesnothProjectBuilder, using the WMLSaxHandler. The default variables will be parsed and added from the CAC file. (cac/variables.txt)

Variables definitions can be triggered using the VARIABLE macro:
{VARIABLE var_name "value"}
or the [set_variable] tag:
[set_variable]
name=my_var
value="value"
[/set_variable]

The ''ConfigFile'' class in the ''org.wesnoth.wml.core'' already has a list of variables. The ''Variable'' class has some fields that allow its identification. We will build that list when we parse each file, adding each variable found by the previous defined triggers.
When the content assist finds the '$' character, it will supply the user + default variables gathered so far.

Since the variables can be cleared, thus they have scope, the ''Variable'' class needs to be refactorted, so it can represent the scope aswell. The scoping was settled before.

===Name Collisions===
I've considered that we should store the variables per project, like we currently do with macros. This will minimize the memory we need, rather than storing variables on each file - like we do currently. With this, I've discovered it's innevitable to have ''collisions''. That is, have the same variable name on multiple files.

To solve this problem, each variable/macro structure, will not have just a single scope, but rather a list of scopes.

===Events===
Besides the default event names, supplied by the wesnoth engine, there can be created custom ones, wich will be triggered with [fire_event]. As usual the default events names will be available in the cac/events.txt file.

The events defined by the user will be parsed from the ''name'' attribute of the [event] tag.

===Attributes===
All attributes are currently got from the schema.cfg

===Attributes Values===
All attributes values should be parsed based on the schema.cfg.

===Macros===
The support for macros is already built in, but it needs a way to let them have scope. That is, when an #undef is found, the certain macro would not be available to subsequent files unless redeclared. This will be done with the aid of the dependency tree and scoping. The collisions will be solved like I said at the variables section

===Support for custom luaWML tags===
The lua can create new WML Tags. It would be nice that the plugin suggest those aswell besides the ''schema.cfg''. The lua will be easily parsed, since there is a simple pattern for creating new tags:
wesnoth.wml_actions.<tag name>(cfg)

The parser will just run over the lua code/file, over each line, trying to match the 'function *wesnoth.wml_actions.*' pattern. If it finds something, it will add the tag name to the list of tags. There is also a small thing we might have missed. The user could use a shorthand notation for the actions namespace, so when searching for the pattern, I will add to the 'pattern to match' list, the respective variable when searching for new WML Tags.

Thus, like the ''wml-tags.lua'' from the data/lua uses:
local wml_actions = wesnoth.wml_actions

the 'to match' list will contain: 'function *wesnoth.wml_actions.*' and 'function *wml_actions.*', thus finding other tags too.

Going further more, for an ''optional'' enhancement, I could also search that function to see if it needs/has some extra attributes. The attributes can be found by:
* function's parameter (usually cfg) is asked for a property. For example:
function wml_actions.terrain(cfg)
local terrain = cfg.terrain or helper.wml_error("[terrain] missing required terrain= attribute")
cfg = helper.shallow_literal(cfg)
cfg.terrain = nil
for i, loc in ipairs(wesnoth.get_locations(cfg)) do
wesnoth.set_terrain(loc[1], loc[2], terrain, cfg.layer, cfg.replace_if_failed)
end
end

Here we need the attributes ''terrain'', ''layer'' and ''replace_if_failed''.

* ''get_child'' call:
function wml_actions.message(cfg)
local show_if = helper.get_child(cfg, "show_if")
if not show_if or wesnoth.eval_conditional(show_if) then
engine_message(cfg)
end
end

Here we need to have the attribute ''show_if''.

==Automatic/headless building==
The eclipse plugins can be automatically built from command line, provided there is the eclipse sdk and the eclipse delta pack on the builder's machine. The plugin can also use Buckminster tool to automate the building of the plugin.

''Notes''
Add all plugin's files *inside* a folder to prevent cluttering the directory where it's extracted

More info at:
* http://wiki.eclipse.org/PDE/Build
* http://wiki.bioclipse.net/index.php?title=How_to_build_plugins_headless
* http://help.eclipse.org/galileo/index.jsp?topic=/org.eclipse.pde.doc.user/guide/intro/pde_overview.htm
* http://www.eclipse.org/articles/Article-PDE-Automation/automation.html

==Standalone app auto-update==
The current standalone application doesn't offer the same eclipse's update system. I will add it, so anytime there is a new version of the plugin, it can be updated with a single click by the user, without the needing to download a new standalone app again.

==Documentation==
===External documentation===
The current existing readme will be split in 2 manuals: User Manual and Developer Manual (Don't forget to add images where relevant).

The user manual will contain:
* Prerequisites and Installing the prerequisites
Note: don't forget to mention the MINIMUM eclipse/java version needed to run
* Installing the plugin / standalone version
* Using the plugin
* Plugin features
* Step-by-step use cases
** Setupping the workspace
** Creating a new project and running it in the game
** Importing existing projects
** Using the WML Editor
** Updating the plugin
* Frequently Asked Questions

The developer manual will contain:
* Prerequisites and Installing the prerequisites
* Adding the plugin's projects in the
* Compiling and Running the plugin
* Deploying the plugin and standalone app

===Internal documentation===
The Eclipse infrastructure has features for letting the developer embed help into the application, depending on the current context. After I will write the external documentation, I will work on adding internal documentation aswell. Some of it already comes from the external one.

* Plugin welcome page
* Eclipse Help (When pressing Help->Help contents)
* Wizards help

==Plugin polishing==
This are some tasks needed to be done in order to get the plugin more stable and more usable than it's currently. Some of the tasks are taken from my todo list. New tasks will be added through the project advancing when improvements to actual code /user interaction can be done, so this list is not final.

# Don't copy a project that belongs to data/campaigns to the user addons's directory. This can be done by looking at the path when creating a new project. (This is prevented by not spawning a ''build.xml'' file in the campaigns's directory)
# Enhance the logging so it can help debugging other's problem much easier. I could split the current log in 2:
## Commands executed by the plugin
## Other information like parsed information/statuses
# Enhance the integration with the eclipse platform by adding the "Wesnoth" related wizards directly to the "New" menu.
# Allow users to import a directory as a wesnoth project. Under the hood it will either open the wesnoth project (if there is any .project files in it) or create a new empty project on it.
# Allow the user to clear it's current plugin's settings just with a simple button.
# Wesnoth Project Explorer - Add error markers just like the Java Explorer has
# Refactor the current way of getting the macro list. Currently if there is no _main.cfg practically the _MACROS_.cfg file is not built resulting in no MACRO suggestions.
# Create a view filter to hide the Project ''_AutoLinked_CFGExternalFiles_'' which is created for opening the external config files (external meaning outside the current workspace).
# Fix the F3 navigation when the map's location is specified withing " ", as a string.

===New parsing method (optional)===
The current parsing method involves a lot of Wesnoth preprocessor/wmlparser.py. This is doing somehow the parsing job double. This is because the xtext framework already does 1 pass over the files when added to the project. My plan is to see if I can reuse the already built AST(Abstract Syntax Tree) and the parse tree, to use those values instead of additional preprocessing/wmlparsing, and use the latter only when really needed.

Using the xtext's model will greatly fasten the "build" time of each project and it will be *much* simpler to work with, since the framework already provides exceptions recovering (that is, when the code is not well formed according to the grammar) and based on the defined grammar the respective tokens. So, for example instead using 2 another external processes, we could just iterate over each WMLTag and get it's WMLKeys and parse their individual values.

If this idea works, I will add it on the Plugin polishing tasks.

==Other ideas==
===Addons management===
There will be a new Addons management view. It will behave much like the in-game addon manager, but it will be more handy since the user doesn't need to start the game for that (and also wait till the cache refreshes after downloading it). This view will be based on the python script from '''data/tools/wesnoth_addon_manager''', like it does currently for uploading the project as an addon.

The view will let the user see the list/details for each of the addons currently on the server. There will be also a filter based on what addon server to use (trunk/1.8/1.9/etc)

The user will be able to just right click on an addon and download it to it's user data folder. Optionally a new project will be created, based on the just downloaded addon.



===Unit testing===
====Grammar====
For a better wml handling with in the editor, I will create a Testing class for the current grammar. The class will do testing on all *.cfgs in the data directory. That way after modifing something in the grammar we will be able to see how many errors we have introduced/eliminated. This will greatly help the developing of a better grammar that can hold all current WML formats.

''Notes'':
optionally rework the grammar and try to use a custom lexer/parser in order to benefit from the preprocessor, injecting the valid tokens. This would help the cases when the current grammar doesn't work:
{name} = value
or unclosed tags

====Parsing and getting information from files====
I will create some basic (or taken from existing campaigns) config files that will be parsed in order to check if the correct behaviour - correct information is extracted from the files.

This will check for extracting the:
scenario name
campaign name
next_scenario
first_scenario
variables
macros

=Timeline=
The GSOC period is between 24th May and 20th August. But since I have exams for 3 weeks (during 30.05-19.06.2011), I will start working on the plugin before the 24th of May, to recover some of the lost time. Also, my ImagineCup team made it to the national phase - that is in 5,6,7 May. That means till that time I will not be able to do so much work, so I'll make the timeline according with the starting of work on 9 May.

Here is a table with key periods of the time spent on this project.
{| border="1"
|'''Period''' || '''Actions'''
|-
| 26 April || Get accepted
|-
| 26 April - 8 May || Busy working on ImagineCup project for the national phase. Little or no work done.
|-
| 9 May - 15 May || Allow headless build of the plugin
|-
| 16 May - 22 May || Add Support for multiple installations
|-
| 23 May - 28 May || Add the auto-update feature for the standalone app
|-
| 30 May - 19 June || Exams
|-
| 20 June - 24 June || Create the external documentation
|-
| 25 June - 16 July || Enhance Content Assist
|-
| 15 July || Mid-term evaluations deadline
|-
| 17 July - 24 July || Addons management view
|-
| 25 July - 30 July || Unit tests
|-
| 1 August - 14 August || Do the Plugin polishing tasks
|-
| 15 August || Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc.
|-
| 15 August - 17 August || Create the internal documentation.
|-
| 18 August - 22 August || Buffer half-week. This will be used in case some tasks fell a bit outside their proposed time.
|-
| 22 August || Firm 'pencils down' date. Mentors, students and organization administrators can begin submitting final evaluations to Google.
|}

=Tasks=
This is a list of the "atomic" tasks that need to be done, based on the project part. Since the big tasks are split into smaller task, the progress will be seen better and any problems that arise with the timeline will be seen faster. I will update this table based on my current progress.

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Headless build ||Research about what system to use for automatic building of the plugin || Done
|-
| Headless build || Implement the chosen system for the wesnoth plugin|| Done
|-
| Multiple installations || Implement the preferences pages || Done
|-
| Multiple installations || Implement the logic for saving and loading the installation's paths on the disk || Done
|-
| Multiple installations || Implement the project preferences page || Done
|-
| Multiple installations || Rewrite the current mechanisms that use the paths to use the ones based on the project. || Done
|-
| Auto-update || Implement the auto-update feature. || In progress
|-
| Documentation || Write the User Manual || Done
|-
| Documentation || Write the Developer Manual || Done
|-
| Documentation || Write the internal documentation || Done
|-
| Enhance Content Assist || Project dependency tree || In progress
|-
| Enhance Content Assist || Content assist files || None
|-
| Enhance Content Assist || Variables || None
|-
| Enhance Content Assist || Events || None
|-
| Enhance Content Assist || Lua tags || None
|-
| Addon management || Create the GUI of the view || Done
|-
| Addon management || Create the view's logic || In progress
|-
| Unit testing || Tests for the grammar || None
|-
| Unit testing || Tests for parsing the config files || None
|}

Optional tasks will be dealt with if the time allows it:

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Enhance Content Assist || Project dependency tree with multiple paths based on defines || None
|-
| Enhance Content Assist || Lua tags attributes || None
|-
| Grammar || Enhance the grammar to support the 2 current unsupported syntax constructs || None
|-
| Documentation || Implement a simple WML project from start to end using Help's built-in cheat sheets tutorial || None
|}

=Questionnaire=
The questionnaire can be found here: http://wiki.wesnoth.org/User:Timotei21/Questionaire

SummerofCode2011 Timotei21

2011-07-08T20:40:30Z

Timotei21: /* Plugin polishing */

{{SoC2011Student_2|timotei|SoC_Ideas_Eclipse_Plugin2011}}

=Description=
<h4>timotei - Improving the Eclipse Plugin</h4>
I aim at improving the plugin, so it will become the tool used by all UMC Authors. That is, UMC Authors will get rid of the lot of different tools they use for different tasks (for example the Emacs WMLMode/other plugins for different text editors), and instead use one single unified Tool that will speed up the development. My target is to make this plugin a complete and very stable suite for all umc tasks that don't need specialized software - like a graphics editor, so I'd like to have this oportunity to finish it in the good sense.

=Contacts=
==IRC==
timotei

==Other==
Forum: timotei 
gna.org: timotei

=SoC Application=
[http://www.google-melange.com/gsoc/proposal/review/google/gsoc2011/timoteidolean/1 Battle for Wesnoth - Google Summer of Code Application]

=Proposal Summary=
Page Last Updated: {{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}} 

In the following lines I will give details on how I'm planning to implement some of the required tasks, and also add some new ones.

The ''Notes'' sections are aimed for personal guideliness. They are took from my todo list.

==Multiple Wesnoth installations==
Having multiple wesnoth setups, and working with them at the same time would be nice to be done from inside the plugin.
For that, there will be a new preferences page. The page will look something like this:
http://dl.dropbox.com/u/462510/personal/soc/installations_management.PNG

There will be buttons that add/remove/edit a certain wesnoth installation. When adding/editing an installation, a new page like the current one (in which we set the paths), will be shown. The user will be able to name it and specify the version (I could automatically get the version by invoking ''wesnoth --version'').
The current page for setting the paths will act as a default installation.

After we have configured the paths, the user can chose the installation to which the (new) projects are bound, by opening the project properties. There will be a wesnoth-related page, where the user will be able to chose to what installation the project binds. With that, every command that uses the paths, won't use the single current paths, but the ones assigned to each project. This project properties page will open new ways for adding new

There would be a problem in case the project will be migrated between 2 different plugin's versions. For example, in one place we would have defined "1.9.4svn" but on the other there would be "trunk".

We can solve this in 3 ways:

# Alert the user that the installation doesn't bind, and let him chose the current matching installation for his plugin.
# Default automatically to the current plugin's default installation.
# "Hardcode" the version, so that there may be defined just installations like: 1.8.0, 1.9.3. With this we lose some flexibility, but we could use this as base version for new installations, so for example, a user can have two 1.9.3 installations. Provided this, we have again a possible problem, which can be solved again by 1. or 2., but this time, trying to match the base version first.

With this feature, the user won't need to restart the plugin at all, switching workspaces.

Regarding the technical PoV, all paths will be stored using eclipse's preferences system, by appending an unique id of each installation to each path in that set.

''Note'':
Add the NO_TERRAIN_GFX preprocess option checkbox to the project properties rather than being a global one.

==Enhance the Content Assist(CA) feature==
The CA framework is very extensible but it lacks proper contexts for providing the content.
I was thinking of trying to accomplish the generating of CA list either by using a config file, in case something like that can be used or writing directly the code that does that.

Another factor that is involved in a better auto-complete, is the ''schema.cfg'' the plugin bases on. Depending on whether the schema is worked on during this summer of code, I'll need to redo a bit the parser of the schema, in case the format/semantics change.

===Project files dependecy tree===
In order for the CA to work better - and maybe other areas would benefit from this - we will need to build a project files tree. With that tree, we can see how a certain declared macro/variable will affect subsequent related files and also their scope. Basically, we can see the relation from a file to anothers.

This tree will be (re)built in 2 situations:
# A file is added/removed/changed it's name
# A full rebuild is triggered (for example, the project is added for the first time in the workspace)

The tree will be built by the WML parser's rules:
# files are processed in the alphabetically order
# _initial.cfg is the first processed before anything else.
# _final.cfg is the last processed after anything else.
# if there is a _main.cfg in the directory, it is the only one processed.

Since the current ''WesnothProjectBuilder'' doesn't take in account the previous rules, I will create my own method of visiting each folder's children in the correct order. This method will look close to wesnoth's one, namely ''get_files_from_in_dir()'' found in ''src/filesystem.cpp:93''.

For a very fast lookup, as a data structure we will use a Hashtable, which has as the key the local project path to the file, and as a value a custom structure, which has the previous/next/parent/son properties, used to traverse the tree. The previous/next go on the same tree level, while the parent/son go up/down in the tree. I will use this instead of a tree, because this will give us access to info about a file, faster, in O(1) compared to a breadth-first search which has O(V+E) - where V is number of vertices and E number of edges.

Talking with Crab about this, he alerted me about a little possible problem with current aproach:
<Crab_> a note about 'The tree will be built by the WML parser's rules: ' - don't forget that you can (conditionally) include files/dirs from a file.
<Crab_> so, if we have 'ai/ais/zzz' which, say, defines a macro, it might get included by campaigns/bbb/scenarios/some_scenario.cfg , even if it is not inside /campaigns/bbb/scenarios

For that we have 2 cases:
{~file/dir path}
or
{file/dir path}

The paths are simply discarded if the current project's directory name is not found in the path.

Currently the so called "Tree" will be actually just a List or a single path tree. For the first iteration of this project, I won't tackle the advanced macro usage that might direct the flow based on defines (this will be optional if there will be time in GSoC, or if not, after GSoC, since I plan to remain active developer to maintain the plugin/enhance it furthermore). So, for example (taken from LoW):

#ifdef CAMPAIGN_LOW

{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#endif

#ifdef MULTIPLAYER

#define EASY
#enddef
{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#undef EASY
...
#endif

With current way to do this we will just take "blindly" all included directories/files without taking in consideration the #define flow control.

If we are at LoW, the following tree(list) will be created on its project:

_main.cfg -> utils/*.cfg -> scenarios/*.cfg -> units/*.cfg

Each file in the dependency tree, will have associated a number. For more details on why this and how it's done, read the Scoping section.

===Scoping===
In order for the plugin to know more about the semnatics, it should have the posibility to represent scopes. The scopes will be used mainly for variables and macros.

The Scoping is a delicate problem, because there are some tricky situations that might interfere with the scoping. I choosed to represent scoping in the following way:

Scoping is everything just about order relations. That is, we will compare numbers when dealing with scoping. With that we move the "problem" upper, to the "Dependency tree". We won't use filenames/paths because:

* The filename might change, but the order index may not. So, not having to update the index helps us.
* Number comparison is faster than string comparison.

So, from now on we'll talk in terms of indexes instead of filenames for scoping.

So, we are working with numbers. But there is still a lil' problem. What happens, when we remove/need to add a new file in the current tree, in the middle of existing 2? We would need to update all subsequent files's indexes. That would not be so ok performance wise.

To counter this problem we will not use consecutive numbers, but rather have a certain step between numbers. The step might be configured inside the plugin based on real statistics (for example, trying to see the number of cfg files per project. Taking a big number, like 1000 won't really hurt). For example, we could take the step 50. That means we would have the following tree for LoW:

0 50 100
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

instead of:
0 1 2
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

So, when it's the case of insertion, we insert the new node at the ''middle'' of the current "distance". That way we may insert/delete files *without* breaking the order, and our scoping will still work.

There is another problem it rised in my head: how do we know when to put the number as the next step (the previous number + step) or add it in the middle? Well, since every project will surely do a '''Full Build''', we'll use that oportunity to create the initial tree. Afterwards we will just insert files based on the halving of the distance between 2 indices.

The scoping will be represented by a simple structure, consisting of start index and offset and end index and offset.

===Content Assist Config(CAC) Files===
The CAC files will provide values that are default/available to config files from the wesnoth engine itself. There will be several files that define the values based on their context. This will allow a very great flexibility editing the CA list.

A CAC file will be just a simple text file, that has on each line one (or more) value(s) depending on the context.

* The ''cac/variables.txt'' will contain variables available. The list is currently available at [http://wiki.wesnoth.org/VariablesWML#Automatically_stored_variables]. For example the file could look like:
$side_number
$turn_number
...

* The ''cac/events.txt'' will contain the game events. The list is availabe at: [http://wiki.wesnoth.org/EventWML#Predefined_.27name.27_Key_Values]. Since the events that have spaces in their names can replace that with an underscore '_', the file will contain the underscore instead space variants also.



===Variables===
The variables are either defined by user or defined by default by the wesnoth engine. User's variables will be parsed from each processed file by the WesnothProjectBuilder, using the WMLSaxHandler. The default variables will be parsed and added from the CAC file. (cac/variables.txt)

Variables definitions can be triggered using the VARIABLE macro:
{VARIABLE var_name "value"}
or the [set_variable] tag:
[set_variable]
name=my_var
value="value"
[/set_variable]

The ''ConfigFile'' class in the ''org.wesnoth.wml.core'' already has a list of variables. The ''Variable'' class has some fields that allow its identification. We will build that list when we parse each file, adding each variable found by the previous defined triggers.
When the content assist finds the '$' character, it will supply the user + default variables gathered so far.

Since the variables can be cleared, thus they have scope, the ''Variable'' class needs to be refactorted, so it can represent the scope aswell. The scoping was settled before.

===Name Collisions===
I've considered that we should store the variables per project, like we currently do with macros. This will minimize the memory we need, rather than storing variables on each file - like we do currently. With this, I've discovered it's innevitable to have ''collisions''. That is, have the same variable name on multiple files.

To solve this problem, each variable/macro structure, will not have just a single scope, but rather a list of scopes.

===Events===
Besides the default event names, supplied by the wesnoth engine, there can be created custom ones, wich will be triggered with [fire_event]. As usual the default events names will be available in the cac/events.txt file.

The events defined by the user will be parsed from the ''name'' attribute of the [event] tag.

===Attributes===
All attributes are currently got from the schema.cfg

===Attributes Values===
All attributes values should be parsed based on the schema.cfg.

===Macros===
The support for macros is already built in, but it needs a way to let them have scope. That is, when an #undef is found, the certain macro would not be available to subsequent files unless redeclared. This will be done with the aid of the dependency tree and scoping. The collisions will be solved like I said at the variables section

===Support for custom luaWML tags===
The lua can create new WML Tags. It would be nice that the plugin suggest those aswell besides the ''schema.cfg''. The lua will be easily parsed, since there is a simple pattern for creating new tags:
wesnoth.wml_actions.<tag name>(cfg)

The parser will just run over the lua code/file, over each line, trying to match the 'function *wesnoth.wml_actions.*' pattern. If it finds something, it will add the tag name to the list of tags. There is also a small thing we might have missed. The user could use a shorthand notation for the actions namespace, so when searching for the pattern, I will add to the 'pattern to match' list, the respective variable when searching for new WML Tags.

Thus, like the ''wml-tags.lua'' from the data/lua uses:
local wml_actions = wesnoth.wml_actions

the 'to match' list will contain: 'function *wesnoth.wml_actions.*' and 'function *wml_actions.*', thus finding other tags too.

Going further more, for an ''optional'' enhancement, I could also search that function to see if it needs/has some extra attributes. The attributes can be found by:
* function's parameter (usually cfg) is asked for a property. For example:
function wml_actions.terrain(cfg)
local terrain = cfg.terrain or helper.wml_error("[terrain] missing required terrain= attribute")
cfg = helper.shallow_literal(cfg)
cfg.terrain = nil
for i, loc in ipairs(wesnoth.get_locations(cfg)) do
wesnoth.set_terrain(loc[1], loc[2], terrain, cfg.layer, cfg.replace_if_failed)
end
end

Here we need the attributes ''terrain'', ''layer'' and ''replace_if_failed''.

* ''get_child'' call:
function wml_actions.message(cfg)
local show_if = helper.get_child(cfg, "show_if")
if not show_if or wesnoth.eval_conditional(show_if) then
engine_message(cfg)
end
end

Here we need to have the attribute ''show_if''.

==Automatic/headless building==
The eclipse plugins can be automatically built from command line, provided there is the eclipse sdk and the eclipse delta pack on the builder's machine. The plugin can also use Buckminster tool to automate the building of the plugin.

''Notes''
Add all plugin's files *inside* a folder to prevent cluttering the directory where it's extracted

More info at:
* http://wiki.eclipse.org/PDE/Build
* http://wiki.bioclipse.net/index.php?title=How_to_build_plugins_headless
* http://help.eclipse.org/galileo/index.jsp?topic=/org.eclipse.pde.doc.user/guide/intro/pde_overview.htm
* http://www.eclipse.org/articles/Article-PDE-Automation/automation.html

==Standalone app auto-update==
The current standalone application doesn't offer the same eclipse's update system. I will add it, so anytime there is a new version of the plugin, it can be updated with a single click by the user, without the needing to download a new standalone app again.

==Documentation==
===External documentation===
The current existing readme will be split in 2 manuals: User Manual and Developer Manual (Don't forget to add images where relevant).

The user manual will contain:
* Prerequisites and Installing the prerequisites
Note: don't forget to mention the MINIMUM eclipse/java version needed to run
* Installing the plugin / standalone version
* Using the plugin
* Plugin features
* Step-by-step use cases
** Setupping the workspace
** Creating a new project and running it in the game
** Importing existing projects
** Using the WML Editor
** Updating the plugin
* Frequently Asked Questions

The developer manual will contain:
* Prerequisites and Installing the prerequisites
* Adding the plugin's projects in the
* Compiling and Running the plugin
* Deploying the plugin and standalone app

===Internal documentation===
The Eclipse infrastructure has features for letting the developer embed help into the application, depending on the current context. After I will write the external documentation, I will work on adding internal documentation aswell. Some of it already comes from the external one.

* Plugin welcome page
* Eclipse Help (When pressing Help->Help contents)
* Wizards help

==Plugin polishing==
This are some tasks needed to be done in order to get the plugin more stable and more usable than it's currently. Some of the tasks are taken from my todo list. New tasks will be added through the project advancing when improvements to actual code /user interaction can be done, so this list is not final.

# Don't copy a project that belongs to data/campaigns to the user addons's directory. This can be done by looking at the path when creating a new project. (This is prevented by not spawning a ''build.xml'' file in the campaigns's directory)
# Enhance the logging so it can help debugging other's problem much easier. I could split the current log in 2:
** Commands executed by the plugin
** Other information like parsed information/statuses
# Enhance the integration with the eclipse platform by adding the "Wesnoth" related wizards directly to the "New" menu.
# Allow users to import a directory as a wesnoth project. Under the hood it will either open the wesnoth project (if there is any .project files in it) or create a new empty project on it.
# Allow the user to clear it's current plugin's settings just with a simple button.
# Wesnoth Project Explorer - Add error markers just like the Java Explorer has
# Refactor the current way of getting the macro list. Currently if there is no _main.cfg practically the _MACROS_.cfg file is not built resulting in no MACRO suggestions.
# Create a view filter to hide the Project ''_AutoLinked_CFGExternalFiles_'' which is created for opening the external config files (external meaning outside the current workspace).
# Fix the F3 navigation when the map's location is specified withing " ", as a string.

===New parsing method (optional)===
The current parsing method involves a lot of Wesnoth preprocessor/wmlparser.py. This is doing somehow the parsing job double. This is because the xtext framework already does 1 pass over the files when added to the project. My plan is to see if I can reuse the already built AST(Abstract Syntax Tree) and the parse tree, to use those values instead of additional preprocessing/wmlparsing, and use the latter only when really needed.

Using the xtext's model will greatly fasten the "build" time of each project and it will be *much* simpler to work with, since the framework already provides exceptions recovering (that is, when the code is not well formed according to the grammar) and based on the defined grammar the respective tokens. So, for example instead using 2 another external processes, we could just iterate over each WMLTag and get it's WMLKeys and parse their individual values.

If this idea works, I will add it on the Plugin polishing tasks.

==Other ideas==
===Addons management===
There will be a new Addons management view. It will behave much like the in-game addon manager, but it will be more handy since the user doesn't need to start the game for that (and also wait till the cache refreshes after downloading it). This view will be based on the python script from '''data/tools/wesnoth_addon_manager''', like it does currently for uploading the project as an addon.

The view will let the user see the list/details for each of the addons currently on the server. There will be also a filter based on what addon server to use (trunk/1.8/1.9/etc)

The user will be able to just right click on an addon and download it to it's user data folder. Optionally a new project will be created, based on the just downloaded addon.



===Unit testing===
====Grammar====
For a better wml handling with in the editor, I will create a Testing class for the current grammar. The class will do testing on all *.cfgs in the data directory. That way after modifing something in the grammar we will be able to see how many errors we have introduced/eliminated. This will greatly help the developing of a better grammar that can hold all current WML formats.

''Notes'':
optionally rework the grammar and try to use a custom lexer/parser in order to benefit from the preprocessor, injecting the valid tokens. This would help the cases when the current grammar doesn't work:
{name} = value
or unclosed tags

====Parsing and getting information from files====
I will create some basic (or taken from existing campaigns) config files that will be parsed in order to check if the correct behaviour - correct information is extracted from the files.

This will check for extracting the:
scenario name
campaign name
next_scenario
first_scenario
variables
macros

=Timeline=
The GSOC period is between 24th May and 20th August. But since I have exams for 3 weeks (during 30.05-19.06.2011), I will start working on the plugin before the 24th of May, to recover some of the lost time. Also, my ImagineCup team made it to the national phase - that is in 5,6,7 May. That means till that time I will not be able to do so much work, so I'll make the timeline according with the starting of work on 9 May.

Here is a table with key periods of the time spent on this project.
{| border="1"
|'''Period''' || '''Actions'''
|-
| 26 April || Get accepted
|-
| 26 April - 8 May || Busy working on ImagineCup project for the national phase. Little or no work done.
|-
| 9 May - 15 May || Allow headless build of the plugin
|-
| 16 May - 22 May || Add Support for multiple installations
|-
| 23 May - 28 May || Add the auto-update feature for the standalone app
|-
| 30 May - 19 June || Exams
|-
| 20 June - 24 June || Create the external documentation
|-
| 25 June - 16 July || Enhance Content Assist
|-
| 15 July || Mid-term evaluations deadline
|-
| 17 July - 24 July || Addons management view
|-
| 25 July - 30 July || Unit tests
|-
| 1 August - 14 August || Do the Plugin polishing tasks
|-
| 15 August || Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc.
|-
| 15 August - 17 August || Create the internal documentation.
|-
| 18 August - 22 August || Buffer half-week. This will be used in case some tasks fell a bit outside their proposed time.
|-
| 22 August || Firm 'pencils down' date. Mentors, students and organization administrators can begin submitting final evaluations to Google.
|}

=Tasks=
This is a list of the "atomic" tasks that need to be done, based on the project part. Since the big tasks are split into smaller task, the progress will be seen better and any problems that arise with the timeline will be seen faster. I will update this table based on my current progress.

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Headless build ||Research about what system to use for automatic building of the plugin || Done
|-
| Headless build || Implement the chosen system for the wesnoth plugin|| Done
|-
| Multiple installations || Implement the preferences pages || Done
|-
| Multiple installations || Implement the logic for saving and loading the installation's paths on the disk || Done
|-
| Multiple installations || Implement the project preferences page || Done
|-
| Multiple installations || Rewrite the current mechanisms that use the paths to use the ones based on the project. || Done
|-
| Auto-update || Implement the auto-update feature. || In progress
|-
| Documentation || Write the User Manual || Done
|-
| Documentation || Write the Developer Manual || Done
|-
| Documentation || Write the internal documentation || Done
|-
| Enhance Content Assist || Project dependency tree || In progress
|-
| Enhance Content Assist || Content assist files || None
|-
| Enhance Content Assist || Variables || None
|-
| Enhance Content Assist || Events || None
|-
| Enhance Content Assist || Lua tags || None
|-
| Addon management || Create the GUI of the view || Done
|-
| Addon management || Create the view's logic || In progress
|-
| Unit testing || Tests for the grammar || None
|-
| Unit testing || Tests for parsing the config files || None
|}

Optional tasks will be dealt with if the time allows it:

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Enhance Content Assist || Project dependency tree with multiple paths based on defines || None
|-
| Enhance Content Assist || Lua tags attributes || None
|-
| Grammar || Enhance the grammar to support the 2 current unsupported syntax constructs || None
|-
| Documentation || Implement a simple WML project from start to end using Help's built-in cheat sheets tutorial || None
|}

=Questionnaire=
The questionnaire can be found here: http://wiki.wesnoth.org/User:Timotei21/Questionaire

SummerofCode2011 Timotei21

2011-07-08T17:53:58Z

Timotei21: update progress

{{SoC2011Student_2|timotei|SoC_Ideas_Eclipse_Plugin2011}}

=Description=
<h4>timotei - Improving the Eclipse Plugin</h4>
I aim at improving the plugin, so it will become the tool used by all UMC Authors. That is, UMC Authors will get rid of the lot of different tools they use for different tasks (for example the Emacs WMLMode/other plugins for different text editors), and instead use one single unified Tool that will speed up the development. My target is to make this plugin a complete and very stable suite for all umc tasks that don't need specialized software - like a graphics editor, so I'd like to have this oportunity to finish it in the good sense.

=Contacts=
==IRC==
timotei

==Other==
Forum: timotei 
gna.org: timotei

=SoC Application=
[http://www.google-melange.com/gsoc/proposal/review/google/gsoc2011/timoteidolean/1 Battle for Wesnoth - Google Summer of Code Application]

=Proposal Summary=
Page Last Updated: {{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}} 

In the following lines I will give details on how I'm planning to implement some of the required tasks, and also add some new ones.

The ''Notes'' sections are aimed for personal guideliness. They are took from my todo list.

==Multiple Wesnoth installations==
Having multiple wesnoth setups, and working with them at the same time would be nice to be done from inside the plugin.
For that, there will be a new preferences page. The page will look something like this:
http://dl.dropbox.com/u/462510/personal/soc/installations_management.PNG

There will be buttons that add/remove/edit a certain wesnoth installation. When adding/editing an installation, a new page like the current one (in which we set the paths), will be shown. The user will be able to name it and specify the version (I could automatically get the version by invoking ''wesnoth --version'').
The current page for setting the paths will act as a default installation.

After we have configured the paths, the user can chose the installation to which the (new) projects are bound, by opening the project properties. There will be a wesnoth-related page, where the user will be able to chose to what installation the project binds. With that, every command that uses the paths, won't use the single current paths, but the ones assigned to each project. This project properties page will open new ways for adding new

There would be a problem in case the project will be migrated between 2 different plugin's versions. For example, in one place we would have defined "1.9.4svn" but on the other there would be "trunk".

We can solve this in 3 ways:

# Alert the user that the installation doesn't bind, and let him chose the current matching installation for his plugin.
# Default automatically to the current plugin's default installation.
# "Hardcode" the version, so that there may be defined just installations like: 1.8.0, 1.9.3. With this we lose some flexibility, but we could use this as base version for new installations, so for example, a user can have two 1.9.3 installations. Provided this, we have again a possible problem, which can be solved again by 1. or 2., but this time, trying to match the base version first.

With this feature, the user won't need to restart the plugin at all, switching workspaces.

Regarding the technical PoV, all paths will be stored using eclipse's preferences system, by appending an unique id of each installation to each path in that set.

''Note'':
Add the NO_TERRAIN_GFX preprocess option checkbox to the project properties rather than being a global one.

==Enhance the Content Assist(CA) feature==
The CA framework is very extensible but it lacks proper contexts for providing the content.
I was thinking of trying to accomplish the generating of CA list either by using a config file, in case something like that can be used or writing directly the code that does that.

Another factor that is involved in a better auto-complete, is the ''schema.cfg'' the plugin bases on. Depending on whether the schema is worked on during this summer of code, I'll need to redo a bit the parser of the schema, in case the format/semantics change.

===Project files dependecy tree===
In order for the CA to work better - and maybe other areas would benefit from this - we will need to build a project files tree. With that tree, we can see how a certain declared macro/variable will affect subsequent related files and also their scope. Basically, we can see the relation from a file to anothers.

This tree will be (re)built in 2 situations:
# A file is added/removed/changed it's name
# A full rebuild is triggered (for example, the project is added for the first time in the workspace)

The tree will be built by the WML parser's rules:
# files are processed in the alphabetically order
# _initial.cfg is the first processed before anything else.
# _final.cfg is the last processed after anything else.
# if there is a _main.cfg in the directory, it is the only one processed.

Since the current ''WesnothProjectBuilder'' doesn't take in account the previous rules, I will create my own method of visiting each folder's children in the correct order. This method will look close to wesnoth's one, namely ''get_files_from_in_dir()'' found in ''src/filesystem.cpp:93''.

For a very fast lookup, as a data structure we will use a Hashtable, which has as the key the local project path to the file, and as a value a custom structure, which has the previous/next/parent/son properties, used to traverse the tree. The previous/next go on the same tree level, while the parent/son go up/down in the tree. I will use this instead of a tree, because this will give us access to info about a file, faster, in O(1) compared to a breadth-first search which has O(V+E) - where V is number of vertices and E number of edges.

Talking with Crab about this, he alerted me about a little possible problem with current aproach:
<Crab_> a note about 'The tree will be built by the WML parser's rules: ' - don't forget that you can (conditionally) include files/dirs from a file.
<Crab_> so, if we have 'ai/ais/zzz' which, say, defines a macro, it might get included by campaigns/bbb/scenarios/some_scenario.cfg , even if it is not inside /campaigns/bbb/scenarios

For that we have 2 cases:
{~file/dir path}
or
{file/dir path}

The paths are simply discarded if the current project's directory name is not found in the path.

Currently the so called "Tree" will be actually just a List or a single path tree. For the first iteration of this project, I won't tackle the advanced macro usage that might direct the flow based on defines (this will be optional if there will be time in GSoC, or if not, after GSoC, since I plan to remain active developer to maintain the plugin/enhance it furthermore). So, for example (taken from LoW):

#ifdef CAMPAIGN_LOW

{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#endif

#ifdef MULTIPLAYER

#define EASY
#enddef
{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#undef EASY
...
#endif

With current way to do this we will just take "blindly" all included directories/files without taking in consideration the #define flow control.

If we are at LoW, the following tree(list) will be created on its project:

_main.cfg -> utils/*.cfg -> scenarios/*.cfg -> units/*.cfg

Each file in the dependency tree, will have associated a number. For more details on why this and how it's done, read the Scoping section.

===Scoping===
In order for the plugin to know more about the semnatics, it should have the posibility to represent scopes. The scopes will be used mainly for variables and macros.

The Scoping is a delicate problem, because there are some tricky situations that might interfere with the scoping. I choosed to represent scoping in the following way:

Scoping is everything just about order relations. That is, we will compare numbers when dealing with scoping. With that we move the "problem" upper, to the "Dependency tree". We won't use filenames/paths because:

* The filename might change, but the order index may not. So, not having to update the index helps us.
* Number comparison is faster than string comparison.

So, from now on we'll talk in terms of indexes instead of filenames for scoping.

So, we are working with numbers. But there is still a lil' problem. What happens, when we remove/need to add a new file in the current tree, in the middle of existing 2? We would need to update all subsequent files's indexes. That would not be so ok performance wise.

To counter this problem we will not use consecutive numbers, but rather have a certain step between numbers. The step might be configured inside the plugin based on real statistics (for example, trying to see the number of cfg files per project. Taking a big number, like 1000 won't really hurt). For example, we could take the step 50. That means we would have the following tree for LoW:

0 50 100
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

instead of:
0 1 2
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

So, when it's the case of insertion, we insert the new node at the ''middle'' of the current "distance". That way we may insert/delete files *without* breaking the order, and our scoping will still work.

There is another problem it rised in my head: how do we know when to put the number as the next step (the previous number + step) or add it in the middle? Well, since every project will surely do a '''Full Build''', we'll use that oportunity to create the initial tree. Afterwards we will just insert files based on the halving of the distance between 2 indices.

The scoping will be represented by a simple structure, consisting of start index and offset and end index and offset.

===Content Assist Config(CAC) Files===
The CAC files will provide values that are default/available to config files from the wesnoth engine itself. There will be several files that define the values based on their context. This will allow a very great flexibility editing the CA list.

A CAC file will be just a simple text file, that has on each line one (or more) value(s) depending on the context.

* The ''cac/variables.txt'' will contain variables available. The list is currently available at [http://wiki.wesnoth.org/VariablesWML#Automatically_stored_variables]. For example the file could look like:
$side_number
$turn_number
...

* The ''cac/events.txt'' will contain the game events. The list is availabe at: [http://wiki.wesnoth.org/EventWML#Predefined_.27name.27_Key_Values]. Since the events that have spaces in their names can replace that with an underscore '_', the file will contain the underscore instead space variants also.



===Variables===
The variables are either defined by user or defined by default by the wesnoth engine. User's variables will be parsed from each processed file by the WesnothProjectBuilder, using the WMLSaxHandler. The default variables will be parsed and added from the CAC file. (cac/variables.txt)

Variables definitions can be triggered using the VARIABLE macro:
{VARIABLE var_name "value"}
or the [set_variable] tag:
[set_variable]
name=my_var
value="value"
[/set_variable]

The ''ConfigFile'' class in the ''org.wesnoth.wml.core'' already has a list of variables. The ''Variable'' class has some fields that allow its identification. We will build that list when we parse each file, adding each variable found by the previous defined triggers.
When the content assist finds the '$' character, it will supply the user + default variables gathered so far.

Since the variables can be cleared, thus they have scope, the ''Variable'' class needs to be refactorted, so it can represent the scope aswell. The scoping was settled before.

===Name Collisions===
I've considered that we should store the variables per project, like we currently do with macros. This will minimize the memory we need, rather than storing variables on each file - like we do currently. With this, I've discovered it's innevitable to have ''collisions''. That is, have the same variable name on multiple files.

To solve this problem, each variable/macro structure, will not have just a single scope, but rather a list of scopes.

===Events===
Besides the default event names, supplied by the wesnoth engine, there can be created custom ones, wich will be triggered with [fire_event]. As usual the default events names will be available in the cac/events.txt file.

The events defined by the user will be parsed from the ''name'' attribute of the [event] tag.

===Attributes===
All attributes are currently got from the schema.cfg

===Attributes Values===
All attributes values should be parsed based on the schema.cfg.

===Macros===
The support for macros is already built in, but it needs a way to let them have scope. That is, when an #undef is found, the certain macro would not be available to subsequent files unless redeclared. This will be done with the aid of the dependency tree and scoping. The collisions will be solved like I said at the variables section

===Support for custom luaWML tags===
The lua can create new WML Tags. It would be nice that the plugin suggest those aswell besides the ''schema.cfg''. The lua will be easily parsed, since there is a simple pattern for creating new tags:
wesnoth.wml_actions.<tag name>(cfg)

The parser will just run over the lua code/file, over each line, trying to match the 'function *wesnoth.wml_actions.*' pattern. If it finds something, it will add the tag name to the list of tags. There is also a small thing we might have missed. The user could use a shorthand notation for the actions namespace, so when searching for the pattern, I will add to the 'pattern to match' list, the respective variable when searching for new WML Tags.

Thus, like the ''wml-tags.lua'' from the data/lua uses:
local wml_actions = wesnoth.wml_actions

the 'to match' list will contain: 'function *wesnoth.wml_actions.*' and 'function *wml_actions.*', thus finding other tags too.

Going further more, for an ''optional'' enhancement, I could also search that function to see if it needs/has some extra attributes. The attributes can be found by:
* function's parameter (usually cfg) is asked for a property. For example:
function wml_actions.terrain(cfg)
local terrain = cfg.terrain or helper.wml_error("[terrain] missing required terrain= attribute")
cfg = helper.shallow_literal(cfg)
cfg.terrain = nil
for i, loc in ipairs(wesnoth.get_locations(cfg)) do
wesnoth.set_terrain(loc[1], loc[2], terrain, cfg.layer, cfg.replace_if_failed)
end
end

Here we need the attributes ''terrain'', ''layer'' and ''replace_if_failed''.

* ''get_child'' call:
function wml_actions.message(cfg)
local show_if = helper.get_child(cfg, "show_if")
if not show_if or wesnoth.eval_conditional(show_if) then
engine_message(cfg)
end
end

Here we need to have the attribute ''show_if''.

==Automatic/headless building==
The eclipse plugins can be automatically built from command line, provided there is the eclipse sdk and the eclipse delta pack on the builder's machine. The plugin can also use Buckminster tool to automate the building of the plugin.

''Notes''
Add all plugin's files *inside* a folder to prevent cluttering the directory where it's extracted

More info at:
* http://wiki.eclipse.org/PDE/Build
* http://wiki.bioclipse.net/index.php?title=How_to_build_plugins_headless
* http://help.eclipse.org/galileo/index.jsp?topic=/org.eclipse.pde.doc.user/guide/intro/pde_overview.htm
* http://www.eclipse.org/articles/Article-PDE-Automation/automation.html

==Standalone app auto-update==
The current standalone application doesn't offer the same eclipse's update system. I will add it, so anytime there is a new version of the plugin, it can be updated with a single click by the user, without the needing to download a new standalone app again.

==Documentation==
===External documentation===
The current existing readme will be split in 2 manuals: User Manual and Developer Manual (Don't forget to add images where relevant).

The user manual will contain:
* Prerequisites and Installing the prerequisites
Note: don't forget to mention the MINIMUM eclipse/java version needed to run
* Installing the plugin / standalone version
* Using the plugin
* Plugin features
* Step-by-step use cases
** Setupping the workspace
** Creating a new project and running it in the game
** Importing existing projects
** Using the WML Editor
** Updating the plugin
* Frequently Asked Questions

The developer manual will contain:
* Prerequisites and Installing the prerequisites
* Adding the plugin's projects in the
* Compiling and Running the plugin
* Deploying the plugin and standalone app

===Internal documentation===
The Eclipse infrastructure has features for letting the developer embed help into the application, depending on the current context. After I will write the external documentation, I will work on adding internal documentation aswell. Some of it already comes from the external one.

* Plugin welcome page
* Eclipse Help (When pressing Help->Help contents)
* Wizards help

==Plugin polishing==
This are some tasks needed to be done in order to get the plugin more stable and more usable than it's currently. Some of the tasks are taken from my todo list. New tasks will be added through the project advancing when improvements to actual code /user interaction can be done, so this list is not final.

* Don't copy a project that belongs to data/campaigns to the user addons's directory. This can be done by looking at the path when creating a new project. (This is prevented by not spawning a ''build.xml'' file in the campaigns's directory)
* Enhance the logging so it can help debugging other's problem much easier. I could split the current log in 2:
** Commands executed by the plugin
** Other information like parsed information/statuses
* Enhance the integration with the eclipse platform by adding the "Wesnoth" related wizards directly to the "New" menu.
* Allow users to import a directory as a wesnoth project. Under the hood it will either open the wesnoth project (if there is any .project files in it) or create a new empty project on it.
* Allow the user to clear it's current plugin's settings just with a simple button.
* Wesnoth Project Explorer - Add error markers just like the Java Explorer has
* Refactor the current way of getting the macro list. Currently if there is no _main.cfg practically the _MACROS_.cfg file is not built resulting in no MACRO suggestions.
* Create a view filter to hide the Project ''_AutoLinked_CFGExternalFiles_'' which is created for opening the external config files (external meaning outside the current workspace).
* Fix the F3 navigation when the map's location is specified withing " ", as a string.

===New parsing method (optional)===
The current parsing method involves a lot of Wesnoth preprocessor/wmlparser.py. This is doing somehow the parsing job double. This is because the xtext framework already does 1 pass over the files when added to the project. My plan is to see if I can reuse the already built AST(Abstract Syntax Tree) and the parse tree, to use those values instead of additional preprocessing/wmlparsing, and use the latter only when really needed.

Using the xtext's model will greatly fasten the "build" time of each project and it will be *much* simpler to work with, since the framework already provides exceptions recovering (that is, when the code is not well formed according to the grammar) and based on the defined grammar the respective tokens. So, for example instead using 2 another external processes, we could just iterate over each WMLTag and get it's WMLKeys and parse their individual values.

If this idea works, I will add it on the Plugin polishing tasks.

==Other ideas==
===Addons management===
There will be a new Addons management view. It will behave much like the in-game addon manager, but it will be more handy since the user doesn't need to start the game for that (and also wait till the cache refreshes after downloading it). This view will be based on the python script from '''data/tools/wesnoth_addon_manager''', like it does currently for uploading the project as an addon.

The view will let the user see the list/details for each of the addons currently on the server. There will be also a filter based on what addon server to use (trunk/1.8/1.9/etc)

The user will be able to just right click on an addon and download it to it's user data folder. Optionally a new project will be created, based on the just downloaded addon.



===Unit testing===
====Grammar====
For a better wml handling with in the editor, I will create a Testing class for the current grammar. The class will do testing on all *.cfgs in the data directory. That way after modifing something in the grammar we will be able to see how many errors we have introduced/eliminated. This will greatly help the developing of a better grammar that can hold all current WML formats.

''Notes'':
optionally rework the grammar and try to use a custom lexer/parser in order to benefit from the preprocessor, injecting the valid tokens. This would help the cases when the current grammar doesn't work:
{name} = value
or unclosed tags

====Parsing and getting information from files====
I will create some basic (or taken from existing campaigns) config files that will be parsed in order to check if the correct behaviour - correct information is extracted from the files.

This will check for extracting the:
scenario name
campaign name
next_scenario
first_scenario
variables
macros

=Timeline=
The GSOC period is between 24th May and 20th August. But since I have exams for 3 weeks (during 30.05-19.06.2011), I will start working on the plugin before the 24th of May, to recover some of the lost time. Also, my ImagineCup team made it to the national phase - that is in 5,6,7 May. That means till that time I will not be able to do so much work, so I'll make the timeline according with the starting of work on 9 May.

Here is a table with key periods of the time spent on this project.
{| border="1"
|'''Period''' || '''Actions'''
|-
| 26 April || Get accepted
|-
| 26 April - 8 May || Busy working on ImagineCup project for the national phase. Little or no work done.
|-
| 9 May - 15 May || Allow headless build of the plugin
|-
| 16 May - 22 May || Add Support for multiple installations
|-
| 23 May - 28 May || Add the auto-update feature for the standalone app
|-
| 30 May - 19 June || Exams
|-
| 20 June - 24 June || Create the external documentation
|-
| 25 June - 16 July || Enhance Content Assist
|-
| 15 July || Mid-term evaluations deadline
|-
| 17 July - 24 July || Addons management view
|-
| 25 July - 30 July || Unit tests
|-
| 1 August - 14 August || Do the Plugin polishing tasks
|-
| 15 August || Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc.
|-
| 15 August - 17 August || Create the internal documentation.
|-
| 18 August - 22 August || Buffer half-week. This will be used in case some tasks fell a bit outside their proposed time.
|-
| 22 August || Firm 'pencils down' date. Mentors, students and organization administrators can begin submitting final evaluations to Google.
|}

=Tasks=
This is a list of the "atomic" tasks that need to be done, based on the project part. Since the big tasks are split into smaller task, the progress will be seen better and any problems that arise with the timeline will be seen faster. I will update this table based on my current progress.

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Headless build ||Research about what system to use for automatic building of the plugin || Done
|-
| Headless build || Implement the chosen system for the wesnoth plugin|| Done
|-
| Multiple installations || Implement the preferences pages || Done
|-
| Multiple installations || Implement the logic for saving and loading the installation's paths on the disk || Done
|-
| Multiple installations || Implement the project preferences page || Done
|-
| Multiple installations || Rewrite the current mechanisms that use the paths to use the ones based on the project. || Done
|-
| Auto-update || Implement the auto-update feature. || In progress
|-
| Documentation || Write the User Manual || Done
|-
| Documentation || Write the Developer Manual || Done
|-
| Documentation || Write the internal documentation || Done
|-
| Enhance Content Assist || Project dependency tree || In progress
|-
| Enhance Content Assist || Content assist files || None
|-
| Enhance Content Assist || Variables || None
|-
| Enhance Content Assist || Events || None
|-
| Enhance Content Assist || Lua tags || None
|-
| Addon management || Create the GUI of the view || Done
|-
| Addon management || Create the view's logic || In progress
|-
| Unit testing || Tests for the grammar || None
|-
| Unit testing || Tests for parsing the config files || None
|}

Optional tasks will be dealt with if the time allows it:

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Enhance Content Assist || Project dependency tree with multiple paths based on defines || None
|-
| Enhance Content Assist || Lua tags attributes || None
|-
| Grammar || Enhance the grammar to support the 2 current unsupported syntax constructs || None
|-
| Documentation || Implement a simple WML project from start to end using Help's built-in cheat sheets tutorial || None
|}

=Questionnaire=
The questionnaire can be found here: http://wiki.wesnoth.org/User:Timotei21/Questionaire

SummerofCode2011 Timotei21

2011-07-08T13:33:23Z

Timotei21: /* Tasks */

{{SoC2011Student_2|timotei|SoC_Ideas_Eclipse_Plugin2011}}

=Description=
<h4>timotei - Improving the Eclipse Plugin</h4>
I aim at improving the plugin, so it will become the tool used by all UMC Authors. That is, UMC Authors will get rid of the lot of different tools they use for different tasks (for example the Emacs WMLMode/other plugins for different text editors), and instead use one single unified Tool that will speed up the development. My target is to make this plugin a complete and very stable suite for all umc tasks that don't need specialized software - like a graphics editor, so I'd like to have this oportunity to finish it in the good sense.

=Contacts=
==IRC==
timotei

==Other==
Forum: timotei 
gna.org: timotei

=SoC Application=
[http://www.google-melange.com/gsoc/proposal/review/google/gsoc2011/timoteidolean/1 Battle for Wesnoth - Google Summer of Code Application]

=Proposal Summary=
Page Last Updated: {{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}} 

In the following lines I will give details on how I'm planning to implement some of the required tasks, and also add some new ones.

The ''Notes'' sections are aimed for personal guideliness. They are took from my todo list.

==Multiple Wesnoth installations==
Having multiple wesnoth setups, and working with them at the same time would be nice to be done from inside the plugin.
For that, there will be a new preferences page. The page will look something like this:
http://dl.dropbox.com/u/462510/personal/soc/installations_management.PNG

There will be buttons that add/remove/edit a certain wesnoth installation. When adding/editing an installation, a new page like the current one (in which we set the paths), will be shown. The user will be able to name it and specify the version (I could automatically get the version by invoking ''wesnoth --version'').
The current page for setting the paths will act as a default installation.

After we have configured the paths, the user can chose the installation to which the (new) projects are bound, by opening the project properties. There will be a wesnoth-related page, where the user will be able to chose to what installation the project binds. With that, every command that uses the paths, won't use the single current paths, but the ones assigned to each project. This project properties page will open new ways for adding new

There would be a problem in case the project will be migrated between 2 different plugin's versions. For example, in one place we would have defined "1.9.4svn" but on the other there would be "trunk".

We can solve this in 3 ways:

# Alert the user that the installation doesn't bind, and let him chose the current matching installation for his plugin.
# Default automatically to the current plugin's default installation.
# "Hardcode" the version, so that there may be defined just installations like: 1.8.0, 1.9.3. With this we lose some flexibility, but we could use this as base version for new installations, so for example, a user can have two 1.9.3 installations. Provided this, we have again a possible problem, which can be solved again by 1. or 2., but this time, trying to match the base version first.

With this feature, the user won't need to restart the plugin at all, switching workspaces.

Regarding the technical PoV, all paths will be stored using eclipse's preferences system, by appending an unique id of each installation to each path in that set.

''Note'':
Add the NO_TERRAIN_GFX preprocess option checkbox to the project properties rather than being a global one.

==Enhance the Content Assist(CA) feature==
The CA framework is very extensible but it lacks proper contexts for providing the content.
I was thinking of trying to accomplish the generating of CA list either by using a config file, in case something like that can be used or writing directly the code that does that.

Another factor that is involved in a better auto-complete, is the ''schema.cfg'' the plugin bases on. Depending on whether the schema is worked on during this summer of code, I'll need to redo a bit the parser of the schema, in case the format/semantics change.

===Project files dependecy tree===
In order for the CA to work better - and maybe other areas would benefit from this - we will need to build a project files tree. With that tree, we can see how a certain declared macro/variable will affect subsequent related files and also their scope. Basically, we can see the relation from a file to anothers.

This tree will be (re)built in 2 situations:
# A file is added/removed/changed it's name
# A full rebuild is triggered (for example, the project is added for the first time in the workspace)

The tree will be built by the WML parser's rules:
# files are processed in the alphabetically order
# _initial.cfg is the first processed before anything else.
# _final.cfg is the last processed after anything else.
# if there is a _main.cfg in the directory, it is the only one processed.

Since the current ''WesnothProjectBuilder'' doesn't take in account the previous rules, I will create my own method of visiting each folder's children in the correct order. This method will look close to wesnoth's one, namely ''get_files_from_in_dir()'' found in ''src/filesystem.cpp:93''.

For a very fast lookup, as a data structure we will use a Hashtable, which has as the key the local project path to the file, and as a value a custom structure, which has the previous/next/parent/son properties, used to traverse the tree. The previous/next go on the same tree level, while the parent/son go up/down in the tree. I will use this instead of a tree, because this will give us access to info about a file, faster, in O(1) compared to a breadth-first search which has O(V+E) - where V is number of vertices and E number of edges.

Talking with Crab about this, he alerted me about a little possible problem with current aproach:
<Crab_> a note about 'The tree will be built by the WML parser's rules: ' - don't forget that you can (conditionally) include files/dirs from a file.
<Crab_> so, if we have 'ai/ais/zzz' which, say, defines a macro, it might get included by campaigns/bbb/scenarios/some_scenario.cfg , even if it is not inside /campaigns/bbb/scenarios

For that we have 2 cases:
{~file/dir path}
or
{file/dir path}

The paths are simply discarded if the current project's directory name is not found in the path.

Currently the so called "Tree" will be actually just a List or a single path tree. For the first iteration of this project, I won't tackle the advanced macro usage that might direct the flow based on defines (this will be optional if there will be time in GSoC, or if not, after GSoC, since I plan to remain active developer to maintain the plugin/enhance it furthermore). So, for example (taken from LoW):

#ifdef CAMPAIGN_LOW

{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#endif

#ifdef MULTIPLAYER

#define EASY
#enddef
{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#undef EASY
...
#endif

With current way to do this we will just take "blindly" all included directories/files without taking in consideration the #define flow control.

If we are at LoW, the following tree(list) will be created on its project:

_main.cfg -> utils/*.cfg -> scenarios/*.cfg -> units/*.cfg

Each file in the dependency tree, will have associated a number. For more details on why this and how it's done, read the Scoping section.

===Scoping===
In order for the plugin to know more about the semnatics, it should have the posibility to represent scopes. The scopes will be used mainly for variables and macros.

The Scoping is a delicate problem, because there are some tricky situations that might interfere with the scoping. I choosed to represent scoping in the following way:

Scoping is everything just about order relations. That is, we will compare numbers when dealing with scoping. With that we move the "problem" upper, to the "Dependency tree". We won't use filenames/paths because:

* The filename might change, but the order index may not. So, not having to update the index helps us.
* Number comparison is faster than string comparison.

So, from now on we'll talk in terms of indexes instead of filenames for scoping.

So, we are working with numbers. But there is still a lil' problem. What happens, when we remove/need to add a new file in the current tree, in the middle of existing 2? We would need to update all subsequent files's indexes. That would not be so ok performance wise.

To counter this problem we will not use consecutive numbers, but rather have a certain step between numbers. The step might be configured inside the plugin based on real statistics (for example, trying to see the number of cfg files per project. Taking a big number, like 1000 won't really hurt). For example, we could take the step 50. That means we would have the following tree for LoW:

0 50 100
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

instead of:
0 1 2
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

So, when it's the case of insertion, we insert the new node at the ''middle'' of the current "distance". That way we may insert/delete files *without* breaking the order, and our scoping will still work.

There is another problem it rised in my head: how do we know when to put the number as the next step (the previous number + step) or add it in the middle? Well, since every project will surely do a '''Full Build''', we'll use that oportunity to create the initial tree. Afterwards we will just insert files based on the halving of the distance between 2 indices.

The scoping will be represented by a simple structure, consisting of start index and offset and end index and offset.

===Content Assist Config(CAC) Files===
The CAC files will provide values that are default/available to config files from the wesnoth engine itself. There will be several files that define the values based on their context. This will allow a very great flexibility editing the CA list.

A CAC file will be just a simple text file, that has on each line one (or more) value(s) depending on the context.

* The ''cac/variables.txt'' will contain variables available. The list is currently available at [http://wiki.wesnoth.org/VariablesWML#Automatically_stored_variables]. For example the file could look like:
$side_number
$turn_number
...

* The ''cac/events.txt'' will contain the game events. The list is availabe at: [http://wiki.wesnoth.org/EventWML#Predefined_.27name.27_Key_Values]. Since the events that have spaces in their names can replace that with an underscore '_', the file will contain the underscore instead space variants also.



===Variables===
The variables are either defined by user or defined by default by the wesnoth engine. User's variables will be parsed from each processed file by the WesnothProjectBuilder, using the WMLSaxHandler. The default variables will be parsed and added from the CAC file. (cac/variables.txt)

Variables definitions can be triggered using the VARIABLE macro:
{VARIABLE var_name "value"}
or the [set_variable] tag:
[set_variable]
name=my_var
value="value"
[/set_variable]

The ''ConfigFile'' class in the ''org.wesnoth.wml.core'' already has a list of variables. The ''Variable'' class has some fields that allow its identification. We will build that list when we parse each file, adding each variable found by the previous defined triggers.
When the content assist finds the '$' character, it will supply the user + default variables gathered so far.

Since the variables can be cleared, thus they have scope, the ''Variable'' class needs to be refactorted, so it can represent the scope aswell. The scoping was settled before.

===Name Collisions===
I've considered that we should store the variables per project, like we currently do with macros. This will minimize the memory we need, rather than storing variables on each file - like we do currently. With this, I've discovered it's innevitable to have ''collisions''. That is, have the same variable name on multiple files.

To solve this problem, each variable/macro structure, will not have just a single scope, but rather a list of scopes.

===Events===
Besides the default event names, supplied by the wesnoth engine, there can be created custom ones, wich will be triggered with [fire_event]. As usual the default events names will be available in the cac/events.txt file.

The events defined by the user will be parsed from the ''name'' attribute of the [event] tag.

===Attributes===
All attributes are currently got from the schema.cfg

===Attributes Values===
All attributes values should be parsed based on the schema.cfg.

===Macros===
The support for macros is already built in, but it needs a way to let them have scope. That is, when an #undef is found, the certain macro would not be available to subsequent files unless redeclared. This will be done with the aid of the dependency tree and scoping. The collisions will be solved like I said at the variables section

===Support for custom luaWML tags===
The lua can create new WML Tags. It would be nice that the plugin suggest those aswell besides the ''schema.cfg''. The lua will be easily parsed, since there is a simple pattern for creating new tags:
wesnoth.wml_actions.<tag name>(cfg)

The parser will just run over the lua code/file, over each line, trying to match the 'function *wesnoth.wml_actions.*' pattern. If it finds something, it will add the tag name to the list of tags. There is also a small thing we might have missed. The user could use a shorthand notation for the actions namespace, so when searching for the pattern, I will add to the 'pattern to match' list, the respective variable when searching for new WML Tags.

Thus, like the ''wml-tags.lua'' from the data/lua uses:
local wml_actions = wesnoth.wml_actions

the 'to match' list will contain: 'function *wesnoth.wml_actions.*' and 'function *wml_actions.*', thus finding other tags too.

Going further more, for an ''optional'' enhancement, I could also search that function to see if it needs/has some extra attributes. The attributes can be found by:
* function's parameter (usually cfg) is asked for a property. For example:
function wml_actions.terrain(cfg)
local terrain = cfg.terrain or helper.wml_error("[terrain] missing required terrain= attribute")
cfg = helper.shallow_literal(cfg)
cfg.terrain = nil
for i, loc in ipairs(wesnoth.get_locations(cfg)) do
wesnoth.set_terrain(loc[1], loc[2], terrain, cfg.layer, cfg.replace_if_failed)
end
end

Here we need the attributes ''terrain'', ''layer'' and ''replace_if_failed''.

* ''get_child'' call:
function wml_actions.message(cfg)
local show_if = helper.get_child(cfg, "show_if")
if not show_if or wesnoth.eval_conditional(show_if) then
engine_message(cfg)
end
end

Here we need to have the attribute ''show_if''.

==Automatic/headless building==
The eclipse plugins can be automatically built from command line, provided there is the eclipse sdk and the eclipse delta pack on the builder's machine. The plugin can also use Buckminster tool to automate the building of the plugin.

''Notes''
Add all plugin's files *inside* a folder to prevent cluttering the directory where it's extracted

More info at:
* http://wiki.eclipse.org/PDE/Build
* http://wiki.bioclipse.net/index.php?title=How_to_build_plugins_headless
* http://help.eclipse.org/galileo/index.jsp?topic=/org.eclipse.pde.doc.user/guide/intro/pde_overview.htm
* http://www.eclipse.org/articles/Article-PDE-Automation/automation.html

==Standalone app auto-update==
The current standalone application doesn't offer the same eclipse's update system. I will add it, so anytime there is a new version of the plugin, it can be updated with a single click by the user, without the needing to download a new standalone app again.

==Documentation==
===External documentation===
The current existing readme will be split in 2 manuals: User Manual and Developer Manual (Don't forget to add images where relevant).

The user manual will contain:
* Prerequisites and Installing the prerequisites
Note: don't forget to mention the MINIMUM eclipse/java version needed to run
* Installing the plugin / standalone version
* Using the plugin
* Plugin features
* Step-by-step use cases
** Setupping the workspace
** Creating a new project and running it in the game
** Importing existing projects
** Using the WML Editor
** Updating the plugin
* Frequently Asked Questions

The developer manual will contain:
* Prerequisites and Installing the prerequisites
* Adding the plugin's projects in the
* Compiling and Running the plugin
* Deploying the plugin and standalone app

===Internal documentation===
The Eclipse infrastructure has features for letting the developer embed help into the application, depending on the current context. After I will write the external documentation, I will work on adding internal documentation aswell. Some of it already comes from the external one.

* Plugin welcome page
* Eclipse Help (When pressing Help->Help contents)
* Wizards help

==Plugin polishing==
This are some tasks needed to be done in order to get the plugin more stable and more usable than it's currently. Some of the tasks are taken from my todo list. New tasks will be added through the project advancing when improvements to actual code /user interaction can be done, so this list is not final.

* Don't copy a project that belongs to data/campaigns to the user addons's directory. This can be done by looking at the path when creating a new project. (This is prevented by not spawning a ''build.xml'' file in the campaigns's directory)
* Enhance the logging so it can help debugging other's problem much easier. I could split the current log in 2:
** Commands executed by the plugin
** Other information like parsed information/statuses
* Enhance the integration with the eclipse platform by adding the "Wesnoth" related wizards directly to the "New" menu.
* Allow users to import a directory as a wesnoth project. Under the hood it will either open the wesnoth project (if there is any .project files in it) or create a new empty project on it.
* Allow the user to clear it's current plugin's settings just with a simple button.
* Wesnoth Project Explorer - Add error markers just like the Java Explorer has
* Refactor the current way of getting the macro list. Currently if there is no _main.cfg practically the _MACROS_.cfg file is not built resulting in no MACRO suggestions.
* Create a view filter to hide the Project ''_AutoLinked_CFGExternalFiles_'' which is created for opening the external config files (external meaning outside the current workspace).
* Fix the F3 navigation when the map's location is specified withing " ", as a string.

===New parsing method (optional)===
The current parsing method involves a lot of Wesnoth preprocessor/wmlparser.py. This is doing somehow the parsing job double. This is because the xtext framework already does 1 pass over the files when added to the project. My plan is to see if I can reuse the already built AST(Abstract Syntax Tree) and the parse tree, to use those values instead of additional preprocessing/wmlparsing, and use the latter only when really needed.

Using the xtext's model will greatly fasten the "build" time of each project and it will be *much* simpler to work with, since the framework already provides exceptions recovering (that is, when the code is not well formed according to the grammar) and based on the defined grammar the respective tokens. So, for example instead using 2 another external processes, we could just iterate over each WMLTag and get it's WMLKeys and parse their individual values.

If this idea works, I will add it on the Plugin polishing tasks.

==Other ideas==
===Addons management===
There will be a new Addons management view. It will behave much like the in-game addon manager, but it will be more handy since the user doesn't need to start the game for that (and also wait till the cache refreshes after downloading it). This view will be based on the python script from '''data/tools/wesnoth_addon_manager''', like it does currently for uploading the project as an addon.

The view will let the user see the list/details for each of the addons currently on the server. There will be also a filter based on what addon server to use (trunk/1.8/1.9/etc)

The user will be able to just right click on an addon and download it to it's user data folder. Optionally a new project will be created, based on the just downloaded addon.



===Unit testing===
====Grammar====
For a better wml handling with in the editor, I will create a Testing class for the current grammar. The class will do testing on all *.cfgs in the data directory. That way after modifing something in the grammar we will be able to see how many errors we have introduced/eliminated. This will greatly help the developing of a better grammar that can hold all current WML formats.

''Notes'':
optionally rework the grammar and try to use a custom lexer/parser in order to benefit from the preprocessor, injecting the valid tokens. This would help the cases when the current grammar doesn't work:
{name} = value
or unclosed tags

====Parsing and getting information from files====
I will create some basic (or taken from existing campaigns) config files that will be parsed in order to check if the correct behaviour - correct information is extracted from the files.

This will check for extracting the:
scenario name
campaign name
next_scenario
first_scenario
variables
macros

=Timeline=
The GSOC period is between 24th May and 20th August. But since I have exams for 3 weeks (during 30.05-19.06.2011), I will start working on the plugin before the 24th of May, to recover some of the lost time. Also, my ImagineCup team made it to the national phase - that is in 5,6,7 May. That means till that time I will not be able to do so much work, so I'll make the timeline according with the starting of work on 9 May.

Here is a table with key periods of the time spent on this project.
{| border="1"
|'''Period''' || '''Actions'''
|-
| 26 April || Get accepted
|-
| 26 April - 8 May || Busy working on ImagineCup project for the national phase. Little or no work done.
|-
| 9 May - 15 May || Allow headless build of the plugin
|-
| 16 May - 22 May || Add Support for multiple installations
|-
| 23 May - 28 May || Add the auto-update feature for the standalone app
|-
| 30 May - 19 June || Exams
|-
| 20 June - 24 June || Create the external documentation
|-
| 25 June - 16 July || Enhance Content Assist
|-
| 15 July || Mid-term evaluations deadline
|-
| 17 July - 24 July || Addons management view
|-
| 25 July - 30 July || Unit tests
|-
| 1 August - 14 August || Do the Plugin polishing tasks
|-
| 15 August || Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc.
|-
| 15 August - 17 August || Create the internal documentation.
|-
| 18 August - 22 August || Buffer half-week. This will be used in case some tasks fell a bit outside their proposed time.
|-
| 22 August || Firm 'pencils down' date. Mentors, students and organization administrators can begin submitting final evaluations to Google.
|}

=Tasks=
This is a list of the "atomic" tasks that need to be done, based on the project part. Since the big tasks are split into smaller task, the progress will be seen better and any problems that arise with the timeline will be seen faster. I will update this table based on my current progress.

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Headless build ||Research about what system to use for automatic building of the plugin || Done
|-
| Headless build || Implement the chosen system for the wesnoth plugin|| Done
|-
| Multiple installations || Implement the preferences pages || Done
|-
| Multiple installations || Implement the logic for saving and loading the installation's paths on the disk || Done
|-
| Multiple installations || Implement the project preferences page || Done
|-
| Multiple installations || Rewrite the current mechanisms that use the paths to use the ones based on the project. || Done
|-
| Auto-update || Implement the auto-update feature. || In progress
|-
| Documentation || Write the User Manual || Done
|-
| Documentation || Write the Developer Manual || Done
|-
| Documentation || Write the internal documentation || Done
|-
| Enhance Content Assist || Project dependency tree || In progress
|-
| Enhance Content Assist || Content assist files || None
|-
| Enhance Content Assist || Variables || None
|-
| Enhance Content Assist || Events || None
|-
| Enhance Content Assist || Lua tags || None
|-
| Addon management || Create the GUI of the view || In progress
|-
| Addon management || Create the view's logic || None
|-
| Unit testing || Tests for the grammar || None
|-
| Unit testing || Tests for parsing the config files || None
|}

Optional tasks will be dealt with if the time allows it:

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Enhance Content Assist || Project dependency tree with multiple paths based on defines || None
|-
| Enhance Content Assist || Lua tags attributes || None
|-
| Grammar || Enhance the grammar to support the 2 current unsupported syntax constructs || None
|-
| Documentation || Implement a simple WML project from start to end using Help's built-in cheat sheets tutorial || None
|}

=Questionnaire=
The questionnaire can be found here: http://wiki.wesnoth.org/User:Timotei21/Questionaire

SummerofCode2011 Timotei21

2011-07-02T14:05:05Z

Timotei21: /* Plugin polishing */

{{SoC2011Student_2|timotei|SoC_Ideas_Eclipse_Plugin2011}}

=Description=
<h4>timotei - Improving the Eclipse Plugin</h4>
I aim at improving the plugin, so it will become the tool used by all UMC Authors. That is, UMC Authors will get rid of the lot of different tools they use for different tasks (for example the Emacs WMLMode/other plugins for different text editors), and instead use one single unified Tool that will speed up the development. My target is to make this plugin a complete and very stable suite for all umc tasks that don't need specialized software - like a graphics editor, so I'd like to have this oportunity to finish it in the good sense.

=Contacts=
==IRC==
timotei

==Other==
Forum: timotei 
gna.org: timotei

=SoC Application=
[http://www.google-melange.com/gsoc/proposal/review/google/gsoc2011/timoteidolean/1 Battle for Wesnoth - Google Summer of Code Application]

=Proposal Summary=
Page Last Updated: {{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}} 

In the following lines I will give details on how I'm planning to implement some of the required tasks, and also add some new ones.

The ''Notes'' sections are aimed for personal guideliness. They are took from my todo list.

==Multiple Wesnoth installations==
Having multiple wesnoth setups, and working with them at the same time would be nice to be done from inside the plugin.
For that, there will be a new preferences page. The page will look something like this:
http://dl.dropbox.com/u/462510/personal/soc/installations_management.PNG

There will be buttons that add/remove/edit a certain wesnoth installation. When adding/editing an installation, a new page like the current one (in which we set the paths), will be shown. The user will be able to name it and specify the version (I could automatically get the version by invoking ''wesnoth --version'').
The current page for setting the paths will act as a default installation.

After we have configured the paths, the user can chose the installation to which the (new) projects are bound, by opening the project properties. There will be a wesnoth-related page, where the user will be able to chose to what installation the project binds. With that, every command that uses the paths, won't use the single current paths, but the ones assigned to each project. This project properties page will open new ways for adding new

There would be a problem in case the project will be migrated between 2 different plugin's versions. For example, in one place we would have defined "1.9.4svn" but on the other there would be "trunk".

We can solve this in 3 ways:

# Alert the user that the installation doesn't bind, and let him chose the current matching installation for his plugin.
# Default automatically to the current plugin's default installation.
# "Hardcode" the version, so that there may be defined just installations like: 1.8.0, 1.9.3. With this we lose some flexibility, but we could use this as base version for new installations, so for example, a user can have two 1.9.3 installations. Provided this, we have again a possible problem, which can be solved again by 1. or 2., but this time, trying to match the base version first.

With this feature, the user won't need to restart the plugin at all, switching workspaces.

Regarding the technical PoV, all paths will be stored using eclipse's preferences system, by appending an unique id of each installation to each path in that set.

''Note'':
Add the NO_TERRAIN_GFX preprocess option checkbox to the project properties rather than being a global one.

==Enhance the Content Assist(CA) feature==
The CA framework is very extensible but it lacks proper contexts for providing the content.
I was thinking of trying to accomplish the generating of CA list either by using a config file, in case something like that can be used or writing directly the code that does that.

Another factor that is involved in a better auto-complete, is the ''schema.cfg'' the plugin bases on. Depending on whether the schema is worked on during this summer of code, I'll need to redo a bit the parser of the schema, in case the format/semantics change.

===Project files dependecy tree===
In order for the CA to work better - and maybe other areas would benefit from this - we will need to build a project files tree. With that tree, we can see how a certain declared macro/variable will affect subsequent related files and also their scope. Basically, we can see the relation from a file to anothers.

This tree will be (re)built in 2 situations:
# A file is added/removed/changed it's name
# A full rebuild is triggered (for example, the project is added for the first time in the workspace)

The tree will be built by the WML parser's rules:
# files are processed in the alphabetically order
# _initial.cfg is the first processed before anything else.
# _final.cfg is the last processed after anything else.
# if there is a _main.cfg in the directory, it is the only one processed.

Since the current ''WesnothProjectBuilder'' doesn't take in account the previous rules, I will create my own method of visiting each folder's children in the correct order. This method will look close to wesnoth's one, namely ''get_files_from_in_dir()'' found in ''src/filesystem.cpp:93''.

For a very fast lookup, as a data structure we will use a Hashtable, which has as the key the local project path to the file, and as a value a custom structure, which has the previous/next/parent/son properties, used to traverse the tree. The previous/next go on the same tree level, while the parent/son go up/down in the tree. I will use this instead of a tree, because this will give us access to info about a file, faster, in O(1) compared to a breadth-first search which has O(V+E) - where V is number of vertices and E number of edges.

Talking with Crab about this, he alerted me about a little possible problem with current aproach:
<Crab_> a note about 'The tree will be built by the WML parser's rules: ' - don't forget that you can (conditionally) include files/dirs from a file.
<Crab_> so, if we have 'ai/ais/zzz' which, say, defines a macro, it might get included by campaigns/bbb/scenarios/some_scenario.cfg , even if it is not inside /campaigns/bbb/scenarios

For that we have 2 cases:
{~file/dir path}
or
{file/dir path}

The paths are simply discarded if the current project's directory name is not found in the path.

Currently the so called "Tree" will be actually just a List or a single path tree. For the first iteration of this project, I won't tackle the advanced macro usage that might direct the flow based on defines (this will be optional if there will be time in GSoC, or if not, after GSoC, since I plan to remain active developer to maintain the plugin/enhance it furthermore). So, for example (taken from LoW):

#ifdef CAMPAIGN_LOW

{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#endif

#ifdef MULTIPLAYER

#define EASY
#enddef
{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#undef EASY
...
#endif

With current way to do this we will just take "blindly" all included directories/files without taking in consideration the #define flow control.

If we are at LoW, the following tree(list) will be created on its project:

_main.cfg -> utils/*.cfg -> scenarios/*.cfg -> units/*.cfg

Each file in the dependency tree, will have associated a number. For more details on why this and how it's done, read the Scoping section.

===Scoping===
In order for the plugin to know more about the semnatics, it should have the posibility to represent scopes. The scopes will be used mainly for variables and macros.

The Scoping is a delicate problem, because there are some tricky situations that might interfere with the scoping. I choosed to represent scoping in the following way:

Scoping is everything just about order relations. That is, we will compare numbers when dealing with scoping. With that we move the "problem" upper, to the "Dependency tree". We won't use filenames/paths because:

* The filename might change, but the order index may not. So, not having to update the index helps us.
* Number comparison is faster than string comparison.

So, from now on we'll talk in terms of indexes instead of filenames for scoping.

So, we are working with numbers. But there is still a lil' problem. What happens, when we remove/need to add a new file in the current tree, in the middle of existing 2? We would need to update all subsequent files's indexes. That would not be so ok performance wise.

To counter this problem we will not use consecutive numbers, but rather have a certain step between numbers. The step might be configured inside the plugin based on real statistics (for example, trying to see the number of cfg files per project. Taking a big number, like 1000 won't really hurt). For example, we could take the step 50. That means we would have the following tree for LoW:

0 50 100
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

instead of:
0 1 2
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

So, when it's the case of insertion, we insert the new node at the ''middle'' of the current "distance". That way we may insert/delete files *without* breaking the order, and our scoping will still work.

There is another problem it rised in my head: how do we know when to put the number as the next step (the previous number + step) or add it in the middle? Well, since every project will surely do a '''Full Build''', we'll use that oportunity to create the initial tree. Afterwards we will just insert files based on the halving of the distance between 2 indices.

The scoping will be represented by a simple structure, consisting of start index and offset and end index and offset.

===Content Assist Config(CAC) Files===
The CAC files will provide values that are default/available to config files from the wesnoth engine itself. There will be several files that define the values based on their context. This will allow a very great flexibility editing the CA list.

A CAC file will be just a simple text file, that has on each line one (or more) value(s) depending on the context.

* The ''cac/variables.txt'' will contain variables available. The list is currently available at [http://wiki.wesnoth.org/VariablesWML#Automatically_stored_variables]. For example the file could look like:
$side_number
$turn_number
...

* The ''cac/events.txt'' will contain the game events. The list is availabe at: [http://wiki.wesnoth.org/EventWML#Predefined_.27name.27_Key_Values]. Since the events that have spaces in their names can replace that with an underscore '_', the file will contain the underscore instead space variants also.



===Variables===
The variables are either defined by user or defined by default by the wesnoth engine. User's variables will be parsed from each processed file by the WesnothProjectBuilder, using the WMLSaxHandler. The default variables will be parsed and added from the CAC file. (cac/variables.txt)

Variables definitions can be triggered using the VARIABLE macro:
{VARIABLE var_name "value"}
or the [set_variable] tag:
[set_variable]
name=my_var
value="value"
[/set_variable]

The ''ConfigFile'' class in the ''org.wesnoth.wml.core'' already has a list of variables. The ''Variable'' class has some fields that allow its identification. We will build that list when we parse each file, adding each variable found by the previous defined triggers.
When the content assist finds the '$' character, it will supply the user + default variables gathered so far.

Since the variables can be cleared, thus they have scope, the ''Variable'' class needs to be refactorted, so it can represent the scope aswell. The scoping was settled before.

===Name Collisions===
I've considered that we should store the variables per project, like we currently do with macros. This will minimize the memory we need, rather than storing variables on each file - like we do currently. With this, I've discovered it's innevitable to have ''collisions''. That is, have the same variable name on multiple files.

To solve this problem, each variable/macro structure, will not have just a single scope, but rather a list of scopes.

===Events===
Besides the default event names, supplied by the wesnoth engine, there can be created custom ones, wich will be triggered with [fire_event]. As usual the default events names will be available in the cac/events.txt file.

The events defined by the user will be parsed from the ''name'' attribute of the [event] tag.

===Attributes===
All attributes are currently got from the schema.cfg

===Attributes Values===
All attributes values should be parsed based on the schema.cfg.

===Macros===
The support for macros is already built in, but it needs a way to let them have scope. That is, when an #undef is found, the certain macro would not be available to subsequent files unless redeclared. This will be done with the aid of the dependency tree and scoping. The collisions will be solved like I said at the variables section

===Support for custom luaWML tags===
The lua can create new WML Tags. It would be nice that the plugin suggest those aswell besides the ''schema.cfg''. The lua will be easily parsed, since there is a simple pattern for creating new tags:
wesnoth.wml_actions.<tag name>(cfg)

The parser will just run over the lua code/file, over each line, trying to match the 'function *wesnoth.wml_actions.*' pattern. If it finds something, it will add the tag name to the list of tags. There is also a small thing we might have missed. The user could use a shorthand notation for the actions namespace, so when searching for the pattern, I will add to the 'pattern to match' list, the respective variable when searching for new WML Tags.

Thus, like the ''wml-tags.lua'' from the data/lua uses:
local wml_actions = wesnoth.wml_actions

the 'to match' list will contain: 'function *wesnoth.wml_actions.*' and 'function *wml_actions.*', thus finding other tags too.

Going further more, for an ''optional'' enhancement, I could also search that function to see if it needs/has some extra attributes. The attributes can be found by:
* function's parameter (usually cfg) is asked for a property. For example:
function wml_actions.terrain(cfg)
local terrain = cfg.terrain or helper.wml_error("[terrain] missing required terrain= attribute")
cfg = helper.shallow_literal(cfg)
cfg.terrain = nil
for i, loc in ipairs(wesnoth.get_locations(cfg)) do
wesnoth.set_terrain(loc[1], loc[2], terrain, cfg.layer, cfg.replace_if_failed)
end
end

Here we need the attributes ''terrain'', ''layer'' and ''replace_if_failed''.

* ''get_child'' call:
function wml_actions.message(cfg)
local show_if = helper.get_child(cfg, "show_if")
if not show_if or wesnoth.eval_conditional(show_if) then
engine_message(cfg)
end
end

Here we need to have the attribute ''show_if''.

==Automatic/headless building==
The eclipse plugins can be automatically built from command line, provided there is the eclipse sdk and the eclipse delta pack on the builder's machine. The plugin can also use Buckminster tool to automate the building of the plugin.

''Notes''
Add all plugin's files *inside* a folder to prevent cluttering the directory where it's extracted

More info at:
* http://wiki.eclipse.org/PDE/Build
* http://wiki.bioclipse.net/index.php?title=How_to_build_plugins_headless
* http://help.eclipse.org/galileo/index.jsp?topic=/org.eclipse.pde.doc.user/guide/intro/pde_overview.htm
* http://www.eclipse.org/articles/Article-PDE-Automation/automation.html

==Standalone app auto-update==
The current standalone application doesn't offer the same eclipse's update system. I will add it, so anytime there is a new version of the plugin, it can be updated with a single click by the user, without the needing to download a new standalone app again.

==Documentation==
===External documentation===
The current existing readme will be split in 2 manuals: User Manual and Developer Manual (Don't forget to add images where relevant).

The user manual will contain:
* Prerequisites and Installing the prerequisites
Note: don't forget to mention the MINIMUM eclipse/java version needed to run
* Installing the plugin / standalone version
* Using the plugin
* Plugin features
* Step-by-step use cases
** Setupping the workspace
** Creating a new project and running it in the game
** Importing existing projects
** Using the WML Editor
** Updating the plugin
* Frequently Asked Questions

The developer manual will contain:
* Prerequisites and Installing the prerequisites
* Adding the plugin's projects in the
* Compiling and Running the plugin
* Deploying the plugin and standalone app

===Internal documentation===
The Eclipse infrastructure has features for letting the developer embed help into the application, depending on the current context. After I will write the external documentation, I will work on adding internal documentation aswell. Some of it already comes from the external one.

* Plugin welcome page
* Eclipse Help (When pressing Help->Help contents)
* Wizards help

==Plugin polishing==
This are some tasks needed to be done in order to get the plugin more stable and more usable than it's currently. Some of the tasks are taken from my todo list. New tasks will be added through the project advancing when improvements to actual code /user interaction can be done, so this list is not final.

* Don't copy a project that belongs to data/campaigns to the user addons's directory. This can be done by looking at the path when creating a new project. (This is prevented by not spawning a ''build.xml'' file in the campaigns's directory)
* Enhance the logging so it can help debugging other's problem much easier. I could split the current log in 2:
** Commands executed by the plugin
** Other information like parsed information/statuses
* Enhance the integration with the eclipse platform by adding the "Wesnoth" related wizards directly to the "New" menu.
* Allow users to import a directory as a wesnoth project. Under the hood it will either open the wesnoth project (if there is any .project files in it) or create a new empty project on it.
* Allow the user to clear it's current plugin's settings just with a simple button.
* Wesnoth Project Explorer - Add error markers just like the Java Explorer has
* Refactor the current way of getting the macro list. Currently if there is no _main.cfg practically the _MACROS_.cfg file is not built resulting in no MACRO suggestions.
* Create a view filter to hide the Project ''_AutoLinked_CFGExternalFiles_'' which is created for opening the external config files (external meaning outside the current workspace).
* Fix the F3 navigation when the map's location is specified withing " ", as a string.

===New parsing method (optional)===
The current parsing method involves a lot of Wesnoth preprocessor/wmlparser.py. This is doing somehow the parsing job double. This is because the xtext framework already does 1 pass over the files when added to the project. My plan is to see if I can reuse the already built AST(Abstract Syntax Tree) and the parse tree, to use those values instead of additional preprocessing/wmlparsing, and use the latter only when really needed.

Using the xtext's model will greatly fasten the "build" time of each project and it will be *much* simpler to work with, since the framework already provides exceptions recovering (that is, when the code is not well formed according to the grammar) and based on the defined grammar the respective tokens. So, for example instead using 2 another external processes, we could just iterate over each WMLTag and get it's WMLKeys and parse their individual values.

If this idea works, I will add it on the Plugin polishing tasks.

==Other ideas==
===Addons management===
There will be a new Addons management view. It will behave much like the in-game addon manager, but it will be more handy since the user doesn't need to start the game for that (and also wait till the cache refreshes after downloading it). This view will be based on the python script from '''data/tools/wesnoth_addon_manager''', like it does currently for uploading the project as an addon.

The view will let the user see the list/details for each of the addons currently on the server. There will be also a filter based on what addon server to use (trunk/1.8/1.9/etc)

The user will be able to just right click on an addon and download it to it's user data folder. Optionally a new project will be created, based on the just downloaded addon.



===Unit testing===
====Grammar====
For a better wml handling with in the editor, I will create a Testing class for the current grammar. The class will do testing on all *.cfgs in the data directory. That way after modifing something in the grammar we will be able to see how many errors we have introduced/eliminated. This will greatly help the developing of a better grammar that can hold all current WML formats.

''Notes'':
optionally rework the grammar and try to use a custom lexer/parser in order to benefit from the preprocessor, injecting the valid tokens. This would help the cases when the current grammar doesn't work:
{name} = value
or unclosed tags

====Parsing and getting information from files====
I will create some basic (or taken from existing campaigns) config files that will be parsed in order to check if the correct behaviour - correct information is extracted from the files.

This will check for extracting the:
scenario name
campaign name
next_scenario
first_scenario
variables
macros

=Timeline=
The GSOC period is between 24th May and 20th August. But since I have exams for 3 weeks (during 30.05-19.06.2011), I will start working on the plugin before the 24th of May, to recover some of the lost time. Also, my ImagineCup team made it to the national phase - that is in 5,6,7 May. That means till that time I will not be able to do so much work, so I'll make the timeline according with the starting of work on 9 May.

Here is a table with key periods of the time spent on this project.
{| border="1"
|'''Period''' || '''Actions'''
|-
| 26 April || Get accepted
|-
| 26 April - 8 May || Busy working on ImagineCup project for the national phase. Little or no work done.
|-
| 9 May - 15 May || Allow headless build of the plugin
|-
| 16 May - 22 May || Add Support for multiple installations
|-
| 23 May - 28 May || Add the auto-update feature for the standalone app
|-
| 30 May - 19 June || Exams
|-
| 20 June - 24 June || Create the external documentation
|-
| 25 June - 16 July || Enhance Content Assist
|-
| 15 July || Mid-term evaluations deadline
|-
| 17 July - 24 July || Addons management view
|-
| 25 July - 30 July || Unit tests
|-
| 1 August - 14 August || Do the Plugin polishing tasks
|-
| 15 August || Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc.
|-
| 15 August - 17 August || Create the internal documentation.
|-
| 18 August - 22 August || Buffer half-week. This will be used in case some tasks fell a bit outside their proposed time.
|-
| 22 August || Firm 'pencils down' date. Mentors, students and organization administrators can begin submitting final evaluations to Google.
|}

=Tasks=
This is a list of the "atomic" tasks that need to be done, based on the project part. Since the big tasks are split into smaller task, the progress will be seen better and any problems that arise with the timeline will be seen faster. I will update this table based on my current progress.

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Headless build ||Research about what system to use for automatic building of the plugin || Done
|-
| Headless build || Implement the chosen system for the wesnoth plugin|| Done
|-
| Multiple installations || Implement the preferences pages || Done
|-
| Multiple installations || Implement the logic for saving and loading the installation's paths on the disk || Done
|-
| Multiple installations || Implement the project preferences page || Done
|-
| Multiple installations || Rewrite the current mechanisms that use the paths to use the ones based on the project. || Done
|-
| Auto-update || Implement the auto-update feature. || In progress
|-
| Documentation || Write the User Manual || Done
|-
| Documentation || Write the Developer Manual || Done
|-
| Documentation || Write the internal documentation || Done
|-
| Enhance Content Assist || Project dependency tree || In progress
|-
| Enhance Content Assist || Content assist files || None
|-
| Enhance Content Assist || Variables || None
|-
| Enhance Content Assist || Events || None
|-
| Enhance Content Assist || Lua tags || None
|-
| Addon management || Create the GUI of the view || None
|-
| Addon management || Create the view's logic || None
|-
| Unit testing || Tests for the grammar || None
|-
| Unit testing || Tests for parsing the config files || None
|}

Optional tasks will be dealt with if the time allows it:

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Enhance Content Assist || Project dependency tree with multiple paths based on defines || None
|-
| Enhance Content Assist || Lua tags attributes || None
|-
| Grammar || Enhance the grammar to support the 2 current unsupported syntax constructs || None
|-
| Documentation || Implement a simple WML project from start to end using Help's built-in cheat sheets tutorial || None
|}

=Questionnaire=
The questionnaire can be found here: http://wiki.wesnoth.org/User:Timotei21/Questionaire

User:Timotei21/Questionaire

2011-07-02T11:39:45Z

Timotei21: /* Questionnaire */

=Questionnaire=
<h3>Basics</h3>

<h4>Write a small introduction to yourself.</h4>
My name is Timotei Dolean, 21 years old and I'm from Cluj, Romania. I'm one of the best students in my year, and I've decided to participate in another GSoC. I'm also very passionate about programming, doing it my spare time and also having fun with other people/my friends.

<h4>State your preferred email address.</h4>
user: {timotei_cluj} __at__ domain:{"yahoo" ,"co", "uk"}

<h4>If you have chosen a nick for IRC and Wesnoth forums, what is it?</h4>
timotei,timotei21 - IRC, timotei - forums

<h4>Why do you want to participate in summer of code?</h4>
I have participated last year and it was an '''awesome''' experience. I've learn a lot of new things, and I've made friends as well. Provided that, I shall go again for a GSoC experience. Also, another reason would be the one that I really wish to finish the work started last summer, so the eclipse plugin will be polished and much stable, so it can become "de facto" for developing UMC content. Since the summer will be holiday for me, GSoC will help me use the holiday at its fully extend, by flipping bits not burgers :P, and the stipend will be very good to have.

<h4>What are you studying, subject, level and school? </h4>
I'm currently 2st year undergraduate at the Technical University of Cluj-Napoca, Computer Science.

<h4>What country are you from, at what time are you most likely to be able to join IRC?</h4>
I'm from Romania, Eastern Europe (Timezone: UTC +2). Usually I'm available for about 2-8 hours a day, but in the day-time - I better sleep in the night, so I can start earlier the next day. In general, based on my current schedule I'll be available: Monday: 18-22 UTC+2, Tuesday: 8 - 22 UTC+2, Wednesday: 16 - 22 UTC+2, Thursday: 16 - 22 UTC+2, Friday-Sunday: 8-22 UTC+2.

<h4>Do you have other commitments for the summer period? Do you plan to take any vacations? If yes, when.</h4>
Like every student, I'll have exams in the following period: 30.05-19.06.2010, that's 3 weeks. So in that period the time for development will be slowed down a lot, to almost none - depends a lot of the time I need to dedicate for each exam. Because of that, I will start the work faster than the official time, so I can recover the "lost" time.

<h3>Experience</h3>

<h4>What programs/software have you worked on before?</h4>
<ul><li>InfoCenter - application for aiding high-school students in learning the C++ language. This is the biggest project I have ever worked on. (technologies and tools used in development: Visual Studio, C#, SVN, XML, MS Access Database, ReSharper)
</li>
<li>Lineage 2 Launcher & Server – application for launching and updating the “Lineage 2” game from a web server, registration on the server for new users. The game was used to connect to my custom “Lineage 2 MMORPG” server (the server was developed in java by an existing open-source community - l2jserver). I modified the server adding new features, fixing bugs and making my own version of game play, not seen on other servers. ( technologies and tools used: Java, Eclipse, SVN – server; C#/.NET/MySQL - launcher)</li>
<li>vLessons – prototype application for a future e-learning application. (Project done as an assignment for courses; technologies and tools used: SQLite, QTCreator, C++)</li>
<li>Y! Detector – prototype application that scans a specified Yahoo! Messenger user for being offline/invisible, and retrieving his/her avatar from the Yahoo servers. (technologies and tools: VS, C#) </li>
<li>Websites – built many custom websites for friends, companies and my high-school.</li>
<li>XNA Game – I have worked on a XNA game with a friend, for participating in the Game Design competition at Imagine Cup; Dream-build-play contest and IGF (Independent Games Festival). (website: http://awkwardgames.wordpress.com/shade/)</li>
<li>Pure Assembly Game - I have made a simple 16-bit assembly game, space invaders, just for fun an experiencing with assembly. Code: http://dl.dropbox.com/u/462510/portofolio/spaceinvaders/spacein.asm | Compiled exe runnable in DosBox: http://dl.dropbox.com/u/462510/portofolio/spaceinvaders/SPACEIN.EXE</li>
<li>Battle for Wesnoth - I have created the eclipse UMC plugin as part of Google Summer of Code 2010, a fabulous tool that helps the UMC Creators to create/develop faster new addons or edit the current ones. The tools'homepage is: www.eclipse.wesnoth.org</li>
</ul>

<h4> Have you developed software in a team environment before? (As opposed to hacking on something on your own)</h4>
Yes. For the XNA Game I've worked with another friend. For an AI project, I've worked with 2 friends. Both times we used SVN to synchronize our modifications. I have also worked with another colleague for a school project. Currently I'm working with another 3 friends on a software solution for the ImagineCup competition.

<h4>Have you participated to the Google Summer of Code before? As a mentor or a student? In what project? Were you successful? If not, why?</h4>
Yes. I have participated to GSoC last year, in 2010, as a student. My mentor was fendrin and I have worked on the Eclipse UMC plugin. The project was successful, although I haven't really finished all task I proposed.

<h4>Are you already involved with any open source development projects? If yes, please describe the project and the scope of your involvement.</h4>
Yes I am. I am developer for Battle For Wesnoth, maintainer for the Eclipse UMC Plugin. I usually fix bugs and add new features (depends on my time if that allows it). Also, about 4 years ago I worked on an open-source project (http://l2jserver.com | http://l2jfree.com) with some friends, modifing the existing files, adding new features and fixing existing bugs, so we could make our own version of the server (if you want you can take a look at an older .diff file here: http://wesnoth.pastebin.com/bGyJ87eY - this was written when my experience/coding style wasn't so good)

<h4>Gaming experience - Are you a gamer?</h4>
I like a lot playing games, especially indie ones. My first contact with video games was with a NES console. After that it followed the PC, starting with very low power configurations but increasing to better ones. So, there were games that I played in low graphics mode, but that didn't stop me from playing them. The gameplay was almost everything.

<h5>What type of gamer are you?</h5>
There are games at which I'm a master, but there are some games in which I am really bad. I know well the DoTa game - a map for Warcraft3 - I was the best in my high-school, and I play racing games in general. I go mainly for gameplay/story rather than for the graphics. In the last months I played minecraft.

<h5>What type of games? </h5>
Sorted by "I like more": Mmorpg/Indie/racing/rpg/adventure/shooters. I played too many games to enumerate them, but some of my favorites: Lineage 2, World of Warcraft, Braid, World of Goo, Warcraft3 (Dota), Need for Speed, Unreal Tournament 3, Minecraft.

<h5>What type of opponents do you prefer? </h5>
If it's AI, then I prefer an adaptive one, growing in the difficulty as the game progresses. If it's human, I like all types, including campers because even this type of opponent is good, because it forces you to develop new strategies to try take it down.

<h5>Are you more interested in story or gameplay? </h5>
It depends a lot on the mood and game type. In a fast-paced game (fighting/race/etc) I would like the gameplay to be very good. If It's an adventure for example, I would like it to have a good story.

<h5>Have you played Wesnoth? If so, tell us roughly for how long and whether you lean towards single player or multiplayer. </h5>
Yes. I have played some parts of the campaigns. I also played on Gambit's multiplayer map "Breaking Ground" - I'd still play that because I won't get bored. I like better the multiplayer ones since they engage more people and it's more fun.

<h4>If you have contributed any patches to Wesnoth, please list them below. You can also list patches that have been submitted but not committed yet and patches that have not been specifically written for GSoC. If you have gained commit access to our SVN (during the evaluation period or earlier) please state so. </h4>
Yes. I have contributed with some patches before last GSoC. After that, till now I have commit access on the SVN.

<h3>Communication skills </h3>

<h4>Though most of our developers are not native English speakers, English is the project's working language. Describe your fluency level in written English.</h4>
My writing in English is pretty good because I speak sometimes with other peoples, which are not Romanian. Also I spent a week with some students that came in Romania from U.S.; when I was Game Master on the L2Server I had to talk in English and try to understand every "variance" of the standard English, so I think I could understand most of the terms. Also, since when I was involved with wesnoth since last year, I can say that both my spoken and written english have improved - thanks especially to Espreon and shadowmaster who kept correcting me on each mispelled/wrong word.

<h4>What spoken languages are you fluent in?</h4>
Romanian and English.

<h4>Are you good at interacting with other players? Our developer community is friendly, but the player community can be a bit rough.</h4>
I'm a very "enduring" when receiving harsh criticisms and I am well-tempered. Is it very hard to upset me. Also I know how to separate feedback (constructive criticism) and useless criticisms.

<h4>Do you give constructive advice? </h4>
Yes. Usually I tend to help people in their problems more than necessary, just to be sure of it, by providing feedback and ideas.

<h4>Do you receive advice well? </h4>
Yes.

<h4>Are you good at sorting useful criticisms from useless ones?</h4>
Yes.

<h4>How autonomous are you when developing ? Would you rather discuss intensively changes and not start coding until you know what you want to do or would you rather code a proof of concept to "see how it turn out", taking the risk of having it thrown away if it doesn't match what the project want</h4>
Somehow between. It depends a lot of my knowledge in that area. If I have enough spare time to try it and know what I have/want to do, I'll do it, providing some results to support my changes. Otherwise, I would wait for the dev guys confirmation.

<h3>Project</h3>

<h4>Did you select a project from our list? If that is the case, what project did you select? What do you want to especially concentrate on?</h4>
I want to work on improving the Eclipse UMC Plugin. Idea's page is: http://wiki.wesnoth.org/SoC_Ideas_Eclipse_Plugin2011. I want to focus on getting the plugin more stable so it can be used even on slower PCs.

<h4>If you have invented your own project, please describe the project and the scope.</h4>
I haven't invented one.

<h4>Why did you choose this project?</h4>
I chose this project because I've worked on it last summer. I know my way around and this GSoC year will give me the opportunity to finish the plugin so it can be properly used by all UMC Authors, like a tool they won't want to stop using. Of course, since the eclipse framework is written in java, the performance might won't be so good on slower PCs,but, depending on the plugin's tools/available options, it may replace even the emacs WML mode, or other tools used currently for writing UMC.

<h4>Include an estimated timeline for your work on the project. Don't forget to mention special things like "I booked holidays between A and B" and "I got an exam at ABC and won't be doing much then".</h4>
See [[SummerofCode2011_Timotei21#Timeline|Timeline]]

<h4>Include as much technical detail about your implementation as you can</h4>
See [[SummerofCode2011_Timotei21#Proposal_Summary|Proposal Summary]]

<h4>What do you expect to gain from this project?</h4>
The thing I'm expecting now, is that the wesnoth community will use the plugin after the 1.9.x branch is getting stable. Aside from this, I'm expecting consolidate my java/eclipse framework knowledge and my coding skills performance-wise.

<h4>What would make you stay in the Wesnoth community after the conclusion of SOC? </h4>
The people I'm working with, the friends made during the "coding" period. If there is need to enhance the plugin I did, I will continue to improve it. The knowledge I gathered directly or indirectly from other wesnoth members was very beneficial for me. Thus, I'm gonna continue being (as times allows me) a maintainer for the eclipse plugin, and if there is the need, to get my hands on other wesnoth's areas too.

<h4>Practical considerations</h4>

<h4>Are you familiar with any of the following tools or languages?</h4>
* Subversion (used for all commits)
Yes. I used subversion for many projects. Right now I prefer using git svn wrapper instead of svn command line/tortoise svn.
* C++ (language used for all the normal source code)
Yes. I've worked with C/C++ for 3 years for different projects and programming contests.
* STL, Boost, SDL (C++ libraries used by Wesnoth)
STL: Only used small parts from it.
Boost: Didn't used it but I know what it offers.
SDL: No.
* Python (optional, mainly used for tools)
No, but I've written some scattered bits of code.
* build environments (eg cmake/autotools/scons)
CMake, Ant - basic usage.
* WML (the wesnoth specific scenario language)
I know just its syntax and some tags/attributes.
* Lua (used in combination with WML to create scenarios)
No. But wishing a lot to learn it.

<h4>Which tools do you normally use for development? Why do you use them?</h4>
I use Visual Studio(C#,C/C++), Expression Studio(C#, WPF), Eclipse(java, php) and (g)vim for short and fast C/C++ programs/scripts. Visual Studio is IMHO the best IDE alongside with Eclipse. The only thing why I didn't move completely from VS to Eclipse, is the enhanced debugger of VS and the very low support for C# in eclipse. Lately, I've started using gvim for more and more tasks that involve writing text. Also, for projects that need more than 2-3 days of development, I use a local git for keeping the changes.

<h4>What programming languages are you fluent in?</h4>
C#, C/C++, Java, Assembly

<h4>Would you mind talking with your mentor on telephone / internet phone? We would like to have a backup way for communications for the case that somehow emails and IRC do fail. If you are willing to do so, please do list a phone number (including international code) so that we are able to contact you. You should probably *only* add this number in the application for you submit to google since the info in the wiki is available in public. We will *not* make any use of your number unless some case of "there is no way to contact you" does arise!</h4>
I won't mind. Even though I think it won't be needed, I will provide the telephone number in the application sent to google.

SummerofCode2011 Timotei21

2011-06-29T18:12:10Z

Timotei21: update progress

{{SoC2011Student_2|timotei|SoC_Ideas_Eclipse_Plugin2011}}

=Description=
<h4>timotei - Improving the Eclipse Plugin</h4>
I aim at improving the plugin, so it will become the tool used by all UMC Authors. That is, UMC Authors will get rid of the lot of different tools they use for different tasks (for example the Emacs WMLMode/other plugins for different text editors), and instead use one single unified Tool that will speed up the development. My target is to make this plugin a complete and very stable suite for all umc tasks that don't need specialized software - like a graphics editor, so I'd like to have this oportunity to finish it in the good sense.

=Contacts=
==IRC==
timotei

==Other==
Forum: timotei 
gna.org: timotei

=SoC Application=
[http://www.google-melange.com/gsoc/proposal/review/google/gsoc2011/timoteidolean/1 Battle for Wesnoth - Google Summer of Code Application]

=Proposal Summary=
Page Last Updated: {{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}} 

In the following lines I will give details on how I'm planning to implement some of the required tasks, and also add some new ones.

The ''Notes'' sections are aimed for personal guideliness. They are took from my todo list.

==Multiple Wesnoth installations==
Having multiple wesnoth setups, and working with them at the same time would be nice to be done from inside the plugin.
For that, there will be a new preferences page. The page will look something like this:
http://dl.dropbox.com/u/462510/personal/soc/installations_management.PNG

There will be buttons that add/remove/edit a certain wesnoth installation. When adding/editing an installation, a new page like the current one (in which we set the paths), will be shown. The user will be able to name it and specify the version (I could automatically get the version by invoking ''wesnoth --version'').
The current page for setting the paths will act as a default installation.

After we have configured the paths, the user can chose the installation to which the (new) projects are bound, by opening the project properties. There will be a wesnoth-related page, where the user will be able to chose to what installation the project binds. With that, every command that uses the paths, won't use the single current paths, but the ones assigned to each project. This project properties page will open new ways for adding new

There would be a problem in case the project will be migrated between 2 different plugin's versions. For example, in one place we would have defined "1.9.4svn" but on the other there would be "trunk".

We can solve this in 3 ways:

# Alert the user that the installation doesn't bind, and let him chose the current matching installation for his plugin.
# Default automatically to the current plugin's default installation.
# "Hardcode" the version, so that there may be defined just installations like: 1.8.0, 1.9.3. With this we lose some flexibility, but we could use this as base version for new installations, so for example, a user can have two 1.9.3 installations. Provided this, we have again a possible problem, which can be solved again by 1. or 2., but this time, trying to match the base version first.

With this feature, the user won't need to restart the plugin at all, switching workspaces.

Regarding the technical PoV, all paths will be stored using eclipse's preferences system, by appending an unique id of each installation to each path in that set.

''Note'':
Add the NO_TERRAIN_GFX preprocess option checkbox to the project properties rather than being a global one.

==Enhance the Content Assist(CA) feature==
The CA framework is very extensible but it lacks proper contexts for providing the content.
I was thinking of trying to accomplish the generating of CA list either by using a config file, in case something like that can be used or writing directly the code that does that.

Another factor that is involved in a better auto-complete, is the ''schema.cfg'' the plugin bases on. Depending on whether the schema is worked on during this summer of code, I'll need to redo a bit the parser of the schema, in case the format/semantics change.

===Project files dependecy tree===
In order for the CA to work better - and maybe other areas would benefit from this - we will need to build a project files tree. With that tree, we can see how a certain declared macro/variable will affect subsequent related files and also their scope. Basically, we can see the relation from a file to anothers.

This tree will be (re)built in 2 situations:
# A file is added/removed/changed it's name
# A full rebuild is triggered (for example, the project is added for the first time in the workspace)

The tree will be built by the WML parser's rules:
# files are processed in the alphabetically order
# _initial.cfg is the first processed before anything else.
# _final.cfg is the last processed after anything else.
# if there is a _main.cfg in the directory, it is the only one processed.

Since the current ''WesnothProjectBuilder'' doesn't take in account the previous rules, I will create my own method of visiting each folder's children in the correct order. This method will look close to wesnoth's one, namely ''get_files_from_in_dir()'' found in ''src/filesystem.cpp:93''.

For a very fast lookup, as a data structure we will use a Hashtable, which has as the key the local project path to the file, and as a value a custom structure, which has the previous/next/parent/son properties, used to traverse the tree. The previous/next go on the same tree level, while the parent/son go up/down in the tree. I will use this instead of a tree, because this will give us access to info about a file, faster, in O(1) compared to a breadth-first search which has O(V+E) - where V is number of vertices and E number of edges.

Talking with Crab about this, he alerted me about a little possible problem with current aproach:
<Crab_> a note about 'The tree will be built by the WML parser's rules: ' - don't forget that you can (conditionally) include files/dirs from a file.
<Crab_> so, if we have 'ai/ais/zzz' which, say, defines a macro, it might get included by campaigns/bbb/scenarios/some_scenario.cfg , even if it is not inside /campaigns/bbb/scenarios

For that we have 2 cases:
{~file/dir path}
or
{file/dir path}

The paths are simply discarded if the current project's directory name is not found in the path.

Currently the so called "Tree" will be actually just a List or a single path tree. For the first iteration of this project, I won't tackle the advanced macro usage that might direct the flow based on defines (this will be optional if there will be time in GSoC, or if not, after GSoC, since I plan to remain active developer to maintain the plugin/enhance it furthermore). So, for example (taken from LoW):

#ifdef CAMPAIGN_LOW

{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#endif

#ifdef MULTIPLAYER

#define EASY
#enddef
{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#undef EASY
...
#endif

With current way to do this we will just take "blindly" all included directories/files without taking in consideration the #define flow control.

If we are at LoW, the following tree(list) will be created on its project:

_main.cfg -> utils/*.cfg -> scenarios/*.cfg -> units/*.cfg

Each file in the dependency tree, will have associated a number. For more details on why this and how it's done, read the Scoping section.

===Scoping===
In order for the plugin to know more about the semnatics, it should have the posibility to represent scopes. The scopes will be used mainly for variables and macros.

The Scoping is a delicate problem, because there are some tricky situations that might interfere with the scoping. I choosed to represent scoping in the following way:

Scoping is everything just about order relations. That is, we will compare numbers when dealing with scoping. With that we move the "problem" upper, to the "Dependency tree". We won't use filenames/paths because:

* The filename might change, but the order index may not. So, not having to update the index helps us.
* Number comparison is faster than string comparison.

So, from now on we'll talk in terms of indexes instead of filenames for scoping.

So, we are working with numbers. But there is still a lil' problem. What happens, when we remove/need to add a new file in the current tree, in the middle of existing 2? We would need to update all subsequent files's indexes. That would not be so ok performance wise.

To counter this problem we will not use consecutive numbers, but rather have a certain step between numbers. The step might be configured inside the plugin based on real statistics (for example, trying to see the number of cfg files per project. Taking a big number, like 1000 won't really hurt). For example, we could take the step 50. That means we would have the following tree for LoW:

0 50 100
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

instead of:
0 1 2
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

So, when it's the case of insertion, we insert the new node at the ''middle'' of the current "distance". That way we may insert/delete files *without* breaking the order, and our scoping will still work.

There is another problem it rised in my head: how do we know when to put the number as the next step (the previous number + step) or add it in the middle? Well, since every project will surely do a '''Full Build''', we'll use that oportunity to create the initial tree. Afterwards we will just insert files based on the halving of the distance between 2 indices.

The scoping will be represented by a simple structure, consisting of start index and offset and end index and offset.

===Content Assist Config(CAC) Files===
The CAC files will provide values that are default/available to config files from the wesnoth engine itself. There will be several files that define the values based on their context. This will allow a very great flexibility editing the CA list.

A CAC file will be just a simple text file, that has on each line one (or more) value(s) depending on the context.

* The ''cac/variables.txt'' will contain variables available. The list is currently available at [http://wiki.wesnoth.org/VariablesWML#Automatically_stored_variables]. For example the file could look like:
$side_number
$turn_number
...

* The ''cac/events.txt'' will contain the game events. The list is availabe at: [http://wiki.wesnoth.org/EventWML#Predefined_.27name.27_Key_Values]. Since the events that have spaces in their names can replace that with an underscore '_', the file will contain the underscore instead space variants also.



===Variables===
The variables are either defined by user or defined by default by the wesnoth engine. User's variables will be parsed from each processed file by the WesnothProjectBuilder, using the WMLSaxHandler. The default variables will be parsed and added from the CAC file. (cac/variables.txt)

Variables definitions can be triggered using the VARIABLE macro:
{VARIABLE var_name "value"}
or the [set_variable] tag:
[set_variable]
name=my_var
value="value"
[/set_variable]

The ''ConfigFile'' class in the ''org.wesnoth.wml.core'' already has a list of variables. The ''Variable'' class has some fields that allow its identification. We will build that list when we parse each file, adding each variable found by the previous defined triggers.
When the content assist finds the '$' character, it will supply the user + default variables gathered so far.

Since the variables can be cleared, thus they have scope, the ''Variable'' class needs to be refactorted, so it can represent the scope aswell. The scoping was settled before.

===Name Collisions===
I've considered that we should store the variables per project, like we currently do with macros. This will minimize the memory we need, rather than storing variables on each file - like we do currently. With this, I've discovered it's innevitable to have ''collisions''. That is, have the same variable name on multiple files.

To solve this problem, each variable/macro structure, will not have just a single scope, but rather a list of scopes.

===Events===
Besides the default event names, supplied by the wesnoth engine, there can be created custom ones, wich will be triggered with [fire_event]. As usual the default events names will be available in the cac/events.txt file.

The events defined by the user will be parsed from the ''name'' attribute of the [event] tag.

===Attributes===
All attributes are currently got from the schema.cfg

===Attributes Values===
All attributes values should be parsed based on the schema.cfg.

===Macros===
The support for macros is already built in, but it needs a way to let them have scope. That is, when an #undef is found, the certain macro would not be available to subsequent files unless redeclared. This will be done with the aid of the dependency tree and scoping. The collisions will be solved like I said at the variables section

===Support for custom luaWML tags===
The lua can create new WML Tags. It would be nice that the plugin suggest those aswell besides the ''schema.cfg''. The lua will be easily parsed, since there is a simple pattern for creating new tags:
wesnoth.wml_actions.<tag name>(cfg)

The parser will just run over the lua code/file, over each line, trying to match the 'function *wesnoth.wml_actions.*' pattern. If it finds something, it will add the tag name to the list of tags. There is also a small thing we might have missed. The user could use a shorthand notation for the actions namespace, so when searching for the pattern, I will add to the 'pattern to match' list, the respective variable when searching for new WML Tags.

Thus, like the ''wml-tags.lua'' from the data/lua uses:
local wml_actions = wesnoth.wml_actions

the 'to match' list will contain: 'function *wesnoth.wml_actions.*' and 'function *wml_actions.*', thus finding other tags too.

Going further more, for an ''optional'' enhancement, I could also search that function to see if it needs/has some extra attributes. The attributes can be found by:
* function's parameter (usually cfg) is asked for a property. For example:
function wml_actions.terrain(cfg)
local terrain = cfg.terrain or helper.wml_error("[terrain] missing required terrain= attribute")
cfg = helper.shallow_literal(cfg)
cfg.terrain = nil
for i, loc in ipairs(wesnoth.get_locations(cfg)) do
wesnoth.set_terrain(loc[1], loc[2], terrain, cfg.layer, cfg.replace_if_failed)
end
end

Here we need the attributes ''terrain'', ''layer'' and ''replace_if_failed''.

* ''get_child'' call:
function wml_actions.message(cfg)
local show_if = helper.get_child(cfg, "show_if")
if not show_if or wesnoth.eval_conditional(show_if) then
engine_message(cfg)
end
end

Here we need to have the attribute ''show_if''.

==Automatic/headless building==
The eclipse plugins can be automatically built from command line, provided there is the eclipse sdk and the eclipse delta pack on the builder's machine. The plugin can also use Buckminster tool to automate the building of the plugin.

''Notes''
Add all plugin's files *inside* a folder to prevent cluttering the directory where it's extracted

More info at:
* http://wiki.eclipse.org/PDE/Build
* http://wiki.bioclipse.net/index.php?title=How_to_build_plugins_headless
* http://help.eclipse.org/galileo/index.jsp?topic=/org.eclipse.pde.doc.user/guide/intro/pde_overview.htm
* http://www.eclipse.org/articles/Article-PDE-Automation/automation.html

==Standalone app auto-update==
The current standalone application doesn't offer the same eclipse's update system. I will add it, so anytime there is a new version of the plugin, it can be updated with a single click by the user, without the needing to download a new standalone app again.

==Documentation==
===External documentation===
The current existing readme will be split in 2 manuals: User Manual and Developer Manual (Don't forget to add images where relevant).

The user manual will contain:
* Prerequisites and Installing the prerequisites
Note: don't forget to mention the MINIMUM eclipse/java version needed to run
* Installing the plugin / standalone version
* Using the plugin
* Plugin features
* Step-by-step use cases
** Setupping the workspace
** Creating a new project and running it in the game
** Importing existing projects
** Using the WML Editor
** Updating the plugin
* Frequently Asked Questions

The developer manual will contain:
* Prerequisites and Installing the prerequisites
* Adding the plugin's projects in the
* Compiling and Running the plugin
* Deploying the plugin and standalone app

===Internal documentation===
The Eclipse infrastructure has features for letting the developer embed help into the application, depending on the current context. After I will write the external documentation, I will work on adding internal documentation aswell. Some of it already comes from the external one.

* Plugin welcome page
* Eclipse Help (When pressing Help->Help contents)
* Wizards help

==Plugin polishing==
This are some tasks needed to be done in order to get the plugin more stable and more usable than it's currently. Some of the tasks are taken from my todo list. New tasks will be added through the project advancing when improvements to actual code /user interaction can be done, so this list is not final.

* Don't copy a project that belongs to data/campaigns to the user addons's directory. This can be done by looking at the path when creating a new project.
* Enhance the logging so it can help debugging other's problem much easier. I could split the current log in 2:
** Commands executed by the plugin
** Other informations like parsed information/statuses
* Enhance the integration with the eclipse platform by adding the "Wesnoth" related wizards directly to the "New" menu.
* Allow users to import a directory as a wesnoth project. Under the hood it will either open the wesnoth project (if there is any .project files in it) or create a new empty project on it.
* Allow the user to clear it's current plugin's settings just with a simple button.
* Wesnoth Project Explorer - Add error markers just like the Java Explorer has
* Refactor the current way of getting the macro list. Currently if there is no _main.cfg practicaly the _MACROS_.cfg file is not built resulting in no MACRO suggestions.
* Create a view filter to hide the Project ''_AutoLinked_CFGExternalFiles_'' which is created for opening the external config files (external meaning outside the current workspace).
* Fix the F3 navigation when the map's location is specified withing " ", as a string.

===New parsing method (optional)===
The current parsing method involves a lot of Wesnoth preprocessor/wmlparser.py. This is doing somehow the parsing job double. This is because the xtext framework already does 1 pass over the files when added to the project. My plan is to see if I can reuse the already built AST(Abstract Syntax Tree) and the parse tree, to use those values instead of additional preprocessing/wmlparsing, and use the latter only when really needed.

Using the xtext's model will greately fasten the "build" time of each project and it will be *much* simpler to work with, since the framework already provides exceptions recovering (that is, when the code is not well formed according to the grammar) and based on the defined grammar the respective tokens. So, for example instead using 2 another external processes, we could just iterate over each WMLTag and get it's WMLKeys and parse their individual values.

If this idea works, I will add it on the Plugin polishing tasks.

==Other ideas==
===Addons management===
There will be a new Addons management view. It will behave much like the in-game addon manager, but it will be more handy since the user doesn't need to start the game for that (and also wait till the cache refreshes after downloading it). This view will be based on the python script from '''data/tools/wesnoth_addon_manager''', like it does currently for uploading the project as an addon.

The view will let the user see the list/details for each of the addons currently on the server. There will be also a filter based on what addon server to use (trunk/1.8/1.9/etc)

The user will be able to just right click on an addon and download it to it's user data folder. Optionally a new project will be created, based on the just downloaded addon.



===Unit testing===
====Grammar====
For a better wml handling with in the editor, I will create a Testing class for the current grammar. The class will do testing on all *.cfgs in the data directory. That way after modifing something in the grammar we will be able to see how many errors we have introduced/eliminated. This will greatly help the developing of a better grammar that can hold all current WML formats.

''Notes'':
optionally rework the grammar and try to use a custom lexer/parser in order to benefit from the preprocessor, injecting the valid tokens. This would help the cases when the current grammar doesn't work:
{name} = value
or unclosed tags

====Parsing and getting information from files====
I will create some basic (or taken from existing campaigns) config files that will be parsed in order to check if the correct behaviour - correct information is extracted from the files.

This will check for extracting the:
scenario name
campaign name
next_scenario
first_scenario
variables
macros

=Timeline=
The GSOC period is between 24th May and 20th August. But since I have exams for 3 weeks (during 30.05-19.06.2011), I will start working on the plugin before the 24th of May, to recover some of the lost time. Also, my ImagineCup team made it to the national phase - that is in 5,6,7 May. That means till that time I will not be able to do so much work, so I'll make the timeline according with the starting of work on 9 May.

Here is a table with key periods of the time spent on this project.
{| border="1"
|'''Period''' || '''Actions'''
|-
| 26 April || Get accepted
|-
| 26 April - 8 May || Busy working on ImagineCup project for the national phase. Little or no work done.
|-
| 9 May - 15 May || Allow headless build of the plugin
|-
| 16 May - 22 May || Add Support for multiple installations
|-
| 23 May - 28 May || Add the auto-update feature for the standalone app
|-
| 30 May - 19 June || Exams
|-
| 20 June - 24 June || Create the external documentation
|-
| 25 June - 16 July || Enhance Content Assist
|-
| 15 July || Mid-term evaluations deadline
|-
| 17 July - 24 July || Addons management view
|-
| 25 July - 30 July || Unit tests
|-
| 1 August - 14 August || Do the Plugin polishing tasks
|-
| 15 August || Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc.
|-
| 15 August - 17 August || Create the internal documentation.
|-
| 18 August - 22 August || Buffer half-week. This will be used in case some tasks fell a bit outside their proposed time.
|-
| 22 August || Firm 'pencils down' date. Mentors, students and organization administrators can begin submitting final evaluations to Google.
|}

=Tasks=
This is a list of the "atomic" tasks that need to be done, based on the project part. Since the big tasks are split into smaller task, the progress will be seen better and any problems that arise with the timeline will be seen faster. I will update this table based on my current progress.

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Headless build ||Research about what system to use for automatic building of the plugin || Done
|-
| Headless build || Implement the chosen system for the wesnoth plugin|| Done
|-
| Multiple installations || Implement the preferences pages || Done
|-
| Multiple installations || Implement the logic for saving and loading the installation's paths on the disk || Done
|-
| Multiple installations || Implement the project preferences page || Done
|-
| Multiple installations || Rewrite the current mechanisms that use the paths to use the ones based on the project. || Done
|-
| Auto-update || Implement the auto-update feature. || In progress
|-
| Documentation || Write the User Manual || Done
|-
| Documentation || Write the Developer Manual || Done
|-
| Documentation || Write the internal documentation || Done
|-
| Enhance Content Assist || Project dependency tree || In progress
|-
| Enhance Content Assist || Content assist files || None
|-
| Enhance Content Assist || Variables || None
|-
| Enhance Content Assist || Events || None
|-
| Enhance Content Assist || Lua tags || None
|-
| Addon management || Create the GUI of the view || None
|-
| Addon management || Create the view's logic || None
|-
| Unit testing || Tests for the grammar || None
|-
| Unit testing || Tests for parsing the config files || None
|}

Optional tasks will be dealt with if the time allows it:

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Enhance Content Assist || Project dependency tree with multiple paths based on defines || None
|-
| Enhance Content Assist || Lua tags attributes || None
|-
| Grammar || Enhance the grammar to support the 2 current unsupported syntax constructs || None
|-
| Documentation || Implement a simple WML project from start to end using Help's built-in cheat sheets tutorial || None
|}

=Questionnaire=
The questionnaire can be found here: http://wiki.wesnoth.org/User:Timotei21/Questionaire

SummerofCode2011 Timotei21

2011-06-28T14:44:02Z

Timotei21: update progress

{{SoC2011Student_2|timotei|SoC_Ideas_Eclipse_Plugin2011}}

=Description=
<h4>timotei - Improving the Eclipse Plugin</h4>
I aim at improving the plugin, so it will become the tool used by all UMC Authors. That is, UMC Authors will get rid of the lot of different tools they use for different tasks (for example the Emacs WMLMode/other plugins for different text editors), and instead use one single unified Tool that will speed up the development. My target is to make this plugin a complete and very stable suite for all umc tasks that don't need specialized software - like a graphics editor, so I'd like to have this oportunity to finish it in the good sense.

=Contacts=
==IRC==
timotei

==Other==
Forum: timotei 
gna.org: timotei

=SoC Application=
[http://www.google-melange.com/gsoc/proposal/review/google/gsoc2011/timoteidolean/1 Battle for Wesnoth - Google Summer of Code Application]

=Proposal Summary=
Page Last Updated: {{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}} 

In the following lines I will give details on how I'm planning to implement some of the required tasks, and also add some new ones.

The ''Notes'' sections are aimed for personal guideliness. They are took from my todo list.

==Multiple Wesnoth installations==
Having multiple wesnoth setups, and working with them at the same time would be nice to be done from inside the plugin.
For that, there will be a new preferences page. The page will look something like this:
http://dl.dropbox.com/u/462510/personal/soc/installations_management.PNG

There will be buttons that add/remove/edit a certain wesnoth installation. When adding/editing an installation, a new page like the current one (in which we set the paths), will be shown. The user will be able to name it and specify the version (I could automatically get the version by invoking ''wesnoth --version'').
The current page for setting the paths will act as a default installation.

After we have configured the paths, the user can chose the installation to which the (new) projects are bound, by opening the project properties. There will be a wesnoth-related page, where the user will be able to chose to what installation the project binds. With that, every command that uses the paths, won't use the single current paths, but the ones assigned to each project. This project properties page will open new ways for adding new

There would be a problem in case the project will be migrated between 2 different plugin's versions. For example, in one place we would have defined "1.9.4svn" but on the other there would be "trunk".

We can solve this in 3 ways:

# Alert the user that the installation doesn't bind, and let him chose the current matching installation for his plugin.
# Default automatically to the current plugin's default installation.
# "Hardcode" the version, so that there may be defined just installations like: 1.8.0, 1.9.3. With this we lose some flexibility, but we could use this as base version for new installations, so for example, a user can have two 1.9.3 installations. Provided this, we have again a possible problem, which can be solved again by 1. or 2., but this time, trying to match the base version first.

With this feature, the user won't need to restart the plugin at all, switching workspaces.

Regarding the technical PoV, all paths will be stored using eclipse's preferences system, by appending an unique id of each installation to each path in that set.

''Note'':
Add the NO_TERRAIN_GFX preprocess option checkbox to the project properties rather than being a global one.

==Enhance the Content Assist(CA) feature==
The CA framework is very extensible but it lacks proper contexts for providing the content.
I was thinking of trying to accomplish the generating of CA list either by using a config file, in case something like that can be used or writing directly the code that does that.

Another factor that is involved in a better auto-complete, is the ''schema.cfg'' the plugin bases on. Depending on whether the schema is worked on during this summer of code, I'll need to redo a bit the parser of the schema, in case the format/semantics change.

===Project files dependecy tree===
In order for the CA to work better - and maybe other areas would benefit from this - we will need to build a project files tree. With that tree, we can see how a certain declared macro/variable will affect subsequent related files and also their scope. Basically, we can see the relation from a file to anothers.

This tree will be (re)built in 2 situations:
# A file is added/removed/changed it's name
# A full rebuild is triggered (for example, the project is added for the first time in the workspace)

The tree will be built by the WML parser's rules:
# files are processed in the alphabetically order
# _initial.cfg is the first processed before anything else.
# _final.cfg is the last processed after anything else.
# if there is a _main.cfg in the directory, it is the only one processed.

Since the current ''WesnothProjectBuilder'' doesn't take in account the previous rules, I will create my own method of visiting each folder's children in the correct order. This method will look close to wesnoth's one, namely ''get_files_from_in_dir()'' found in ''src/filesystem.cpp:93''.

For a very fast lookup, as a data structure we will use a Hashtable, which has as the key the local project path to the file, and as a value a custom structure, which has the previous/next/parent/son properties, used to traverse the tree. The previous/next go on the same tree level, while the parent/son go up/down in the tree. I will use this instead of a tree, because this will give us access to info about a file, faster, in O(1) compared to a breadth-first search which has O(V+E) - where V is number of vertices and E number of edges.

Talking with Crab about this, he alerted me about a little possible problem with current aproach:
<Crab_> a note about 'The tree will be built by the WML parser's rules: ' - don't forget that you can (conditionally) include files/dirs from a file.
<Crab_> so, if we have 'ai/ais/zzz' which, say, defines a macro, it might get included by campaigns/bbb/scenarios/some_scenario.cfg , even if it is not inside /campaigns/bbb/scenarios

For that we have 2 cases:
{~file/dir path}
or
{file/dir path}

The paths are simply discarded if the current project's directory name is not found in the path.

Currently the so called "Tree" will be actually just a List or a single path tree. For the first iteration of this project, I won't tackle the advanced macro usage that might direct the flow based on defines (this will be optional if there will be time in GSoC, or if not, after GSoC, since I plan to remain active developer to maintain the plugin/enhance it furthermore). So, for example (taken from LoW):

#ifdef CAMPAIGN_LOW

{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#endif

#ifdef MULTIPLAYER

#define EASY
#enddef
{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#undef EASY
...
#endif

With current way to do this we will just take "blindly" all included directories/files without taking in consideration the #define flow control.

If we are at LoW, the following tree(list) will be created on its project:

_main.cfg -> utils/*.cfg -> scenarios/*.cfg -> units/*.cfg

Each file in the dependency tree, will have associated a number. For more details on why this and how it's done, read the Scoping section.

===Scoping===
In order for the plugin to know more about the semnatics, it should have the posibility to represent scopes. The scopes will be used mainly for variables and macros.

The Scoping is a delicate problem, because there are some tricky situations that might interfere with the scoping. I choosed to represent scoping in the following way:

Scoping is everything just about order relations. That is, we will compare numbers when dealing with scoping. With that we move the "problem" upper, to the "Dependency tree". We won't use filenames/paths because:

* The filename might change, but the order index may not. So, not having to update the index helps us.
* Number comparison is faster than string comparison.

So, from now on we'll talk in terms of indexes instead of filenames for scoping.

So, we are working with numbers. But there is still a lil' problem. What happens, when we remove/need to add a new file in the current tree, in the middle of existing 2? We would need to update all subsequent files's indexes. That would not be so ok performance wise.

To counter this problem we will not use consecutive numbers, but rather have a certain step between numbers. The step might be configured inside the plugin based on real statistics (for example, trying to see the number of cfg files per project. Taking a big number, like 1000 won't really hurt). For example, we could take the step 50. That means we would have the following tree for LoW:

0 50 100
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

instead of:
0 1 2
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

So, when it's the case of insertion, we insert the new node at the ''middle'' of the current "distance". That way we may insert/delete files *without* breaking the order, and our scoping will still work.

There is another problem it rised in my head: how do we know when to put the number as the next step (the previous number + step) or add it in the middle? Well, since every project will surely do a '''Full Build''', we'll use that oportunity to create the initial tree. Afterwards we will just insert files based on the halving of the distance between 2 indices.

The scoping will be represented by a simple structure, consisting of start index and offset and end index and offset.

===Content Assist Config(CAC) Files===
The CAC files will provide values that are default/available to config files from the wesnoth engine itself. There will be several files that define the values based on their context. This will allow a very great flexibility editing the CA list.

A CAC file will be just a simple text file, that has on each line one (or more) value(s) depending on the context.

* The ''cac/variables.txt'' will contain variables available. The list is currently available at [http://wiki.wesnoth.org/VariablesWML#Automatically_stored_variables]. For example the file could look like:
$side_number
$turn_number
...

* The ''cac/events.txt'' will contain the game events. The list is availabe at: [http://wiki.wesnoth.org/EventWML#Predefined_.27name.27_Key_Values]. Since the events that have spaces in their names can replace that with an underscore '_', the file will contain the underscore instead space variants also.



===Variables===
The variables are either defined by user or defined by default by the wesnoth engine. User's variables will be parsed from each processed file by the WesnothProjectBuilder, using the WMLSaxHandler. The default variables will be parsed and added from the CAC file. (cac/variables.txt)

Variables definitions can be triggered using the VARIABLE macro:
{VARIABLE var_name "value"}
or the [set_variable] tag:
[set_variable]
name=my_var
value="value"
[/set_variable]

The ''ConfigFile'' class in the ''org.wesnoth.wml.core'' already has a list of variables. The ''Variable'' class has some fields that allow its identification. We will build that list when we parse each file, adding each variable found by the previous defined triggers.
When the content assist finds the '$' character, it will supply the user + default variables gathered so far.

Since the variables can be cleared, thus they have scope, the ''Variable'' class needs to be refactorted, so it can represent the scope aswell. The scoping was settled before.

===Name Collisions===
I've considered that we should store the variables per project, like we currently do with macros. This will minimize the memory we need, rather than storing variables on each file - like we do currently. With this, I've discovered it's innevitable to have ''collisions''. That is, have the same variable name on multiple files.

To solve this problem, each variable/macro structure, will not have just a single scope, but rather a list of scopes.

===Events===
Besides the default event names, supplied by the wesnoth engine, there can be created custom ones, wich will be triggered with [fire_event]. As usual the default events names will be available in the cac/events.txt file.

The events defined by the user will be parsed from the ''name'' attribute of the [event] tag.

===Attributes===
All attributes are currently got from the schema.cfg

===Attributes Values===
All attributes values should be parsed based on the schema.cfg.

===Macros===
The support for macros is already built in, but it needs a way to let them have scope. That is, when an #undef is found, the certain macro would not be available to subsequent files unless redeclared. This will be done with the aid of the dependency tree and scoping. The collisions will be solved like I said at the variables section

===Support for custom luaWML tags===
The lua can create new WML Tags. It would be nice that the plugin suggest those aswell besides the ''schema.cfg''. The lua will be easily parsed, since there is a simple pattern for creating new tags:
wesnoth.wml_actions.<tag name>(cfg)

The parser will just run over the lua code/file, over each line, trying to match the 'function *wesnoth.wml_actions.*' pattern. If it finds something, it will add the tag name to the list of tags. There is also a small thing we might have missed. The user could use a shorthand notation for the actions namespace, so when searching for the pattern, I will add to the 'pattern to match' list, the respective variable when searching for new WML Tags.

Thus, like the ''wml-tags.lua'' from the data/lua uses:
local wml_actions = wesnoth.wml_actions

the 'to match' list will contain: 'function *wesnoth.wml_actions.*' and 'function *wml_actions.*', thus finding other tags too.

Going further more, for an ''optional'' enhancement, I could also search that function to see if it needs/has some extra attributes. The attributes can be found by:
* function's parameter (usually cfg) is asked for a property. For example:
function wml_actions.terrain(cfg)
local terrain = cfg.terrain or helper.wml_error("[terrain] missing required terrain= attribute")
cfg = helper.shallow_literal(cfg)
cfg.terrain = nil
for i, loc in ipairs(wesnoth.get_locations(cfg)) do
wesnoth.set_terrain(loc[1], loc[2], terrain, cfg.layer, cfg.replace_if_failed)
end
end

Here we need the attributes ''terrain'', ''layer'' and ''replace_if_failed''.

* ''get_child'' call:
function wml_actions.message(cfg)
local show_if = helper.get_child(cfg, "show_if")
if not show_if or wesnoth.eval_conditional(show_if) then
engine_message(cfg)
end
end

Here we need to have the attribute ''show_if''.

==Automatic/headless building==
The eclipse plugins can be automatically built from command line, provided there is the eclipse sdk and the eclipse delta pack on the builder's machine. The plugin can also use Buckminster tool to automate the building of the plugin.

''Notes''
Add all plugin's files *inside* a folder to prevent cluttering the directory where it's extracted

More info at:
* http://wiki.eclipse.org/PDE/Build
* http://wiki.bioclipse.net/index.php?title=How_to_build_plugins_headless
* http://help.eclipse.org/galileo/index.jsp?topic=/org.eclipse.pde.doc.user/guide/intro/pde_overview.htm
* http://www.eclipse.org/articles/Article-PDE-Automation/automation.html

==Standalone app auto-update==
The current standalone application doesn't offer the same eclipse's update system. I will add it, so anytime there is a new version of the plugin, it can be updated with a single click by the user, without the needing to download a new standalone app again.

==Documentation==
===External documentation===
The current existing readme will be split in 2 manuals: User Manual and Developer Manual (Don't forget to add images where relevant).

The user manual will contain:
* Prerequisites and Installing the prerequisites
Note: don't forget to mention the MINIMUM eclipse/java version needed to run
* Installing the plugin / standalone version
* Using the plugin
* Plugin features
* Step-by-step use cases
** Setupping the workspace
** Creating a new project and running it in the game
** Importing existing projects
** Using the WML Editor
** Updating the plugin
* Frequently Asked Questions

The developer manual will contain:
* Prerequisites and Installing the prerequisites
* Adding the plugin's projects in the
* Compiling and Running the plugin
* Deploying the plugin and standalone app

===Internal documentation===
The Eclipse infrastructure has features for letting the developer embed help into the application, depending on the current context. After I will write the external documentation, I will work on adding internal documentation aswell. Some of it already comes from the external one.

* Plugin welcome page
* Eclipse Help (When pressing Help->Help contents)
* Wizards help

==Plugin polishing==
This are some tasks needed to be done in order to get the plugin more stable and more usable than it's currently. Some of the tasks are taken from my todo list. New tasks will be added through the project advancing when improvements to actual code /user interaction can be done, so this list is not final.

* Don't copy a project that belongs to data/campaigns to the user addons's directory. This can be done by looking at the path when creating a new project.
* Enhance the logging so it can help debugging other's problem much easier. I could split the current log in 2:
** Commands executed by the plugin
** Other informations like parsed information/statuses
* Enhance the integration with the eclipse platform by adding the "Wesnoth" related wizards directly to the "New" menu.
* Allow users to import a directory as a wesnoth project. Under the hood it will either open the wesnoth project (if there is any .project files in it) or create a new empty project on it.
* Allow the user to clear it's current plugin's settings just with a simple button.
* Wesnoth Project Explorer - Add error markers just like the Java Explorer has
* Refactor the current way of getting the macro list. Currently if there is no _main.cfg practicaly the _MACROS_.cfg file is not built resulting in no MACRO suggestions.
* Create a view filter to hide the Project ''_AutoLinked_CFGExternalFiles_'' which is created for opening the external config files (external meaning outside the current workspace).
* Fix the F3 navigation when the map's location is specified withing " ", as a string.

===New parsing method (optional)===
The current parsing method involves a lot of Wesnoth preprocessor/wmlparser.py. This is doing somehow the parsing job double. This is because the xtext framework already does 1 pass over the files when added to the project. My plan is to see if I can reuse the already built AST(Abstract Syntax Tree) and the parse tree, to use those values instead of additional preprocessing/wmlparsing, and use the latter only when really needed.

Using the xtext's model will greately fasten the "build" time of each project and it will be *much* simpler to work with, since the framework already provides exceptions recovering (that is, when the code is not well formed according to the grammar) and based on the defined grammar the respective tokens. So, for example instead using 2 another external processes, we could just iterate over each WMLTag and get it's WMLKeys and parse their individual values.

If this idea works, I will add it on the Plugin polishing tasks.

==Other ideas==
===Addons management===
There will be a new Addons management view. It will behave much like the in-game addon manager, but it will be more handy since the user doesn't need to start the game for that (and also wait till the cache refreshes after downloading it). This view will be based on the python script from '''data/tools/wesnoth_addon_manager''', like it does currently for uploading the project as an addon.

The view will let the user see the list/details for each of the addons currently on the server. There will be also a filter based on what addon server to use (trunk/1.8/1.9/etc)

The user will be able to just right click on an addon and download it to it's user data folder. Optionally a new project will be created, based on the just downloaded addon.



===Unit testing===
====Grammar====
For a better wml handling with in the editor, I will create a Testing class for the current grammar. The class will do testing on all *.cfgs in the data directory. That way after modifing something in the grammar we will be able to see how many errors we have introduced/eliminated. This will greatly help the developing of a better grammar that can hold all current WML formats.

''Notes'':
optionally rework the grammar and try to use a custom lexer/parser in order to benefit from the preprocessor, injecting the valid tokens. This would help the cases when the current grammar doesn't work:
{name} = value
or unclosed tags

====Parsing and getting information from files====
I will create some basic (or taken from existing campaigns) config files that will be parsed in order to check if the correct behaviour - correct information is extracted from the files.

This will check for extracting the:
scenario name
campaign name
next_scenario
first_scenario
variables
macros

=Timeline=
The GSOC period is between 24th May and 20th August. But since I have exams for 3 weeks (during 30.05-19.06.2011), I will start working on the plugin before the 24th of May, to recover some of the lost time. Also, my ImagineCup team made it to the national phase - that is in 5,6,7 May. That means till that time I will not be able to do so much work, so I'll make the timeline according with the starting of work on 9 May.

Here is a table with key periods of the time spent on this project.
{| border="1"
|'''Period''' || '''Actions'''
|-
| 26 April || Get accepted
|-
| 26 April - 8 May || Busy working on ImagineCup project for the national phase. Little or no work done.
|-
| 9 May - 15 May || Allow headless build of the plugin
|-
| 16 May - 22 May || Add Support for multiple installations
|-
| 23 May - 28 May || Add the auto-update feature for the standalone app
|-
| 30 May - 19 June || Exams
|-
| 20 June - 24 June || Create the external documentation
|-
| 25 June - 16 July || Enhance Content Assist
|-
| 15 July || Mid-term evaluations deadline
|-
| 17 July - 24 July || Addons management view
|-
| 25 July - 30 July || Unit tests
|-
| 1 August - 14 August || Do the Plugin polishing tasks
|-
| 15 August || Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc.
|-
| 15 August - 17 August || Create the internal documentation.
|-
| 18 August - 22 August || Buffer half-week. This will be used in case some tasks fell a bit outside their proposed time.
|-
| 22 August || Firm 'pencils down' date. Mentors, students and organization administrators can begin submitting final evaluations to Google.
|}

=Tasks=
This is a list of the "atomic" tasks that need to be done, based on the project part. Since the big tasks are split into smaller task, the progress will be seen better and any problems that arise with the timeline will be seen faster. I will update this table based on my current progress.

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Headless build ||Research about what system to use for automatic building of the plugin || Done
|-
| Headless build || Implement the chosen system for the wesnoth plugin|| Done
|-
| Multiple installations || Implement the preferences pages || Done
|-
| Multiple installations || Implement the logic for saving and loading the installation's paths on the disk || Done
|-
| Multiple installations || Implement the project preferences page || Done
|-
| Multiple installations || Rewrite the current mechanisms that use the paths to use the ones based on the project. || In progress
|-
| Auto-update || Implement the auto-update feature. || In progress
|-
| Documentation || Write the User Manual || Done
|-
| Documentation || Write the Developer Manual || Done
|-
| Documentation || Write the internal documentation || Done
|-
| Enhance Content Assist || Project dependency tree || In progress
|-
| Enhance Content Assist || Content assist files || None
|-
| Enhance Content Assist || Variables || None
|-
| Enhance Content Assist || Events || None
|-
| Enhance Content Assist || Lua tags || None
|-
| Addon management || Create the GUI of the view || None
|-
| Addon management || Create the view's logic || None
|-
| Unit testing || Tests for the grammar || None
|-
| Unit testing || Tests for parsing the config files || None
|}

Optional tasks will be dealt with if the time allows it:

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Enhance Content Assist || Project dependency tree with multiple paths based on defines || None
|-
| Enhance Content Assist || Lua tags attributes || None
|-
| Grammar || Enhance the grammar to support the 2 current unsupported syntax constructs || None
|-
| Documentation || Implement a simple WML project from start to end using Help's built-in cheat sheets tutorial || None
|}

=Questionnaire=
The questionnaire can be found here: http://wiki.wesnoth.org/User:Timotei21/Questionaire

SummerofCode2011 Timotei21

2011-06-28T05:47:56Z

Timotei21: update progress

{{SoC2011Student_2|timotei|SoC_Ideas_Eclipse_Plugin2011}}

=Description=
<h4>timotei - Improving the Eclipse Plugin</h4>
I aim at improving the plugin, so it will become the tool used by all UMC Authors. That is, UMC Authors will get rid of the lot of different tools they use for different tasks (for example the Emacs WMLMode/other plugins for different text editors), and instead use one single unified Tool that will speed up the development. My target is to make this plugin a complete and very stable suite for all umc tasks that don't need specialized software - like a graphics editor, so I'd like to have this oportunity to finish it in the good sense.

=Contacts=
==IRC==
timotei

==Other==
Forum: timotei 
gna.org: timotei

=SoC Application=
[http://www.google-melange.com/gsoc/proposal/review/google/gsoc2011/timoteidolean/1 Battle for Wesnoth - Google Summer of Code Application]

=Proposal Summary=
Page Last Updated: {{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}} 

In the following lines I will give details on how I'm planning to implement some of the required tasks, and also add some new ones.

The ''Notes'' sections are aimed for personal guideliness. They are took from my todo list.

==Multiple Wesnoth installations==
Having multiple wesnoth setups, and working with them at the same time would be nice to be done from inside the plugin.
For that, there will be a new preferences page. The page will look something like this:
http://dl.dropbox.com/u/462510/personal/soc/installations_management.PNG

There will be buttons that add/remove/edit a certain wesnoth installation. When adding/editing an installation, a new page like the current one (in which we set the paths), will be shown. The user will be able to name it and specify the version (I could automatically get the version by invoking ''wesnoth --version'').
The current page for setting the paths will act as a default installation.

After we have configured the paths, the user can chose the installation to which the (new) projects are bound, by opening the project properties. There will be a wesnoth-related page, where the user will be able to chose to what installation the project binds. With that, every command that uses the paths, won't use the single current paths, but the ones assigned to each project. This project properties page will open new ways for adding new

There would be a problem in case the project will be migrated between 2 different plugin's versions. For example, in one place we would have defined "1.9.4svn" but on the other there would be "trunk".

We can solve this in 3 ways:

# Alert the user that the installation doesn't bind, and let him chose the current matching installation for his plugin.
# Default automatically to the current plugin's default installation.
# "Hardcode" the version, so that there may be defined just installations like: 1.8.0, 1.9.3. With this we lose some flexibility, but we could use this as base version for new installations, so for example, a user can have two 1.9.3 installations. Provided this, we have again a possible problem, which can be solved again by 1. or 2., but this time, trying to match the base version first.

With this feature, the user won't need to restart the plugin at all, switching workspaces.

Regarding the technical PoV, all paths will be stored using eclipse's preferences system, by appending an unique id of each installation to each path in that set.

''Note'':
Add the NO_TERRAIN_GFX preprocess option checkbox to the project properties rather than being a global one.

==Enhance the Content Assist(CA) feature==
The CA framework is very extensible but it lacks proper contexts for providing the content.
I was thinking of trying to accomplish the generating of CA list either by using a config file, in case something like that can be used or writing directly the code that does that.

Another factor that is involved in a better auto-complete, is the ''schema.cfg'' the plugin bases on. Depending on whether the schema is worked on during this summer of code, I'll need to redo a bit the parser of the schema, in case the format/semantics change.

===Project files dependecy tree===
In order for the CA to work better - and maybe other areas would benefit from this - we will need to build a project files tree. With that tree, we can see how a certain declared macro/variable will affect subsequent related files and also their scope. Basically, we can see the relation from a file to anothers.

This tree will be (re)built in 2 situations:
# A file is added/removed/changed it's name
# A full rebuild is triggered (for example, the project is added for the first time in the workspace)

The tree will be built by the WML parser's rules:
# files are processed in the alphabetically order
# _initial.cfg is the first processed before anything else.
# _final.cfg is the last processed after anything else.
# if there is a _main.cfg in the directory, it is the only one processed.

Since the current ''WesnothProjectBuilder'' doesn't take in account the previous rules, I will create my own method of visiting each folder's children in the correct order. This method will look close to wesnoth's one, namely ''get_files_from_in_dir()'' found in ''src/filesystem.cpp:93''.

For a very fast lookup, as a data structure we will use a Hashtable, which has as the key the local project path to the file, and as a value a custom structure, which has the previous/next/parent/son properties, used to traverse the tree. The previous/next go on the same tree level, while the parent/son go up/down in the tree. I will use this instead of a tree, because this will give us access to info about a file, faster, in O(1) compared to a breadth-first search which has O(V+E) - where V is number of vertices and E number of edges.

Talking with Crab about this, he alerted me about a little possible problem with current aproach:
<Crab_> a note about 'The tree will be built by the WML parser's rules: ' - don't forget that you can (conditionally) include files/dirs from a file.
<Crab_> so, if we have 'ai/ais/zzz' which, say, defines a macro, it might get included by campaigns/bbb/scenarios/some_scenario.cfg , even if it is not inside /campaigns/bbb/scenarios

For that we have 2 cases:
{~file/dir path}
or
{file/dir path}

The paths are simply discarded if the current project's directory name is not found in the path.

Currently the so called "Tree" will be actually just a List or a single path tree. For the first iteration of this project, I won't tackle the advanced macro usage that might direct the flow based on defines (this will be optional if there will be time in GSoC, or if not, after GSoC, since I plan to remain active developer to maintain the plugin/enhance it furthermore). So, for example (taken from LoW):

#ifdef CAMPAIGN_LOW

{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#endif

#ifdef MULTIPLAYER

#define EASY
#enddef
{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#undef EASY
...
#endif

With current way to do this we will just take "blindly" all included directories/files without taking in consideration the #define flow control.

If we are at LoW, the following tree(list) will be created on its project:

_main.cfg -> utils/*.cfg -> scenarios/*.cfg -> units/*.cfg

Each file in the dependency tree, will have associated a number. For more details on why this and how it's done, read the Scoping section.

===Scoping===
In order for the plugin to know more about the semnatics, it should have the posibility to represent scopes. The scopes will be used mainly for variables and macros.

The Scoping is a delicate problem, because there are some tricky situations that might interfere with the scoping. I choosed to represent scoping in the following way:

Scoping is everything just about order relations. That is, we will compare numbers when dealing with scoping. With that we move the "problem" upper, to the "Dependency tree". We won't use filenames/paths because:

* The filename might change, but the order index may not. So, not having to update the index helps us.
* Number comparison is faster than string comparison.

So, from now on we'll talk in terms of indexes instead of filenames for scoping.

So, we are working with numbers. But there is still a lil' problem. What happens, when we remove/need to add a new file in the current tree, in the middle of existing 2? We would need to update all subsequent files's indexes. That would not be so ok performance wise.

To counter this problem we will not use consecutive numbers, but rather have a certain step between numbers. The step might be configured inside the plugin based on real statistics (for example, trying to see the number of cfg files per project. Taking a big number, like 1000 won't really hurt). For example, we could take the step 50. That means we would have the following tree for LoW:

0 50 100
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

instead of:
0 1 2
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

So, when it's the case of insertion, we insert the new node at the ''middle'' of the current "distance". That way we may insert/delete files *without* breaking the order, and our scoping will still work.

There is another problem it rised in my head: how do we know when to put the number as the next step (the previous number + step) or add it in the middle? Well, since every project will surely do a '''Full Build''', we'll use that oportunity to create the initial tree. Afterwards we will just insert files based on the halving of the distance between 2 indices.

The scoping will be represented by a simple structure, consisting of start index and offset and end index and offset.

===Content Assist Config(CAC) Files===
The CAC files will provide values that are default/available to config files from the wesnoth engine itself. There will be several files that define the values based on their context. This will allow a very great flexibility editing the CA list.

A CAC file will be just a simple text file, that has on each line one (or more) value(s) depending on the context.

* The ''cac/variables.txt'' will contain variables available. The list is currently available at [http://wiki.wesnoth.org/VariablesWML#Automatically_stored_variables]. For example the file could look like:
$side_number
$turn_number
...

* The ''cac/events.txt'' will contain the game events. The list is availabe at: [http://wiki.wesnoth.org/EventWML#Predefined_.27name.27_Key_Values]. Since the events that have spaces in their names can replace that with an underscore '_', the file will contain the underscore instead space variants also.



===Variables===
The variables are either defined by user or defined by default by the wesnoth engine. User's variables will be parsed from each processed file by the WesnothProjectBuilder, using the WMLSaxHandler. The default variables will be parsed and added from the CAC file. (cac/variables.txt)

Variables definitions can be triggered using the VARIABLE macro:
{VARIABLE var_name "value"}
or the [set_variable] tag:
[set_variable]
name=my_var
value="value"
[/set_variable]

The ''ConfigFile'' class in the ''org.wesnoth.wml.core'' already has a list of variables. The ''Variable'' class has some fields that allow its identification. We will build that list when we parse each file, adding each variable found by the previous defined triggers.
When the content assist finds the '$' character, it will supply the user + default variables gathered so far.

Since the variables can be cleared, thus they have scope, the ''Variable'' class needs to be refactorted, so it can represent the scope aswell. The scoping was settled before.

===Name Collisions===
I've considered that we should store the variables per project, like we currently do with macros. This will minimize the memory we need, rather than storing variables on each file - like we do currently. With this, I've discovered it's innevitable to have ''collisions''. That is, have the same variable name on multiple files.

To solve this problem, each variable/macro structure, will not have just a single scope, but rather a list of scopes.

===Events===
Besides the default event names, supplied by the wesnoth engine, there can be created custom ones, wich will be triggered with [fire_event]. As usual the default events names will be available in the cac/events.txt file.

The events defined by the user will be parsed from the ''name'' attribute of the [event] tag.

===Attributes===
All attributes are currently got from the schema.cfg

===Attributes Values===
All attributes values should be parsed based on the schema.cfg.

===Macros===
The support for macros is already built in, but it needs a way to let them have scope. That is, when an #undef is found, the certain macro would not be available to subsequent files unless redeclared. This will be done with the aid of the dependency tree and scoping. The collisions will be solved like I said at the variables section

===Support for custom luaWML tags===
The lua can create new WML Tags. It would be nice that the plugin suggest those aswell besides the ''schema.cfg''. The lua will be easily parsed, since there is a simple pattern for creating new tags:
wesnoth.wml_actions.<tag name>(cfg)

The parser will just run over the lua code/file, over each line, trying to match the 'function *wesnoth.wml_actions.*' pattern. If it finds something, it will add the tag name to the list of tags. There is also a small thing we might have missed. The user could use a shorthand notation for the actions namespace, so when searching for the pattern, I will add to the 'pattern to match' list, the respective variable when searching for new WML Tags.

Thus, like the ''wml-tags.lua'' from the data/lua uses:
local wml_actions = wesnoth.wml_actions

the 'to match' list will contain: 'function *wesnoth.wml_actions.*' and 'function *wml_actions.*', thus finding other tags too.

Going further more, for an ''optional'' enhancement, I could also search that function to see if it needs/has some extra attributes. The attributes can be found by:
* function's parameter (usually cfg) is asked for a property. For example:
function wml_actions.terrain(cfg)
local terrain = cfg.terrain or helper.wml_error("[terrain] missing required terrain= attribute")
cfg = helper.shallow_literal(cfg)
cfg.terrain = nil
for i, loc in ipairs(wesnoth.get_locations(cfg)) do
wesnoth.set_terrain(loc[1], loc[2], terrain, cfg.layer, cfg.replace_if_failed)
end
end

Here we need the attributes ''terrain'', ''layer'' and ''replace_if_failed''.

* ''get_child'' call:
function wml_actions.message(cfg)
local show_if = helper.get_child(cfg, "show_if")
if not show_if or wesnoth.eval_conditional(show_if) then
engine_message(cfg)
end
end

Here we need to have the attribute ''show_if''.

==Automatic/headless building==
The eclipse plugins can be automatically built from command line, provided there is the eclipse sdk and the eclipse delta pack on the builder's machine. The plugin can also use Buckminster tool to automate the building of the plugin.

''Notes''
Add all plugin's files *inside* a folder to prevent cluttering the directory where it's extracted

More info at:
* http://wiki.eclipse.org/PDE/Build
* http://wiki.bioclipse.net/index.php?title=How_to_build_plugins_headless
* http://help.eclipse.org/galileo/index.jsp?topic=/org.eclipse.pde.doc.user/guide/intro/pde_overview.htm
* http://www.eclipse.org/articles/Article-PDE-Automation/automation.html

==Standalone app auto-update==
The current standalone application doesn't offer the same eclipse's update system. I will add it, so anytime there is a new version of the plugin, it can be updated with a single click by the user, without the needing to download a new standalone app again.

==Documentation==
===External documentation===
The current existing readme will be split in 2 manuals: User Manual and Developer Manual (Don't forget to add images where relevant).

The user manual will contain:
* Prerequisites and Installing the prerequisites
Note: don't forget to mention the MINIMUM eclipse/java version needed to run
* Installing the plugin / standalone version
* Using the plugin
* Plugin features
* Step-by-step use cases
** Setupping the workspace
** Creating a new project and running it in the game
** Importing existing projects
** Using the WML Editor
** Updating the plugin
* Frequently Asked Questions

The developer manual will contain:
* Prerequisites and Installing the prerequisites
* Adding the plugin's projects in the
* Compiling and Running the plugin
* Deploying the plugin and standalone app

===Internal documentation===
The Eclipse infrastructure has features for letting the developer embed help into the application, depending on the current context. After I will write the external documentation, I will work on adding internal documentation aswell. Some of it already comes from the external one.

* Plugin welcome page
* Eclipse Help (When pressing Help->Help contents)
* Wizards help

==Plugin polishing==
This are some tasks needed to be done in order to get the plugin more stable and more usable than it's currently. Some of the tasks are taken from my todo list. New tasks will be added through the project advancing when improvements to actual code /user interaction can be done, so this list is not final.

* Don't copy a project that belongs to data/campaigns to the user addons's directory. This can be done by looking at the path when creating a new project.
* Enhance the logging so it can help debugging other's problem much easier. I could split the current log in 2:
** Commands executed by the plugin
** Other informations like parsed information/statuses
* Enhance the integration with the eclipse platform by adding the "Wesnoth" related wizards directly to the "New" menu.
* Allow users to import a directory as a wesnoth project. Under the hood it will either open the wesnoth project (if there is any .project files in it) or create a new empty project on it.
* Allow the user to clear it's current plugin's settings just with a simple button.
* Wesnoth Project Explorer - Add error markers just like the Java Explorer has
* Refactor the current way of getting the macro list. Currently if there is no _main.cfg practicaly the _MACROS_.cfg file is not built resulting in no MACRO suggestions.
* Create a view filter to hide the Project ''_AutoLinked_CFGExternalFiles_'' which is created for opening the external config files (external meaning outside the current workspace).
* Fix the F3 navigation when the map's location is specified withing " ", as a string.

===New parsing method (optional)===
The current parsing method involves a lot of Wesnoth preprocessor/wmlparser.py. This is doing somehow the parsing job double. This is because the xtext framework already does 1 pass over the files when added to the project. My plan is to see if I can reuse the already built AST(Abstract Syntax Tree) and the parse tree, to use those values instead of additional preprocessing/wmlparsing, and use the latter only when really needed.

Using the xtext's model will greately fasten the "build" time of each project and it will be *much* simpler to work with, since the framework already provides exceptions recovering (that is, when the code is not well formed according to the grammar) and based on the defined grammar the respective tokens. So, for example instead using 2 another external processes, we could just iterate over each WMLTag and get it's WMLKeys and parse their individual values.

If this idea works, I will add it on the Plugin polishing tasks.

==Other ideas==
===Addons management===
There will be a new Addons management view. It will behave much like the in-game addon manager, but it will be more handy since the user doesn't need to start the game for that (and also wait till the cache refreshes after downloading it). This view will be based on the python script from '''data/tools/wesnoth_addon_manager''', like it does currently for uploading the project as an addon.

The view will let the user see the list/details for each of the addons currently on the server. There will be also a filter based on what addon server to use (trunk/1.8/1.9/etc)

The user will be able to just right click on an addon and download it to it's user data folder. Optionally a new project will be created, based on the just downloaded addon.



===Unit testing===
====Grammar====
For a better wml handling with in the editor, I will create a Testing class for the current grammar. The class will do testing on all *.cfgs in the data directory. That way after modifing something in the grammar we will be able to see how many errors we have introduced/eliminated. This will greatly help the developing of a better grammar that can hold all current WML formats.

''Notes'':
optionally rework the grammar and try to use a custom lexer/parser in order to benefit from the preprocessor, injecting the valid tokens. This would help the cases when the current grammar doesn't work:
{name} = value
or unclosed tags

====Parsing and getting information from files====
I will create some basic (or taken from existing campaigns) config files that will be parsed in order to check if the correct behaviour - correct information is extracted from the files.

This will check for extracting the:
scenario name
campaign name
next_scenario
first_scenario
variables
macros

=Timeline=
The GSOC period is between 24th May and 20th August. But since I have exams for 3 weeks (during 30.05-19.06.2011), I will start working on the plugin before the 24th of May, to recover some of the lost time. Also, my ImagineCup team made it to the national phase - that is in 5,6,7 May. That means till that time I will not be able to do so much work, so I'll make the timeline according with the starting of work on 9 May.

Here is a table with key periods of the time spent on this project.
{| border="1"
|'''Period''' || '''Actions'''
|-
| 26 April || Get accepted
|-
| 26 April - 8 May || Busy working on ImagineCup project for the national phase. Little or no work done.
|-
| 9 May - 15 May || Allow headless build of the plugin
|-
| 16 May - 22 May || Add Support for multiple installations
|-
| 23 May - 28 May || Add the auto-update feature for the standalone app
|-
| 30 May - 19 June || Exams
|-
| 20 June - 24 June || Create the external documentation
|-
| 25 June - 16 July || Enhance Content Assist
|-
| 15 July || Mid-term evaluations deadline
|-
| 17 July - 24 July || Addons management view
|-
| 25 July - 30 July || Unit tests
|-
| 1 August - 14 August || Do the Plugin polishing tasks
|-
| 15 August || Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc.
|-
| 15 August - 17 August || Create the internal documentation.
|-
| 18 August - 22 August || Buffer half-week. This will be used in case some tasks fell a bit outside their proposed time.
|-
| 22 August || Firm 'pencils down' date. Mentors, students and organization administrators can begin submitting final evaluations to Google.
|}

=Tasks=
This is a list of the "atomic" tasks that need to be done, based on the project part. Since the big tasks are split into smaller task, the progress will be seen better and any problems that arise with the timeline will be seen faster. I will update this table based on my current progress.

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Headless build ||Research about what system to use for automatic building of the plugin || Done
|-
| Headless build || Implement the chosen system for the wesnoth plugin|| Done
|-
| Multiple installations || Implement the preferences pages || Done
|-
| Multiple installations || Implement the logic for saving and loading the installation's paths on the disk || Done
|-
| Multiple installations || Implement the project preferences page || Done
|-
| Multiple installations || Rewrite the current mechanisms that use the paths to use the ones based on the project. || In progress
|-
| Auto-update || Implement the auto-update feature. || In progress
|-
| Documentation || Write the User Manual || Done
|-
| Documentation || Write the Developer Manual || Done
|-
| Documentation || Write the internal documentation || In progress
|-
| Enhance Content Assist || Project dependency tree || None
|-
| Enhance Content Assist || Content assist files || None
|-
| Enhance Content Assist || Variables || None
|-
| Enhance Content Assist || Events || None
|-
| Enhance Content Assist || Lua tags || None
|-
| Addon management || Create the GUI of the view || None
|-
| Addon management || Create the view's logic || None
|-
| Unit testing || Tests for the grammar || None
|-
| Unit testing || Tests for parsing the config files || None
|}

Optional tasks will be dealt with if the time allows it:

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Enhance Content Assist || Project dependency tree with multiple paths based on defines || None
|-
| Enhance Content Assist || Lua tags attributes || None
|-
| Grammar || Enhance the grammar to support the 2 current unsupported syntax constructs || None
|-
| Documentation || Implement a simple WML project from start to end using Help's built-in cheat sheets tutorial || None
|}

=Questionnaire=
The questionnaire can be found here: http://wiki.wesnoth.org/User:Timotei21/Questionaire

SummerofCode2011 Timotei21

2011-06-27T11:48:49Z

Timotei21: update progress

{{SoC2011Student_2|timotei|SoC_Ideas_Eclipse_Plugin2011}}

=Description=
<h4>timotei - Improving the Eclipse Plugin</h4>
I aim at improving the plugin, so it will become the tool used by all UMC Authors. That is, UMC Authors will get rid of the lot of different tools they use for different tasks (for example the Emacs WMLMode/other plugins for different text editors), and instead use one single unified Tool that will speed up the development. My target is to make this plugin a complete and very stable suite for all umc tasks that don't need specialized software - like a graphics editor, so I'd like to have this oportunity to finish it in the good sense.

=Contacts=
==IRC==
timotei

==Other==
Forum: timotei 
gna.org: timotei

=SoC Application=
[http://www.google-melange.com/gsoc/proposal/review/google/gsoc2011/timoteidolean/1 Battle for Wesnoth - Google Summer of Code Application]

=Proposal Summary=
Page Last Updated: {{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}} 

In the following lines I will give details on how I'm planning to implement some of the required tasks, and also add some new ones.

The ''Notes'' sections are aimed for personal guideliness. They are took from my todo list.

==Multiple Wesnoth installations==
Having multiple wesnoth setups, and working with them at the same time would be nice to be done from inside the plugin.
For that, there will be a new preferences page. The page will look something like this:
http://dl.dropbox.com/u/462510/personal/soc/installations_management.PNG

There will be buttons that add/remove/edit a certain wesnoth installation. When adding/editing an installation, a new page like the current one (in which we set the paths), will be shown. The user will be able to name it and specify the version (I could automatically get the version by invoking ''wesnoth --version'').
The current page for setting the paths will act as a default installation.

After we have configured the paths, the user can chose the installation to which the (new) projects are bound, by opening the project properties. There will be a wesnoth-related page, where the user will be able to chose to what installation the project binds. With that, every command that uses the paths, won't use the single current paths, but the ones assigned to each project. This project properties page will open new ways for adding new

There would be a problem in case the project will be migrated between 2 different plugin's versions. For example, in one place we would have defined "1.9.4svn" but on the other there would be "trunk".

We can solve this in 3 ways:

# Alert the user that the installation doesn't bind, and let him chose the current matching installation for his plugin.
# Default automatically to the current plugin's default installation.
# "Hardcode" the version, so that there may be defined just installations like: 1.8.0, 1.9.3. With this we lose some flexibility, but we could use this as base version for new installations, so for example, a user can have two 1.9.3 installations. Provided this, we have again a possible problem, which can be solved again by 1. or 2., but this time, trying to match the base version first.

With this feature, the user won't need to restart the plugin at all, switching workspaces.

Regarding the technical PoV, all paths will be stored using eclipse's preferences system, by appending an unique id of each installation to each path in that set.

''Note'':
Add the NO_TERRAIN_GFX preprocess option checkbox to the project properties rather than being a global one.

==Enhance the Content Assist(CA) feature==
The CA framework is very extensible but it lacks proper contexts for providing the content.
I was thinking of trying to accomplish the generating of CA list either by using a config file, in case something like that can be used or writing directly the code that does that.

Another factor that is involved in a better auto-complete, is the ''schema.cfg'' the plugin bases on. Depending on whether the schema is worked on during this summer of code, I'll need to redo a bit the parser of the schema, in case the format/semantics change.

===Project files dependecy tree===
In order for the CA to work better - and maybe other areas would benefit from this - we will need to build a project files tree. With that tree, we can see how a certain declared macro/variable will affect subsequent related files and also their scope. Basically, we can see the relation from a file to anothers.

This tree will be (re)built in 2 situations:
# A file is added/removed/changed it's name
# A full rebuild is triggered (for example, the project is added for the first time in the workspace)

The tree will be built by the WML parser's rules:
# files are processed in the alphabetically order
# _initial.cfg is the first processed before anything else.
# _final.cfg is the last processed after anything else.
# if there is a _main.cfg in the directory, it is the only one processed.

Since the current ''WesnothProjectBuilder'' doesn't take in account the previous rules, I will create my own method of visiting each folder's children in the correct order. This method will look close to wesnoth's one, namely ''get_files_from_in_dir()'' found in ''src/filesystem.cpp:93''.

For a very fast lookup, as a data structure we will use a Hashtable, which has as the key the local project path to the file, and as a value a custom structure, which has the previous/next/parent/son properties, used to traverse the tree. The previous/next go on the same tree level, while the parent/son go up/down in the tree. I will use this instead of a tree, because this will give us access to info about a file, faster, in O(1) compared to a breadth-first search which has O(V+E) - where V is number of vertices and E number of edges.

Talking with Crab about this, he alerted me about a little possible problem with current aproach:
<Crab_> a note about 'The tree will be built by the WML parser's rules: ' - don't forget that you can (conditionally) include files/dirs from a file.
<Crab_> so, if we have 'ai/ais/zzz' which, say, defines a macro, it might get included by campaigns/bbb/scenarios/some_scenario.cfg , even if it is not inside /campaigns/bbb/scenarios

For that we have 2 cases:
{~file/dir path}
or
{file/dir path}

The paths are simply discarded if the current project's directory name is not found in the path.

Currently the so called "Tree" will be actually just a List or a single path tree. For the first iteration of this project, I won't tackle the advanced macro usage that might direct the flow based on defines (this will be optional if there will be time in GSoC, or if not, after GSoC, since I plan to remain active developer to maintain the plugin/enhance it furthermore). So, for example (taken from LoW):

#ifdef CAMPAIGN_LOW

{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#endif

#ifdef MULTIPLAYER

#define EASY
#enddef
{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#undef EASY
...
#endif

With current way to do this we will just take "blindly" all included directories/files without taking in consideration the #define flow control.

If we are at LoW, the following tree(list) will be created on its project:

_main.cfg -> utils/*.cfg -> scenarios/*.cfg -> units/*.cfg

Each file in the dependency tree, will have associated a number. For more details on why this and how it's done, read the Scoping section.

===Scoping===
In order for the plugin to know more about the semnatics, it should have the posibility to represent scopes. The scopes will be used mainly for variables and macros.

The Scoping is a delicate problem, because there are some tricky situations that might interfere with the scoping. I choosed to represent scoping in the following way:

Scoping is everything just about order relations. That is, we will compare numbers when dealing with scoping. With that we move the "problem" upper, to the "Dependency tree". We won't use filenames/paths because:

* The filename might change, but the order index may not. So, not having to update the index helps us.
* Number comparison is faster than string comparison.

So, from now on we'll talk in terms of indexes instead of filenames for scoping.

So, we are working with numbers. But there is still a lil' problem. What happens, when we remove/need to add a new file in the current tree, in the middle of existing 2? We would need to update all subsequent files's indexes. That would not be so ok performance wise.

To counter this problem we will not use consecutive numbers, but rather have a certain step between numbers. The step might be configured inside the plugin based on real statistics (for example, trying to see the number of cfg files per project. Taking a big number, like 1000 won't really hurt). For example, we could take the step 50. That means we would have the following tree for LoW:

0 50 100
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

instead of:
0 1 2
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

So, when it's the case of insertion, we insert the new node at the ''middle'' of the current "distance". That way we may insert/delete files *without* breaking the order, and our scoping will still work.

There is another problem it rised in my head: how do we know when to put the number as the next step (the previous number + step) or add it in the middle? Well, since every project will surely do a '''Full Build''', we'll use that oportunity to create the initial tree. Afterwards we will just insert files based on the halving of the distance between 2 indices.

The scoping will be represented by a simple structure, consisting of start index and offset and end index and offset.

===Content Assist Config(CAC) Files===
The CAC files will provide values that are default/available to config files from the wesnoth engine itself. There will be several files that define the values based on their context. This will allow a very great flexibility editing the CA list.

A CAC file will be just a simple text file, that has on each line one (or more) value(s) depending on the context.

* The ''cac/variables.txt'' will contain variables available. The list is currently available at [http://wiki.wesnoth.org/VariablesWML#Automatically_stored_variables]. For example the file could look like:
$side_number
$turn_number
...

* The ''cac/events.txt'' will contain the game events. The list is availabe at: [http://wiki.wesnoth.org/EventWML#Predefined_.27name.27_Key_Values]. Since the events that have spaces in their names can replace that with an underscore '_', the file will contain the underscore instead space variants also.



===Variables===
The variables are either defined by user or defined by default by the wesnoth engine. User's variables will be parsed from each processed file by the WesnothProjectBuilder, using the WMLSaxHandler. The default variables will be parsed and added from the CAC file. (cac/variables.txt)

Variables definitions can be triggered using the VARIABLE macro:
{VARIABLE var_name "value"}
or the [set_variable] tag:
[set_variable]
name=my_var
value="value"
[/set_variable]

The ''ConfigFile'' class in the ''org.wesnoth.wml.core'' already has a list of variables. The ''Variable'' class has some fields that allow its identification. We will build that list when we parse each file, adding each variable found by the previous defined triggers.
When the content assist finds the '$' character, it will supply the user + default variables gathered so far.

Since the variables can be cleared, thus they have scope, the ''Variable'' class needs to be refactorted, so it can represent the scope aswell. The scoping was settled before.

===Name Collisions===
I've considered that we should store the variables per project, like we currently do with macros. This will minimize the memory we need, rather than storing variables on each file - like we do currently. With this, I've discovered it's innevitable to have ''collisions''. That is, have the same variable name on multiple files.

To solve this problem, each variable/macro structure, will not have just a single scope, but rather a list of scopes.

===Events===
Besides the default event names, supplied by the wesnoth engine, there can be created custom ones, wich will be triggered with [fire_event]. As usual the default events names will be available in the cac/events.txt file.

The events defined by the user will be parsed from the ''name'' attribute of the [event] tag.

===Attributes===
All attributes are currently got from the schema.cfg

===Attributes Values===
All attributes values should be parsed based on the schema.cfg.

===Macros===
The support for macros is already built in, but it needs a way to let them have scope. That is, when an #undef is found, the certain macro would not be available to subsequent files unless redeclared. This will be done with the aid of the dependency tree and scoping. The collisions will be solved like I said at the variables section

===Support for custom luaWML tags===
The lua can create new WML Tags. It would be nice that the plugin suggest those aswell besides the ''schema.cfg''. The lua will be easily parsed, since there is a simple pattern for creating new tags:
wesnoth.wml_actions.<tag name>(cfg)

The parser will just run over the lua code/file, over each line, trying to match the 'function *wesnoth.wml_actions.*' pattern. If it finds something, it will add the tag name to the list of tags. There is also a small thing we might have missed. The user could use a shorthand notation for the actions namespace, so when searching for the pattern, I will add to the 'pattern to match' list, the respective variable when searching for new WML Tags.

Thus, like the ''wml-tags.lua'' from the data/lua uses:
local wml_actions = wesnoth.wml_actions

the 'to match' list will contain: 'function *wesnoth.wml_actions.*' and 'function *wml_actions.*', thus finding other tags too.

Going further more, for an ''optional'' enhancement, I could also search that function to see if it needs/has some extra attributes. The attributes can be found by:
* function's parameter (usually cfg) is asked for a property. For example:
function wml_actions.terrain(cfg)
local terrain = cfg.terrain or helper.wml_error("[terrain] missing required terrain= attribute")
cfg = helper.shallow_literal(cfg)
cfg.terrain = nil
for i, loc in ipairs(wesnoth.get_locations(cfg)) do
wesnoth.set_terrain(loc[1], loc[2], terrain, cfg.layer, cfg.replace_if_failed)
end
end

Here we need the attributes ''terrain'', ''layer'' and ''replace_if_failed''.

* ''get_child'' call:
function wml_actions.message(cfg)
local show_if = helper.get_child(cfg, "show_if")
if not show_if or wesnoth.eval_conditional(show_if) then
engine_message(cfg)
end
end

Here we need to have the attribute ''show_if''.

==Automatic/headless building==
The eclipse plugins can be automatically built from command line, provided there is the eclipse sdk and the eclipse delta pack on the builder's machine. The plugin can also use Buckminster tool to automate the building of the plugin.

''Notes''
Add all plugin's files *inside* a folder to prevent cluttering the directory where it's extracted

More info at:
* http://wiki.eclipse.org/PDE/Build
* http://wiki.bioclipse.net/index.php?title=How_to_build_plugins_headless
* http://help.eclipse.org/galileo/index.jsp?topic=/org.eclipse.pde.doc.user/guide/intro/pde_overview.htm
* http://www.eclipse.org/articles/Article-PDE-Automation/automation.html

==Standalone app auto-update==
The current standalone application doesn't offer the same eclipse's update system. I will add it, so anytime there is a new version of the plugin, it can be updated with a single click by the user, without the needing to download a new standalone app again.

==Documentation==
===External documentation===
The current existing readme will be split in 2 manuals: User Manual and Developer Manual (Don't forget to add images where relevant).

The user manual will contain:
* Prerequisites and Installing the prerequisites
Note: don't forget to mention the MINIMUM eclipse/java version needed to run
* Installing the plugin / standalone version
* Using the plugin
* Plugin features
* Step-by-step use cases
** Setupping the workspace
** Creating a new project and running it in the game
** Importing existing projects
** Using the WML Editor
** Updating the plugin
* Frequently Asked Questions

The developer manual will contain:
* Prerequisites and Installing the prerequisites
* Adding the plugin's projects in the
* Compiling and Running the plugin
* Deploying the plugin and standalone app

===Internal documentation===
The Eclipse infrastructure has features for letting the developer embed help into the application, depending on the current context. After I will write the external documentation, I will work on adding internal documentation aswell. Some of it already comes from the external one.

* Plugin welcome page
* Eclipse Help (When pressing Help->Help contents)
* Wizards help

==Plugin polishing==
This are some tasks needed to be done in order to get the plugin more stable and more usable than it's currently. Some of the tasks are taken from my todo list. New tasks will be added through the project advancing when improvements to actual code /user interaction can be done, so this list is not final.

* Don't copy a project that belongs to data/campaigns to the user addons's directory. This can be done by looking at the path when creating a new project.
* Enhance the logging so it can help debugging other's problem much easier. I could split the current log in 2:
** Commands executed by the plugin
** Other informations like parsed information/statuses
* Enhance the integration with the eclipse platform by adding the "Wesnoth" related wizards directly to the "New" menu.
* Allow users to import a directory as a wesnoth project. Under the hood it will either open the wesnoth project (if there is any .project files in it) or create a new empty project on it.
* Allow the user to clear it's current plugin's settings just with a simple button.
* Wesnoth Project Explorer - Add error markers just like the Java Explorer has
* Refactor the current way of getting the macro list. Currently if there is no _main.cfg practicaly the _MACROS_.cfg file is not built resulting in no MACRO suggestions.
* Create a view filter to hide the Project ''_AutoLinked_CFGExternalFiles_'' which is created for opening the external config files (external meaning outside the current workspace).
* Fix the F3 navigation when the map's location is specified withing " ", as a string.

===New parsing method (optional)===
The current parsing method involves a lot of Wesnoth preprocessor/wmlparser.py. This is doing somehow the parsing job double. This is because the xtext framework already does 1 pass over the files when added to the project. My plan is to see if I can reuse the already built AST(Abstract Syntax Tree) and the parse tree, to use those values instead of additional preprocessing/wmlparsing, and use the latter only when really needed.

Using the xtext's model will greately fasten the "build" time of each project and it will be *much* simpler to work with, since the framework already provides exceptions recovering (that is, when the code is not well formed according to the grammar) and based on the defined grammar the respective tokens. So, for example instead using 2 another external processes, we could just iterate over each WMLTag and get it's WMLKeys and parse their individual values.

If this idea works, I will add it on the Plugin polishing tasks.

==Other ideas==
===Addons management===
There will be a new Addons management view. It will behave much like the in-game addon manager, but it will be more handy since the user doesn't need to start the game for that (and also wait till the cache refreshes after downloading it). This view will be based on the python script from '''data/tools/wesnoth_addon_manager''', like it does currently for uploading the project as an addon.

The view will let the user see the list/details for each of the addons currently on the server. There will be also a filter based on what addon server to use (trunk/1.8/1.9/etc)

The user will be able to just right click on an addon and download it to it's user data folder. Optionally a new project will be created, based on the just downloaded addon.



===Unit testing===
====Grammar====
For a better wml handling with in the editor, I will create a Testing class for the current grammar. The class will do testing on all *.cfgs in the data directory. That way after modifing something in the grammar we will be able to see how many errors we have introduced/eliminated. This will greatly help the developing of a better grammar that can hold all current WML formats.

''Notes'':
optionally rework the grammar and try to use a custom lexer/parser in order to benefit from the preprocessor, injecting the valid tokens. This would help the cases when the current grammar doesn't work:
{name} = value
or unclosed tags

====Parsing and getting information from files====
I will create some basic (or taken from existing campaigns) config files that will be parsed in order to check if the correct behaviour - correct information is extracted from the files.

This will check for extracting the:
scenario name
campaign name
next_scenario
first_scenario
variables
macros

=Timeline=
The GSOC period is between 24th May and 20th August. But since I have exams for 3 weeks (during 30.05-19.06.2011), I will start working on the plugin before the 24th of May, to recover some of the lost time. Also, my ImagineCup team made it to the national phase - that is in 5,6,7 May. That means till that time I will not be able to do so much work, so I'll make the timeline according with the starting of work on 9 May.

Here is a table with key periods of the time spent on this project.
{| border="1"
|'''Period''' || '''Actions'''
|-
| 26 April || Get accepted
|-
| 26 April - 8 May || Busy working on ImagineCup project for the national phase. Little or no work done.
|-
| 9 May - 15 May || Allow headless build of the plugin
|-
| 16 May - 22 May || Add Support for multiple installations
|-
| 23 May - 28 May || Add the auto-update feature for the standalone app
|-
| 30 May - 19 June || Exams
|-
| 20 June - 24 June || Create the external documentation
|-
| 25 June - 16 July || Enhance Content Assist
|-
| 15 July || Mid-term evaluations deadline
|-
| 17 July - 24 July || Addons management view
|-
| 25 July - 30 July || Unit tests
|-
| 1 August - 14 August || Do the Plugin polishing tasks
|-
| 15 August || Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc.
|-
| 15 August - 17 August || Create the internal documentation.
|-
| 18 August - 22 August || Buffer half-week. This will be used in case some tasks fell a bit outside their proposed time.
|-
| 22 August || Firm 'pencils down' date. Mentors, students and organization administrators can begin submitting final evaluations to Google.
|}

=Tasks=
This is a list of the "atomic" tasks that need to be done, based on the project part. Since the big tasks are split into smaller task, the progress will be seen better and any problems that arise with the timeline will be seen faster. I will update this table based on my current progress.

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Headless build ||Research about what system to use for automatic building of the plugin || Done
|-
| Headless build || Implement the chosen system for the wesnoth plugin|| Done
|-
| Multiple installations || Implement the preferences pages || Done
|-
| Multiple installations || Implement the logic for saving and loading the installation's paths on the disk || Done
|-
| Multiple installations || Implement the project preferences page || Done
|-
| Multiple installations || Rewrite the current mechanisms that use the paths to use the ones based on the project. || Done
|-
| Auto-update || Implement the auto-update feature. || In progress
|-
| Documentation || Write the User Manual || In Progress
|-
| Documentation || Write the Developer Manual || Done
|-
| Documentation || Write the internal documentation || None
|-
| Enhance Content Assist || Project dependency tree || None
|-
| Enhance Content Assist || Content assist files || None
|-
| Enhance Content Assist || Variables || None
|-
| Enhance Content Assist || Events || None
|-
| Enhance Content Assist || Lua tags || None
|-
| Addon management || Create the GUI of the view || None
|-
| Addon management || Create the view's logic || None
|-
| Unit testing || Tests for the grammar || None
|-
| Unit testing || Tests for parsing the config files || None
|}

Optional tasks will be dealt with if the time allows it:

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Enhance Content Assist || Project dependency tree with multiple paths based on defines || None
|-
| Enhance Content Assist || Lua tags attributes || None
|-
| Grammar || Enhance the grammar to support the 2 current unsupported syntax constructs || None
|-
| Documentation || Implement a simple WML project from start to end using Help's built-in cheat sheets tutorial || None
|}

=Questionnaire=
The questionnaire can be found here: http://wiki.wesnoth.org/User:Timotei21/Questionaire

SummerofCode2011 Timotei21

2011-06-25T16:51:44Z

Timotei21: update progress

{{SoC2011Student_2|timotei|SoC_Ideas_Eclipse_Plugin2011}}

=Description=
<h4>timotei - Improving the Eclipse Plugin</h4>
I aim at improving the plugin, so it will become the tool used by all UMC Authors. That is, UMC Authors will get rid of the lot of different tools they use for different tasks (for example the Emacs WMLMode/other plugins for different text editors), and instead use one single unified Tool that will speed up the development. My target is to make this plugin a complete and very stable suite for all umc tasks that don't need specialized software - like a graphics editor, so I'd like to have this oportunity to finish it in the good sense.

=Contacts=
==IRC==
timotei

==Other==
Forum: timotei 
gna.org: timotei

=SoC Application=
[http://www.google-melange.com/gsoc/proposal/review/google/gsoc2011/timoteidolean/1 Battle for Wesnoth - Google Summer of Code Application]

=Proposal Summary=
Page Last Updated: {{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}} 

In the following lines I will give details on how I'm planning to implement some of the required tasks, and also add some new ones.

The ''Notes'' sections are aimed for personal guideliness. They are took from my todo list.

==Multiple Wesnoth installations==
Having multiple wesnoth setups, and working with them at the same time would be nice to be done from inside the plugin.
For that, there will be a new preferences page. The page will look something like this:
http://dl.dropbox.com/u/462510/personal/soc/installations_management.PNG

There will be buttons that add/remove/edit a certain wesnoth installation. When adding/editing an installation, a new page like the current one (in which we set the paths), will be shown. The user will be able to name it and specify the version (I could automatically get the version by invoking ''wesnoth --version'').
The current page for setting the paths will act as a default installation.

After we have configured the paths, the user can chose the installation to which the (new) projects are bound, by opening the project properties. There will be a wesnoth-related page, where the user will be able to chose to what installation the project binds. With that, every command that uses the paths, won't use the single current paths, but the ones assigned to each project. This project properties page will open new ways for adding new

There would be a problem in case the project will be migrated between 2 different plugin's versions. For example, in one place we would have defined "1.9.4svn" but on the other there would be "trunk".

We can solve this in 3 ways:

# Alert the user that the installation doesn't bind, and let him chose the current matching installation for his plugin.
# Default automatically to the current plugin's default installation.
# "Hardcode" the version, so that there may be defined just installations like: 1.8.0, 1.9.3. With this we lose some flexibility, but we could use this as base version for new installations, so for example, a user can have two 1.9.3 installations. Provided this, we have again a possible problem, which can be solved again by 1. or 2., but this time, trying to match the base version first.

With this feature, the user won't need to restart the plugin at all, switching workspaces.

Regarding the technical PoV, all paths will be stored using eclipse's preferences system, by appending an unique id of each installation to each path in that set.

''Note'':
Add the NO_TERRAIN_GFX preprocess option checkbox to the project properties rather than being a global one.

==Enhance the Content Assist(CA) feature==
The CA framework is very extensible but it lacks proper contexts for providing the content.
I was thinking of trying to accomplish the generating of CA list either by using a config file, in case something like that can be used or writing directly the code that does that.

Another factor that is involved in a better auto-complete, is the ''schema.cfg'' the plugin bases on. Depending on whether the schema is worked on during this summer of code, I'll need to redo a bit the parser of the schema, in case the format/semantics change.

===Project files dependecy tree===
In order for the CA to work better - and maybe other areas would benefit from this - we will need to build a project files tree. With that tree, we can see how a certain declared macro/variable will affect subsequent related files and also their scope. Basically, we can see the relation from a file to anothers.

This tree will be (re)built in 2 situations:
# A file is added/removed/changed it's name
# A full rebuild is triggered (for example, the project is added for the first time in the workspace)

The tree will be built by the WML parser's rules:
# files are processed in the alphabetically order
# _initial.cfg is the first processed before anything else.
# _final.cfg is the last processed after anything else.
# if there is a _main.cfg in the directory, it is the only one processed.

Since the current ''WesnothProjectBuilder'' doesn't take in account the previous rules, I will create my own method of visiting each folder's children in the correct order. This method will look close to wesnoth's one, namely ''get_files_from_in_dir()'' found in ''src/filesystem.cpp:93''.

For a very fast lookup, as a data structure we will use a Hashtable, which has as the key the local project path to the file, and as a value a custom structure, which has the previous/next/parent/son properties, used to traverse the tree. The previous/next go on the same tree level, while the parent/son go up/down in the tree. I will use this instead of a tree, because this will give us access to info about a file, faster, in O(1) compared to a breadth-first search which has O(V+E) - where V is number of vertices and E number of edges.

Talking with Crab about this, he alerted me about a little possible problem with current aproach:
<Crab_> a note about 'The tree will be built by the WML parser's rules: ' - don't forget that you can (conditionally) include files/dirs from a file.
<Crab_> so, if we have 'ai/ais/zzz' which, say, defines a macro, it might get included by campaigns/bbb/scenarios/some_scenario.cfg , even if it is not inside /campaigns/bbb/scenarios

For that we have 2 cases:
{~file/dir path}
or
{file/dir path}

The paths are simply discarded if the current project's directory name is not found in the path.

Currently the so called "Tree" will be actually just a List or a single path tree. For the first iteration of this project, I won't tackle the advanced macro usage that might direct the flow based on defines (this will be optional if there will be time in GSoC, or if not, after GSoC, since I plan to remain active developer to maintain the plugin/enhance it furthermore). So, for example (taken from LoW):

#ifdef CAMPAIGN_LOW

{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#endif

#ifdef MULTIPLAYER

#define EASY
#enddef
{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#undef EASY
...
#endif

With current way to do this we will just take "blindly" all included directories/files without taking in consideration the #define flow control.

If we are at LoW, the following tree(list) will be created on its project:

_main.cfg -> utils/*.cfg -> scenarios/*.cfg -> units/*.cfg

Each file in the dependency tree, will have associated a number. For more details on why this and how it's done, read the Scoping section.

===Scoping===
In order for the plugin to know more about the semnatics, it should have the posibility to represent scopes. The scopes will be used mainly for variables and macros.

The Scoping is a delicate problem, because there are some tricky situations that might interfere with the scoping. I choosed to represent scoping in the following way:

Scoping is everything just about order relations. That is, we will compare numbers when dealing with scoping. With that we move the "problem" upper, to the "Dependency tree". We won't use filenames/paths because:

* The filename might change, but the order index may not. So, not having to update the index helps us.
* Number comparison is faster than string comparison.

So, from now on we'll talk in terms of indexes instead of filenames for scoping.

So, we are working with numbers. But there is still a lil' problem. What happens, when we remove/need to add a new file in the current tree, in the middle of existing 2? We would need to update all subsequent files's indexes. That would not be so ok performance wise.

To counter this problem we will not use consecutive numbers, but rather have a certain step between numbers. The step might be configured inside the plugin based on real statistics (for example, trying to see the number of cfg files per project. Taking a big number, like 1000 won't really hurt). For example, we could take the step 50. That means we would have the following tree for LoW:

0 50 100
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

instead of:
0 1 2
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

So, when it's the case of insertion, we insert the new node at the ''middle'' of the current "distance". That way we may insert/delete files *without* breaking the order, and our scoping will still work.

There is another problem it rised in my head: how do we know when to put the number as the next step (the previous number + step) or add it in the middle? Well, since every project will surely do a '''Full Build''', we'll use that oportunity to create the initial tree. Afterwards we will just insert files based on the halving of the distance between 2 indices.

The scoping will be represented by a simple structure, consisting of start index and offset and end index and offset.

===Content Assist Config(CAC) Files===
The CAC files will provide values that are default/available to config files from the wesnoth engine itself. There will be several files that define the values based on their context. This will allow a very great flexibility editing the CA list.

A CAC file will be just a simple text file, that has on each line one (or more) value(s) depending on the context.

* The ''cac/variables.txt'' will contain variables available. The list is currently available at [http://wiki.wesnoth.org/VariablesWML#Automatically_stored_variables]. For example the file could look like:
$side_number
$turn_number
...

* The ''cac/events.txt'' will contain the game events. The list is availabe at: [http://wiki.wesnoth.org/EventWML#Predefined_.27name.27_Key_Values]. Since the events that have spaces in their names can replace that with an underscore '_', the file will contain the underscore instead space variants also.



===Variables===
The variables are either defined by user or defined by default by the wesnoth engine. User's variables will be parsed from each processed file by the WesnothProjectBuilder, using the WMLSaxHandler. The default variables will be parsed and added from the CAC file. (cac/variables.txt)

Variables definitions can be triggered using the VARIABLE macro:
{VARIABLE var_name "value"}
or the [set_variable] tag:
[set_variable]
name=my_var
value="value"
[/set_variable]

The ''ConfigFile'' class in the ''org.wesnoth.wml.core'' already has a list of variables. The ''Variable'' class has some fields that allow its identification. We will build that list when we parse each file, adding each variable found by the previous defined triggers.
When the content assist finds the '$' character, it will supply the user + default variables gathered so far.

Since the variables can be cleared, thus they have scope, the ''Variable'' class needs to be refactorted, so it can represent the scope aswell. The scoping was settled before.

===Name Collisions===
I've considered that we should store the variables per project, like we currently do with macros. This will minimize the memory we need, rather than storing variables on each file - like we do currently. With this, I've discovered it's innevitable to have ''collisions''. That is, have the same variable name on multiple files.

To solve this problem, each variable/macro structure, will not have just a single scope, but rather a list of scopes.

===Events===
Besides the default event names, supplied by the wesnoth engine, there can be created custom ones, wich will be triggered with [fire_event]. As usual the default events names will be available in the cac/events.txt file.

The events defined by the user will be parsed from the ''name'' attribute of the [event] tag.

===Attributes===
All attributes are currently got from the schema.cfg

===Attributes Values===
All attributes values should be parsed based on the schema.cfg.

===Macros===
The support for macros is already built in, but it needs a way to let them have scope. That is, when an #undef is found, the certain macro would not be available to subsequent files unless redeclared. This will be done with the aid of the dependency tree and scoping. The collisions will be solved like I said at the variables section

===Support for custom luaWML tags===
The lua can create new WML Tags. It would be nice that the plugin suggest those aswell besides the ''schema.cfg''. The lua will be easily parsed, since there is a simple pattern for creating new tags:
wesnoth.wml_actions.<tag name>(cfg)

The parser will just run over the lua code/file, over each line, trying to match the 'function *wesnoth.wml_actions.*' pattern. If it finds something, it will add the tag name to the list of tags. There is also a small thing we might have missed. The user could use a shorthand notation for the actions namespace, so when searching for the pattern, I will add to the 'pattern to match' list, the respective variable when searching for new WML Tags.

Thus, like the ''wml-tags.lua'' from the data/lua uses:
local wml_actions = wesnoth.wml_actions

the 'to match' list will contain: 'function *wesnoth.wml_actions.*' and 'function *wml_actions.*', thus finding other tags too.

Going further more, for an ''optional'' enhancement, I could also search that function to see if it needs/has some extra attributes. The attributes can be found by:
* function's parameter (usually cfg) is asked for a property. For example:
function wml_actions.terrain(cfg)
local terrain = cfg.terrain or helper.wml_error("[terrain] missing required terrain= attribute")
cfg = helper.shallow_literal(cfg)
cfg.terrain = nil
for i, loc in ipairs(wesnoth.get_locations(cfg)) do
wesnoth.set_terrain(loc[1], loc[2], terrain, cfg.layer, cfg.replace_if_failed)
end
end

Here we need the attributes ''terrain'', ''layer'' and ''replace_if_failed''.

* ''get_child'' call:
function wml_actions.message(cfg)
local show_if = helper.get_child(cfg, "show_if")
if not show_if or wesnoth.eval_conditional(show_if) then
engine_message(cfg)
end
end

Here we need to have the attribute ''show_if''.

==Automatic/headless building==
The eclipse plugins can be automatically built from command line, provided there is the eclipse sdk and the eclipse delta pack on the builder's machine. The plugin can also use Buckminster tool to automate the building of the plugin.

''Notes''
Add all plugin's files *inside* a folder to prevent cluttering the directory where it's extracted

More info at:
* http://wiki.eclipse.org/PDE/Build
* http://wiki.bioclipse.net/index.php?title=How_to_build_plugins_headless
* http://help.eclipse.org/galileo/index.jsp?topic=/org.eclipse.pde.doc.user/guide/intro/pde_overview.htm
* http://www.eclipse.org/articles/Article-PDE-Automation/automation.html

==Standalone app auto-update==
The current standalone application doesn't offer the same eclipse's update system. I will add it, so anytime there is a new version of the plugin, it can be updated with a single click by the user, without the needing to download a new standalone app again.

==Documentation==
===External documentation===
The current existing readme will be split in 2 manuals: User Manual and Developer Manual (Don't forget to add images where relevant).

The user manual will contain:
* Prerequisites and Installing the prerequisites
Note: don't forget to mention the MINIMUM eclipse/java version needed to run
* Installing the plugin / standalone version
* Using the plugin
* Plugin features
* Step-by-step use cases
** Setupping the workspace
** Creating a new project and running it in the game
** Importing existing projects
** Using the WML Editor
** Updating the plugin
* Frequently Asked Questions

The developer manual will contain:
* Prerequisites and Installing the prerequisites
* Adding the plugin's projects in the
* Compiling and Running the plugin
* Deploying the plugin and standalone app

===Internal documentation===
The Eclipse infrastructure has features for letting the developer embed help into the application, depending on the current context. After I will write the external documentation, I will work on adding internal documentation aswell. Some of it already comes from the external one.

* Plugin welcome page
* Eclipse Help (When pressing Help->Help contents)
* Wizards help

==Plugin polishing==
This are some tasks needed to be done in order to get the plugin more stable and more usable than it's currently. Some of the tasks are taken from my todo list. New tasks will be added through the project advancing when improvements to actual code /user interaction can be done, so this list is not final.

* Don't copy a project that belongs to data/campaigns to the user addons's directory. This can be done by looking at the path when creating a new project.
* Enhance the logging so it can help debugging other's problem much easier. I could split the current log in 2:
** Commands executed by the plugin
** Other informations like parsed information/statuses
* Enhance the integration with the eclipse platform by adding the "Wesnoth" related wizards directly to the "New" menu.
* Allow users to import a directory as a wesnoth project. Under the hood it will either open the wesnoth project (if there is any .project files in it) or create a new empty project on it.
* Allow the user to clear it's current plugin's settings just with a simple button.
* Wesnoth Project Explorer - Add error markers just like the Java Explorer has
* Refactor the current way of getting the macro list. Currently if there is no _main.cfg practicaly the _MACROS_.cfg file is not built resulting in no MACRO suggestions.
* Create a view filter to hide the Project ''_AutoLinked_CFGExternalFiles_'' which is created for opening the external config files (external meaning outside the current workspace).
* Fix the F3 navigation when the map's location is specified withing " ", as a string.

===New parsing method (optional)===
The current parsing method involves a lot of Wesnoth preprocessor/wmlparser.py. This is doing somehow the parsing job double. This is because the xtext framework already does 1 pass over the files when added to the project. My plan is to see if I can reuse the already built AST(Abstract Syntax Tree) and the parse tree, to use those values instead of additional preprocessing/wmlparsing, and use the latter only when really needed.

Using the xtext's model will greately fasten the "build" time of each project and it will be *much* simpler to work with, since the framework already provides exceptions recovering (that is, when the code is not well formed according to the grammar) and based on the defined grammar the respective tokens. So, for example instead using 2 another external processes, we could just iterate over each WMLTag and get it's WMLKeys and parse their individual values.

If this idea works, I will add it on the Plugin polishing tasks.

==Other ideas==
===Addons management===
There will be a new Addons management view. It will behave much like the in-game addon manager, but it will be more handy since the user doesn't need to start the game for that (and also wait till the cache refreshes after downloading it). This view will be based on the python script from '''data/tools/wesnoth_addon_manager''', like it does currently for uploading the project as an addon.

The view will let the user see the list/details for each of the addons currently on the server. There will be also a filter based on what addon server to use (trunk/1.8/1.9/etc)

The user will be able to just right click on an addon and download it to it's user data folder. Optionally a new project will be created, based on the just downloaded addon.



===Unit testing===
====Grammar====
For a better wml handling with in the editor, I will create a Testing class for the current grammar. The class will do testing on all *.cfgs in the data directory. That way after modifing something in the grammar we will be able to see how many errors we have introduced/eliminated. This will greatly help the developing of a better grammar that can hold all current WML formats.

''Notes'':
optionally rework the grammar and try to use a custom lexer/parser in order to benefit from the preprocessor, injecting the valid tokens. This would help the cases when the current grammar doesn't work:
{name} = value
or unclosed tags

====Parsing and getting information from files====
I will create some basic (or taken from existing campaigns) config files that will be parsed in order to check if the correct behaviour - correct information is extracted from the files.

This will check for extracting the:
scenario name
campaign name
next_scenario
first_scenario
variables
macros

=Timeline=
The GSOC period is between 24th May and 20th August. But since I have exams for 3 weeks (during 30.05-19.06.2011), I will start working on the plugin before the 24th of May, to recover some of the lost time. Also, my ImagineCup team made it to the national phase - that is in 5,6,7 May. That means till that time I will not be able to do so much work, so I'll make the timeline according with the starting of work on 9 May.

Here is a table with key periods of the time spent on this project.
{| border="1"
|'''Period''' || '''Actions'''
|-
| 26 April || Get accepted
|-
| 26 April - 8 May || Busy working on ImagineCup project for the national phase. Little or no work done.
|-
| 9 May - 15 May || Allow headless build of the plugin
|-
| 16 May - 22 May || Add Support for multiple installations
|-
| 23 May - 28 May || Add the auto-update feature for the standalone app
|-
| 30 May - 19 June || Exams
|-
| 20 June - 24 June || Create the external documentation
|-
| 25 June - 16 July || Enhance Content Assist
|-
| 15 July || Mid-term evaluations deadline
|-
| 17 July - 24 July || Addons management view
|-
| 25 July - 30 July || Unit tests
|-
| 1 August - 14 August || Do the Plugin polishing tasks
|-
| 15 August || Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc.
|-
| 15 August - 17 August || Create the internal documentation.
|-
| 18 August - 22 August || Buffer half-week. This will be used in case some tasks fell a bit outside their proposed time.
|-
| 22 August || Firm 'pencils down' date. Mentors, students and organization administrators can begin submitting final evaluations to Google.
|}

=Tasks=
This is a list of the "atomic" tasks that need to be done, based on the project part. Since the big tasks are split into smaller task, the progress will be seen better and any problems that arise with the timeline will be seen faster. I will update this table based on my current progress.

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Headless build ||Research about what system to use for automatic building of the plugin || Done
|-
| Headless build || Implement the chosen system for the wesnoth plugin|| Done
|-
| Multiple installations || Implement the preferences pages || Done
|-
| Multiple installations || Implement the logic for saving and loading the installation's paths on the disk || Done
|-
| Multiple installations || Implement the project preferences page || Done
|-
| Multiple installations || Rewrite the current mechanisms that use the paths to use the ones based on the project. || Done
|-
| Auto-update || Implement the auto-update feature. || In progress
|-
| Documentation || Write the User Manual || In Progress
|-
| Documentation || Write the Developer Manual || In Progress
|-
| Documentation || Write the internal documentation || None
|-
| Enhance Content Assist || Project dependency tree || None
|-
| Enhance Content Assist || Content assist files || None
|-
| Enhance Content Assist || Variables || None
|-
| Enhance Content Assist || Events || None
|-
| Enhance Content Assist || Lua tags || None
|-
| Addon management || Create the GUI of the view || None
|-
| Addon management || Create the view's logic || None
|-
| Unit testing || Tests for the grammar || None
|-
| Unit testing || Tests for parsing the config files || None
|}

Optional tasks will be dealt with if the time allows it:

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Enhance Content Assist || Project dependency tree with multiple paths based on defines || None
|-
| Enhance Content Assist || Lua tags attributes || None
|-
| Grammar || Enhance the grammar to support the 2 current unsupported syntax constructs || None
|-
| Documentation || Implement a simple WML project from start to end using Help's built-in cheat sheets tutorial || None
|}

=Questionnaire=
The questionnaire can be found here: http://wiki.wesnoth.org/User:Timotei21/Questionaire

SummerofCode2011 Timotei21

2011-06-22T12:42:11Z

Timotei21: /* Tasks */

{{SoC2011Student_2|timotei|SoC_Ideas_Eclipse_Plugin2011}}

=Description=
<h4>timotei - Improving the Eclipse Plugin</h4>
I aim at improving the plugin, so it will become the tool used by all UMC Authors. That is, UMC Authors will get rid of the lot of different tools they use for different tasks (for example the Emacs WMLMode/other plugins for different text editors), and instead use one single unified Tool that will speed up the development. My target is to make this plugin a complete and very stable suite for all umc tasks that don't need specialized software - like a graphics editor, so I'd like to have this oportunity to finish it in the good sense.

=Contacts=
==IRC==
timotei

==Other==
Forum: timotei 
gna.org: timotei

=SoC Application=
[http://www.google-melange.com/gsoc/proposal/review/google/gsoc2011/timoteidolean/1 Battle for Wesnoth - Google Summer of Code Application]

=Proposal Summary=
Page Last Updated: {{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}} 

In the following lines I will give details on how I'm planning to implement some of the required tasks, and also add some new ones.

The ''Notes'' sections are aimed for personal guideliness. They are took from my todo list.

==Multiple Wesnoth installations==
Having multiple wesnoth setups, and working with them at the same time would be nice to be done from inside the plugin.
For that, there will be a new preferences page. The page will look something like this:
http://dl.dropbox.com/u/462510/personal/soc/installations_management.PNG

There will be buttons that add/remove/edit a certain wesnoth installation. When adding/editing an installation, a new page like the current one (in which we set the paths), will be shown. The user will be able to name it and specify the version (I could automatically get the version by invoking ''wesnoth --version'').
The current page for setting the paths will act as a default installation.

After we have configured the paths, the user can chose the installation to which the (new) projects are bound, by opening the project properties. There will be a wesnoth-related page, where the user will be able to chose to what installation the project binds. With that, every command that uses the paths, won't use the single current paths, but the ones assigned to each project. This project properties page will open new ways for adding new

There would be a problem in case the project will be migrated between 2 different plugin's versions. For example, in one place we would have defined "1.9.4svn" but on the other there would be "trunk".

We can solve this in 3 ways:

# Alert the user that the installation doesn't bind, and let him chose the current matching installation for his plugin.
# Default automatically to the current plugin's default installation.
# "Hardcode" the version, so that there may be defined just installations like: 1.8.0, 1.9.3. With this we lose some flexibility, but we could use this as base version for new installations, so for example, a user can have two 1.9.3 installations. Provided this, we have again a possible problem, which can be solved again by 1. or 2., but this time, trying to match the base version first.

With this feature, the user won't need to restart the plugin at all, switching workspaces.

Regarding the technical PoV, all paths will be stored using eclipse's preferences system, by appending an unique id of each installation to each path in that set.

''Note'':
Add the NO_TERRAIN_GFX preprocess option checkbox to the project properties rather than being a global one.

==Enhance the Content Assist(CA) feature==
The CA framework is very extensible but it lacks proper contexts for providing the content.
I was thinking of trying to accomplish the generating of CA list either by using a config file, in case something like that can be used or writing directly the code that does that.

Another factor that is involved in a better auto-complete, is the ''schema.cfg'' the plugin bases on. Depending on whether the schema is worked on during this summer of code, I'll need to redo a bit the parser of the schema, in case the format/semantics change.

===Project files dependecy tree===
In order for the CA to work better - and maybe other areas would benefit from this - we will need to build a project files tree. With that tree, we can see how a certain declared macro/variable will affect subsequent related files and also their scope. Basically, we can see the relation from a file to anothers.

This tree will be (re)built in 2 situations:
# A file is added/removed/changed it's name
# A full rebuild is triggered (for example, the project is added for the first time in the workspace)

The tree will be built by the WML parser's rules:
# files are processed in the alphabetically order
# _initial.cfg is the first processed before anything else.
# _final.cfg is the last processed after anything else.
# if there is a _main.cfg in the directory, it is the only one processed.

Since the current ''WesnothProjectBuilder'' doesn't take in account the previous rules, I will create my own method of visiting each folder's children in the correct order. This method will look close to wesnoth's one, namely ''get_files_from_in_dir()'' found in ''src/filesystem.cpp:93''.

For a very fast lookup, as a data structure we will use a Hashtable, which has as the key the local project path to the file, and as a value a custom structure, which has the previous/next/parent/son properties, used to traverse the tree. The previous/next go on the same tree level, while the parent/son go up/down in the tree. I will use this instead of a tree, because this will give us access to info about a file, faster, in O(1) compared to a breadth-first search which has O(V+E) - where V is number of vertices and E number of edges.

Talking with Crab about this, he alerted me about a little possible problem with current aproach:
<Crab_> a note about 'The tree will be built by the WML parser's rules: ' - don't forget that you can (conditionally) include files/dirs from a file.
<Crab_> so, if we have 'ai/ais/zzz' which, say, defines a macro, it might get included by campaigns/bbb/scenarios/some_scenario.cfg , even if it is not inside /campaigns/bbb/scenarios

For that we have 2 cases:
{~file/dir path}
or
{file/dir path}

The paths are simply discarded if the current project's directory name is not found in the path.

Currently the so called "Tree" will be actually just a List or a single path tree. For the first iteration of this project, I won't tackle the advanced macro usage that might direct the flow based on defines (this will be optional if there will be time in GSoC, or if not, after GSoC, since I plan to remain active developer to maintain the plugin/enhance it furthermore). So, for example (taken from LoW):

#ifdef CAMPAIGN_LOW

{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#endif

#ifdef MULTIPLAYER

#define EASY
#enddef
{campaigns/Legend_of_Wesmere/utils}
{campaigns/Legend_of_Wesmere/scenarios}
#undef EASY
...
#endif

With current way to do this we will just take "blindly" all included directories/files without taking in consideration the #define flow control.

If we are at LoW, the following tree(list) will be created on its project:

_main.cfg -> utils/*.cfg -> scenarios/*.cfg -> units/*.cfg

Each file in the dependency tree, will have associated a number. For more details on why this and how it's done, read the Scoping section.

===Scoping===
In order for the plugin to know more about the semnatics, it should have the posibility to represent scopes. The scopes will be used mainly for variables and macros.

The Scoping is a delicate problem, because there are some tricky situations that might interfere with the scoping. I choosed to represent scoping in the following way:

Scoping is everything just about order relations. That is, we will compare numbers when dealing with scoping. With that we move the "problem" upper, to the "Dependency tree". We won't use filenames/paths because:

* The filename might change, but the order index may not. So, not having to update the index helps us.
* Number comparison is faster than string comparison.

So, from now on we'll talk in terms of indexes instead of filenames for scoping.

So, we are working with numbers. But there is still a lil' problem. What happens, when we remove/need to add a new file in the current tree, in the middle of existing 2? We would need to update all subsequent files's indexes. That would not be so ok performance wise.

To counter this problem we will not use consecutive numbers, but rather have a certain step between numbers. The step might be configured inside the plugin based on real statistics (for example, trying to see the number of cfg files per project. Taking a big number, like 1000 won't really hurt). For example, we could take the step 50. That means we would have the following tree for LoW:

0 50 100
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

instead of:
0 1 2
_main.cfg -> utils/_main.cfg -> utils/journey.cfg -> ....

So, when it's the case of insertion, we insert the new node at the ''middle'' of the current "distance". That way we may insert/delete files *without* breaking the order, and our scoping will still work.

There is another problem it rised in my head: how do we know when to put the number as the next step (the previous number + step) or add it in the middle? Well, since every project will surely do a '''Full Build''', we'll use that oportunity to create the initial tree. Afterwards we will just insert files based on the halving of the distance between 2 indices.

The scoping will be represented by a simple structure, consisting of start index and offset and end index and offset.

===Content Assist Config(CAC) Files===
The CAC files will provide values that are default/available to config files from the wesnoth engine itself. There will be several files that define the values based on their context. This will allow a very great flexibility editing the CA list.

A CAC file will be just a simple text file, that has on each line one (or more) value(s) depending on the context.

* The ''cac/variables.txt'' will contain variables available. The list is currently available at [http://wiki.wesnoth.org/VariablesWML#Automatically_stored_variables]. For example the file could look like:
$side_number
$turn_number
...

* The ''cac/events.txt'' will contain the game events. The list is availabe at: [http://wiki.wesnoth.org/EventWML#Predefined_.27name.27_Key_Values]. Since the events that have spaces in their names can replace that with an underscore '_', the file will contain the underscore instead space variants also.



===Variables===
The variables are either defined by user or defined by default by the wesnoth engine. User's variables will be parsed from each processed file by the WesnothProjectBuilder, using the WMLSaxHandler. The default variables will be parsed and added from the CAC file. (cac/variables.txt)

Variables definitions can be triggered using the VARIABLE macro:
{VARIABLE var_name "value"}
or the [set_variable] tag:
[set_variable]
name=my_var
value="value"
[/set_variable]

The ''ConfigFile'' class in the ''org.wesnoth.wml.core'' already has a list of variables. The ''Variable'' class has some fields that allow its identification. We will build that list when we parse each file, adding each variable found by the previous defined triggers.
When the content assist finds the '$' character, it will supply the user + default variables gathered so far.

Since the variables can be cleared, thus they have scope, the ''Variable'' class needs to be refactorted, so it can represent the scope aswell. The scoping was settled before.

===Name Collisions===
I've considered that we should store the variables per project, like we currently do with macros. This will minimize the memory we need, rather than storing variables on each file - like we do currently. With this, I've discovered it's innevitable to have ''collisions''. That is, have the same variable name on multiple files.

To solve this problem, each variable/macro structure, will not have just a single scope, but rather a list of scopes.

===Events===
Besides the default event names, supplied by the wesnoth engine, there can be created custom ones, wich will be triggered with [fire_event]. As usual the default events names will be available in the cac/events.txt file.

The events defined by the user will be parsed from the ''name'' attribute of the [event] tag.

===Attributes===
All attributes are currently got from the schema.cfg

===Attributes Values===
All attributes values should be parsed based on the schema.cfg.

===Macros===
The support for macros is already built in, but it needs a way to let them have scope. That is, when an #undef is found, the certain macro would not be available to subsequent files unless redeclared. This will be done with the aid of the dependency tree and scoping. The collisions will be solved like I said at the variables section

===Support for custom luaWML tags===
The lua can create new WML Tags. It would be nice that the plugin suggest those aswell besides the ''schema.cfg''. The lua will be easily parsed, since there is a simple pattern for creating new tags:
wesnoth.wml_actions.<tag name>(cfg)

The parser will just run over the lua code/file, over each line, trying to match the 'function *wesnoth.wml_actions.*' pattern. If it finds something, it will add the tag name to the list of tags. There is also a small thing we might have missed. The user could use a shorthand notation for the actions namespace, so when searching for the pattern, I will add to the 'pattern to match' list, the respective variable when searching for new WML Tags.

Thus, like the ''wml-tags.lua'' from the data/lua uses:
local wml_actions = wesnoth.wml_actions

the 'to match' list will contain: 'function *wesnoth.wml_actions.*' and 'function *wml_actions.*', thus finding other tags too.

Going further more, for an ''optional'' enhancement, I could also search that function to see if it needs/has some extra attributes. The attributes can be found by:
* function's parameter (usually cfg) is asked for a property. For example:
function wml_actions.terrain(cfg)
local terrain = cfg.terrain or helper.wml_error("[terrain] missing required terrain= attribute")
cfg = helper.shallow_literal(cfg)
cfg.terrain = nil
for i, loc in ipairs(wesnoth.get_locations(cfg)) do
wesnoth.set_terrain(loc[1], loc[2], terrain, cfg.layer, cfg.replace_if_failed)
end
end

Here we need the attributes ''terrain'', ''layer'' and ''replace_if_failed''.

* ''get_child'' call:
function wml_actions.message(cfg)
local show_if = helper.get_child(cfg, "show_if")
if not show_if or wesnoth.eval_conditional(show_if) then
engine_message(cfg)
end
end

Here we need to have the attribute ''show_if''.

==Automatic/headless building==
The eclipse plugins can be automatically built from command line, provided there is the eclipse sdk and the eclipse delta pack on the builder's machine. The plugin can also use Buckminster tool to automate the building of the plugin.

''Notes''
Add all plugin's files *inside* a folder to prevent cluttering the directory where it's extracted

More info at:
* http://wiki.eclipse.org/PDE/Build
* http://wiki.bioclipse.net/index.php?title=How_to_build_plugins_headless
* http://help.eclipse.org/galileo/index.jsp?topic=/org.eclipse.pde.doc.user/guide/intro/pde_overview.htm
* http://www.eclipse.org/articles/Article-PDE-Automation/automation.html

==Standalone app auto-update==
The current standalone application doesn't offer the same eclipse's update system. I will add it, so anytime there is a new version of the plugin, it can be updated with a single click by the user, without the needing to download a new standalone app again.

==Documentation==
===External documentation===
The current existing readme will be split in 2 manuals: User Manual and Developer Manual (Don't forget to add images where relevant).

The user manual will contain:
* Prerequisites and Installing the prerequisites
Note: don't forget to mention the MINIMUM eclipse/java version needed to run
* Installing the plugin / standalone version
* Using the plugin
* Plugin features
* Step-by-step use cases
** Setupping the workspace
** Creating a new project and running it in the game
** Importing existing projects
** Using the WML Editor
** Updating the plugin
* Frequently Asked Questions

The developer manual will contain:
* Prerequisites and Installing the prerequisites
* Adding the plugin's projects in the
* Compiling and Running the plugin
* Deploying the plugin and standalone app

===Internal documentation===
The Eclipse infrastructure has features for letting the developer embed help into the application, depending on the current context. After I will write the external documentation, I will work on adding internal documentation aswell. Some of it already comes from the external one.

* Plugin welcome page
* Eclipse Help (When pressing Help->Help contents)
* Wizards help

==Plugin polishing==
This are some tasks needed to be done in order to get the plugin more stable and more usable than it's currently. Some of the tasks are taken from my todo list. New tasks will be added through the project advancing when improvements to actual code /user interaction can be done, so this list is not final.

* Don't copy a project that belongs to data/campaigns to the user addons's directory. This can be done by looking at the path when creating a new project.
* Enhance the logging so it can help debugging other's problem much easier. I could split the current log in 2:
** Commands executed by the plugin
** Other informations like parsed information/statuses
* Enhance the integration with the eclipse platform by adding the "Wesnoth" related wizards directly to the "New" menu.
* Allow users to import a directory as a wesnoth project. Under the hood it will either open the wesnoth project (if there is any .project files in it) or create a new empty project on it.
* Allow the user to clear it's current plugin's settings just with a simple button.
* Wesnoth Project Explorer - Add error markers just like the Java Explorer has
* Refactor the current way of getting the macro list. Currently if there is no _main.cfg practicaly the _MACROS_.cfg file is not built resulting in no MACRO suggestions.
* Create a view filter to hide the Project ''_AutoLinked_CFGExternalFiles_'' which is created for opening the external config files (external meaning outside the current workspace).
* Fix the F3 navigation when the map's location is specified withing " ", as a string.

===New parsing method (optional)===
The current parsing method involves a lot of Wesnoth preprocessor/wmlparser.py. This is doing somehow the parsing job double. This is because the xtext framework already does 1 pass over the files when added to the project. My plan is to see if I can reuse the already built AST(Abstract Syntax Tree) and the parse tree, to use those values instead of additional preprocessing/wmlparsing, and use the latter only when really needed.

Using the xtext's model will greately fasten the "build" time of each project and it will be *much* simpler to work with, since the framework already provides exceptions recovering (that is, when the code is not well formed according to the grammar) and based on the defined grammar the respective tokens. So, for example instead using 2 another external processes, we could just iterate over each WMLTag and get it's WMLKeys and parse their individual values.

If this idea works, I will add it on the Plugin polishing tasks.

==Other ideas==
===Addons management===
There will be a new Addons management view. It will behave much like the in-game addon manager, but it will be more handy since the user doesn't need to start the game for that (and also wait till the cache refreshes after downloading it). This view will be based on the python script from '''data/tools/wesnoth_addon_manager''', like it does currently for uploading the project as an addon.

The view will let the user see the list/details for each of the addons currently on the server. There will be also a filter based on what addon server to use (trunk/1.8/1.9/etc)

The user will be able to just right click on an addon and download it to it's user data folder. Optionally a new project will be created, based on the just downloaded addon.



===Unit testing===
====Grammar====
For a better wml handling with in the editor, I will create a Testing class for the current grammar. The class will do testing on all *.cfgs in the data directory. That way after modifing something in the grammar we will be able to see how many errors we have introduced/eliminated. This will greatly help the developing of a better grammar that can hold all current WML formats.

''Notes'':
optionally rework the grammar and try to use a custom lexer/parser in order to benefit from the preprocessor, injecting the valid tokens. This would help the cases when the current grammar doesn't work:
{name} = value
or unclosed tags

====Parsing and getting information from files====
I will create some basic (or taken from existing campaigns) config files that will be parsed in order to check if the correct behaviour - correct information is extracted from the files.

This will check for extracting the:
scenario name
campaign name
next_scenario
first_scenario
variables
macros

=Timeline=
The GSOC period is between 24th May and 20th August. But since I have exams for 3 weeks (during 30.05-19.06.2011), I will start working on the plugin before the 24th of May, to recover some of the lost time. Also, my ImagineCup team made it to the national phase - that is in 5,6,7 May. That means till that time I will not be able to do so much work, so I'll make the timeline according with the starting of work on 9 May.

Here is a table with key periods of the time spent on this project.
{| border="1"
|'''Period''' || '''Actions'''
|-
| 26 April || Get accepted
|-
| 26 April - 8 May || Busy working on ImagineCup project for the national phase. Little or no work done.
|-
| 9 May - 15 May || Allow headless build of the plugin
|-
| 16 May - 22 May || Add Support for multiple installations
|-
| 23 May - 28 May || Add the auto-update feature for the standalone app
|-
| 30 May - 19 June || Exams
|-
| 20 June - 24 June || Create the external documentation
|-
| 25 June - 16 July || Enhance Content Assist
|-
| 15 July || Mid-term evaluations deadline
|-
| 17 July - 24 July || Addons management view
|-
| 25 July - 30 July || Unit tests
|-
| 1 August - 14 August || Do the Plugin polishing tasks
|-
| 15 August || Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc.
|-
| 15 August - 17 August || Create the internal documentation.
|-
| 18 August - 22 August || Buffer half-week. This will be used in case some tasks fell a bit outside their proposed time.
|-
| 22 August || Firm 'pencils down' date. Mentors, students and organization administrators can begin submitting final evaluations to Google.
|}

=Tasks=
This is a list of the "atomic" tasks that need to be done, based on the project part. Since the big tasks are split into smaller task, the progress will be seen better and any problems that arise with the timeline will be seen faster. I will update this table based on my current progress.

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Headless build ||Research about what system to use for automatic building of the plugin || Done
|-
| Headless build || Implement the chosen system for the wesnoth plugin|| Done
|-
| Multiple installations || Implement the preferences pages || Done
|-
| Multiple installations || Implement the logic for saving and loading the installation's paths on the disk || Done
|-
| Multiple installations || Implement the project preferences page || Done
|-
| Multiple installations || Rewrite the current mechanisms that use the paths to use the ones based on the project. || Done
|-
| Auto-update || Implement the auto-update feature. || In progress
|-
| Documentation || Write the User Manual || In Progress
|-
| Documentation || Write the Developer Manual || None
|-
| Documentation || Write the internal documentation || None
|-
| Enhance Content Assist || Project dependency tree || None
|-
| Enhance Content Assist || Content assist files || None
|-
| Enhance Content Assist || Variables || None
|-
| Enhance Content Assist || Events || None
|-
| Enhance Content Assist || Lua tags || None
|-
| Addon management || Create the GUI of the view || None
|-
| Addon management || Create the view's logic || None
|-
| Unit testing || Tests for the grammar || None
|-
| Unit testing || Tests for parsing the config files || None
|}

Optional tasks will be dealt with if the time allows it:

{|border="1"
|Project part || Task || Status (Legend: None, Done, Not done, In Progress)
|-
| Enhance Content Assist || Project dependency tree with multiple paths based on defines || None
|-
| Enhance Content Assist || Lua tags attributes || None
|-
| Grammar || Enhance the grammar to support the 2 current unsupported syntax constructs || None
|-
| Documentation || Implement a simple WML project from start to end using Help's built-in cheat sheets tutorial || None
|}

=Questionnaire=
The questionnaire can be found here: http://wiki.wesnoth.org/User:Timotei21/Questionaire