Представление кода в печатном виде (Что обычно требуется?)

[Evgueni]

Сейчас обдумываю что следует включить в серию статей по LaTeX. Предварительно решил, что одна из статей будет посвящена оформлению кода. Хотелось бы понять что для представления кода нужно.

Мне лично достаточно просто напечатать код с минимальными "украшательствами", как то подпись, выделение ключевых слов, автоматическая нумерация строк.

Надо ли описывать как рисовать блок схемы программ? Или это излишне? Если надо, то на сколько подробно это описывать? Я как-то не сталкивался с такой необходимостью.

Ну и вообще что для написания технической документации вообще нужно?

С уважением Евгений

[sarutobi]

А что Вы понимаете под технической документацией?
Обычно исходный код в ней является лишь малой частью, весь его показывать смысла не имеет.
Имеет смысл показать основные диаграммы в виде UML представлений, краткое описание модулей и функциональных элементов, кросс-линки на зависящие/зависимые элементы (диаграмма наследования для ООП). Руководство пользователя, программиста, ман - все это тоже части ТД. Не знаю всех возможностей TeX/LaTeX, поэтому не могу сказать что три последних элемента тоже требуется описать
Вообще есть проект Doxygen который облегчает написание ТД. Он умеет генерить документацию в LaTeX (и еще десяток других форматов) из определенным образом оформленного исходного кода.
Все написанное ИМХО.

[Evgueni]

А что Вы понимаете под технической документацией?

А что Вам надо под этим словом понимать?

Обычно исходный код в ней является лишь малой частью, весь его показывать смысла не имеет.

Естественно, весь код какой-то конкретной программы смысла, наверное, показывать не имеет, но, например, примеры использования, алгоритмы и тому подобное, вполне осмысленный текст.

С другой стороны тот же Кнут проповедовал Literate Programming - там как раз именно код и печатается. У Кнута даже книга была выпущена, которая состояла целиком из распечатки - TeX the Program называлась - до сих пор продаётся.

Имеет смысл показать основные диаграммы в виде UML представлений, краткое описание модулей и функциональных элементов, кросс-линки на зависящие/зависимые элементы (диаграмма наследования для ООП).

Ну это руками вряд-ли есть смысл набирать. Это должно автоматически генериться. IMHO для пользователя это не самая удобная документация - но в любом случае гляну.

Руководство пользователя, программиста, ман - все это тоже части ТД. Не знаю всех возможностей TeX/LaTeX, поэтому не могу сказать что три последних элемента тоже требуется описать

Понятно. Подумаю над этим тоже.

Вообще есть проект Doxygen который облегчает написание ТД. Он умеет генерить документацию в LaTeX (и еще десяток других форматов) из определенным образом оформленного исходного кода.

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

[Egan]

Чем больше будет написано, тем лучше, для всего найдётся свой читатель.

[ArtSh]

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

[Evgueni]

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

Это-то понятно. Первым занимается пакет listings - много языков и диалектов поддерживает, а со скриншортами работать надо так же, как и с другими картинками, правда необходимо учитывать что это растр. Создание самих картинок, естественно, выносится за рамки процесса вёрстки.

[vorchun]

Пытаюсь сформулировать, что требовалось мне (при описании программ для "продвинутых" пользователей):

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

Учитывая мою специфику работы, больше мне ничего не требовалось, но, скорее всего, это именно моя специфика работы.

[Evgueni]

Диаграммы переходов между режимами работы программы.

Где-нибудь можно посмотреть на пример? Если я правильно понял, то такая возможность есть.

Отдельные стили для а) элементов управления программой (каманды меню, экранные кнопки, клавиши клавиатуры), б) пользовательского ввода и в) вывода программы.

Названия клавиш типа Enter в рамке существуют. Вывод программы можно оформить как окружение verbatim (текст без форматирования). А как оформить команды меню и экранные кнопки? Там же необходимо, чтобы эти элементы совпадали с программой.

Псевдоязык для описания алгоритма работы программы (похоже на блок-схему алгоритма, но почти в "чисто текстовом" виде).

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

С уважением Евгений

[Георгий]

Не забудьте указать как транслировать исходники в dvi-файлы. А то я прочитал кучу документации,а этого не увидел. Пришлось спрашивать.Объяснили.

[Evgueni]

Не забудьте указать как транслировать исходники в dvi-файлы. А то я прочитал кучу документации,а этого не увидел. Пришлось спрашивать.Объяснили.

? В смысле? Исходники latex или имеются в виду исходники программ? Почему в именно в dvi?

[vorchun]

Диаграммы переходов между режимами работы программы.

Где-нибудь можно посмотреть на пример? Если я правильно понял, то такая возможность есть.

С использованием внешних пакетов, да, возможность есть. По сути сильно походит на блок-схему алгоритма.

Отдельные стили для а) элементов управления программой (каманды меню, экранные кнопки, клавиши клавиатуры), б) пользовательского ввода и в) вывода программы.

Названия клавиш типа Enter в рамке существуют. Вывод программы можно оформить как окружение verbatim (текст без форматирования). А как оформить команды меню и экранные кнопки? Там же необходимо, чтобы эти элементы совпадали с программой.

Не обязательно. Например, я делал примерно так:

Код: Выделить всё

% Элементы ЭКГ должны набираться наклонным  шрифтом
\newcommand{\ECG}[1]{\textsl{#1}}

Ну и дальше понятно как. Имя команды пусть не смущает, так было удобнее.

Псевдоязык для описания алгоритма работы программы (похоже на блок-схему алгоритма, но почти в "чисто текстовом" виде).

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

Это точно!

[Георгий]

? В смысле? Исходники latex или имеются в виду исходники программ? Почему в именно в dvi?

Ну я сделал документ для TeX. Потом делаю latex document.tex и получаю файл пригодный для просмотра. Просто DVI это все,что я знаю из форматов.

[Evgueni]

? В смысле? Исходники latex или имеются в виду исходники программ? Почему в именно в dvi?

Ну я сделал документ для TeX. Потом делаю latex document.tex и получаю файл пригодный для просмотра. Просто DVI это все,что я знаю из форматов.

Ааа, ну это описано в первой части, которая была в сентябрьском номере. Просто обычно на выходе используют PostScript или pdf, да и сам tex-файл можно в текстовом редакторе посмотреть