ch0ic3/free-programming-books
1
0
Fork 0
mirror of https://github.com/EbookFoundation/free-programming-books.git synced 2024-12-24 04:15:28 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
410d056aff
free-programming-books/docs/CONTRIBUTING-ru.md
David Ordás 84438cb1df
docs(contributing): Homogenize format across translated files (#6625) 
* docs(contributing): remove trailing spaces

* docs(contributing): Apply headings `2-1` empty lines lint rule

* docs(contributing): Apply headings `2-1` empty lines lint rule

forgotten in previous commit: e83220aa4c

* docs(contributing): Move anchor alias to inside list items

... there where an anchor alias `<a name="...">` is used near to each of those list items

This solves markdownlint `MD032/blanks-around-lists` issue

* docs(contributing): Homogenize `1` blank line in nutshell enumeration

* docs(contributing): Homogenize `1` blank line inside Formatting section

* docs(contributing): Ensure `4-spaces` indent `.editorconfig` param

* docs(contributing): Homogenize format & indent of code blocks

- Format using fenced style.
- Well indent in those placed inside list enumerations.
- Simulate `Good` - `Bad` monospace double colon indent inside each one.

- Examples highlighting as `text-plain`. The `md, markdown` style doesn't work very well since blocks has mixed syntax.
- `check_urls` code block highlighted as `properties` style (key-value pair).

Solves markdownlint rules:
- MD040/fenced-code-language: Fenced code blocks should have a language specified
- MD046/code-block-style: Code block style [Expected: indented; Actual: fenced]

* docs(contributing): Ensure `4-spaces` indent `.editorconfig` param

Forgotten in commit: 31c776cb52

* docs(contributing): Homogenize format & indent of code blocks

- Simulate `Good` - `Bad` monospace double colon indent inside each one.

Revert commit f9dc719aef only in this file after check non-needs in a deployed web snapshot

* docs(contributing): Use "consistent" unordered list mark

Solves markdownlint rules:
MD004/ul-style: Unordered list style "consistent"

* docs(contributing): Solve `no-space-in-*` lint rules

markdownlint rules:
MD037/no-space-in-emphasis: Spaces inside emphasis
MD038/no-space-in-code: Spaces inside code span elements
MD039/no-space-in-links: Spaces inside link text

* docs(contributing): Move some punctuation just before any closing brackets after it

* docs(contributing): Hack highlight IDE/Editors headings+HTML

It apply the hack to highlight in IDE/Editors those headings with an anchor alias just before itself

* docs(contributing): Homogenize Pull Request acronym

* docs(contributing): Fix `GitHub` trademark typos

* docs(contributing): ALLCAPS

* docs(contributing): Git trademark

* docs(contributing): YouTube trademark

* docs(contributing): ISBN acronym

* fix: flag emoji code `en` > `us`

Resolves d775cb34fb (commitcomment-59537594)

#5831: `:en:` emoji flag markup doesn't work. Use `🇺🇸` 🇺🇸 or `🇬🇧` 🇬🇧

d775cb34fb (diff-b35eb40c148657d4ea1361c44496e11c5625f484a4c6040c022770e88cbcfdccR8-R10)

* docs(contributing): Fix fa_IR broken anchors

* docs(contributing): filenames in monospace font

* docs(contributing): Homogenize `check_urls=file_to_check`

* docs(contributing): literals/markup texts in monospace font

- `et al.`
- File extensions `.md`
- Protocols: `http`, `https`...
- Notes: LeanPub, require email, StackOverflow, in process, archived

trailing dots in that lines

* docs(contributing): linkify wayback machine

* docs(contributing): Fix `Leanpub` trademark typos

* chore: Rename `master` to `main` #blacklivesmatter

Resolves EbookFoundation/free-programming-books#5803

* docs(contributing): fix broken ref link to `programming-playgrounds`

Fix over EbookFoundation/free-programming-books#5449 and commit 3c42c3629e

(cherry picked from commit 59ebfe3f97e318fa43d58877cbc5bfdd8b0c7426)

* docs(contributing): fix repo urls on initial FR translation

- `ElivreFoundation` -> `EbookFoundation`
- `free-programming-livres` ->`free-programming-books`

PR: #5554
Commit: e629db6b05

Affected lines: 
- 18bb745c90 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R4) // e629db6b05 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R4)
- 18bb745c90 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R7) // e629db6b05 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R7)
- 18bb745c90 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R13) // e629db6b05 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R13)
- 18bb745c90 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R45) // e629db6b05 (diff-d6fa57ebb070f7f05f8c686a2fe92110652f48886774460ffee08d4be4cd5f27R45)

* docs(contributing): use relative urls EN

Via #6614

* docs(contributing): greek. place translations link in right place

Via #6614

* Merge EbookFoundation/free-programming-books#6631 upstream/main commit into docs/contributing/sync/1

* Add repo badges (see EbookFoundation/free-programming-books#5983)

(cherry picked from a16a79b12d solving merge conflict)

* Merge EbookFoundation/free-programming-books#6662 upstream/main commit into docs/contributing/sync/1

* Apply centering proposed at #5983 but not implemented in #6631

(cherry picked from commit f36fd03c06)

* format(contributing): Bold 5th nutshell equal zh

* Merge #6677 upstream/main commit into docs/contributing/sync/1

fix(docs): Use Kramdown processor (#6677)
* Update _config.yml
* add markdown="1"
* update url
* complete removing spaces?
* explicitly use kramdown

(cherry picked from commit de2f31976f)
2022-02-02 20:39:27 -05:00

256 lines
23 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

*[Доступно на других языках](../README.md#translations)*
<!----><a name="contributor-license-agreement"></a>
## Лицензионное соглашение с участником
Принимая участие, вы соглашаетесь с [ЛИЦЕНЗИЕЙ](../LICENSE) этого репозитория.
<!----><a name="contributor-code-of-conduct"></a>
## Кодекс поведения автора
Принимая участие, вы соглашаетесь соблюдать [Кодекс поведения](CODE_OF_CONDUCT-ru.md) этого репозитория. ([translations](../README.md#translations))
<!----><a name="in-a-nutshell"></a>
## В двух словах
1. «Ссылка для легкой загрузки книги» не всегда является ссылкой на *бесплатную* книгу. Пожалуйста, размещайте только бесплатный контент. Убедитесь, что это бесплатно. Мы не принимаем ссылки на страницы, которым *требуются* адреса электронной почты на рабочем домене для получения книг. Однако мы приветствуем списки, которые запрашивают их.
2. Вам необязательно знать Git: если вы нашли что-то интересное, чего *еще нет в этом репозитории*, пожалуйста, откройте [Issue](https://github.com/EbookFoundation/free-programming-books/issues) с вашими предложениями.
- Если вы знакомы с Git, пожалуйста форкните репозиторий и пришлите пулреквест (PR).
3. У нас есть 5 видов списков. Выберите подходящий:
- *Книги*: PDF, HTML, ePub, сайт на основе gitbook.io, репозиторий Git и т. Д.
- *Курсы*: курс - это учебный материал, который не является книгой. [Это курс](http://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-006-introduction-to-algorithms-fall-2011/).
- *Интерактивные учебные пособия*: интерактивный веб-сайт, который позволяет пользователю вводить код или команды и оценивать результат (под «результатом» мы не подразумеваем «оценку»). например: [Попробуйте Haskell](http://tryhaskell.org), [Попробуйте GitHub](http://try.github.io).
- *Подкасты и скринкасты*: подкасты и скринкасты.
- *Наборы задач и соревновательное программирование*: веб-сайт или программа, которое позволяет вам оценить свои навыки программирования, решая простые или сложные задачи, с проверкой кода или без нее, со сравнением результатов с результатами других пользователей или без него.
4. Обязательно следуйте [Руководству, приведённому ниже](#guidelines) и соблюдайте [Markdown форматирование](#formatting) файлов.
5. GitHub Actions запустит тесты, чтобы убедиться, что ваши **списки отсортированы по алфавиту** и **соблюдаются правила форматирования**. **Обязательно проверьте**, чтобы ваши изменения прошли проверку.
<!----><a name="guidelines"></a>
### Руководство
- Убедитесь что книга бесплатна. При необходимости проверьте еще раз. Администраторам помогает, если вы описываете в PR, почему вы думаете, что книга бесплатная.
- Мы не принимаем файлы, размещенные на Google Drive, Dropbox, Mega, Scribd, Issuu и других подобных платформах для загрузки файлов.
- Вставляйте ссылки в алфавитном порядке. Если вы видите ссылку нарушающую порядок, измените ее порядок и отправьте PR
- Используйте ссылку с наиболее авторитетным источником (то есть сайт автора лучше, чем сайт редактора, что лучше, чем сторонний сайт)
- не с файловых хостингов (включая (но не ограничиваясь) ссылками на Dropbox и Google Drive)
- всегда предпочитайте ссылку `https` вместо ссылки `http` - если они находятся в одном домене и обслуживают один и тот же контент
- в корневых доменах удалите косую черту в конце: `http://example.com` вместо `http://example.com/`
- всегда предпочитайте самую короткую ссылку: `http://example.com/dir/` лучше, чем `http://example.com/dir/index.html`
- избегайте сервисы сокращения ссылок
- Обычно предпочитают ссылку на "актуальную" версию, чем на конкретную: `http://example.com/dir/book/current/` лучше, чем `http://example.com/dir/book/v1.0.0/index.html`
- Если ссылка имеет просроченный сертификат/самоподписанный сертификат/SSL-сертификат любого другого типа:
1. *замените её* его эквивалентом http, если это возможно (поскольку принятие исключений может быть затруднено на мобильных устройствах).
2. *оставьте её*, если версия http недоступна, но ссылка все еще доступна через `https` путем добавления исключения в браузер или игнорирования предупреждения.
3. *удалите* в противном случае.
- Если ссылка существует в нескольких форматах, добавьте отдельную ссылку с примечанием о каждом формате
- Если ресурс существует в разных местах в Интернете
- используйте ссылку с наиболее авторитетным источником (это означает, что сайт автора лучше, чем сайт редактора, лучше, чем сторонний сайт)
- если они ссылаются на разные выпуски и вы считаете, что эти выпуски достаточно разные, чтобы их стоило сохранить, добавьте отдельную ссылку с примечанием о каждом выпуске (см. [Issue #2353](https://github.com/EbookFoundation/free-programming-books/issues/2353), чтобы обсудить форматирование).
- Предпочитайте атомарные коммиты (по одному коммиту на каждое добавление/удаление/модификацию) большим коммитам. Не нужно собирать все коммиты в один перед тем, как отправить PR. (Мы никогда не будем настаивать на этом, поскольку это просто вопрос удобства для сопровождающих)
- Если книга более старая, укажите дату публикации в названии.
- Укажите имя автора или имена там, где это необходимо. Вы можете сократить списки авторов с помощью «`и др.`» («`et al.`»).
- если книга не закончена, и работа над ней продолжается, добавьте пометку «`в процессе`», как описано [ниже](#in_process).
- если перед загрузкой запрашивается адрес электронной почты или настройка учетной записи, добавьте в скобки примечания на соответствующем языке, например: `(адрес электронной почты *запрашивают*, но он не требуется для загрузки)`.
<!----><a name="formatting"></a>
### Форматирование
- Все списки представляют собой файлы с расширением `.md`. Попробуйте изучить синтаксис [Markdown](https://guides.github.com/features/mastering-markdown/). Это просто!
- Все списки начинаются с индекса. Идея состоит в том, чтобы перечислить и связать там все разделы и подразделы. Храните их в алфавитном порядке.
- В разделах используются заголовки уровня 3 (`###`), а в подразделах используются заголовки уровня 4 (`####`).
Идея состоит в том, чтобы иметь:
- `2` пустые строки между последней ссылкой и новым разделом.
- `1` пустую строку между заголовком и первой ссылкой его раздела.
- `0` пустых ссылок между двумя ссылками.
- `1` пустую строку в конце каждого `.md` файла.
Пример:
```text
[...]
* [Шикарная книга](http://example.com/example.html)
(пустая строка)
(пустая строка)
### Пример
(пустая строка)
* [Другая шикарная книга](http://example.com/book.html)
* [Ещё одна другая книга](http://example.com/other.html)
```
- Не вставляйте пробел между `]` и `(`:
```text
ПЛОХО : * [Другая шикарная книга] (http://example.com/book.html)
ХОРОШО: * [Другая шикарная книга](http://example.com/book.html)
```
- Если вы указываете автора, используйте ` - ` (тире, окруженное одиночными пробелами):
```text
ПЛОХО : * [Другая шикарная книга](http://example.com/book.html)- Джон Доу
ХОРОШО: * [Другая шикарная книга](http://example.com/book.html) - Джон Доу
```
- Отбейте ссылку и её формат пробелом:
```text
ПЛОХО : * [Очень хорошая книга](https://example.org/book.pdf)(PDF)
ХОРОШО: * [Очень хорошая книга](https://example.org/book.pdf) (PDF)
```
- Сперва автор, потом формат:
```text
ПЛОХО : * [Очень хорошая книга](https://example.org/book.pdf)- (PDF) Джейн Роу
ХОРОШО: * [Очень хорошая книга](https://example.org/book.pdf) - Джейн Роу (PDF)
```
- Несколько форматов:
```text
ПЛОХО : * [Другая шикарная книга](http://example.com/)- Джон Доу (HTML)
ПЛОХО : * [Другая шикарная книга](https://downloads.example.org/book.html)- Джон Доу (cайт для загрузки)
ХОРОШО: * [Другая шикарная книга](http://example.com/) - Джон Доу (HTML) [(PDF, EPUB)](https://downloads.example.org/book.html)
```
- Включите год публикации в заголовок для старых книг:
```text
ПЛОХО : * [Очень хорошая книга](https://example.org/book.html) - Джейн Роу - 1970
ХОРОШО: * [Очень хорошая книга (1970)](https://example.org/book.html) - Джейн Роу
```
- <a name="in_process"></a>Незавершенные книги:
```text
ХОРОШО: * [Скоро будет отличная книга](http://example.com/book2.html) - Джон Доу (HTML) (:construction: *in process*)
```
<!----><a name="notes"></a>
### Примечания
Хотя основы относительно просты, перечисленные нами ресурсы очень разнообразны. Вот несколько замечаний о том, как мы справляемся с этим разнообразием.
<!----><a name="metadata"></a>
#### Метаданные
Наши списки предоставляют минимальный набор метаданных: заголовки, URL-адреса, создателей, платформы и примечания к доступу.
<!----><a name="titles"></a>
##### Заголовки
- Никаких вымышленных названий. Мы стараемся брать названия с самих ресурсов; призываем авторов пулреквестов не придумывать заголовки и не использовать их в редакционных целях, если этого можно избежать. Исключение составляют более старые работы; если они представляют в первую очередь исторический интерес, год в скобках, добавленный к названию, помогает пользователям узнать, представляют ли они интерес.
- Избегайте заголовков ПОЛНОСТЬЮ ЗАГЛАВНЫМИ БУКВАМИ. Обычно уместен регистр заголовка, но в случае сомнений используйте заглавные буквы из источника.
<!----><a name="urls"></a>
##### URLs
- Мы не разрешаем сокращенные URL-адреса.
- Коды отслеживания должны быть удалены из URL.
- Международные URL-адреса должны быть экранированы. Адресная панель браузера обычно отображают их в Unicode, но, пожалуйста, используйте копирование и вставку.
- Безопасные (`https`) URL-адреса всегда предпочтительнее небезопасных (`http`) URL-адресов, в которых реализован HTTPS.
- Нам не нравятся URL-адреса, которые указывают на страницы со ссылкой на другое место вместо указанного ресурса.
<!----><a name="creators"></a>
##### Creators
- Хотим поблагодарить создателей бесплатных ресурсов, где это возможно, в том числе переводчиков!
- Для переведенных работ следует указать оригинального автора.
- Мы не разрешаем ссылки на авторов.
- Для подборок и смешенных изданий «создателю» может потребоваться описание. Например, книги «GoalKicker» считаются «`Скомпилированными из документации StackOverflow`» ("на английском: «`Compiled from StackOverflow documentation`»).
<!----><a name="platforms-and-access-notes"></a>
##### Платформы и примечания к доступу
- Курсы. Платформа является важной частью описания ресурсов, особенно для наших списков курсов. Это связано с тем, что платформы курсов имеют разные возможности и модели доступа. Хотя мы обычно не перечисляем книги, требующие регистрации, на многих платформах курсов есть возможности, которые не работают без какой-либо учетной записи. Например, как на Coursera, EdX, Udacity и Udemy. Если курс зависит от платформы, название платформы должно быть указано в скобках.
- YouTube. У нас есть много курсов, состоящих из плейлистов YouTube. Мы не указываем YouTube как платформу, мы пытаемся указать автора на YouTube, который часто является под-платформой.
- YouTube видео. Обычно мы не ссылаемся на отдельные видео YouTube, если они не длится более часа или не структурированы как курс или учебное пособие.
- Leanpub. Leanpub размещает книги с различными моделями доступа. Иногда книгу можно прочитать без регистрации; иногда для бесплатного доступа к книге требуется учетная запись Leanpub. Учитывая качество книг, а также сочетание и гибкость моделей доступа к Leanpub, мы разрешаем перечисление последних с указанием доступа `*(требуется учетная запись Leanpub или действующий адрес электронной почты)*`.
<!----><a name="genres"></a>
#### Жанры
Первое правило при принятии решения, к какому списку принадлежит ресурс, — это посмотреть, как ресурс описывает себя. Если он называет себя книгой, то, возможно, это книга.
<!----><a name="genres-we-dont-list"></a>
##### Жанры, которые мы не вносим в списки
Поскольку Интернет огромен, мы не включаем в наши списки:
- блоги
- Сообщения в блоге
- статьи
- веб-сайты (за исключением тех, размещающих МНОГО элементов которые мы перечисляем).
- видео, не являющиеся курсами или скринкастами.
- главы книги
- ознакомительные образцы из книг
- IRC или Telegram каналы
- Slacks или списки рассылки
В наших списках соревновательного программирования эти исключения не так строги. Объем репо определяется сообществом; если вы хотите предложить изменение или дополнение к области, пожалуйста, используйте Issue, чтобы сделать предложение.
<!----><a name="books-vs-other-stuff"></a>
##### Книги против прочих ресурсов
Мы не так привередливы в "книжности" ресурса. Вот некоторые атрибуты, которые указывают на то, что ресурс - это книга:
- имеет ISBN (международный стандартный книжный номер)
- имеет Оглавление
- предлагается загружаемая версия, особенно ePub
- есть редакции
- не зависит от интерактивного контента или видео
- пытается всесторонне осветить тему
- он самодостаточен
Мы перечисляем множество книг, у которых нет этих атрибутов; это может зависеть от контекста.
<!----><a name="books-vs-courses"></a>
##### Книги против курсов
Иногда их бывает трудно отличить!
С курсами часто связаны учебники, которые мы перечисляем в наших списках книг. В курсах есть лекции, упражнения, тесты, заметки или другие дидактические пособия. Отдельная лекция или видео - это не курс. PowerPoint - это не курс.
<!----><a name="interactive-tutorials-vs-other-stuff"></a>
##### Интерактивные учебники и другие материалы
Если вы можете распечатать его и сохранить его суть, это не интерактивное руководство.
<!----><a name="automation"></a>
### Автоматизация
- Применение правил форматирования автоматизировано с помощью [GitHub Actions](https://github.com/features/actions) с использованием [fpb-lint](https://github.com/vhf/free-programming-books-lint) (см. [`.github/workflows/fpb-lint.yml`](.github/workflows/fpb-lint.yml))
- Для проверки URL используется [awesome_bot](https://github.com/dkhamsing/awesome_bot)
- Чтобы запустить проверку URL, нажмите фиксацию, которая включает сообщение фиксации, содержащее `check_urls=ссылка_для_проверки`:
```properties
check_urls=free-programming-books.md free-programming-books-ru.md
```
- Вы можете указать более одного файла для проверки, используя один пробел для разделения каждой записи.
- Если вы укажете более одного файла, результаты сборки будут основаны на результате последнего проверенного файла. Вы должны знать, что из-за этого вы можете получить проходящие зеленые сборки, поэтому обязательно проверьте журнал сборки в конце пулреквеста, нажав "Show all checks" -> "Details".
Reference in New Issue View Git Blame Copy Permalink