Need style guidelines for the card text

[wvoigt]

In order to promote uniformity with the cards, we should have a short style guide which instructs on the preferred way of representing card texts.

[wvoigt]

Capturing here comments from @soudek01 in Issue #73

The new formatting changes require vanilla bonuses within the text to be bolded. Example: Nobles, Choose one: +3 Cards; or +2 Actions.

Vanilla bonuses aren't represented in a consistent way. Some of the tabs have: "the vanilla bonuses, (card text)." Others have: "the vanilla bonuses, more vanilla bonuses, then (card text) beneath." Another example: Look at Bazaar, and then look at Grand Market. Grand Market is better imo, but they aren't uniform.

To make the cards uniform, all the vanilla bonuses could be bolded (including vanilla bonuses within the text) and placed above the card text. Here is some info from the fan card creation guide on the DS forum: "If your card offers +Cards, +Actions, +Buys, +$, and/or +VP then list them in that order. It sounds nitpicky, but all of the official cards adhere to this strict ordering and have consequently trained our eyes to use shortcuts to ingest the information. For example, if the first thing on a card is a boldface "+1 Buy," many experienced players will immediately understand this to be a terminal action without reading further -- because the "+1 Action," had it been present, would have appeared above the "+1 Buy" line. Adhering to the standard ordering will guard against players misreading your cards." More info at: http://forum.dominionstrategy.com/index.php?topic=699.0

Tabs with multiple cards generate inuniformly (some have: "Card Name: Card Text" others have: "Card Name: Card Text Below." Example: "Hovel: When you buy a Victory card, you may trash this from your hand." vs "Settlers: +1 Card +1 Action Look through your discard pile. You may reveal a Copper from it and put it into your hand." I like Settlers more.

Also consider underlining card names (Settlers:)

[wvoigt]

In order to facilitate giving the cards some style, I have added the following text formatting options for the "extra" and "description" fields (now in Pull #105) :

• <tab> and <t> to add a tab (4 spaces)
• <n> as an alternative to \n (hard new line)
• <br> as an alternative to <br /> (soft new line)
• <c> and <center> add hard new line and center text until the next hard new line
• <l> and <left> add hard new line and left align text until the next hard new line
• <r> and <right> add hard new line and right align text until the next hard new line
• <j> and <justify> add hard new line and justify align text until the next hard new line
• <line> to add a hard new line, a centered dividing line, and a trailing hard new line

Hard new lines (\n and <n>), will reset the paragraph formatting back to the default (justified, plain text). Soft new lines will insert a new line, but will continue the current formatting.

This goes with the existing codes that could already be used (and probably no one knew):

• <br/> or <br /> for a line break (soft new line)
• <b>...</b> for bold
• <i>...</i> for italics
• <u>...</u> for underline

[nickv2002]

Style guidelines are a great idea. I agree consistent formatting is important. However, I'm sure you'll agree it's a tier 2 problem to just getting the 2nd edition cards out there at this point. Let's try to stick to the style presented by the new 2nd edition cards where possible as they have been revised for style too. See scans of them all here and here.

[wvoigt]

@nickv2002 I agree it is a 2nd tier issue. The release should not wait on it. But I am trying to put as much ground work in place as I can before everything is committed.

[wvoigt]

I added a start to the style guide in the translation.txt files.

## Style Guide

 - All card names should be underlined.
   Example "<u>Settlers</u>:<n>"

 - Bonuses within the text to be bolded.
   Example: "Choose one: <b>+3 Cards</b>; or <b>+2 Actions</b>.

 - Bonuses should be listed in the following order:
         +Cards, +Actions, +Buys, +Coins, then +<VP>

 - When possible, bonuses should be listed vertically and centered.
   Example: "<center><b>+1 Card<br>+1 Action<br>+1 Buy<br>+1 Coin<br>+2 <VP><n>"

 - If a Dividers/Tab has more than one card explanation, if space permits, try to mimic a stand alone Dividers/Tab in the overall format.
   Example from "Settlers - Bustling Village": "<u>Settlers</u>:<center><b>+1 Card<br>+1 Action<n>Look through your discard pile. You may reveal a Copper from it and put it into your hand.<n><u>Bustling Village</u>:<center><b>+1 Card<br>+3 Actions<n>Look through your discard pile. You may reveal a Settlers from it and put it into your hand."

[soudek01]

Yes, nickv2002, this a tier 2 issue.

I like your style guidelines, wvoigt, I would add that all vanilla bonuses should be bolded (both inside and outside of text).

How do i see the most updated versions of the tabs so that I can give more accurate feedback?

[soudek01]

"Let's try to stick to the style presented by the new 2nd edition cards where possible as they have been revised for style too. See scans of them all here and here." -nickv2002

Yes, this is the idea: that the tabs would incorporate the new, official, style guidlines from v2. Along these lines, it makes since to me to use all of the card wordings from v2. I am not going to replace my v1 dominion cards with the v2s. However, I would like to have easy access to the exact v2 card wordings in my storage solution, i.e. on the tabs. Besides, they made the v2 changes because they are better.

[wvoigt]

I've made a first pass at updating the en_us cards in the Card-DB-refactoring for the above style.

That said, it was a pain. Adding the <b> </b> pairs to bold the bonuses took up a lot of time. In fact, in the end, I cheated and used regex to do most of the hard work. I fear translators will have a problem with it. And in the end, it clutters up the files quite a bit.

So I am toying with the idea of automatically adding the <b> </b> pairs to the formatting. I had it all working for English. Then it dawned on me that the words are different for each language.

So that would mean another translation set. The easy way would be to add yet another json file. Say, bonus_xx.json. It would be small, the keys would only be: "Card", "Cards", "Action", "Actions", "Buy", "Buys", "Token", "Tokens" Coins are not needed, since translations should continue to use "Coin" to get the images. Why the "Token"? It is used as a negative match. For example, "Move your +1 Action token..." should not have the +1 Action in bold.

That said, I'm starting to get worried about all the translation files needed. Three of them would be relatively small, but I'm worried translators might be scared away by just the number. But I'm not sure how valid that fear is. Other options would be to combine bonuses with the types, or combine sets, types, and bonuses together into one file (3 sets of sets). And it we go that far, should we just put them all into one big file?

Any thoughts?

PS. None of this should hold up the v2 release. This can all be done in the future. And the web interface would not need any changes for it. Everything would be "under the covers" so to speak.

[sumpfork]

I think we should just make sure that any translation can be done incrementally without having to provide content for all the files. So if you just specify card set names and card names for some cards, you should get blank dividers for those cards in your language. If you add some card texts, those should go on. And we should make that clear in the instructions, so that to contribute people really feel they just need to fill out some names and texts to start.

[wvoigt]

@sumpfork We have that. Everything can be done incrementally. If something is missing, we substitute the en_us version. That way they get text to start with. If they want to translate that text, we could do it one card at a time if needed.

[wvoigt]

I added the automatic bonus highlighting. To do it, I created a bonuses_xx.json file in each language. The xx version looks like:

{
    "exclude": [
        "token",
        "Tokens"
    ],
    "include": [
        "Coins",
        "Coin",
        "Cards",
        "Card",
        "Buys",
        "Buy",
        "Actions",
        "Action"
    ]
}

Basically it finds any form of +# include_term that is not followed by exclude_term For example, "+2 Actions" will be found, but not "+1 card tokens". The search is case insensitive. This makes editing the cards_xx.json much easier and the output is much nicer too.

[wvoigt]

I'm cross posting this in issue #73 Here are sample files from the current Card db refactoring pull #105 Each language (de, en_us, it, nl_du) has 3 files:

• Test-xx-all.pdf has a copy of all the dividers
• Test-xx-groups.pdf has a copy of the dividers with --special_card_groups
• Test-xx-extras.pdf has copy of the dividers with --expansions adventures --expansions empires --expansions promo --expansions base --special_card_groups --exclude_events --exclude_landmarks

Between the 3 files, I believe every card text option is used for that language.

Please review for style, consistency, errors, and/or any other style suggestions.

Test-de-all.pdf Test-de-extras.pdf Test-de-groups.pdf Test-en_us-all.pdf Test-en_us-extras.pdf Test-en_us-groups.pdf Test-it-all.pdf Test-it-extras.pdf Test-it-groups.pdf Test-nl_du-all.pdf Test-nl_du-extras.pdf Test-nl_du-groups.pdf