From 21ad76246245123f73057fa6a740703e9eba108f Mon Sep 17 00:00:00 2001 From: Norwid Behrnd Date: Wed, 30 Nov 2022 14:01:21 +0100 Subject: replace tabulator spaces by explicit spaces An instance of `sed -i "s/\t/ /g" CONTRIBUTING.markdown`. --- CONTRIBUTING.markdown | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.markdown b/CONTRIBUTING.markdown index 8d2a8320..bd4a8b25 100644 --- a/CONTRIBUTING.markdown +++ b/CONTRIBUTING.markdown @@ -35,7 +35,7 @@ review them more effectively and/or individually. in Vim) + You can check if the file contains a BOM on Linux/Unix systems by running `file language.html.markdown` You will see this if it uses a BOM: - `UTF-8 Unicode (with BOM) text`. + `UTF-8 Unicode (with BOM) text`. ### Header configuration @@ -87,19 +87,19 @@ You can build the site locally to test your changes. Follow the steps below. * Install Ruby language runtime and RubyGems. See [here](https://middlemanapp.com/basics/install/) for more details. * Clone or zip download the [learnxinyminutes-site](https://github.com/adambard/learnxinyminutes-site) repo. - * `git clone https://github.com/adambard/learnxinyminutes-site` + * `git clone https://github.com/adambard/learnxinyminutes-site` * Install Middleman and other required dependencies using Bundler. - * `cd learnxinyminutes-site/` - * `bundle install` + * `cd learnxinyminutes-site/` + * `bundle install` * Get the source in place - * Copy the contents of your clone of the fork of learnxinyminutes-docs repo - into the `source/docs` folder. There shouldn't be a `learnxinyminutes-docs` - folder inside the `docs` folder, it should just contain all the repo - contents. - * Checkout your fork of the learnxinyminutes-docs repo as `source/docs`. - * `cd source/docs/` - * `git clone https://github.com/YOUR-USERNAME/learnxinyminutes-docs ./source/docs/` + * Copy the contents of your clone of the fork of learnxinyminutes-docs repo + into the `source/docs` folder. There shouldn't be a `learnxinyminutes-docs` + folder inside the `docs` folder, it should just contain all the repo + contents. + * Checkout your fork of the learnxinyminutes-docs repo as `source/docs`. + * `cd source/docs/` + * `git clone https://github.com/YOUR-USERNAME/learnxinyminutes-docs ./source/docs/` * Build the site or run a development server to test your changes (NOTE: run these commands at `learnxinyminutes-site/`). - * Build - `bundle exec middleman build` - * Dev server - `bundle exec middleman --force-polling --verbose` + * Build - `bundle exec middleman build` + * Dev server - `bundle exec middleman --force-polling --verbose` -- cgit v1.2.3 From 140b6da5cd603c04f993ca37ecd645b509d084dc Mon Sep 17 00:00:00 2001 From: Norwid Behrnd Date: Wed, 30 Nov 2022 14:04:36 +0100 Subject: consistent mark-up first level bullet list An instance of `sed -i "s/^-/*/" CONTRIBUTING.markdown`. --- CONTRIBUTING.markdown | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/CONTRIBUTING.markdown b/CONTRIBUTING.markdown index bd4a8b25..97e7a821 100644 --- a/CONTRIBUTING.markdown +++ b/CONTRIBUTING.markdown @@ -16,19 +16,19 @@ review them more effectively and/or individually. ## Style Guidelines -- **Keep lines under 80 chars** +* **Keep lines under 80 chars** + Try to keep **line length in code blocks to 80 characters or fewer**. + Otherwise, the text will overflow and look odd. -- **Prefer example to exposition** +* **Prefer example to exposition** + Try to use as few words as possible. + Code examples are preferred over exposition in all cases. -- **Eschew surplusage** +* **Eschew surplusage** + We welcome newcomers, but the target audience for this site is programmers with some experience. + Try to avoid explaining basic concepts except for those specific to the language in question. + Keep articles succinct and scannable. We all know how to use Google here. -- **Use UTF-8** +* **Use UTF-8** + For translations (or EN articles with non-ASCII characters) please make sure your file is UTF-8 encoded. + Try to leave out the byte-order-mark at the start of the file. (`:set nobomb` @@ -47,31 +47,31 @@ some key information be defined in the header. The following fields are necessary for English articles about programming languages: -- **language** The *programming language* in question -- **contributors** A list of [author, URL] lists to credit +* **language** The *programming language* in question +* **contributors** A list of [author, URL] lists to credit Other fields: -- **category**: The category of the article. So far, can be one of *language*, +* **category**: The category of the article. So far, can be one of *language*, *tool* or *Algorithms & Data Structures*. Defaults to *language* if omitted. -- **filename**: The filename for this article's code. It will be fetched, mashed +* **filename**: The filename for this article's code. It will be fetched, mashed together, and made downloadable. + For non-English articles, *filename* should have a language-specific suffix. -- **lang**: For translations, the human language this article is in. For +* **lang**: For translations, the human language this article is in. For categorization, mostly. Here's an example header for an Esperanto translation of Ruby: ```yaml ---- +*-- language: ruby filename: learnruby-epo.ruby contributors: - ["Doktor Esperanto", "http://example.com/"] - ["Someone else", "http://someoneelseswebsite.com/"] lang: ep-ep ---- +*-- ``` ### Should I add myself as a Contributor? -- cgit v1.2.3 From fcc67f098b03074a0f3fd6502dfaecff59028cc7 Mon Sep 17 00:00:00 2001 From: Norwid Behrnd Date: Wed, 30 Nov 2022 14:07:56 +0100 Subject: use asterisk for second level bullet points Running `sed -i "s/^ +/ */" CONTRIBUTING.markdown`. This is to be complemented by a manual correction in the lower section, too. --- CONTRIBUTING.markdown | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.markdown b/CONTRIBUTING.markdown index 97e7a821..df0ef80a 100644 --- a/CONTRIBUTING.markdown +++ b/CONTRIBUTING.markdown @@ -17,23 +17,23 @@ review them more effectively and/or individually. ## Style Guidelines * **Keep lines under 80 chars** - + Try to keep **line length in code blocks to 80 characters or fewer**. - + Otherwise, the text will overflow and look odd. + * Try to keep **line length in code blocks to 80 characters or fewer**. + * Otherwise, the text will overflow and look odd. * **Prefer example to exposition** - + Try to use as few words as possible. - + Code examples are preferred over exposition in all cases. + * Try to use as few words as possible. + * Code examples are preferred over exposition in all cases. * **Eschew surplusage** - + We welcome newcomers, but the target audience for this site is programmers + * We welcome newcomers, but the target audience for this site is programmers with some experience. - + Try to avoid explaining basic concepts except for those specific to the + * Try to avoid explaining basic concepts except for those specific to the language in question. - + Keep articles succinct and scannable. We all know how to use Google here. + * Keep articles succinct and scannable. We all know how to use Google here. * **Use UTF-8** - + For translations (or EN articles with non-ASCII characters) please make sure + * For translations (or EN articles with non-ASCII characters) please make sure your file is UTF-8 encoded. - + Try to leave out the byte-order-mark at the start of the file. (`:set nobomb` + * Try to leave out the byte-order-mark at the start of the file. (`:set nobomb` in Vim) - + You can check if the file contains a BOM on Linux/Unix systems by running + * You can check if the file contains a BOM on Linux/Unix systems by running `file language.html.markdown` You will see this if it uses a BOM: `UTF-8 Unicode (with BOM) text`. -- cgit v1.2.3 From f33c10645494888c2f0d0c046bde20d1e0223462 Mon Sep 17 00:00:00 2001 From: Norwid Behrnd Date: Wed, 30 Nov 2022 14:15:44 +0100 Subject: manual adjustments, second level of indentation Manual adjustments and light edits to stay within the 80 character limit per line. Manual dedent of second level entries met in the lower part of the document. --- CONTRIBUTING.markdown | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/CONTRIBUTING.markdown b/CONTRIBUTING.markdown index df0ef80a..af97f92d 100644 --- a/CONTRIBUTING.markdown +++ b/CONTRIBUTING.markdown @@ -24,15 +24,15 @@ review them more effectively and/or individually. * Code examples are preferred over exposition in all cases. * **Eschew surplusage** * We welcome newcomers, but the target audience for this site is programmers - with some experience. + with some experience. * Try to avoid explaining basic concepts except for those specific to the - language in question. + language in question. * Keep articles succinct and scannable. We all know how to use Google here. * **Use UTF-8** - * For translations (or EN articles with non-ASCII characters) please make sure - your file is UTF-8 encoded. - * Try to leave out the byte-order-mark at the start of the file. (`:set nobomb` - in Vim) + * For translations (or EN articles with non-ASCII characters) please ensure + your file is UTF-8 encoded. + * Try to leave out the byte-order-mark at the start of the file (in Vim, use + `:set nobomb`). * You can check if the file contains a BOM on Linux/Unix systems by running `file language.html.markdown` You will see this if it uses a BOM: `UTF-8 Unicode (with BOM) text`. @@ -56,8 +56,8 @@ Other fields: *tool* or *Algorithms & Data Structures*. Defaults to *language* if omitted. * **filename**: The filename for this article's code. It will be fetched, mashed together, and made downloadable. - + For non-English articles, *filename* should have a language-specific - suffix. + * For non-English articles, *filename* should have a language-specific + suffix. * **lang**: For translations, the human language this article is in. For categorization, mostly. @@ -87,19 +87,19 @@ You can build the site locally to test your changes. Follow the steps below. * Install Ruby language runtime and RubyGems. See [here](https://middlemanapp.com/basics/install/) for more details. * Clone or zip download the [learnxinyminutes-site](https://github.com/adambard/learnxinyminutes-site) repo. - * `git clone https://github.com/adambard/learnxinyminutes-site` + * `git clone https://github.com/adambard/learnxinyminutes-site` * Install Middleman and other required dependencies using Bundler. - * `cd learnxinyminutes-site/` - * `bundle install` + * `cd learnxinyminutes-site/` + * `bundle install` * Get the source in place - * Copy the contents of your clone of the fork of learnxinyminutes-docs repo - into the `source/docs` folder. There shouldn't be a `learnxinyminutes-docs` - folder inside the `docs` folder, it should just contain all the repo - contents. - * Checkout your fork of the learnxinyminutes-docs repo as `source/docs`. + * Copy the contents of your clone of the fork of learnxinyminutes-docs repo + into the `source/docs` folder. There shouldn't be a `learnxinyminutes-docs` + folder inside the `docs` folder, it should just contain all the repo + contents. + * Checkout your fork of the learnxinyminutes-docs repo as `source/docs`. * `cd source/docs/` * `git clone https://github.com/YOUR-USERNAME/learnxinyminutes-docs ./source/docs/` * Build the site or run a development server to test your changes (NOTE: run these commands at `learnxinyminutes-site/`). - * Build - `bundle exec middleman build` - * Dev server - `bundle exec middleman --force-polling --verbose` + * Build - `bundle exec middleman build` + * Dev server - `bundle exec middleman --force-polling --verbose` -- cgit v1.2.3 From 7cf9a2b7aaab2829e7dcb28d082e4e4fab74336f Mon Sep 17 00:00:00 2001 From: Norwid Behrnd Date: Wed, 30 Nov 2022 14:18:56 +0100 Subject: adjust third level of indentation (manual) --- CONTRIBUTING.markdown | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.markdown b/CONTRIBUTING.markdown index af97f92d..a3d75101 100644 --- a/CONTRIBUTING.markdown +++ b/CONTRIBUTING.markdown @@ -97,8 +97,8 @@ You can build the site locally to test your changes. Follow the steps below. folder inside the `docs` folder, it should just contain all the repo contents. * Checkout your fork of the learnxinyminutes-docs repo as `source/docs`. - * `cd source/docs/` - * `git clone https://github.com/YOUR-USERNAME/learnxinyminutes-docs ./source/docs/` + * `cd source/docs/` + * `git clone https://github.com/YOUR-USERNAME/learnxinyminutes-docs ./source/docs/` * Build the site or run a development server to test your changes (NOTE: run these commands at `learnxinyminutes-site/`). * Build - `bundle exec middleman build` -- cgit v1.2.3 From eddf5accb885230940aa8d7c9a3375755d057e7b Mon Sep 17 00:00:00 2001 From: Norwid Behrnd Date: Wed, 30 Nov 2022 14:22:46 +0100 Subject: additional polish with markdownlint Accounts for most of the remaining suggestions by markdownlint.[1] [1] https://github.com/markdownlint/markdownlint, version 0.12.0. --- CONTRIBUTING.markdown | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.markdown b/CONTRIBUTING.markdown index a3d75101..3d2853c6 100644 --- a/CONTRIBUTING.markdown +++ b/CONTRIBUTING.markdown @@ -37,7 +37,6 @@ review them more effectively and/or individually. `file language.html.markdown` You will see this if it uses a BOM: `UTF-8 Unicode (with BOM) text`. - ### Header configuration The actual site uses Middleman to generate HTML files from these Markdown ones. @@ -56,7 +55,7 @@ Other fields: *tool* or *Algorithms & Data Structures*. Defaults to *language* if omitted. * **filename**: The filename for this article's code. It will be fetched, mashed together, and made downloadable. - * For non-English articles, *filename* should have a language-specific + * For non-English articles, *filename* should have a language-specific suffix. * **lang**: For translations, the human language this article is in. For categorization, mostly. @@ -85,8 +84,12 @@ addition or not. You can build the site locally to test your changes. Follow the steps below. -* Install Ruby language runtime and RubyGems. See [here](https://middlemanapp.com/basics/install/) for more details. -* Clone or zip download the [learnxinyminutes-site](https://github.com/adambard/learnxinyminutes-site) repo. +* Install Ruby language runtime and RubyGems. See + [here](https://middlemanapp.com/basics/install/) + for more details. +* Clone or zip download the + [learnxinyminutes-site](https://github.com/adambard/learnxinyminutes-site) + repository. * `git clone https://github.com/adambard/learnxinyminutes-site` * Install Middleman and other required dependencies using Bundler. * `cd learnxinyminutes-site/` @@ -100,6 +103,6 @@ You can build the site locally to test your changes. Follow the steps below. * `cd source/docs/` * `git clone https://github.com/YOUR-USERNAME/learnxinyminutes-docs ./source/docs/` * Build the site or run a development server to test your changes (NOTE: run -these commands at `learnxinyminutes-site/`). + these commands at `learnxinyminutes-site/`). * Build - `bundle exec middleman build` * Dev server - `bundle exec middleman --force-polling --verbose` -- cgit v1.2.3 From 23a2d02f7f3a5b8750c2061e60d16156fe843d15 Mon Sep 17 00:00:00 2001 From: Norwid Behrnd Date: Wed, 30 Nov 2022 14:28:20 +0100 Subject: add hint to markdownlint In the longer term, the use of a linter (similar to pylint for Python) may contribute to easier maintenance of the markdown files and consistent display of the content on the web page. --- CONTRIBUTING.markdown | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CONTRIBUTING.markdown b/CONTRIBUTING.markdown index 3d2853c6..430ecea0 100644 --- a/CONTRIBUTING.markdown +++ b/CONTRIBUTING.markdown @@ -19,6 +19,9 @@ review them more effectively and/or individually. * **Keep lines under 80 chars** * Try to keep **line length in code blocks to 80 characters or fewer**. * Otherwise, the text will overflow and look odd. + * This and other potential pitfalls to format the content consistently are + identified by the freely available + [markdownlint](https://github.com/markdownlint/markdownlint). * **Prefer example to exposition** * Try to use as few words as possible. * Code examples are preferred over exposition in all cases. -- cgit v1.2.3