Как отформатировать исходный код в документе Framemaker?
Я должен написать технический документ в Framemaker, который объясняет различные исходные коды программирования.
Итак, мой документ состоит из набора текста, за которым следует набор исходного кода (Java, XML), а затем еще текст и т. Д.
Этот вопрос не о том, должен ли я использовать Framemaker или нет - это программное обеспечение, которое я должен использовать.,,
Что меня смущает, так это как форматировать исходный код как часть моего документа. Кто-нибудь сделал это для технического документа и натолкнулся на какие-либо инструкции или советы? Пока что мой поиск в Google не дал ничего общего с тем, что мне нужно делать.
2 ответа
По крайней мере, создайте стиль абзаца для примеров кода, используйте хороший моноширинный шрифт и не забудьте отключить переносы.
Когда я делал это, я создавал стиль таблицы и вставлял туда код, поэтому над ним был красивый заголовок заголовка, и он немного выделялся. Единственное, что нужно, - это то, что ячейки таблицы Frame не будут разбиваться на разрыв страницы, поэтому, если ваш код длиннее страницы или угрожает оказаться ниже нижней части страницы, вам нужно создать несколько строк в таблице и разбить код по строкам.
Из статьи, которую я написал об этом несколько лет назад, которая снова будет доступна онлайн на следующей неделе.
Типографы в первую очередь занимаются разборчивостью и имеют инструменты, практики и традиции, насчитывающие сотни и даже тысячи лет, на которые можно полагаться при написании текстов на естественных языках. Однако компьютерные программы не написаны на естественных языках. Они написаны на "языках программирования": искусственных языках, которые имеют свои собственные правила синтаксиса, свои собственные правила представления и свои собственные критерии разборчивости. Поэтому компьютерный код - это особая область для набора текста, равно как и музыка, математика и химия. Эти домены имеют свои собственные правила, которые не используются при настройке естественных языков.
Само по себе компьютерное программирование имеет очень недавнее происхождение, и практика его ввода в типографию насчитывает не более 45 лет: значительные объемы компьютерного кода были опубликованы только за последние 20 лет или менее. Связанная с этим типографская дисциплина является незрелой или, по сути, практически отсутствует, и типографские ожидания практиков в этой области также низки, как вы можете видеть, изучив множество торговых книг. Нет никаких причин, почему вы не можете попытаться сделать лучше.
Используйте шрифт без засечек. В одной из моих книг я использовал одно и то же семейство шрифтов, FF Scala для текста и FF Scala Sans для кода. Я думаю, это выглядит великолепно, но существуют противоположные мнения: они могут заставить вас использовать моноширинный шрифт, хотя лично я думаю, что это очень устарело. Избегайте курьера, он ни с чем не сочетается.
Отступ является частью обозначения. Вы должны уважать существующие левые отступы. Исходный код уже будет с вкладками. Уменьшите каждую вкладку до одного или двух пробелов максимум, иначе у вас не останется горизонтальной комнаты.
Постарайтесь потерять как можно больше вертикального пространства, например, подавить пустые строки. Попробуйте поместить весь образец на одну страницу. Позвольте этому плавать в случае необходимости, чтобы достигнуть этого.
Разрывы строк являются частью обозначения. Не добавляйте разрывы строк без консультации с автором.
Кавычки являются частью обозначения. Не меняйте одинарный на двойной или наоборот.
Обоснование: компьютерные программы всегда пишутся, просматриваются и устанавливаются по левому краю, по правому краю.
Разрывы страниц. При настройке компьютерного кода в книге разрывы страниц не могут просто следовать простым принципам "сирота / вдова", используемым при наборе текста на естественных языках. Вместо этого, по возможности, логические "блоки" кода должны храниться вместе. Обычно типограф не может определить границы блоков в коде, хотя пустая строка обычно является приемлемой точкой для разрыва страницы. "Блочные комментарии" следует хранить со следующим блоком кода. Если вы не знаете, что это такое, спросите автора.
Перенос. Языки программирования не являются естественными языками и не соблюдают обычные правила переноса слов. Обратитесь к автору, если вам нужно дефисировать, или просто нет. Слова в тексте программы никогда не должны быть дефисами или переносами, кроме как в соответствии с инструкциями автора.
Верхний и нижний регистр. Случай в программном коде обычно важен для компьютера и практически всегда для писателей и их читателей. Часто используются пары слов, которые отличаются только регистром и представляют разные вещи: например, BufferedOutputStream и bufferedOutputStream. Программисты, особенно авторы-программисты, обычно очень систематичны в отношении кейса способами, которые не обязательно имеют смысл для типографа (или других программистов!).
Практические рекомендации
- Отступ в единицах em. Решением многих проблем при наборе компьютерных программ является EM. Скорее всего, вкладки автора будут на следующем кратном из 8 пробелов (1, 9, 17, …); типографские вкладки для кода программы должны быть кратны 1 или 2 ems. Принятие их в качестве единицы отступа может поначалу показаться автору "смешным", поскольку отступы могут быть гораздо уже, чем на экранах или распечатках. Однако до тех пор, пока сохраняется вертикальное выравнивание позиций табуляции, намерение автора полностью сохраняется.
- Разрывы строки должны быть в соответствии с MS.
- Разрывы страниц: если разрывы страниц могут возникать в середине программного кода, необходимо проконсультироваться с автором относительно предпочтительных точек разрыва страницы. Обычно этого следует избегать в коротких примерах; в более длинных программах автор должен указать все возможные разрывы страниц в MS.
- Цитаты. Обычно используются "прямые" цитаты, а не типографские. Это исторически обусловлено использованием шрифтов без типографских кавычек (например, Courier, Helvetica) в набранном компьютерном коде. Это не требуется по свойствам обозначений. Я не вижу оснований против использования типографских кавычек при настройке компьютерных программ, если одинарные кавычки остаются одинарными, а двойные кавычки остаются двойными, т. Е. До тех пор, пока цитаты автора сохраняются, а не "исправляются" в стандартной типографской практике.
- Цифры. Обычно в коде программы всегда используются цифры подкладки. Если вы можете быть обеспокоены использованием цифр старого стиля в программном коде, или если шрифт построен таким образом, я не вижу причин против этого. Вы должны выбрать шрифт, в котором 1, I и l (строчные буквы L) различны, а также 0 (ноль) и O.