Manual redraft

[dlp]

2 new minor points:

1.2.3: The envelope icon is hard to spot in the Main Window graphic, so I suggest adding (new text in italics): "...clicking on the envelope icon (in the lower-right corner of the main window) opens a dialog box..."

1.3.1, last sentence: New players may get bogged down with all the (potentially overwhelming) info about playing scenario-only and/or MP, so I suggest adding a new last sentence: "If you're a new player, you may wish to skip section 1.3.2 for now and read it later."

[Simons Mith]

Final draft done and attached. I went on an image-making spree and the whole thing now exceeds the forums' 2Mb attachment limit. I've been applying corrections based on everyone's comments as I went along. Thanks all.

Part 1 is just the HTML. Parts 2 and 3 are all the jpg files and all the pngs. Merging all three together will give you a full set of images, and hopefully a complete manual. It works for me locally! But for page copy only, all you need is part one. these are mostly older images made in version 1.2.5, so there all slight differences, but nothing major. I plan to check all the images when I've got my computer with 1.6 on it back in use, and I'll refresh any out-of-date images then. At that point, I will also make lossless versions of all the images available for SVN, and possibly even provide a saved game with all the units arranged in their little cameos to make future image generation easier. But don't try too hard to hold me to that ...

Future developments: Possibly split the manual into separate documents: a main manual, a multiplayer guide, a strategy guide, a map editor guide, and I suppose ultimately a WML guide too. But I think what we have here will do for now.

[dlp]

Assembling the files as you suggested produced a perfect manual for me.

I think strategy should be addressed solely in one, separate guide. It should be ref'd in the game manual, though.

Would the separate MP guide you have in mind be more extensive than what's here now, or the same content? As it is, I think it makes sense to cover MP here, but new players should be advised that it might be best to skip that material, at first. I expect most people start by playing campaigns against the computer, rather than going directly to MP. Alternatively, the MP material could be moved toward the end.

Congratulations on an excellent job. I look forward to seeing the official release (which I hope will be announced prominently) and the responses it gets.

[Simons Mith]

Assembling the files as you suggested produced a perfect manual for me.

I think strategy should be addressed solely in one, separate guide. It should be ref'd in the game manual, though.

Would the separate MP guide you have in mind be more extensive than what's here now, or the same content?

Well, the only MP I've done is the occasional hotseat game. So if I write an MP guide I'm unlikely to add anything new. However, it's going to be some weeks before I get my chance to double-check what I've written so far against v 1.6.1/1.6.2/... I'm hoping that by the time I'm ready, the MP changes mentioned by Wintermute (http://www.wesnoth.org/forum/viewtopic. ... 44#p355844) will have been implemented. Assuming the timing works out about right I can write a new, separate MP guide covering the new MP user interface then. However, I'm certainly intending to make extensive use of cut-and-paste from what's already written. If someone else beats me to it, of course, things may work out differently.

[Wintermute]

The MP lobby changes are a Google Summer of Code project, so I would not expect them to be complete until nearer the end of the summer.

[Simons Mith]

The MP lobby changes are a Google Summer of Code project, so I would not expect them to be complete until nearer the end of the summer.

Oh, OK. Plenty of time then.

By the way, manual draft 5 is waiting in the wings for any last-minute things people spot missing in draft 4. As far as I can see, the manual is broadly good to go as soon as I've had a thumbs-up from a Dev or writer with commit access.

I have already made a handful of minor corrections, but here's a bigger gap I've just spotted; while I covered all the hotkey functions that actually have hotkeys bound to them, the game has extra functions that don't have hotkeys at all by default, and I haven't covered them at all. [Go to Preferences -> Hotkeys to see the full list] In some cases ('Play', for example), I have no idea what the function does. There are several which are rather gnomic. Anyone care to work through these and give me a line of text explaining each? I know that there's at least one new addition not available under v1.2.5 so I'd need help anyway.

BTW, command mode is ostensibly ":", but AFAICS it's actually accessed with "Shift-;" - or is that just a quirk of my machine? If it is "shift-;" on all platforms, I think that's what I shuold document it as, for consistency with the rest of the hotkey table.

[dlp]

BTW, command mode is ostensibly ":", but AFAICS it's actually accessed with "Shift-;" - or is that just a quirk of my machine?

Well, first, there's no minus sign or hyphen involved in the keying sequence. Second, I expect everyone knows that one produces a colon on a QWERTY keyboard by pressing the semicolon/colon key with the shift key held down, so leaving things as they are should be fine. (Doesn't yours show a colon above the semicolon?) Indeed, "shift-;" would be apt to confuse people. Would anyone advocate denoting "H" as "shift-h", for example?

PS - Thanks for introducing me to "gnomic." I like it, especially in the context of a BfW discussion.

[Simons Mith]

Would anyone advocate denoting "H" as "shift-h", for example?

Yes, of course I would. It's a hotkey fer goodness sakes. It's grossly abnormal to have case-sensitive hotkeys. If pressing the H key produces different dehaviour depending on whether Caps Lock is on or off, that's a bug, - and a brilliantly confusing piece of UI design to boot.

The correct way to refer to a set of hotkeys would be 'N', 'Shift-N', 'Alt-N' and so on. You know, referring to the keys by their labels, not by the characters they produce? That's the normal way to do it. That's how it's been in every manual I've ever read that had a hotkey list in it.

[Soliton]

Would anyone advocate denoting "H" as "shift-h", for example?

Yes, of course I would. It's a hotkey fer goodness sakes. It's grossly abnormal to have case-sensitive hotkeys. If pressing the H key produces different dehaviour depending on whether Caps Lock is on or off, that's a bug, - and a brilliantly confusing piece of UI design to boot.

So brilliantly confusing infact that so far you and most every other wesnoth player hasn't noticed or complained about it.

The correct way to refer to a set of hotkeys would be 'N', 'Shift-N', 'Alt-N' and so on. You know, referring to the keys by their labels, not by the characters they produce? That's the normal way to do it. That's how it's been in every manual I've ever read that had a hotkey list in it.

While that may work well with letters "Shift-;" is certainly not ":" on every keyboard layout.

[dlp]

It's grossly abnormal to have case-sensitive hotkeys.

The real problem, then, is that this is a poor choice for a hotkey. We aren't in a position to change that, though.

I haven't paid enough attention to established conventions for hotkeys and their notation, apparently. I never gave any thought to whether this command is a hotkey and what that might be supposed to imply. Instead, I saw ":" in the instructions and typed it. I'd do the same thing if I saw "&" but would wonder if it was denoted "shift-7". Maybe the typical BfW user is more sophisticated, but even in that case I doubt many have been confused by ":". Is there contrary evidence?

"Shift-;" is certainly not ":" on every keyboard layout.

I think that settles it.

[Simons Mith]

It's grossly abnormal to have case-sensitive hotkeys.

The real problem, then, is that this is a poor choice for a hotkey.

Oh, yes.

I haven't paid enough attention to established conventions for hotkeys and their notation, apparently.

I did do a Google search for 'case-sensitive hotkeys' after posting, and the vast majority of apps (90-95%+) appear to use case-insensitive hotkeys.

"Shift-;" is certainly not ":" on every keyboard layout.

I think that settles it.[/quote]

Quite agree. Glad I double-checked.

[ancestral]

Some suggestions:

242:34: "The tutorial is a simplified scenario that teaches you the game's basic controls."
Isn't it really a couple of scenarios?

242:370: "or he might turn you into a newt."
I'd kind of like an exclamation mark at the end instead of simply a period.

247: You've got four very short sentences all talking about the same thing. Can't these be combined? My suggestion would be: "The Battle for Wesnoth was primarily designed to play campaigns, a series of connected scenarios. Click the Campaign button to start a new campaign and you will be presented with a list of the campaigns currently available on your computer."

247:764: Unless this is quite informal, you should refrain from starting the sentence with "but". Taking the word out here and starting the sentence with "if" would work just fine.

252:90: "You can play games over the internet or at your computer,"
This sounds vague and confused me when I first read it, because I play games over the Internet at my computer. I think you should say something like: "You can play games over the Internet, on a LAN, or a hotseat game with another player using the same computer, against computer or human opponents, or both." In any case, there is only one Internet; it should be capitalized (look at 252:118, 262:123, 506:487, 547:224, 549:77, 604:279).

299:39 and 303:80: "Battle for Wesnoth has a variety of user preference settings that can be altered."
This is redundant; I'd choose to use either "user preferences" or "user settings".

397: "Otherwise the various Wesnoth mouse pointers are displayed using two colors only."
Is that correct? The system standard pointer appears for me. My standard pointer could be more or fewer than two colors.

412: "You can choose Battle for Wesnoth's preferred display resolution."
Isn't it just the display resolution? The "preferred" makes it sound like if possible this is what I want when in actuality, that's simply what it is. I'd recommend "You can change Battle for Wesnoth's display resolution."

429:77 "and their relative volumes controlled using the two slider bars."
You're missing "are"; should be "volumes are controlled".

445:128 "are displayed from the top-left corner of the game window"
"from" is awkward here; better would be "are displayed in the top-left corner"

445:224 "Setting too few lines may mean you miss some of the other players' comments."
Probably better as "you may miss"

450:104 "If this checkbox is active, whenever someone says something, a timestamp is added to what they say."
A brief explanation on what a timestamp is would be useful; "a timestamp (the current date and time) is shown when they speak."

467:8 "The advanced preferences section"
Like all the other sections, you should capitalize this as "Advanced".

571:75 "You will end in the lobby where you can create or join games as you wish."
Better would be to add "up" giving "You will end up in the lobby" which I think sounds a little better.

584:373 "you should type the following into the dialog box"
Is that really necessary? Doesn't Wesnoth assume you're using port 15000 unless you've specified otherwise?

615:497 "and you can fine-tune the income per village"
This could be confused as micro-managing each village, fine-tuning the income for each one. Perhaps you might use "income gained for each village owned"


I'm still reading this through, but great job so far!

[dlp]

247: My suggestion would be: "The Battle for Wesnoth was primarily designed to play campaigns, a series of connected scenarios. Click the Campaign button to start a new campaign and you will be presented with a list of the campaigns currently available on your computer

I believe this should read "designed primarily" and "available currently." Also, the 1st sentence's comma should be a colon.

[Simons Mith]

Two weeks without any further activity. I think that's long enough to wait. The manual ain't perfect, but v5 is certainly good enough to be used in its current state. I'll add v5 to the start of the thread shortly.

[ancestral]

1567: Usage of "less"
Use less when you're talking about items that are impossible or simply so innumerable that it's impractical to measure (e.g. time, food, damage, red) and fewer when you're talking about quantifiable things (e.g. points, days, chairs, bags).

Also using "they" again for a list of items ("they have A, they have B, and they do C") could easily be simplified ("they have A, B, and do C").

They have eight hitpoints fewer than normal, one fewer movement point, and they do one point fewer damage in melee combat.

Here "damage" is quantifiable since we're preceding it with "one point," thus it should be "fewer" instead of "less". We're actually counting the points of damage.

So the usage at 2419:104 it's correct since it doesn't specify a particular amount.

1577:64 "less" → "fewer"