Обсуждение стандартов/практик/рекомендаций/стилей оформления текста

[oshliaer]

TOC

В репозитории

• Рекомендации и соглашения по переводу!
• Порядок внесения изменений

В этом топике

• Inline код
• Отступы между строк
• Обратный апостроф
• mdn ссылки
• Сверка с другими источниками

Описание проблемы

Некоторые элементы текста удручают своим разнообразием. Предлагаю хотя бы собрать попавшиеся варианты.

Например, разметка сниппета

````warn header="`matchAll` возвращает итератор, а не массив"
````

Ломает штатный syntax highlighting моих редакторов напрочь.

Ну, и т.д.

[oshliaer]

Inline код

Как правильно?

флаг `'g'`
флаг `"g"`
флаг `g`

В главе про регулярные выражения встречаются все три варианта

[oshliaer]

Отступы между строк

Некоторые страницы содержат больше нужного отступов между строками. Особенно это касается сниппетов

some text




````
a snippet
````


some text

Некоторые сниппеты выдержаны на расстоянии трех или четырех строк от основного повествования.

[aruseni]

Как мы будем называть по-русски вот этот символ: `? В английском он называется backticks. Предлагаю вариант обратный апостроф.

[lex111]

@aruseni да, верно.

[oshliaer]

В #60 сказано, что будет "glossary and style guide"

[aruseni]

[docs](mdn:/JavaScript/Reference/Template_literals#Tagged_template_literals)

Вот такие ссылки надо менять? Они автоматически преобразуются при рендеринге учебника?

[oshliaer]

@aruseni, насколько я понимаю механизм, менять такие ссылки не нужно.

Ссылки будут заменены в зависимости от контекста https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals или https://developer.mozilla.org/ru/docs/Web/JavaScript/Reference/Template_literals

[oshliaer]

@aruseni, в рекомендациях по переводу указанно, что менять только если ссылка внешняя https://github.com/javascript-tutorial/ru.javascript.info/blob/master/TRANSLATION.md

[xcurveballx]

такой еще вопросик возник - что делать со словами типа tag, stack и т.д.? Можно писать тЕг, а можно тЭг, аналогично стек/стэк. По моим наблюдениям, более популярен вариант через Е, но это нигде особо не отражено.

[oshliaer]

Правило русского языка:

После согласных пишется е, кроме слов пэр, мэр, сэр, а также некоторых собственных имён, например: Улан-Удэ, Бэкон, Тэн.

СТОП ФАНТАЗИЯ!

[GordonDrop]

Подскажите как переводить такие термины, как dispach, custom. Конекст Dispatching custom events.

Приходят в голову варианты:

• генерация собственных событий
• рассылка
• создание...

[aruseni]

Dispatch — отправка.

Custom — это интереснее, обычно я употребляю слово «кастомный».

Если есть какая-то причина не использовать кальку, то надо или искать похожее слово, или придумать новое. Из похожих есть, например, «пользовательский». Новое — тут может быть всё, что угодно, например, «своеный».

[oshliaer]

@GordonDrop, можно свериться с предыдущим переводом, если он есть для этого раздела.

Как я понимаю https://learn.javascript.ru/dispatch-events.

Попробуйте подыскать общеупотребительный термин на MDN или академическое значение, если оно где-то упомянуто (например, на Мультитране или Реверсо).

[iliakan]

Согласен, постарайтесь найти аналогичный текст, переведенный грамотным переводчиком, и взять перевод оттуда. Тема генерации событий довольно общая, текст может быть даже не по JS.

По поводу dispatch - в контексте событий я бы перевел как "генерация".
Слово custom - "свой".

Генерация "своих" событий.

Слово кастомный - имхо как крайний вариант, вряд ли оно будет понятно не англоговорящим.

[dandgerson]

@oshliaer

Правило русского языка:

После согласных пишется е, кроме слов пэр, мэр, сэр, а также некоторых собственных имён, например: Улан-Удэ, Бэкон, Тэн.

СТОП ФАНТАЗИЯ!

Но "стэк/стек" это не русский язык, это кириллическая транскрипция английского, тут не работают эти правила =). И зачем же отказываться от фантазии?

[dandgerson]

И потом, что это за правила? Можно и нужно их обдумывать.
Когда-то в нашем родном языке было гораздо больше символов-букв-образов. Но одним формалистским преступным махом кто-то урезал десяток символов-букв-образов. А если посчитать и вдуматься... ?

Сколько букв -- почти столько и их комбинаций - слов. В азбуке из пяти букв будет 120 слов. Простой факториал. А в азбуке из 33 букв? А в азбуке из 44?

А если из азбуки с 44-мя символами-образами убрать всего один? На сколько слов обеднеет будущая письменная речь? Давайте посчитаем:
factorial(44) -> 2658271574788448768043625811014615890319638528000000000
factorial(43) -> 60415263063373835637355132068513997507264512000000000
грубая разница -- два порядка!!! А всего-то одна буковка... А теперь от 33:
factorial(33) -> 8683317618811886495518194401280000000
Вот как обеднела наша письменная речь с начала века. Не считая остальных "правил".

P.S. Где письменная речь - там и устная, и мышление, и фантазия, и изобретательность, ум, творчество.

[oshliaer]

Это правило Русского языка. Я не вижу смысла, способностей и времени его менять. Транскрипция же на письме выделяется по-другому, с указанием значащих и активных звуков, со схематическими обозначениями. Например, [ст’эк].
Наша способность, как людей в группе, написать и произнести одинаково одно и то же слово делает нас образованными. Не мы делаем образование, а оно нас.
Для того, чтобы вести спор, необходимо выбрать область значений и определений. Это, кстати, правило Логики. То ли мы рассматриваем филологические аспекты в историческом контексте, то ли это технически обоснованная экономия пространства машинной памяти, то ли еще какие-то границы. Мешать все в кучу не получится.

[dandgerson]

@oshliaer
Пожалуйста, не воспринимайте это, как вызов или приглашение к спору. В спорах не рождается истина. Я лишь хотел обратить на это Ваше внимание. Благодарю за ответ.

К слову, написание стэк, гораздо точнее передаёт образ, т.к. стек, можно спутать с глаголом стёк. Есть русский вариант стопка =) И заметьте, в правиле, на которое Вы ссылаетесь, через "э", в качестве исключения, пишутся только иностранные слова. стэк - иностранное слово.
Так, что предлагаю добавить это слово в список исключений и везде писать через "Э".

[oshliaer]

Это првило для написания иностранных слов. Слова исключения: мэр, пэр, сэр; если не ошибаюсь.
В любом случе, я не видел книг, где бы было написано с э, хоть это и во всём очень прекрасная и интересная буква.