From 56a21863021a98f85114259fa8c347a1482e8af5 Mon Sep 17 00:00:00 2001 From: Bruno Bord Date: Wed, 21 Sep 2016 22:10:01 +0200 Subject: [PATCH] contributing docs revamp related to #46, but not only --- .github/CONTRIBUTING.md | 97 ++++++++++++++++++++++++++++++++++++++++- CHANGELOG.md | 2 +- README.md | 89 +++++-------------------------------- 3 files changed, 107 insertions(+), 81 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 6328c61..9a75d38 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,8 +1,101 @@ # How to contribute -## When you add a translation +You can either submit a bug-report, fix an issue or submit a new translation. -Draft checklist: +## 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](https://twitter.com/brunobord) or [G+](https://plus.google.com/+brunobord) 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. + +#### 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](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](https://help.github.com/articles/basic-writing-and-formatting-syntax/) 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"*. +5. when you're done, submit a [pull-request](https://help.github.com/articles/creating-a-pull-request/), +6. 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](http://jehaisleprintemps.net/contact/) or [Twitter](https://twitter.com/brunobord) or [G+](https://plus.google.com/+brunobord) 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](http://tox.readthedocs.org/) 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](http://yaml.org/), but it shouldn't be a problem. Your "klingon" meta file should look like this: + +```yaml +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. + +In order to get the "Converting saves" tables aligned and pretty, we're using the following CSS style: + +```css +#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: + +```css +#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; +} +``` + + +## Adding a translation checklist - [ ] New directory with the new language name, - [ ] the black hack translation file name **must be** `the-black-hack.md` diff --git a/CHANGELOG.md b/CHANGELOG.md index af15325..cbc40f8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,7 +3,7 @@ ## master (unreleased) * Added a "language count" on the homepage (#43). -* Build a raw, but readable PDF for every language (#21). +* Build a raw, but readable PDF for every language (#21, #46). ## 2.3.0 (2016-09-16) diff --git a/README.md b/README.md index fef8921..4f5c475 100644 --- a/README.md +++ b/README.md @@ -13,94 +13,27 @@ See the [License](LICENSE) for more details. ## Contribute -### Fix +The main document describing the [guidelines on how to contribute is readable here](.github/CONTRIBUTING.md). Please read it carefully in order to make sure your contribution will be easily reviewed and accepted. -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](https://twitter.com/brunobord) or [G+](https://plus.google.com/+brunobord) if you spot any typo to be fixed. +### Requirements -### Translate +You must have [Python language](https://www.python.org/) available on your system, and either a way to create a virtualenv with a recent version of [tox](http://tox.readthedocs.io/en/latest/) or a recent version of tox available system-wide. -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. - -##### 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](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](https://help.github.com/articles/basic-writing-and-formatting-syntax/) 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"*. -5. when you're done, submit a [pull-request](https://help.github.com/articles/creating-a-pull-request/), -6. 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](http://jehaisleprintemps.net/contact/) or [Twitter](https://twitter.com/brunobord) or [G+](https://plus.google.com/+brunobord) 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](http://tox.readthedocs.org/) 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](http://yaml.org/), but it shouldn't be a problem. Your "klingon" meta file should look like this: - -```yaml -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 +To build the HTML pages, you can run on of the following commands: ``` - -**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. - -In order to get the "Converting saves" tables aligned and pretty, we're using the following CSS style: - -```css -#converting-saves + p + table, #converting-saves + p + table + table { - display: table; -} +make html +tox -e html ``` -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. +The build pages are in the ``build/`` directory. This may help you if you try to fix or translate into a new language. -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. +You'll probably won't have to, but if you want to build PDF files, you'll need to install [wkhtmltopdf](http://wkhtmltopdf.org/) on your system. And you may run ``tox -e pdf`` to build PDF files. -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. +If you want to target a specific language, you can run: -In order to have the next two tables correctly aligned, here's my new CSS instructions: - -```css -#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; -} +``` +tox -e pdf -- french ``` ----