Skip to content

Latest commit

 

History

History
138 lines (92 loc) · 7.43 KB

CONTRIBUTING.md

File metadata and controls

138 lines (92 loc) · 7.43 KB
Raw

How to contribute

You can either submit a bug-report, fix an issue or submit a new translation.

Fix

Despite my keen eyes, I may have failed to correctly copy-paste the raw text and tables. Please ping me via this project issues or via Twitter or G+ if you spot any typo to be fixed.

You're welcome to submit a "fix" PR if you can.

Translate

The main purpose of this project is to allow translations of this open game content into other languages.

How-to

Let's say you want to translate "The Black Hack" into Klingon.

TL;DR: you may use this checklist when you're fine with this process. But I'd advise you to carefully read what's just below.

If you know how to use Github

  1. fork this project on github,
  2. on your local copy, create a klingon directory,
  3. in this directory, create a meta.yaml file. This file is plain text and should be exactly like the english/meta.yaml file, See the "meta" for more details.
  4. in this directory, create a the-black-hack.md file and start translating. This file should fit the Github Markdown syntax,
  5. Don't forget to add your name in the LICENSE file, in the last section "15 COPYRIGHT NOTICE" like this: "Klingon translation Copyright 2016, B'Elanna Torres".
  6. when you're done, submit a pull-request,
  7. there may be a few discussion about your translation (mostly about the Markdown syntax). When the pull-request is "ok", it'll be merged into the main repository.

If you don't know how Github is working

Contact me via e-mail or Twitter or G+ or any mean you can find and send me over a raw text translation of the game. I'll try to add it to the project ; and I may ask you to eventually help me to integrate it as best as possible.

Congratulations, you have contributed to this project

Make sure your contribution is okay

If you're geeky enough, you can try to use the command: make html to build HTML pages into the build/ directory. It only requires that (a recent version of) tox is available on your system.

Browse the build/ directory with your web browser to see your translation along with the others.

The Meta file

The meta file is a YAML, but it shouldn't be a problem. Your "klingon" meta file should look like this:

label: Klingon
pages:
    -
        label: The Black Hack in Klingon
        author: B'Elanna Torres
        version: '1.1.2'
    -
        label: Additional Things
        author: B'Ellana Torres
        filename: additional-things.md

Important

  • The meta file is completely optional, but it'll help improve the look'n'feel of the homepage & build the extra content. If you don't have this meta.yaml file, the site builder will create the main page (The Black Hack rules) but it won't build the other contents. If you have difficulties creating this YAML file, don't worry, I'll take care of it.
  • All the field names are case-sensitive, so be careful if you're writing this file yourself.
  • even though the author information is optional, although I'd recommend to provide it, in order to receive feedback (including praises from the community).

Required fields:

  • label: This will be displayed on the homepage, it's the language label (that is to say "Français" for "French"),
  • the filename field is optional if your language only has the main translation (The Black Hack ruleset) ; if you want to build extra pages (for example Additional Things, you must provide the filename).

Specific styles

Note: If you think that the following is too complicated for you, don't worry, I'll take care of this.

Converting saves tables

In order to get the "Converting saves" tables aligned and pretty, we're using the following CSS style:

#converting-saves + p + table, #converting-saves + p + table + table {
    display: table;
}

It might look a bit complicated, but it goes like this: it's using the anchor name of the "Converting saves" header, skips the next paragraph, and changes the display CSS attribute for the next two tables.

Whenever you're adding a new language directory, or if you're modifiying your translation of "Converting saves", the anchor name also changes, if you want the styles to fit.

Let's say I'm adding French. The translation reads "Conversion des jets de sauvegarde". The anchor name will be: conversion-des-jets-de-sauvegarde. To check it, just build the HTML files and go to this specific section. The anchor link would appear when you roll your mouse over the "¶" sign next to the title.

In order to have the next two tables correctly aligned, here's my new CSS instructions:

#converting-saves + p + table, #converting-saves + p + table + table,
#conversion-des-jets-de-sauvegarde + p + table, #conversion-des-jets-de-sauvegarde + p + table + table {
    display: table;
}

PDF Page breaks

Note #1: This trick is even more tricky than the "converting save table" CSS ; you really don't have to try to fix these page breaks if you don't feel like it, the maintainer of the project will take care for you.

Note #2: Please note that if you've added a change in one of the available documents, you may want to check if you didn't mess up a page break.

Let's say you've added the klingon language. For building the klingon PDF, you'll have to run the following:

tox -e pdf -- klingon

You'll probably have a new file in your repository, named: static/pdfs/the-black-hack-klingon-v1.0.pdf. Open this PDF using your favorite document viewer and check the page breaks. Ideally, the page breaks shouldn't occur in the middle of a section, but would rather start with a "level 2 heading". If it doesn't, just try to spot the heading that should mark the beginning of a page, and retrieve its CSS id, as described in the Converting saves tables section above.

Then, open the wkhtmltopdf.css file in your favorite text editor and add something like:

#choose-a-class,
#armor-proficiency + p + table {
    page-break-before: always;
}

Selecting some elements might be a bit tricky... I you can't, don't insist.

Adding a translation checklist

  • New directory with the new language name,
    • the black hack translation file name must be the-black-hack.md
    • For other files they can be named as you want, but they must have a .md extension and be referenced in the meta.yaml file
    • the meta.yaml
      • should mention the language name,
      • you must add the files you've translated with the version of the translation (if it's the first one, '1.0' is fine)
      • the name of the author is the name of the translator,
    • You may add a README.md to explain things, thank people, give yourself credits, etc.
  • You must add your contribution to the LICENSE file, in the last section.
  • You may add a line in the changelog describing your contribution.
  • Have a look at the section Specific styles. If you don't know how to handle it, leave it away, the maintainer will provide help.