Как отформатировать исходный код в документе Framemaker?[закрыто]

Question

Я должен написать технический документ в Framemaker, который объясняет различные исходные коды программирования.

Итак, мой документ состоит из набора текста, за которым следует набор исходного кода (Java, XML), а затем еще больше текста и т.д.

Этот вопрос не о том , должен я или не должен использовать Framemaker - это программное обеспечение, которое я должен использовать ...

Что меня смущает, так это то, как отформатировать исходный код как часть моего документа.Кто-нибудь делал это для технического документа и сталкивался с какими-либо инструкциями или советами?Пока что мой поиск в Google не дал ничего, относящегося к тому, что мне нужно сделать.

Answer 1

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

Когда я делал это, я создавал стиль таблицы и вставлял туда код, поэтому над ним был красивый заголовок заголовка, и он немного выделялся. Единственный недостаток - это то, что ячейки таблицы Frame не будут разбиваться на разрыв страницы, поэтому, если ваш код длиннее страницы или угрожает оказаться ниже нижней части страницы, вам нужно создать несколько строк в таблице и разбить код на строки.

Answer 2

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

Печатники первую очередь касается читаемости, и есть инструменты, практики и традиций уже сотни и действительно, тысячи лет, на которые можно опереться при создании текстов в естественные языки.Однако компьютерные программы написаны не на естественных языках.Они написаны на ‘языках программирования’:искусственные языки, которые имеют свои собственные правила синтаксиса, свои собственные соглашения о представлении и свои собственные критерии разборчивости.Компьютер таким образом, код является особой областью верстки, так же как музыка, математика и химия.Эти домены имеют свои собственные правила, которые не являются правилами, используемыми при настройке естественных языков .

Само по себе компьютерное программирование появилось совсем недавно, и практика его ввода в type насчитывает не более 45 лет:значительные объемы компьютерный код, были опубликованы в последние 20 лет или меньше.Связанная с этим типографская дисциплина незрелая или фактически отсутствует, как и типографские ожидания специалистов-практиков в этой области также низки, как вы можете убедиться, просмотрев множество профессиональных книг.Нет никаких причин, по которым вы не могли бы попытаться добиться большего.

1. Используйте шрифт без засечек.В одной из своих книг я использовал то же семейство шрифтов, FF Scala для текста и FF Scala Sans для кода.Я думаю, что это выглядит великолепно, но есть противоположные мнения:это может вынудить вас использовать моноширинный шрифт, хотя лично я считаю, что он очень устарел.Избегайте курьера, он ни с чем не сочетается.

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

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

4. Разрывы строк являются частью обозначения.Не добавляйте разрывы строк, не посоветовавшись с автором.

5. Кавычки являются частью обозначения.Не меняйте single на double и наоборот.

6. Обоснование:Компьютерные программы всегда пишутся, просматриваются и устанавливаются с выравниванием по левому краю и с неровностями по правому краю.

7. Разрывы страниц.При настройке компьютерного кода в книге разрывы страниц не могут просто следовать простым принципам "сирота / вдова", используемым при наборе текста на естественных языках.Вместо этого логические ‘блоки’ кода должны храниться вместе, если это возможно.Типограф обычно не может определить границы блоков в коде, хотя пустая строка обычно является приемлемой точкой для разрыва страницы.‘Блок комментариев’ должен быть сохранен вместе со следующим блоком кода.Если вы не знаете, что это такое, спросите автора.

8. Расстановка переносов.Языки программирования не являются естественными языками и не соблюдают обычных правил расстановки переносов.Проконсультируйтесь с автором, если вам нужно расставить дефисы, или просто не делайте этого.Слова в тексте программы ни в коем случае не должны быть написаны через дефис или разрыв строки, за исключением случаев, предусмотренных инструкциями автора.

9. Верхний и нижний регистр.Регистр в программном коде обычно важен для компьютера и практически всегда для авторов и их читателей.Часто используются пары слов, которые отличаются только регистром, обозначая разные вещи:например ,BufferedOutputStream и BufferedOutputStream.Программисты, особенно программисты-авторы, обычно очень систематичны в отношении оформления, причем такими способами, которые не обязательно имеют смысл для типографа (или других программистов!).

Практические рекомендации

• Отступ в единицах измерения em.Решением многих проблем, связанных с версткой компьютерных программ, является em.Авторские вкладки, скорее всего, будут располагаться через следующие 8 пробелов (1, 9, 17, ...).;типографские вкладки для программного кода должны быть кратны 1 или 2 ems.Использование em в качестве единицы отступа поначалу может показаться автору ‘забавным", поскольку отступы могут быть намного уже, чем видно на экранах или распечатках.Однако до тех пор, пока сохраняется вертикальное выравнивание табуляций, намерение автора полностью сохраняется.
• Разрывы строк должны соответствовать MS.
• Разрывы страниц:Если в середине программного кода могут возникать разрывы страниц, необходимо проконсультироваться с автором относительно предпочтительных точек разрыва страниц.Обычно этого следует вообще избегать в коротких примерах;в более длинных программах автор должен указывать все возможные разрывы страниц в MS.
• Цитаты:Обычно используются ‘прямые’ кавычки, а не типографские.Это исторически обусловлено использованием шрифтов без типографских кавычек (например,Courier, Helvetica) в набранном компьютерном коде.Это не требуется свойствами обозначения.Я не вижу причин против использования типографских кавычек при настройке компьютерных программ, если одинарные кавычки остаются одинарными, а двойные - двойными, т.е.пока автора цитаты сохранились, а не "исправленную" стандартной типографской практике.
• Цифры:Традиционно в программном коде всегда использовались накладные цифры.Если вас беспокоит использование цифр старого стиля в программном коде, или если шрифт построен таким образом, я не вижу причин возражать против этого.Вы должны выбрать шрифт, в котором различаются 1, I и l (строчные буквы L), а также 0 (ноль) и O.