Cheap in-game Help

[SirVer]

As a totally awesome, overcool online help with cross linking and layouting is still some time away, I suggest adding a "cheap" help to widelands in build 17.

The idea is that basically every window gets a "?" button which opens a window with a textarea explaining what's going on here. The texts could be saved in external files (for example lua scripts) which would make translating easier as it does away with layouting more easily. This is an easy enhancement that only requires a lot of writing and a bit more code.

Note that I feel that this a 80% solution, but better than the nothing we currently have.

[Hans Joachim Desserud (hjd)]

In-game help, especially with links going back and forth would be awesome.
I'm unsure why you label it as online help, though. Could you elaborate a bit there? Shouldn't the help files be available locally without Internet connection as well?

[SirVer (sirver)]

I miswrote, of course I meant ingame help. I corrected the name of this bug.

As mentioned, this is not about a help with images and links between topics (that would be my 100% solution; i always drool when I take a look at wesnoth's help). What i suggest with this bug report is a cheap help window with a plaintext very much like settlers 2 had. Just to give the user some kind of reference in game.

[Hans Joachim Desserud (hjd)]

Ok, thanks for clarifying.

[Hans Joachim Desserud (hjd)]

Note that currently it is impossible to add help-section to buildings. See bug 696251 for details.

[SirVer (sirver)]

Bug 696251 has been fixed and it makes up for a good chunk of this very bug. If someone wants to work on this, he should take the lua help script approach I took in bug 696251. I suggest waiting for a while until the needs of documentation writers becomes more apparent.

[SirVer (sirver)]

Note that bug 750400 is related to this.

[SirVer (sirver)]

The framework is in place. Astuur and Venatrix have begone the work but I have no idea what the state is. I think having something plain text and very simple for build 17 is still viable and a good idea. Done is better than perfect.

[SirVer (sirver)]

Astuur, I assigned you because I want to hear your opinion on #7.

[Astuur (wolfsteinmetz)]

Blush --- I am not really used to being "assigned" :)

Well Sirver, my last post from the 23.1.12 still stands uncommented here -

http://wl.widelands.org/forum/post/6973/

I was hoping for some additions, most prominently a way to make a box,
but this seems all abit complicated.
I have not been able to do any further work since then, and only now I emerge a bit
from my RL workload. Just _a bit_ unfortunately from a workload I could not anticipate.

I will, however, see what other buildings I can finish.
Venetrix, can you please make the lua file available that produced the screenshot from your last posting?
I want to learn, how you did this, and see whether I can myself use the features.
Otherwise I'd still need somebody to convert my .wpd (Wordperfect) files or .pdfs to lua.

[SirVer (sirver)]

>Blush --- I am not really used to being "assigned" :)
Well, this is your bug :)

I cannot speak for Venatrix and all questions concerning nicer
formatting will need to be answered with "not at this point in time". I
wish I could work more on widelands, but my thesis is in a critical
state and everything WL is currently strictly critical stuff.

That said, having plain text - or very simple formatted - help would
help already a ton and would be a good feature to have for b17.

[Chuck Wilder (chuckw20)]

Edited pdf

[Chuck Wilder (chuckw20)]

Edited ascii file

[Venatrix (elisabeth)]

First version of Astuur’s Deep Coal Mine help in Lua.

[Venatrix (elisabeth)]

The format_help.lua needed in the scripting folder.

[Astuur (wolfsteinmetz)]

We have agreed to place files here, while (for a broader audience) the discussion of things related to the Cheap in-game help
stays at out homepage at http://wl.widelands.org/forum/topic/903/

Next, in order to work economically, is the small barbarian coalmine :)
So here it is.

[Astuur (wolfsteinmetz)]

and the ascii file.

[SirVer (sirver)]

I already lost track.... Is the work flow correct as follows? Astuur makes texts (in ASCII), chuck proofreads them, venatrix turns them into lua? If so, is it correct, that I only have to add the lua files in the correct place? Could you then add the files with "MERGE PLEASE to /barbarians/deep_coalmine/help.lua or something along these lines?

[Astuur (wolfsteinmetz)]

The next one. The Barbarian Deeper Coalmine

[Astuur (wolfsteinmetz)]

The Barbarian Deeper Coalmine as ASCII

[Chuck Wilder (chuckw20)]

Barbarian Deeper Coal Mine as PDF - proofed

[Chuck Wilder (chuckw20)]

Barbarian Deeper Coal Mine as ascii - proofed

[Chuck Wilder (chuckw20)]

Barbarian Coal Mine as PDF - proofed

[Chuck Wilder (chuckw20)]

Barbarian Coal Mine as ASCII - proofed

[Venatrix (elisabeth)]

@SirVer: Yes, the workflow seems to be that way. And yes, you just have to add them in the right place.
Do you mean, you want the info where to put the files? Because I don’t feel they are ready to really be merged into game right now…

[Venatrix (elisabeth)]

New version of the format.lua.

[Venatrix (elisabeth)]

Newest version of the Barbarian Coal Mine.

[Venatrix (elisabeth)]

Adjusted version of the Deep Coal Mine.

[Venatrix (elisabeth)]

First version of the Deeper Coal Mine.

[Venatrix (elisabeth)]

Yes, almost forgot: This arrow is needed for the dependencies rows.

[Angelo Locritani (alocritani)]

Sorry, guys (and ladies) but would a branch with all .lua files added be a better idea?
This way you can upload pdf only on this bugreport (for discussion/show) and who wants to try it can simply merge the branch. I think it will ensure no file is missing, when it will be merged to trunk.

If you have any problem I can create this branch with the latest version of your files and (if I understand how - hints?) make it public or at least restricted. What do you think?

[Angelo Locritani (alocritani)]

I found I cannot create a branch where everyone can upload, since only members of "Widelands Developers" can.

[Venatrix (elisabeth)]

It would certainly be better. But I don’t know how to use branches except from downloading and compiling… And I’m no member of the Widelands Developers.

[Angelo Locritani (alocritani)]

@Venatrix:
it's quite easy; I've just sent a PM to you with a step-by-step approach.

[Angelo Locritani (alocritani)]

"And I’m no member of the Widelands Developers."

Chuck it's a member. What do you think, chuck, about creating a small "ingamehelp-team" in order to have a team that can create and share a branch for that?

If you disagree, I've just PMed Venatrix with a method for creating a branch on launchpad or I can push a branch with all modifications you're doing. This will increase the working chain (astuur-> chuck -> venatrix -> me), but it's not a problem for me...

[Angelo Locritani (alocritani)]

sorry for this triple-posting, but just found that *anyone* could create a team.

and if you have a team, you may have a shared branch...

Developers, will you approve a Widelands-ingamehelp" team?
members: astuur, chuck and venatrix and maybe anyone who want to join their efforts...

[Chuck Wilder (chuckw20)]

@#34 "What do you think, chuck, about creating a small "ingamehelp-team" in order to have a team that can create and share a branch for that?"

A branch for the in-game help effort will certainly be a good vehicle to keep things organized. The attachments to this bug report are growing faster than I realized they would. :) I've not set up a team before, but I'm willing to try, though the act may require SirVer as he is the administrator.

[Angelo Locritani (alocritani)]

@#36
"I've not set up a team before, but I'm willing to try, though the act may require SirVer as he is the administrator."

not sure If you'll need Sirver (https://help.launchpad.net/Teams/CreatingAndRunning) but it's of course a good idea having his approval... :)

[Chuck Wilder (chuckw20)]

@# 37
We'll need SirVer's action on this. I do not have administrator rights on the Widelands-Dev project only the Widelands-Media project and that won't get us to where we wish to be. ;)

So I will ask for his assistance (and approval) in this matter.

[Astuur (wolfsteinmetz)]

Hope, all this is not getting too complicated,
but since I don't have any experience, (and no better idea either) I'll try to comply.
Just tell me what I should do, when all is setup and done.

Here is the next building:
Barbarian Deeper Ironore mine.

[Astuur (wolfsteinmetz)]

and the Ascii text

[Venatrix (elisabeth)]

I must confess that I don’t like the idea of merging something only half finished. There are some inconsistencies and missing facts/texts, that I would like to see commented.

So, my opinion: I’m for not merging now but rather make a really cool help for build18. ;-)

[Astuur (wolfsteinmetz)]

Oah.... what a pitty.
I thought the idea was to show to a broader user base what we are about to do and receive some comments
and suggestions for improvements, no?
It was clear from the beginning that we would not be able to finish all houses for all tribes.
And even if we were able, we'd probably want to use some more formatting with the next release.
We will certain have to work on, but a little feedback from the outside should help with the content
and looks.
So I would prefer to see it in even if it isn't comprehensive.

[Chuck Wilder (chuckw20)]

If I may add my opinion, I think Astuur's argument has merit. The in-game help feature is a large "bite to chew" for one swallow. As we are doing with seafaring, I think it is a good idea to introduce the feature in its incomplete pre-alpha state to get feedback from the larger community.
I feel that, if we advertise to the public the approach that we are taking with the help system and seafaring features, we should be able to manage their expectations and solicit their involvement in the development of both features.

+1 for including what we can reasonably accomplish as long as we present it/them as a work in progress.

[SirVer (sirver)]

I fully agree with chuck and Astuur: done is better than perfect, our builds are labeled as Alpha software AND we might draw in new contributors for the help if people see that stuff is missing. We will also get feedback which might change some of our approaches.

Nevertheless, we do not want to merge when something is known to be broken in the the branch or some work is in progress that will be committed soonish. The first snow feature freeze will start with merging this feature though, so I really want to have it in trunk before next week if this is possible at all.

[Chuck Wilder (chuckw20)]

I would suggest that, to assist people's understanding that the in-game help feature is incomplete and under active development, we might plug some such comment parenthetically at the beginning of each pop-up. Of course, that is only if that would be a simple modification to the code and one we could implement and remove relatively easily.

[Chuck Wilder (chuckw20)]

Alternatively to #149, we might present a default "under construction" pop-up for those items that are not yet documented.

[Venatrix (elisabeth)]

Right, convinced.

@Astuur: Can you have a look into the buildings you didn’t provide (primarily the farm)? I would like to complete the buildings we have.

It should be no problem to make both #149 and #150 work. I’ll work on it tonight (means after writing this comment ;-) ).

[Venatrix (elisabeth)]

Pushed in rev6308.

[Chuck Wilder (chuckw20)]

Thanks, Venatrix. I'll try it out as soon as I can. (May not be until tomorrow, though.) :)

[SirVer (sirver)]

I am not too fond of #149 but this is your decision to make - after all you are the help-development team :P. My reason is: everything in widelands is alpha and under development and not finished - why bother telling so for what we already have?

However: is it possible to get this mergable till monday? I would like to make the first snow freeze on monday. First snow means no more translatable string changes - that is it would be the version shipped with build 17.

[Chuck Wilder (chuckw20)]

I like the "under construction pop-ups for the buildings currently without help documentation, but I have to admit that after seeing it in the game, I share SirVer's opinion of #149.

Can you keep the verbage for the under-construction screens and eliminate it from the complete one?

Sorry to flip-flop on my own suggestion.

[Chuck Wilder (chuckw20)]

Nice job on the layouts, by the way.

[Astuur (wolfsteinmetz)]

Hello Venatrix, I have copied the help.lua files over
and looked at your work. All very fine.
Thank you for your bravery.
I wished I could have done more,
but even now I cannot come up with
any of the lore parts missing right away.
I've seen the necessary changes you made, and I think we can
come out with this, without any need to alert
to the fact that it is not complete.
That is to say, I support Sirver's and Chuck's
idea to eliminate the orange part from the
houses that are basically done.

[Venatrix (elisabeth)]

It’s no problem to eliminate it.

I just wonder, why only from the houses that are complete? Don’t you think the "under construction" text is enough?

BTW: Shall I make "under construction" notes for the other tribes too or do we leave them alone at the moment?

[Venatrix (elisabeth)]

Oh, and comments like "text needed" and "source needed" don’t need to be translatable, do they?

[Chuck Wilder (chuckw20)]

@Venatrix #158

As far as I am concerned, the orange text can be removed entirely. IMHO, I think the "under construction" graphics and text say all that is needed.

As for the other tribes, I think that if the "?" button appears in the building's window, there should be some kind of response when it is clicked. So, +1 for adding the "under construction" for EVERY incomplete building regardless of tribe.

[Chuck Wilder (chuckw20)]

@ #159

It would certainly be a courtesy to non-English speakers, but I think the graphic gets the point across. Either way is fine with me. (Then again, English is my native tongue.) ;)

[Venatrix (elisabeth)]

@Chuck #160

Then I’ll eliminate the orange text out of the other files, too.

The "?" button only appears if there exists a help file in the building’s directory. So there is no really need to make that window. That’s why I asked. ;-)

And for #161

I meant the buildings with missing lore sections (there are three at the moment: farm, cattle farm, bakery). There just are notes saying "text needed" and "source needed" (and performance: "calculation needed" in case of the farm). I made them untranslatable for marking the interim state, as long as nobody has an idea what to write there till tomorrow. ;-) Everything else is translatable.

[Chuck Wilder (chuckw20)]

@Venatrix #162

Great! No button - no place-holder needed.

Regarding the translatable/not tranlsatable question, I bow to your and other's opinions on the matter. :)

[Astuur (wolfsteinmetz)]

Fine with me

[Chuck Wilder (chuckw20)]

@Venatrix
I just noticed that the Coal Mine displays the IronOre graphic in the "Purpose" section instead of the coal graphic used through the rest of the pop-up.

[Venatrix (elisabeth)]

Thanks - corrected.

[SirVer (sirver)]

I am planing to set first snow ff this evening, roughly 10 hours from now. Speak now or life with the consequences :)

[Venatrix (elisabeth)]

I would have liked to increase the consistency between the buildings a bit more, but unfortunatly I don’t have that much time I thought I would have to do so.

I was convinced to make the "… needed" strings translatable again, but this will be my last commit before feature freeze unless somebody discovers more serious mistakes.

[Chuck Wilder (chuckw20)]

@Venatrix #168
"I was convinced to make the "… needed" strings translatable again, but this will be my last commit before feature freeze unless somebody discovers more serious mistakes."

Having heard no reports of mistakes over the last 4 hours, I will take the steps to merge ~widelands-dev/widelands/help_development rev #6312 into the trunk.

[Chuck Wilder (chuckw20)]

Changes pushed to trunk in bzr rev#6326

[Chuck Wilder (chuckw20)]

@SirVer
What sort of status should be assigned to this bug report now? "Fix Commited" even though the content is incomplete?

[Chuck Wilder (chuckw20)]

I guess I answered my own question. :) This bug was to introduce the feature. That has been done. We should probably create a new bug report to complete the In-Game Help content. Don't you think?

[Chuck Wilder (chuckw20)]

BTW - Congratulations Widelands Help Team! This has been an excellent start made even nicer by its inclusion in Build 17!

[SirVer (sirver)]

I agree fully with chuck!

answer to 171: You can also retarget to build 18. But maybe having more different bug reports (maybe for the various tribes or even finer cut slices) makes the whole process a little easier to follow and a clearer picture of the work that still is to do. I leave this decision the help development team.

[Chuck Wilder (chuckw20)]

Re: #174
What do you think, team? I have submitted bug report#969605 to pick up where we have left off in Build17.
Would dividing the effort into separate bug reports by tribe or some other criteria be helpful to get things organized into manageable sub projects?

[Astuur (wolfsteinmetz)]

We will have an ongoing need for participation in the course of completing this help.
For one thing there are the continued efforts to improve the formatting.
I think we will get Sirver's help on that (maybe others', too) after release 17.
So I think a bug report "Improve help formatting" would be good to have

For another, the lore section will require to draw a clearer picture of the tribes' underlying culture.
Many details concerning this exist only in the heads of the founders or those that conceptually have
envisioned the tribes for a long time, but we need to reference those especially on the "in depth" side.
In order not to create discrepancies and to inlcude the ideas of guys like Sirver and Nasenbaer (and ...?)
we must remain in close contact and exchange.

Splitting this into three (for each tribe) bug reports may help.
I plan to keep on making pdfs for each building.
They seem to transport all aspects well, and allow easy correction and commenting for
formatting, content, linguistic and orthographic proofing, and graphical additions.
They should be easy to quick check for conceptual consistancy, too.
But it's hard at this point to predict how things will evolve.

So, to sum it up:
I suggest 4 reports

1) improve lua formatting options
2) Imperial in-game help development
3) Atlantean in-game help development
4) Barbarian in-game help development

Any good?

[Chuck Wilder (chuckw20)]

@Astuur #176

The four reports you suggest sound reasonable to me.
I will reword bug report#969605 to focus on the barbarian tribe segment which is already started. I will also initiate reports for the other two tribes.

Astuur, as you are more in touch with the lua formatting aspect than I, would you see to initiating that bug report please?

If anyone else has a better approach, let us hear it. For now anyway, I think this gets the major thrusts partitioned into their own reports.

[Chuck Wilder (chuckw20)]

ERRATUM: The new bug report is bug #959605, not 969605 as stated above (twice). :P

[Astuur (wolfsteinmetz)]

Me? .... in touch? with .lua?
You must be joking, Chuck :)
Venatrix, please help...

[Venatrix (elisabeth)]

@Astuur: I think Chuck meant that you are the guy who has the ideas what would be cool to have as formatting possiblities.

But I think that the name shouldn’t be "improve lua formatting options" but something like "improve the rich text renderer", for that’s what isn’t capable of the things we would like, if I understood right.

[Chuck Wilder (chuckw20)]

@Venatrix #180
Thank you, Venatrix. That is EXACTLY what I meant. :)

You, Astuur and Angelo are far more familiar than I with the formatting limitations that we are currently facing.

[Astuur (wolfsteinmetz)]

I have done that, as far as I could without knowing much about the problems that
Venatrix had to face in creating the .luas
Please add your thoughts and the problems you were experiencing!
It is bug #965044

[Chuck Wilder (chuckw20)]

Thanks, Astuur!

[SirVer (sirver)]

Released in build17-rc1.