ViJu - Почему DocBook? - Комментарии

Обратите

pvnhome — Tue, 05 Aug 2008 23:33:23 +0400

Обратите внимание что в примере все настроено для "xi:include".
"Сборка" из частей была одним из основных условий. Тоже сразу не работало. Видимо руки кривые или ошибка в ДНК. Гы-гы-гы!!!

Инструкции

Ах да! Забыл еще

pvnhome — Tue, 05 Aug 2008 23:30:14 +0400

Ах да! Забыл еще один важный весч! Хе-хе!
Правда совсем не хе-хе, а ХЕР. Для преобразования в PDF. Правда ХЕР ставит снизу на странице свой лэйбл, но при печати не видно и с русским работает ОК. Можете экспериментировать с другими пакетами. Терпенье и труд все перетрут :)

Здесь же все уже настроено (например, шрифты).

Опять же пропишите путь к x4u.bat и xep.bat. Ну и в них загляните. Там надо тоже пути подправить.

Итак рецепт "слезы комсомолки":

http://files2.north.kz/f/ftp6101/xep.7z

Если что не пойдет, то может быть даже отвече на мэйлы :)

Вот это

pvnhome — Tue, 05 Aug 2008 23:22:14 +0400

Вот это настроенный софт (libxml, docbook_xsl ):

http://files2.north.kz/f/ftp6101/docbook_bins.7z

Его надо куда-то разархивировать (например, D:\CPP\libxml) и прописать путь к каталогу D:\CPP\libxml\bin

Вот это демо проект
http://files2.north.kz/f/ftp6101/DevGuide.7z

В xsl\html.xsl и xsl\pdf_xer.xsl надо поменять пути к D:\CPP\libxml

Описать

pvnhome — Tue, 05 Aug 2008 23:05:06 +0400

Описать установку и настройку - это трудно. Я несколько раз переустанавливал и каждый раз "парился". Легче выложить уже настроенный пакет и пример документа с командными файлами (например, bat) для преобразований. Про "прекрасно настраиваемые DSSSL и XSL stylesheets" - это тоже смело сказано. А в остальном согласен MSO как и OOo не средства для создания тех.документации, а особенно если над документом работает несколько человек. DocBook + контроль версий рулят!

А не опишите

Алексей — Thu, 31 Jul 2008 16:51:18 +0400

А не опишите подробнее про установку необходимых программ под Windows?
Самая основная проблема, с которой столкнулся, это вывод русских букв в PDF.

Oxygen вроде кучу

ffsdmad — Wed, 27 Feb 2008 00:23:37 +0300

Oxygen вроде кучу денег стоит
я по старинке, в любом текстовом редакторе

OOo умеет

Юлия — Tue, 26 Feb 2008 12:44:33 +0300

OOo умеет работать с DocBook - очень коротко можно посмотреть тут
http://xml.openoffice.org/xmerge/docbook/UserGuide.html
Но не советую использовать OOo для docbook - неудобно.

Лучше использовать Xml редакторы.
Если Вы технический писатель и работаете с большими текстами,
Вам подойдет Serna.
Если Вы разработчик, то Вам подойдет
Oxygen или AltovaXMLspy

Спасибо автору,

ffsdmad — Tue, 26 Feb 2008 02:01:38 +0300

Спасибо автору, материал просто замечательный
Жалко, что я сначала разобрался методом тыка и чтения манов, прежде чем нашёл Вашу заметку
Отныне с собираюсь везде и повсеместно в своих проектах примерять DocBook
а MSO я не применяю уже года два, вместо него использую ООо
Интересно ООо умеет работать с DocBook ?

Для того, чтобы

Эдуард — Sun, 02 Sep 2007 00:09:42 +0400

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

P.S. Под XP все просто настраивается.

Почему то вы не

Антон — Fri, 27 Apr 2007 11:37:05 +0400

Почему то вы не упомянули процесс инсталляции и настройки продуктов. Если MS Word устанавливается в автоматическом режиме, пользователю надо только следовать мастеру установки. С DocBook же ситуация достаточно запутанная, надо установить несколько продуктов от разных производителей. Более того, пока я нигде в интернете не смог найти пошагового описания настройки DocBook под WindowsXP.

Т.е. время вхождения в этот проект гораздо выше, чем для MS Word.

Почему DocBook?

Юлия — Fri, 29 Jun 2007 20:16:47 +0400

Это история о том, как автоматизировать подготовку технической документации.

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

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

Начинаем писать текст

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

MS Word.

На первый взгляд Word предоставляет самые широкие возможности форматирования - пользуйся стилями и все в порядке. Но за кажущейся простотой применения стилей в Word, скрывается много сложностей и ошибок, подстерегающих неопытного пользователя и много головной боли для опытного пользователя.

Проблема первая - текст, который легко форматируется впоследствии

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

В Word

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

В DocBook

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

Вот пример текста двух абзацев с выделенным словом и тегами внутри:

<para>На собственном опыте проверено, что DocBook имеет <emphasis>все</emphasis> необходимое - чтобы правильно структурировать текст как большой, типа книги, так и маленький - как, например, эта статья.</para> <para>Названия тегов интуитивно понятны и не возникает двусмысленности, не надо задумываться какой тег выбрать. Если это заголовок, не вожно чего статьи или секции - это <sgmltag>title</sgmltag>, если это сноска - значить <sgmltag>footnote</sgmltag> - все очень-очень просто.</para> *

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

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

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

Наглядность набираемого текста обеспечивается подсветкой тегов существующей в XML редакторах, а также в некоторых XML редакторах предусмотрены специальные WISYWIG режимы, в которых вы как и в Word'e видете и редактируете сразу отформатированный текст:

Еще одно преимущество XML формата и XML редактора - вы никак не ошибетесь с форматированием - редактор всегда подскажет и укажет, как тег в данном контексте уместен, а какой просто не возможен. Таким образом на выходе вы всегда получаете "чистую" разметку.

Проблема вторая - изменение внешнего вида

Исходник текста

и два варианта выходных форматов *

В Word

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

Ну а если мы желаем применить какой то особенный стиль всего текста, например, наш собственный корпоративный стиль? Меняем стиль каждого элемента поотдельности или пытаемся применить свой шаблон документа, в котором кстати имена стилей одинаковых по смыслу элементов могут и не соответствовать; к тому же, к слову сказать, применение другого шаблона к уже написанному тексту не совсем тривиальная задача в Word'е. Далее, на следующей неделе мы поменяли свой корпоративный стиль (может даже и не сильно), что делать с уже написанным текстом? опять менять шаблон.

В DocBook

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

Благодаря открытому проекту DocBook XSLs, представляющему собой набор прекрасно настраиваемых DSSSL и XSL stylesheets, и использованию CSS, вы или кто-то другой легко сможете настроить внешний вид выходного документа, в любой момент его можно изменить и применить уже готовые использованные ранее шаблоны.

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

Ниже приведена классификация тегов DocBook (автор А. Белайчук). Это не полная классификация, но в ней приведены большинство наиболее употребительных тегов (см. там).

Сохраняем, публикуем и печатаем текст

Проблема третья - хранение исходного текста документа

Хранение документа в формате Word

с немалыми затратами дискового пространства. В этом формате хранятся как данные, так и форматирование этого документа, причем в файле Word кроме необходимого форматирования, которое обеспечивает внешний вид нашего документа, сохраняется также много "лишних" данных.

Таким образом, сохраняя в Word несколько документов одинакового форматирования, информация о форматах дублируется во всех файлах.

В DocBook

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

Проблема четвертая - сохранение в различных форматах.

В Word 2003

существует возможность сохранить текст в следующих форматах -

MS Word (.doc), различные версии;
веб-страница (.html), несколько вариантов;
RTF;
обычный текст;
XML документ (WordML или свой формат XML - надо только подключить XML схему *).

Все эти форматы плохо передают форматирование, сделанное в Word; и к тому же добавляют много совершенно ненужной информации.

В DocBook

Благодаря открытому проекту DocBook XSLs, представляющему собой набор прекрасно настраиваемых DSSSL и XSL stylesheets, и существованию ряда как бесплатных, так и коммерческих инструментов для преобразования XML, вы легко (одной кнопкой) получаете свою документацию в различных форматах, в том числе и подготовленной для печати (в формате PDF).

Форматы поддерживаемые DocBook XSLs:

HTML, XHTML (один выходной файл или несколько с навигацией для переходов по страницам)
HTMLhelp (CHM)
XSL-FO (затем в PDF)
javahelp
manpages
slides (создание слайдов, выходной формат - любой из выше перечисленных)
WordML

Используем текст повторно

Включаем в текст внешние данные

Классификация тэгов DocBook

- article — для документов относительно небольшого объема (формата статьи)
- book — для более объемных и строже оформленных документов (книг)
- title — название
- author — авторы
- keyword — ключевые слова
- copyright — авторские права
- revhistory — история изменений
- chapter — глава книги
- section — раздел книги или статьи (произвольного уровня)
- abstract — аннотация
- preface — вступительное слово
- appendix — приложение
- bibliography — список литературы
- index — предметный указатель
Главы и разделы обычно начинаются с названия title.
- note — примечание
- tip — подсказка, совет
- warning — предупреждение (обычно об опасности для человека)
- caution — предупреждение (обычно об опасности для оборудования)
- important — важное замечание
- itemizedlist — маркированный
- orderedlist — нумерованный
- variablelist — список переменных или определений
Пункт списка оформляется тэгом listitem, термин или переменная в variablelist — тэгом term.
- emphasis — смысловое ударение
- filename — имя файла
- command — компьютерная команда
- option — опция (ключ) команды
- replaceable — переменная часть (аргумент) команды
- userinput — текст, вводимый пользователем
- computeroutput — сообщение программы
- literal — кодовое слово
- quote — просто закавыченный текст внутри абзаца
- blockquote — цитата из одного или нескольких абзацев
- citetitle — название процитированного источника
- ulink — интернет-ссылки
- link — перекрестные ссылки внутри документа, текст ссылки подставляется автоматически
- xref — перекрестные ссылки внутри документа, текстом ссылки можно задавать произвольно
- olink — ссылки на другие документы в рамках единой базы данных ресурсов
- footnote — примечание к тексту
- callout — примечание к иллюстрации или листингу программы
- graphic — простой, но не гибкий
- mediaobject — более сложный, позволяет автору предоставлять несколько альтернативных форматов изображения
- figure — иллюстрация, включаемая в автоматически генерируемый список иллюстраций
- informalfigure — иллюстрация без названия и не попадающая в список иллюстрация
- screenshot — графическая копия экрана компьютера
- inlinegraphic — упрощенный вариант
- inlinemediaobject — универсальный вариант
- table — таблица, включаемая в автоматически генерируемый список таблиц
- informaltable — таблица без названия и не включаемая список таблиц
- thead — шапка
- tbody — тело
- tfoot — подвал
- row — строка
- entry — ячейка
- entrytbl — вложенная таблица
- code — фрагмент программного кода внутри абзаца
- programlisting — текст программы
- screen — текст, видимый на экране компьютера
- literallayout — произвольный заранее отформатированный текст
- example — пример, включаемый в автоматически генерируемый список примеров
- informalexample — пример без названия и не попадающий в список примеров
- co — место, к которому относится примечание
- calloutlist — список примечаний, обычно следующий за листингом
- callout — текст примечания

В пятой версии DocBook теги sgmltag заменены на tag.

В данном примере различия определяются наличием и отсутствием одной небольшой CSS.

с подключением XML схем в Word - много проблем: далеко не каждая XML схема, даже соответствующая стандарту W3C XML shema, может быть использована в Word.