Manual redraft

[Simons Mith]

Edit: Right. This Will Do. I've not looked at it myself so a while, so hopefully the fresh pass I've just done will have caught most of the remaining issues.

Final version attached. HTML only. Please continue to use the image set from draft 4. Full lossless image set available on request, but I wouldn't worry about that. I plan to regenerate the entire image set anyway once my Mac's back in use. When I do, I'll make that set available for inclusion in the CVS, along with a saved game containing all the units in their little cameos.

I also expect to make some other final tweaks to the text in some places (mainly so that they match the regenerated images when I create them), but I'm not going to do that until I'm back on a current version of the game.

Can this be commited to the dev version please? I'd do it myself if I had suitable CVS access and wasn't on dialup. TYVM

Images available at this post: http://wesnoth.org/forum/viewtopic.php?p=355897#p355897

[Wintermute]

I look forward to reading the draft when I get some time, but here are some short answers to a few of your questions.

* As an experiment, wrote numbers in the range 1-10 as words for clarity. Abbreviations HP, MP, ZOC, XP defined but not used anywhere. In the on-line help and in the game, it makes sense to use numbers as numbers, but in a manual writing these terms out should help readability and reduce errors. Comments?

Those are all "official" acronyms, documented here. Perhaps linking to that page would be a good idea for any uses of acronyms? Spelling them out is not a problem I think, but in game the user will see acronyms much of the time, so in some ways it may be good to get them used to that...

* Multiplayer server addresses - IP address or hostnames? I've assumed IP address but could be wrong.

Either would work, but since these are entered you should never have to type them in. As such, I'm not sure if it's useful info for the manual? Maybe.

* Titles such as 'Tome of Wesnoth', ATOTB, HTTT et al should possibly also be highlighted in some way.
* Added MP as abbreviation for Movement Point.

The relevant cases could also be directed to the wiki acronym page perhaps?

* Is the game's name 'Battle for Wesnoth' or 'The Battle for Wesnoth'? I'm currently assuming the former.

It is the latter AFAIK (wesnoth.org seems to agree), though it is often seen as just "Battle for Wesnoth" (as in the case for install directories for example)

* Can one player control multiple sides?

Sure!

* Shall I mention :debug and 'win the scenario in one command' in section 3?
* What other command mode lines to mention? Altering the music? Changing unit hitpoints? Adding traits?

I would direct them to the wiki again, there is a nice writeup here . I think that those are features that are not needed to play the game, and are probably only used by a relatively small number of people.

** Cuttle Fish should be Cuttlefish, shouldn't it?

Yes.

I don't have a strong opinion about which way the formatting and hyphenating should go, but I agree that making it all mostly go the same way would be a good idea. Nice work so far. I'm not sure when I'll be able to read the draft, but I am looking forward to it.

[dlp]

Are we using British or American spelling? I saw "favour" in one spot, but haven't checked for consistency. (The original manual uses American.)

WRT one of your requests for opinions: I agree about Sections 1.3.6, etc. 3.1 could be replaced entirely by a sentence or two containing a link to http://www.wesnoth.org/wiki/AdvancedTactics . (As an aside: http://www.wesnoth.org/wiki/GettingStarted should be removed because it's redundant with the manual and its existence creates the potential for inconsistencies. People should be directed to the manual, instead.)

2.2.2 says "You can undo recruitment, provided the new unit has no random traits..." but Section 2.3.2 says "Most Wesnoth units have two randomly-assigned traits..." So the 2.2.2 sentence should be followed by something like "Most units have random traits, though, so recruitment can't be undone, usually." (And, FWIW, the style guide I'm familiar with says "-ly" compounds aren't hyphenated -- don't know how common this rule is.)

2.5: It would be good to state explicitly up front that there are only 2 types of attacks. This wasn't clear to me when I first read the manual. We shouldn't assume the reader will infer this fact just because only 2 types are mentioned.

2.6 says "A unit may be healed a maximum of eight hitpoints per turn." but 2.6.3 says "Multiple healers from different allied sides can all heal the same unit, each on their own turn." Perhaps "A unit may be healed a maximum of eight hitpoints during its turn, plus an additional eight hitpoints by allied healers during the ally's turn." would be better. (BTW, are there campaigns where a side can have more than one ally?)

[The1exile]

This is nitpicking in the extreme, but I've found a few issues. Firstly, A few niggles with the hotkey list (section 2.1, "Controls"):

D Delay shroud updates
D Describe current unit
L Move to leader unit
M Message another player (in multiplayer)
N Cycle through units that have movement left
R Redo move
S Show statistics
S Update shroud now

The delay and update shroud options should in fact be Shift+D and Shift+S respectively.

WRT Section 2.2.2, following on from dlp's comment I'm also unsure in which event you can actually undo recruitment. Is it almost exclusively for WCs and trolls on maps with no fog or shroud?

Section 2.3.1 ("Alignment"): makes no mention of the ability to illuminate or endarken (I forget what the actual ability is - but I think that may simply be a UMC-based unit ability in any case) and its effect on troops. Adding an "illuminated" image to the table would probably help, along with an explanation of its effects.

Section 2.3.3 ("Weapon Specials"): I would recommend rewording the Plague section: "When a unit is killed by a Plague attack, it rises again as a Walking Corpse on the same side as the unit that killed it. This special doesn't work on undead, mechanicals, or units in villages." to "When a unit is killed by an attack with the Plague ability, it rises again as a Walking Corpse on the same side as the unit that killed it. This ability doesn't work on units which are undead, mechanical in nature, or stationed in villages." I'm also concerned that "Poison" is a bit misleading - it doesn't mention that you can stop the 8hp damage by standing next to a +4 healer even if they lack the cure ability (as mentioned later in the section on abilities, heal +4), and I thought the sidebar displays a green skull, not a potion bottle.

Section 2.3.4 ("Abilities"): Ambush I think should be changed slightly. My suggestion would be to amend it to "This unit can pass undetected through forest hexes. Unless there is an enemy unit adjacent to it, it vanishes from the enemy view of the map. If a hostile unit accidentally moves next to this one, a pop-up message of "Ambushed!" will appear and will prevent the enemy unit from moving further that turn. A unit waiting in ambush is faded slightly on the controlling player's map to indicate that it is invisible. Note that if a unit with Ambush is revealed, it becomes visible to all sides, not just the side that discovered it. Note also that triggering an ambush means you cannot undo any movement prior to that point – even if the ambush was triggered by a skirmisher." This is because you can track allied ambush units (which makes me uneasy about the "only you can see me" overtone of "faded slightly on the controlling player's map to indicate that it is invisible") and that I'm pretty sure it is not just zone of control rules that dictate that the ambushed unit can't withdraw.

Cures: Change "such as a Healthy dwarf" to "such as a dwarf unit with the Healthy trait" for clarification.

Teleport: I would recommend adding something along the lines of "as if the two villages were adjacent" and clarify that you can't have your unit teleport into allied villages (which can be construed as "friendly" under the current wording).

Section 2.4 ("Movement"): "but will also end the turn's movement for that unit." would be clearer (I think) if instead it read "will end the unit's movement for that turn". It might be worth adding a sentence to the effect that moving into a villlage that you do own incurs no extra movement cost.

Section 2.4.3 ("Ellipses, Team Colors and Hero Icons"): "Other campaigns use a silver crown icon above the energy bar to denote heroes, or a blue shield" - I think the reference to colour of the crown icon should be removed, as units with a gold crown are also hero units, and merely denote that that unit is able to recruit (or conversely, silver denotes that despite being hero units, they aren't).

Section 2.5.1 ("Attack types"): I would rephrase "Examples: hammer, mace, staff, Troll fist." to "Examples include the hammer of a Dwarven Fighter, the staff of a Mage, or the fist of a Troll". If nothing else, "Troll" looks oddly capitalised in the first simply by being out of place. Similarly, Arcane I think is better rephrased to "The lightbeam attack of a White Mage".

Section 2.5.2 ("Resistances"): "Using an optimum attack type..." should be "Using an optimal attack type..."

Section 2.6 ("Healing"): Is an AMLA ever not 3 hitpoint gain? And doesn't an AMLA still remove poison and slow effects? If so, I'm not sure that it even merits its own line, and think it is better left as an addendum to the "Gaining a level" line (e.g. "In the case of AMLAs, the units total hitpoints increase by three, and the unit is fully healed" or similar.)

Section 3.1.9 ("Experience"): "You need to keep him safe, but if you coddle him too much he will be too weak to survive future battles anyway." The "anyway" seems superfluous and to slightly damage the tone of the sentence.

[Simons Mith]

This is nitpicking in the extreme, but I've found a few issues. Firstly, A few niggles with the hotkey list (section 2.1, "Controls"):

<snip>
Ah yes, an overlooked side-effect of converting the original list to upper-case.

[everyone] In general, thanks for the suggestions. They are pretty much all being applied, except for where I'd already [tried to] address them in my second draft.

At this stage, I'm hoping only minor issues remain, which means only extreme nitpicking will pick up on them. So by all means carry on.

[The1exile]

FWIW, assuming the manual is written in American (I'm a Brit, so bleh ) section 2.5.1 uses "armour" rather than "armor", section 2.5.3 has "favour" where "favor" would be used, and section 2.4.2 uses "colours" as opposed to "colors". Beyond that, I think it's free of British spelling.

[Soliton]

Yes, the original language should be American English. We have a translation for British English.

[Simons Mith]

I've updated my first post with a copy of the second draft. But a quick PS here; the two areas I'm most worried about, not having a current version of Wesnoth handy to check against, are what I've written about healing and about the multiplayer version of the game. Treat those bits with extra suspicion.

BTW I've had an idea about in-game abbreviations, which I haven't implemented yet; use the short forms, ZOC, XP etc. in most areas, and expand them using the <ABBR> tag. Doh.

[dlp]

Are the graphics supposed to be showing up in the manual? They don't for me (Firefox 3.0.8, OSX 10.5.6), although they're in the zip folder.

[Simons Mith]

No, I've followed the same link structure as in the original manual. To get my images working, create an images folder, put 'em in there, (with the manual outside) and they should work. Or, replace the existing manual inside /docs with this one, put the images inside /docs/images, and all the images should work including the current manual images that I haven't provided replacements for.

(I'd copy the docs folder somewhere safe first though, just in case.)

PS My images are just placeholder images, because they're not up-to-date.

[dlp]

That worked -- thanks.

You might want to insert placeholder text for images that aren't included yet, to help ensure the ones that are present in the current manual don't get omitted.

Comparing your versions of the Attack and Damage Calculations windows with mine (which were taken from 1.6), I see no stylistic differences, so I think yours are fine.

Your graphic for the right panel of the Game Screen lacks the map, TOD indicator, and End Turn button, all of which are ref'd in the text.

The Illuminates graphic is a good idea. It might be good to add a second one, made in a cave, where the surrounding darkness would make the visual effect more obvious. (The one you have is good, though, because it underscores the fact that Illuminate is helpful above ground, which I hadn't realized before, even though the manual says this plainly enough.) Fog and Shroud graphics would be good, too, and I agree that Ambush would also be good.

2.2.1: "You can undo recruitment, but only in certain special cases."

In 2.5, "Attacks are divided into two kinds;" -- the semicolon should be a colon.

I see you edited 2.6 to explain healing better, but I'm afraid I'm still confused. If having a friendly +8 and an allied +8 healer next to a unit does no more good than having only one, what does "Multiple healers from different allied sides can all heal the same unit, each on their own turn. This can greatly speed up healing." mean?

The effect of waiting in a village next to a healer is unclear, too. I've found from experience that putting a healer next to a unit in a village accomplishes nothing, but the current text doesn't spell that out.

Perhaps part of what's needed is to first distinguish between the effects of healing vs. resting (and maybe vs. curing, too), and then explain that healing can be accomplished by adjacency to a healer or waiting in a village. I know from some forum threads I've seen that I'm not the only person who's confused about all this, so it would be great if we could find a clear way to explain the interactions (or lack of them).

I like the way you expanded the Turns column in Table 2.2. I hadn't noticed how predictably TOD relates to turn number, and your change made it jump out for me.

[Simons Mith]

I see you edited 2.6 to explain healing better, but I'm afraid I'm still confused. If having a friendly +8 and an allied +8 healer next to a unit does no more good than having only one, what does "Multiple healers from different allied sides can all heal the same unit, each on their own turn. This can greatly speed up healing." mean?

The effect of waiting in a village next to a healer is unclear, too. I've found from experience that putting a healer next to a unit in a village accomplishes nothing, but the current text doesn't spell that out.

Yes, I suppose 'speed up' is the wrong phrase. It's not that you get more healing overall, but that you can get healed earlier in the turn.

Now, some 1.6 questions:

1a. A wounded unit captures a village next to an allied +8 healer. When it starts its next turn, it will qualify for 8 points of village healing, and that will max out its healing allowance for next turn anyway. But what about this turn? It's next to an allied healer, and it hasn't had any healing so far this turn. When the allied healer starts it turn, will it heal the unit standing in the village?
1b. What if the wounded unit was side 3 and the healer was side 1? In this case, the new turn would start, the side-1 healer would heal the unit in the village, then side 3's turn would start and the unit presumably wouldn't get the village healing because it had already received its 8-point healing quota for the turn.

1c. Related: How is Wesnoth healing actually coded? The simplest way I see is to skip hostile units, units standing on villages and units with regenerate, then heal everyone else, checking that no unit gains more than 8 points of healing over the course of a turn. So in a multi-side fight with lots of allied healers (say, a nice balanced 8 vs 1 multiplayer), a unit could take 1 point, be healed for 1, take another 1, be healed for that, take another 1, and so on until it either reached 8 points of total healing or a new turn started, in which case the amount healed would reset to zero.

2. If a unit with Skirmish is ambushed, can it move away from the ambusher? Once I was sure I remembered moving a skirmisher away from an ambusher, but now I'm not.

[Turuk]

2. If a unit with Skirmish is ambushed, can it move away from the ambusher? Once I was sure I remembered moving a skirmisher away from an ambusher, but now I'm not.

No, when a unit with skirmish is ambushed they lose all of their remaining movement points, if they have any left.

[Wintermute]

1a. A wounded unit captures a village next to an allied +8 healer. When it starts its next turn, it will qualify for 8 points of village healing, and that will max out its healing allowance for next turn anyway. But what about this turn? It's next to an allied healer, and it hasn't had any healing so far this turn. When the allied healer starts it turn, will it heal the unit standing in the village?
1b. What if the wounded unit was side 3 and the healer was side 1? In this case, the new turn would start, the side-1 healer would heal the unit in the village, then side 3's turn would start and the unit presumably wouldn't get the village healing because it had already received its 8-point healing quota for the turn.

Currently (1.6.1) allied healing stacks with your own healing, so in 1a) the unit would be healed again on your ally's turn. In 1b) the unit would be healed by your ally, and then would get normal village healing on your turn.

[Simons Mith]

Currently (1.6.1) allied healing stacks with your own healing, so in 1a) the unit would be healed again on your ally's turn. In 1b) the unit would be healed by your ally, and then would get normal village healing on your turn.

Ah, thanks. So now the healing limit is 8 points per side turn rather than eight points per entire [4-hour] turn.

Ew, though. What about a unit that regenerates? Does it regenerate on its turn, then get healing from an ally as well? Whether it does or doesn't, that raises some supplementary questions, but I'll ask them in the healing thread, not here.