Руководство по набору кода для непрограммистов

Фон

Я написал научную статью, содержащую код, и недавно получил доказательства, то есть то, что наборщики журнала создали из моей рукописи. Результат не был приемлемым: отступы противоречивы; в конце каждого блока кода стоит полная остановка; кавычки были уничтожены и т. д. Обратите внимание, что все ошибки не были характерны для языка программирования, который я использовал.

Теперь я понимаю, почему кто-то, у кого нет опыта программирования и нет внешних ресурсов, допустил бы такие ошибки, но во времена Интернета никто не должен быть без внешних ресурсов. Таким образом, я посоветовался с моей любимой поисковой системой, чтобы найти что-то, чтобы предложить, и не нашел ... ничего. Существует множество руководств для программистов о том, как красиво набирать код в LaTeX или аналогичном, что хорошо и правильно, но, очевидно, это не сделано для наборщика, который должен набирать чужой код.

Вопрос

Я ищу ресурс, который:

• объясняет основы набора текста,
• предназначен для наборщиков без опыта программирования.

Возможно, в действительности смысл в том, что код не должен быть набран так, как люди понимают его. Таким образом, при вставке кода в документ он должен быть дословным , как и во всех пробелах, вкладках, специальных или не специальных символах и без разрывов строк.

• Вкладки должны быть шириной от 4 до 8 пробелов (наиболее распространенными являются четыре)
• Шрифт должен быть шрифтом фиксированной ширины. И почти повсеместно имеет быть.

• Убедитесь, что ваше приложение не делает никаких замен!

  Это означает, что нет лигатур.

  Также во многих программах (например, Word и InDesign) приложения заменяют прямые кавычки на пары типографов. Убедитесь, что такие параметры отключены, прежде чем вставлять код в документ.

• Не позволяйте коду автоматически переходить из одной строки в другую. Не трогайте код, вы не эксперт!

Код не является основным текстом, он не следует типографским соглашениям. Спросите себя, вы бы набрали текст на иллюстрации?

Если вы эксперт

Если вы являетесь экспертом и знаете язык, о котором идет речь, применяется следующее.

Примечание : не угадывайте и не делайте вывод, прочитайте сказанное. Многие языки выглядят одинаково, и код может быть псевдо-языком, который выглядит как реальный код. Тогда ты можешь:

• Делайте редактор как раскраска / выделение / выделение ключевых слов, если и только если ваша замена имеет одинаковую фиксированную ширину. Лучше пусть редактор сделает это за вас (такие редакторы, как, скажем, scintilla могут экспортировать отформатированный код). Помните, что редактор должен знать язык, может быть, библиотеки тоже.

  Обратите внимание, что если вы делаете это неправильно, это приносит больше вреда, чем пользы.

Если вы являетесь экспертом в области. Как знать язык и библиотеку и понимать соответствующий код:

• Затем вы можете перестроить код в несколько строк, если он не соответствует вашему макету. Не делайте этого, если вы действительно не знаете, что делаете, вы можете нанести непоправимый вред.

  Лакмусовый тест: не могли бы вы написать соответствующий код? Если нет, то вы не можете судить. Спросите автора.

  Как с этим бороться? Программисты понимают стандарты стиля кода. Просто напишите в инструкции по подаче заявки, что в каждой строке можно разместить не более X символов. Программисты могут сделать это сами. Редакторы кода часто имеют инструменты для этого. Еще одна причина использовать моноширинный шрифт.

Но тогда вы знали все это, в конце концов, вы были экспертом. Лучше пусть автор отредактирует код.

Номера строк?

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

Проблемы.

Имейте в виду, что независимо от того, что вы делаете, вы можете столкнуться с невозможными техническими препятствиями. Код на самом деле не должен быть набран, это должен быть просто неформатированный текст. Это приводит к удивительным проблемам.

Например: такие языки, как Python, не могут обрабатываться многими программами просмотра PDF, такими как Adobe Acrobat. Если вы вставите код из файла PDF, редактор решит не включать предыдущий пробел при вставке копии. Это уничтожает возможность вставлять код из PDF в редактор. Там действительно нет хорошего способа справиться с этим!

Ответ, конечно, может зависеть от многих факторов, но если мы начнем с правильного, хорошо отформатированного простого текстового кода , то здесь можно более или менее обобщить вещи.

Начальное «форматирование» в исходном тексте будет: символы новой строки , пробела и символов табуляции . Обратите внимание, что новая строка и ручной разрыв строки (как в программном обеспечении DTP) - это не одно и то же, и наоборот, некоторые редкие языки могут разрешать другие символы форматирования, хотя я никогда не слышал о таком.

Комментарии не являются исполняемой частью кода, поэтому они могут быть переформатированы без особого риска, если вы знаете, действительно ли это комментарий. Итак, первое, на что нужно обратить внимание, это то, как помечаются комментарии.

Полезно знать некоторые основы начального форматирования открытого текста. Например, для Python есть руководство по стилю PEP8 . Хотя это руководство предназначено для Python, его можно использовать как справочник по основным языкам, таким как C / C ++ и Java. Изучение примеров проектов может помочь, если есть сомнения.

Таким образом, первый принцип: не меняйте исходный текст. Я бы прошел контрольный список - убедитесь, что:

• На любом этапе не происходит автозамена персонажа .
• Редактирование текста не производится (если только вы не уверены на 100%).
• Строки не отображаются.
• Отступы сохраняются визуально и являются последовательными (около четырех х  ширины на уровень отступа).
• Начальный (нулевой) уровень отступа должен быть видимым.
• Определенные стили не разрушают форматирование синтаксиса (если используется подсветка синтаксиса).
• Сделайте резервную копию исходного текста в виде простого текста, чтобы иметь возможность перепроверить исходное форматирование или начать заново.
• Номера строк, если таковые имеются, должны быть неповрежденными, особенно если на них есть ссылки в пояснениях.

На самом деле, если исходный источник правильно отформатирован, не должно быть переноса строк вообще. Если обернутые линии все еще появляются и их нельзя избежать, то наиболее распространенным решением является одноуровневый висячий отступ (см. Выше связанный PEP). Если разрыв строки необходим - лучше обратитесь к руководству по стилю или к автору.

Тем не менее, некоторые незначительные символы «пробела» могут потребовать замены. Так как источник может включать символы табуляции, это, конечно, означает, что наборщик должен гарантировать, что все вкладки в начале каждой строки согласованы, то есть вложенные отступы сохраняются визуально, и каждый следующий уровень отступа имеет одинаковую ширину (около четырех х  ширина на один уровень отступа).

В идеале отступы, которые были сделаны с помощью пробелов или смешанных пробелов и табуляций, должны быть заменены табуляцией (или тем, что программное обеспечение DTP может сделать лучше для вложенных отступов), поэтому, при необходимости, регулировка отступов может быть проще.
Конечно, можно оставлять пробелы, но может быть сложнее управлять их шириной при изменении шрифта и сложнее выравнивать отступы внутренней строки, как в столбцах таблицы.

Моноширинный шрифт + пробелы

Обратите внимание, что если источник отформатирован с пробелами преднамеренно и предназначался для чтения только в моноширинном шрифте (например, ASCII-диаграммы или ASCII-art), следует сохранить пробелы полностью без изменений , но это решение должно быть принято с самого начала. Шрифт "Courier New" является наиболее распространенным для этого случая. Тем не менее, если в этом нет особой необходимости, я советую не использовать моноширинный формат, потому что все меньше и меньше новых людей сегодня выбирают моноширинный код для кодирования, а в случае корректуры пропорциональные шрифты улучшат качество чтения.

Как правило, сжатые (например, узкие шрифты Arial) или более мелкие шрифты могут работать лучше: это делает больший акцент в отличие от основного текста, делает код более компактным и, таким образом, менее вероятно появление нежелательных переносов строк.

Я думаю, что здесь можно нарисовать линию, и если вышеупомянутое сделано, то есть 99% -ная вероятность, что все должно быть хорошо, по крайней мере для простого одноконтрольного кодового блока без цветов.

Инструменты и расширенное форматирование

Кроме того, внешний вид может быть значительно улучшен с помощью подсветки синтаксиса.

• цветная печать или просмотр экрана: в полноцветном макете может быть использована любая функция выделения, так что это лучший вариант, но печать может привести к некоторым изменениям цвета.

• Оттенки серого или ч / б: здесь, конечно, можно использовать жирный шрифт (например, ключевые слова) или курсив (например, комментарии), но обратите внимание, что цвета будут преобразованы в серый со всеми вытекающими последствиями. Например, комментарии, выделенные серым цветом, могут отлично выглядеть на дисплее, но могут стать слишком бледными на бумаге.

Самый важный вопрос заключается в том, есть ли у разработчика макета инструменты, которые могут представлять код в удобочитаемой форме. К счастью, существует множество бесплатных инструментов для редактирования кода, наиболее заметными (для Windows) являются: Notepad ++, VSCode, Visual Studio . Но следует помнить о возможных неявных автоматических преобразованиях табуляции в пробелы.

В Notepad ++ есть возможность экспортировать код в формате RTF , который сохранит все форматирование и подсветку синтаксиса источника.

Если макет не требует изменения потока текста в представлении кода, можно напрямую использовать изображения (снимки экрана) - он не так гибок, как текст, но сохранит 100% форматирование и нумерацию строк и может сэкономить много времени. Например, номера строк сложно сохранить в текстовом виде. Также экспорт в PDF является хорошей альтернативой - но не все программное обеспечение DTP может встраивать PDF-файлы, и при печати в PDF может быть потеряно некоторое форматирование.

Например, мои настройки для кода Python в Notepad ++ выглядят так:

Это просто чтобы проиллюстрировать, что можно напрямую использовать скриншоты, и это может быть самым простым способом. Существуют различные инструменты, которые могут помочь с захватом экрана - может потребоваться «сшивание» экранов для изображений с более высоким разрешением.

Цветовая схема, конечно, индивидуальна, определена в конфигураторе стилей редактора, который уже знает о поддерживаемом языке, что затрудняет ложное форматирование, даже если кто-то не знает синтаксис. Здесь должны работать общие правила типографики: не слишком много цветов, согласованные шрифты, отступы, удобный межстрочный интервал.

Дополнительные инструменты / плагины для пользовательских определений языка также распространены, но они требуют знания синтаксиса.

В HTML есть набор тегов <code> ... </ code>, который говорит читателю / интерпретатору обрабатывать содержимое буквально. Кроме того, <pre> ... </ pre> делает то же самое. Как человек, которому часто приходилось набирать формулы, уравнения и код для публикации, я также выступаю за использование ИЗОБРАЖЕНИЙ для этого ... создайте .gif, .jpg или .png проблемного элемента.

Другим фактором является то, что код традиционно отображается в моноширинном Courier или другом моноширинном шрифте, потому что он семафор или телеграфирует читателю, что это не основной текст. Я подписываюсь на этот стиль выбора, я думаю, что это имеет большой смысл.

В большинстве "унаследованных" систем набора текста математические уравнения достаточно высокой сложности были чрезвычайно трудоемкими ... и чреваты ошибками.