v1.9 30 Мая 2000 года. Данный документ переведен в рамках проекта Russian Linux Documentation Project. В этом документе собраны полезные советы,описания утилит и приемов работы, которые призваны помочь авторам документов HOWTO ускорить их написание. Этот документ был написан 26 Августа 1999 Mark F. Komarinski после двух дней,потраченных на то,чтобы заставить инструменты необходимые для написания HOWTO работать как надо. Если этот документ поможет хотя бы одному автору документации,автор будет считать свою работу полностью выполненной. Последнюю версию этого документа в формате sgml (на английском языке) можно получить с домашней страницы автора http://www.cgipc.com/˜markk/. Другие версии в различных форматах можно взять с сайта LDP (http://www.linuxdoc.org). Комментарии по поводу этого HOWTO направляйте по адресу:(markk@linuxdoc.org). Данный документ был переведен в рамках проекта Russian Linux Documentation Project. Цель данного проекта - перевод документации, посвященной различным аспектам настройки и использования ОС Линукс на русский язык. Более подробно узнать о проекте вы можете на нашем веб сайте http://www.linux.ru.net/~RLDP. В переводе данного HOWTO участвовали: Александр Михайлов. alexmikh@linux.ru.net v1.9 (Май 30, 2000) Информация о PSGML была получены от Mark Craig. Начато описание различий между HOWTO и mini-HOWTO (c) 1999-2000 Mark F. Komarinski Данное пособие может распространяться целиком или в виде фрагмента,без уплаты каких либо лицензионных отчислений,при условии соблюдения следующих ограничений. Сообщение о копирайте приведенное ниже и данное предложение должны быть сохранены без изменений во всех полных или частичных копиях. Любой перевод или основанная на этом документе работы должны быть одобрены автором в письменном виде до их публикации. Если вы распространяете фрагмент данного документа, должны быть включены инструкции по получению полной версии данного пособия, и даны соответвующие ссылки. Небольшие фрагменты данного документа могут быть включены в качестве иллюстрации или цитаты в другие работы без копирования данного документа, если дано правильное цитирование. Исключения могут быть сделаны для научных целей: Напишите автору и спросите его. Эти ограничения сделаны для того, чтобы защитить нас как авторов, а некоем случае не для ограничения вас как читателей и обучающихся. Любой исходный код (помимо sgml кода данного документа) в данном документе подпадает под действие GNU General Public License, доступной через анонимный FTP доступ в архиве GNU. Спасибо всем кто давал мне комментарии во время написания этого документа. Среди них: Deb Richardson, Daniel Barlow, Greg Ferguson, Mark Craig и другие подписчики рассылки ldp-discuss. Некоторые секции были взяты из HOWTO Index (доступно на сайте LDP) и документации на sgmltools.Секции о CVS доступе были частично написаны Serek (ser@serek.arch.pwr.wroc.pl). Секции о DocBook были написаны Jorge Godoy (godoy@conectiva.com.br). Выражаю им свою признательность за их помощь. Проект Linux Documentation Project (LDP) был начат с целью предоставить новым пользователям быстрый путь получения информации о конкретном предмете. Он не только содержит серию книг о администрировании, работе в сетях и программировании, но и огромное число небольших работ, посвященных конкретным проблемам, написанных теми кто сталкивался с ними. Например, если вы хотите узнать о печати,возмите Printing HOWTO. Если хотите знать как работает ваша Enthernet карта под Линукс,возмите Enthernet HOWTO и так далее. Первоначально многие из этих работ были в текстовом или HTML формате. Но с течение времени стало ясно, что должен существовать лучший путь хранения и обработки этих документов. Путь, который позволил бы вам читать документ с веб страницы, в виде текстового файла на CD-ROM, или даже на карманном PDA. И ответ был найден - SGML. Стандартный обобщенный язык разметки (SGML) - это язык, который основан на внедрении кодов внутрь документа. Этим он похож на HTML, но на этом их сходство заканчивается. Сила SGML в том, что в отличии от WYSIWYG (What You See Is What You Get), вы не определяете такие вещи как цвета,размеры шрифтов или какое либо форматирование. Вместо этого вы определяете элементы составляющие документ (параграфы,секции,нумерованные списки ...) и предоставляете SGML процессору вместе с конечной программой заботу о размещении элементов,цветах,шрифтах и прочем. HTML делает примерно тоже самое и на самом деле является лишь одной из форм SGML. SGML состоит из двух основных вещей. Во первых это Структура, которая обычно называется DTD (Document Type Definition - "определение типа документа"). DTD определяет зависимости между элементами. Например для создания этого документа использовалось DocBook DTD. DTD привносит общий вид и структуру во все документы, созданные с его использованием. Во вторых это наполнение, которое визуализируется SGML процессором и которое видит затем читатель. Например этот параграф - наполнение, но с таким же успехом наполнением может быть графическое изображение, таблица, список и т.д. Наполнение ограничивается тэгами,чтобы отделить элементы друг от друга. SGML предоставляет не только форматирование. Вы можете автоматически генерировать индексы, оглавления, и ссылки внутри документа или на внешние источники. Пакеты Jade и OpenJade позволяют вам экспортировать (далее это называется "визуализацией") SGML в LaTeX,info,text,HTML и RTF. Из этих базовых форматов вы можете затем создать другие, такие как : MS Word,PostScript,PDF и т.д. . Программы подобные Lyx, позволяют вам писать документы в формате TeX, затем экспортировать их в SGML и визуализировать из него в любой другой формат. SGML описывает как элементы работают а не на том как они выглядят. Он позволит вам писать документы быстрее, т.к. вам не нужно заботиться о размещении параграфов, размерах шрифтов и тому подобных вещах. В этой секции я приведу описание некоторых инструментов, которые могут вам понадобиться для создания собственной LDP документации. Я лишь опишу их здесь, подробнее об их использовании и установке вы сможете прочитать позже. Если вы используете какие-нибудь еще инструменты при написании LDP документации, пожалуйста дайте мне знать и я добавлю информацию о них в этот документ. Необходим если вы не используете openjade - ftp://ftp.jclark.com/pub/jade/jade-1.2.1.tar.gz Jade это фронт-енд процессор для SGML. Он использует DSSSL и DocBook DTD для верификации и визуализации SGML в другие форматы. Замена для Jade - http://openjade.sourceforge.net/ Расширенная версия Jade написанная DSSSL сообществом (смотрите ниже о DSSSL). Некоторые приложения требуют Jade, но для многие из них изменены(или изменяются) для поддержки этого пакета. Необходим - http://nwalsh.com/docbook/dsssl/db152.zip Document Style Semantics and Specification Language говорит jade как визуализировать SGML документ в печатную или онлайновую форму. DSSSL это то,что конвертирует тэг title в <H1> тэг в HTML,или bold, 14 point Times Roman для RTF,например. Документация к DSSSL расположена по адресу http://nwalsh.com/docbook/dsssl/db152d.zip. Заметьте, что модификация DSSSL не скажется на самом DocBook DTD. Она просто изменит то как выглядит визуализированый текст. LDP использует модифицированный DSSSL, который предоставляет оглавление. Необходим - http://www.oasis-open.org/docbook/sgml/3.1/docbk31.zip DocBook DTD определяет тэги и структуру DocBook SGML документа. Если произвести изменение в DTD,например добавить новый тэг,то он перестанет быть DocBook DTD. Очень рекомендуется - http://sgmltools-lite.sourceforge.net/ Это наследник проекта sgmltools,которые был официально остановлен более года назад. После этого Cees de Groot создал немного отличный от него проект,который работает как wrapper для SGML процессора Jade. Он прячет от пользователя сложный синтаксис. Я установил старые sgmltools, затем sgmltools-lite и смог отформатировать этот документ достаточно просто. Есть даже man страница для sgmltools, на которой описан его синтаксис. Необязательно TeX (рифмуется с blech!) это популярный язык разметки, который используют многие люди, особенно в математическом мире. Я до сих пор помню многие Calculus экзамены, которые были написаны на TeX. Это также один из первых языков разметки, который до сих пор используется (другой это формат *roff используемый в man страницах). TeX следует концепциям схожим с SGML. Так ка TeX визуализирует свои файлы в DVI (Device Independent - "независящий от устройства") который может быть в свою очередь визуализирован в другой формат. К сожалению DVI не так то легко конвертировать во что-либо, кроме языков печати (PostScript,PCL),что делает сложным генерацию HTML. TeX устанавливается или доступен в большинстве дистрибутивов Линукс. TeX также прилагается практически ко всем дистрибьюциям как LaTeX или TeTex. Любой из них подойдет вам. Необязательно - http://www.lyx.org/ LyX сочетает мощь SGML с простотой использования обычного ворд-процессора.Но это не WYSIWYG программа, а WYSIWYM (What You See Is What You Mean - "То-Что-Ты-Видишь-Это-То-Что-Ты-Имел-Ввиду") приложение,т.к. то что вы видите на экране это не обязательно то , что будет видеть пользователь после обработки вашего документа SGML процессором. То как LyX отображает документ, похоже на то как визуализирует его Jade, но не полностью. Хотя достаточно близко, чтобы представить себе как будет выглядеть документ. Секции и под-секции пронумерованы и выделены жирным шрифтом, для представления таких вещей как тэги <code> и <url> используются разные шрифты. Большинство тэгов спрятано от вас во время редактирования, т.к. LyX пишет в TeX,а затем экспортирует TeX в SGML. Необязательно - http://www.lysator.liu.se/~lenst/about_psgml/ В Emacs есть режим написания SGML называемый psgml. Автор этого документа с удовольствием примет любую информацию от людей имеющих опыт работы в этом режиме (пишите на e-mail). Psgml - это главный режим в Emacs, разработанный для написания SGML и XML документов. Он предоставляет " подсветку синтаксиса " и "приятную печать" свойства, которые отделяют SGML тэги от содержания, способ вставки "тэгов" как альтернативу их ручному вводу и способность проверки правильности документа (соответствие его DTD) во время его написания. Для пользователей Emacs это великолепный способ набора таких документов и многие считают его наиболее универсальным и гибким, среди всех доступных SGML утилит. Он работает с DocBook,LinuxDoc и другими DTD одинаково хорошо. Не рекомендуется - http://www.corel.com/ WodrPerfect 2000 для MS Windows имеет ограниченную поддержку SGML и DocBook 3.00. WordPerfect для Линукс не имеет поддержки SGML. Необязательно (но рекомендуется) - http://www.docbook.org/ Эта книга была выпущена издательством O'Reilly в октябре 1999, и представляет из себя великолепное справочное пособие для DocBook. Я считаю её великолепным практическим пособием, упор делается на XML,но тэги DocBook версии 3.1, также описаны в удобном формате. Вы можете приобрести её у вашего любимого продавца книг. Полная версия книги доступна в интернет по адресу указанному выше. Необязательно - http://aspell.sourceforge.net/ Это приложение для проверки орфографии может работать между SGML тэгами, и проверять только содержимое заключенное между ними. Обычные программы проверки орфографии, такие как ispell будут пытаться проверить тэги, вызывая ошибку на каждом новом встреченном тэге. Необязательно (возможно Red Hat специфичны) - http://www.redhat.com/ Red Hat распространяет три пакета, возможно начиная с версии 6.2,которые обеспечивают поддержку DocBook и некоторые утилиты. Они обеспечивают визуализацию только в форматы HTML и PDF,но их просто установить, если вы используете Red Hat,что поможет вам быстро начать писать, не тратя время на борьбу с утилитами. TeTex 0.9,Jade и Jadetex должны быть установлены перед этими пакетами. Эта секция рассказывает о новом методе написания LDP документации, используя DocBook 3.1 DTD. Мы расскажем о том как получить,установить и использовать утилиты, а также о тэгах DocBook. Так как существует более 300 DocBook тэгов, мы естественно не сможем описать все их здесь. По настоящему заинтересованные читатели могут зайти на http://www.docbook.org для получения более подробной информации. Если вы новичок в LDP и хотите взять одно из брошенных HOWTO или написать новый HOWTO/mini-HOWTO документ, то вам необходимо связаться с координатором HOWTO ldp-discuss@lists.linuxdoc.org. Это необходимо, чтобы координатор знал,кто работает над данной документацией. Также заметьте, что все HOWTO должны быть в SGML формате, с использованием DocBook 3.1 DTD. Если это mini-HOWTO, то вы можете использовать как SGML так и HTML форматы, но только SGML-форматированные документы будут включены в печатные версии HOWTO. LDP включает два набора HOWTO. Большие HOWTO всегда написаны в формате SGML (DocBook или LinuxDoc, но DocBook предпочтителен). HOWTO обычно более масштабны и длинее чем две или три печатных страницы. Mini-HOWTO меньше по размеру, могут быть опубликованы в формате SGML или HTML,и занимают две - три печатных страницы. Если вы хотите принять участие в работе LDP, то существует несколько листов рассылки, на которые вы можете подписаться. Первый - это ldp-discuss@lists.linuxdoc.org, это главная дискуссионная группа LDP. Для того, чтобы подписаться, пошлите сообщение с темой "subscribe" по адресу: ldp-discuss-request@lists.linuxdoc.org. Для отказа от подписки, пошлите сообщение с темой "unsubscribe" по тому-же адресу. Это "быстрый и грязный" путь, который должен работать независимо от того, какой дистрибутив вы используете. Создайте базовую директорию где вы будете хранить все необходимое. Например: /usr/local/sgml. Далее по тексту мы будем называть её $_toolroot. Установите Jade, DocBook DTD, и DSSSL, так чтобы базовой директорией всех их была $_toolroot (создав $_toolroot/jade-1.2.1, $_toolroot/dtd, $_toolroot/dssl) Вам нужно установить переменную окружения SGML_CATALOG_FILES указывающую на каталоги которые находятся в $_toolroot. Вы можете сделать это с помощью следующей команды: $ENV{'SGML_CATALOG_FILES'} = “$_toolroot/dtd/docbook.cat;$_toolroot/dsssl/docbook/catalog;$_toolroot/jade-1.2.1/dsssl/catalog” Теперь вы готовы к использованию Jade. Чтобы создать отдельные HTML файлы: $_toolroot/jade-1.2.1/jade/jade -t sgml -i html -d $_toolroot/dsssl/docbook/html/docbook.dsl howto.sgml Чтобы создать один большой HTML файл,добавьте -V nochunks в приведенную выше команду. Вам понадобятся sgmltools версии 2.x для использования с DocBook. Так как все бэк-энд программы также сменились, вам придется забыть о программах типа sgml2xxx. А так как с большинством дистрибутивов поставляются sgml 1.x, вам придется удалить пакет sgml 1.x и установить CVS версию или версию 2.0. Чтобы получить последнюю версию CVS кода,вы можете использовать следующие команды. CVSROOT=:pserver:cvs@cvs.sgmltools.org:/home/cvs export CVSROOT cvs login cvs -z6 get sgmltools Пароль для CVS - 'cvs'. Загрузив исходный код, вы можете использовать ./compile make make install чтобы установить sgmltools. Для Red Hat (или основанных на них) систем вы можете использовать команду rpmfind чтобы получить последнюю версию sgmltools. Эту программу можно найти по адресу http://www.rpmfind.net/. Убедитесь в том, что вы скачали именно sgmltools а не sgml-tools, т.к. последний - это sgmltools версии 1.0.9. Для систем базирующихся на Debian, используйте apt-get, чтобы получить нужный вам пакет: # apt-get install sgmltools Также как и в случае с RedHat, убедитесь, что скачали sgmltools а не sgml-tools. Эти утилиты поставляются с дистрибутивом Red Hat 6.2. Убедитесь,что установлены следующие пакеты: sgml-common docbook stylesheets Последнии версии всегда доступны на сайте RedHat: http://www.redhat.com/support/errata/RHBA-2000022-01.html. Загрузите/возьмите/утяните RPMки на вашу машину и установите как обычно (станьте root и дайте команду rpm -Uvh имя_файла). Установив соответвующие RPM пакеты вы можете использовать следующие команды, для визуализации DocBook: db2html имя_файла Визуализирует DocBook в HTML. Будет создана поддиректория с именем имя_файла (минус расширение .sgml), в которой будут размещены HTML файлы. db2pdf имя_файла Визуализирует DocBook в PDF файл. Большая часть этого вопроса освещена в документе Jorge Godoy "Using DocBook". Если вас это интересует, то вы можете прочесть о написании DocBook документов с помощью вашего любимого текстового редактора, по адресу: http://metalab.unc.edu/godoy/using-docbook/using-docbook.html. Начать писать новое HOWTO с помощью LyX очень просто. Используйте команду меню File->New from template..., чтобы вызвать на экран список шаблонов. Выберите Templates на правой части экрана, затем выберите docbook_template.lyx в списке файлов. Нажмите OK и вы получите новый документ. Заполните такие вещи как заголовок,краткое описание и имя автора, и приступайте к написанию документа. Если у вас уже есть LyX, TeX, или текстовый документ, вы можете импортировать его в LyX с помощью команды File->import. Импортировав файл, идите в Layout->Document... . В появившемся окне, под Style, выберите SGML (DocBook Article). Вас спросят хотите ли вы конвертировать весь текст, ответьте "Yes". Вам потребуется изменить большую часть тэгов, но это довольно простое дело: выделяйте текст и изменяйте стиль.Для многих Lyx функций существуют горячие клавиши, они помогут вам сделать это быстрее. Написав документ или конвертировав его, сохраните его в формате LyX. Это позволит вам легко редактировать следующие версии. Затем идите в File->Export->as DocBook..., и файл будет экспортирован в DocBook. Если у вас установлен один из новых дистрибутивов, у вас уже должен быть установлен PSGML для использования с Emacs. Чтобы проверить, запустите Emacs и взгляните на документацию по PSGML (C-h i m psgml). Далее, мы будем считать, что у вас установлена новая версия PSGML для использования с новый версией GNU Emacs. Если это слишком краткие инструкции для вас, просмотрите бесплатную главу из книги Bob Ducharme's SGML CD book: http://www.snee.com/bob/sgmlfree/. Если вы хотите, чтобы GNU Emacs входил в PSGML режим, когда вы открываете .sgml файл и был готов к редактированию SGML, убедитесь, что PSGML может найти DocBook DTD. Если ваш дистрибутив уже имеет поддержку PSGML для GNU Emacs,вам скорее всего ничего не придеться делать, чтобы заставить это работать как надо. Иначе, вам будет нужно установить переменную окружения, которая сообщит PSGML, где находится SGML catalog (список DTD). Например: bash$ export SGML_CATALOG_FILES=/usr/lib/sgml/catalog Затем добавьте что нибудь в этом духе в ваш .emacs файл. ;; ******************************************************************* ;; set up psgml mode... ;; use psgml-mode instead of emacs native sgml-mode ;; (autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t ) (setq auto-mode-alist (append (list '("\\.sgm$" . sgml-mode) '("\\.sgml$" . sgml-mode)) auto-mode-alist)) ;; set some psgml variables (setq sgml-auto-activate-dtd t) (setq sgml-omittag-transparent t) (setq sgml-balanced-tag-edit t) (setq sgml-auto-insert-required-elements t) (setq sgml-live-element-indicator t) (setq sgml-indent-step nil) ;; create faces to assign to markup categories (make-face 'sgml-comment-face) (make-face 'sgml-start-tag-face) (make-face 'sgml-end-tag-face) (make-face 'sgml-entity-face) (make-face 'sgml-doctype-face) ; DOCTYPE data (make-face 'sgml-ignored-face) ; data ignored by PSGML (make-face 'sgml-ms-start-face) ; marked sections start (make-face 'sgml-ms-end-face) ; end of marked sections (make-face 'sgml-pi-face) ; processing instructions (make-face 'sgml-sgml-face) ; the SGML declaration (make-face 'sgml-shortref-face) ; short references ;; view a list of available colors with the emacs-lisp command: ;; ;; list-colors-display ;; ;; please assign your own groovy colors, because these are pretty bad (set-face-foreground 'sgml-comment-face "coral") ;(set-face-background 'sgml-comment-face "cornflowerblue") (set-face-foreground 'sgml-start-tag-face "slateblue") ;(set-face-background 'sgml-start-tag-face "cornflowerblue") (set-face-foreground 'sgml-end-tag-face "slateblue") ;(set-face-background 'sgml-end-tag-face "cornflowerblue") (set-face-foreground 'sgml-entity-face "lavender") ;(set-face-background 'sgml-entity-face "cornflowerblue") (set-face-foreground 'sgml-doctype-face "lavender") ;(set-face-background 'sgml-doctype-face "cornflowerblue") (set-face-foreground 'sgml-ignored-face "cornflowerblue") ;(set-face-background 'sgml-ignored-face "cornflowerblue") (set-face-foreground 'sgml-ms-start-face "coral") ;(set-face-background 'sgml-ms-start-face "cornflowerblue") (set-face-foreground 'sgml-ms-end-face "coral") ;(set-face-background 'sgml-ms-end-face "cornflowerblue") (set-face-foreground 'sgml-pi-face "coral") ;(set-face-background 'sgml-pi-face "cornflowerblue") (set-face-foreground 'sgml-sgml-face "coral") ;(set-face-background 'sgml-sgml-face "cornflowerblue") (set-face-foreground 'sgml-shortref-face "coral") ;(set-face-background 'sgml-shortref-face "cornflowerblue") ;; assign faces to markup categories (setq sgml-markup-faces '((comment . sgml-comment-face) (start-tag . sgml-start-tag-face) (end-tag . sgml-end-tag-face) (entity . sgml-entity-face) (doctype . sgml-doctype-face) (ignored . sgml-ignored-face) (ms-start . sgml-ms-start-face) (ms-end . sgml-ms-end-face) (pi . sgml-pi-face) (sgml . sgml-sgml-face) (shortref . sgml-shortref-face))) ;; tell PSGML to pay attention to face settings (setq sgml-set-face t) ;; ...done setting up psgml-mode. ;; ******************************************************************* Затем перезапустите Emacs. Попробуйте следующий тест. Создайте новый файл, например /tmp/test.sgml,и введите следующее. ]> ]]> Введите C-c C-p.Если Emacs использует ваше DTD, вы увидите Parsing prolog...done в мини-буфере. Попробуйте нажать C-c C-e RETURN, чтобы вставить элемент <test>. Если все работает правильно вы увидите следующее: ]> ]]> Создайте новый файл для вашего HOWTO и введите следующее: ]]> Введите C-c C-p и задержите дыхание :) . Если все прошло как планировалось, то через несколько секунд вы увидите Parsing prolog...done в мини-буфере. Теперь введите C-c C-e RETURN, чтобы вставить <article> элемент и продолжайте написание вашего HOWTO. Смотрите "Nik Clayton's primer for FreeBSD documentation": http://www.freebsd.org/tutorials/docproj-primer/psgml-mode.html В этой секции описывается как начать писать вашу собственную LDP документацию. Установка и настройка утилит, связь с LDP и распространение ваших знаний всем пользователям Линукс. Если вы новичок в LDP и хотите взять одно из брошенных HOWTO, или написать новый HOWTO/mini-HOWTO документ, то вам необходимо связаться с координатором HOWTO ldp-discuss@lists.linuxdoc.org. Это необходимо, чтобы координатор знал,кто работает над данной документацией. Также заметьте, что все HOWTO должны быть в SGML формате, с использованием DocBook 3.1 DTD. Если это mini-HOWTO, то вы можете использовать как SGML так и HTML форматы, но только SGML-форматированные документы будут включены в печатные версии HOWTO. Если вы хотите принять участие в работе LDP, то существует несколько листов рассылки, на которые вы можете подписаться. Первый - ldp-discuss@lists.linuxdoc.org, это главная дискуссионная группа LDP. Для того, чтобы подписаться пошлите сообщение с темой "subscribe" по адресу :ldp-discuss-request@lists.linuxdoc.org. Для отказа от подписки, пошлите сообщение с темой "unsubscribe" по тому-же адресу. Загрузите пакет sgmltools по адресу http://www.sgmltools.org/, или возьмите его из вашего дистрибутива. Пакеты на sgmltools.org содержат исходный код, так что вам придется скомпилировать их для вашей системы. Использование скомпилированных пакетов для вашего дистрибутива проще,т.к. вам не придется компилировать исходные коды и разбираться с возможными ошибками в ходе компиляции (если вы не программист конечно). Sgmltools включены в новые версии RedHat. Если нет, вы можете загрузить соответвующие пакеты с ftp.redhat.com или с одного из зеркал, как часть основного дистрибутива. Если вы используете Debian (пакет с sgmltools также включен в новые версии), вы можете использовать команду apt-get, чтобы загрузить и установить пакет: # apt-get install sgml-tools Узнать больше о пакете для Debian, вы можете по адресу http://www.debian.org/Packages/stable/text/sgml-tools.html. Если вы компилируете пакет из исходников,то вам нужно сделать следующее: # tar -zxvf sgmltools-x.x.x.tar.gz # cd sgmltools-x.x.x # ./configure # make # make install Замените sgmltools-x.x.x на номер версии, которую вы используете. На момент написания последней версией использующей LinuxDoc была версия 1.0.9. Версия поддерживающая DocBook это 2.0.2. Обе этих версии доступны на указанном выше сайте. Установив эти утилиты,вы получите в своё распоряжение следующие команды: sgmlcheck file.sgml- Checks the syntax of a given document. sgmlcheck file.sgml- Проверит синтаксис заданного документа. sgml2html file.sgml- Визуализирует SGML файл в HTML. Создает file.html который содержит Оглавление, затем создает file-x.html файлы, где x это номер секции. sgml2rtf file.sgml- Конвертирует SGML файл в Rich Text Format (RTF). Создает два файла, первый - это file.rtf содержащий оглавление, и файл file-0.rtf,который содержит все секции. sgml2txt file.sgml- Конвертирует SGML файл в ASCII текст. Оглавление и все секции помещаются в файл file.txt. sgml2info file.sgml- Конвертирует SGML файл в формат INFO, используемый командой info. Весь документ будет помещен в file.info. sgml2latex file.sgml- Конвертирует SGML в TeX. sgml2lyx file.sgml- Конвертирует SGML в формат фронт-енд редактора LyX. Это поможет вам конвертировать уже существующие SGML файлы для использования с LyX. Как и в случае с HTML, вы можете писать SGML документы вручную, если знаете все необходимые управляющие коды. В качестве пособия для начинающего вполне может быть использован и этот документ, в SGML формате (сайт с которого можно скачать его, указан в секции "Введение"). Т.к. SGML может обрабатываться различно, в зависимости от формата создаваемого файла, я постараюсь перечислить некоторые вещи, которые пригодятся вам в процессе написания документов. Чтобы начать писать новый документ, создайте новый документ в вашем любимом ASCII редакторе и начните его с этого: <!doctype linuxdoc system>. Эта запись определяет тип документа (LinuxDoc в данном случае), который использует SGML процессор при визуализации документа в выходной формат. Сам этот тэг не визуализируется. После этого вам необходимо ограничить ваш документ тэгами <article> и </article>. Это означает начало содержимого (статьи). Если вы знакомы с HTML, то вы можете представить это как ограничение вашего документа тэгами <html> и </html>. Документ должен начинаться с информации о его содержании. Это похоже на несколько первых страниц книги, где находиться заглавная страница (название работы, имя автора, дата публикации, оглавление, и тому подобное). Название документа заключено в тэги <title> и </title>. Автор указывается с помощью тэгов <author> и </author>. Дата с помощью <date> и </date>. Следующие два информационных поля это <abstract> и </abstract>, которые кратко описывают содержание документа, и тэг <toc>, который указывает куда нужно поместить оглавление. Оглавление автоматически генерируется SGML процессором. О секциях мы расскажем далее. А сейчас давайте посмотрим, как это выглядит все вместе. Возьмем фрагмент SGML кода (который использовался при создании этого документа): <!doctype linuxdoc system> <!-- LinuxDoc file was created by LyX 1.0 (C) 1995-1999 by <markk> Tue Dec 14 15:24:03 1999--> <article> <title>HOWTO HOWTO </title> <author>Mark F. Komarinski </author> <date>v1.1, 14 Декабрь 1999 </date> <abstract>Здесь перечислены утилиты, процедуры, и советы, призванные помочь авторам HOWTO ускорить их написание. </abstract> <toc> Этот фрагмент кода создает главную страницу документа,которую вы видите, когда вы просматриваете документ в RTF или HTML форматах, и размещает на ней оглавление. Чтобы создать оглавление, документ должен содержать некоторую информацию. Секции в случае с SGML, это все равно,что главы в традиционной печати. Документ обычно состоит из множества секций, каждая из секций содержит под-секции, которые в свою очередь могут содержать свои под-секции и так далее. Полезно начать свой документ с описания секций, так как это позволит вам выделить основные темы, которые будет покрывать ваш документ. Затем вы можете разбивать эти секции на более мелкие,пока не получите фрагменты, которые будут содержать всего несколько параграфов. При написании этого документа, я начал свою работу именно так. Секции - это одни из немногих SGML тэгов, которые не надо закрывать. То есть, не существует тэга </sect>. Также вам не нужно думать о нумерации. SGML процессор сам позаботиться о ней, когда вы будете визуализировать SGML во что нибудь другое. Секции начинаются с тэга <sect>. Каждый <sect> тэг, означает начало новой секции. Первая секции носит номер 1. Под-секции (например 1.1) создаются с помощью тэга <sect1>. Нумерации под-секций также начинается с единицы. Под-секции под-секций (1.1.1) создаются с помощью тэгов <sect2>, и также нумеруются начиная с 1.Когда SGML процессор встречает тэг <toc>, он просматривает остальной документ и создает оглавление, основываясь на количестве тэгов секций, найденных в документе. Секции перечисляются и нумеруются в оглавлении и затем используются в остальном документе. Под-секции (1.1.1) не перечисляются в оглавлении, но, если возможно, выделяются в тексте. Создание параграфов текста, очень похоже на то, как это делается в HTML. Используйте тэг <p>, для указания новой строки и начинайте писать. SGML игнорирует пустые места, такие как символы табуляции, многократные пробелы, и символы новой строки. Когда SGML встречает тэг <p>, он начинает новый параграф. Корректный SGML код должен содержать также и завершающий тэг </p>, в конце параграфа. Иногда вам может понадобится отделить один фрагмент текста от другого. Например, чтобы выделить код или имя команды. Первое (выделение текста) делается с помощью тэгов <em> и </em>. Эффект печатной машинки (второй пример) создается с помощью <tt> и </tt>. В SGML существует два вида списков. Первый это нумерованный список, в котором каждый элемент списка пронумерован (как секции) начиная с единицы. 1. Это первый элемент нумерованного списка. 2. Это второй. 3. Третий. Код приведенного выше списка выглядит как: <enum> <item>Это первый элемент нумерованного списка. <item>Это второй. <item>Третий. </enum> Тэг <enum> открывает нумерованный список. Второй тип списков - не нумерованные, в которых возле каждого элемента стоит звездочка, или кружок, или точка, либо существует какое то еще выделение элементов. Это первый элемент не нумерованного списка Это второй Третий Вот как выглядит SGML код этого списка. <itemize> <item>Это первый элемент не нумерованного списка <item>Это второй <item>Третий </itemize> Как вы можете видеть, тэг <item> одинаков для нумерованных и не нумерованных списков. Третья форма списков - это описательные списки. Они состоят из терминов и соответвующие им описаний. LDP The Linux Documentation Project SGML Standard Generalized Markup Language. Код для этого примера выглядит так: <descrip> <tag>LDP</tag>The Linux Documentation Project <tag>SGML</tag>Standard Generalized Markup Language </descrip> Это не совсем как для нумерованных или не нумерованных списков, но весь список также окружен общим тэгами (<descrip> и </descrip>) а определяемые слова заключены в <tag> и </tag>. Остаток строки рассматривается как описание предшествующего термина. Иногда нужно заставить текст выглядеть точно так, как он набран. Для этого вы можете использовать тэги <verb> и </verb>, чтобы определить неформатируемый параграф. Пробелы, возвраты строки, и другой текст (включая специальные символы) будут отображены так как они были набраны, вплоть до закрывающего тэга </verb>. Это неформатированный текст. SGML также поддерживает Универсальные указатели ресурсов (URL), любого типа. Правда работать они будут только при визуализации в HTML, но другие форматы также могут использовать их тем или иным способом. URL не имеет завершающего тэга, т.к сама информация размещена внутри тэга <url>. Этот URL указывает на домашнюю страницу LDP : http://www.linuxdoc.org/. А это его SGML код: <url url="http://www.linuxdoc.org/" name="http://www.linuxdoc.org/"> Параметр url=\"{}http://www.linuxdoc.org/\"{}, указывает браузеру куда направится по этой ссылке, в то время как параметр name=\"{}http://www.linuxdoc.org/\"{}, говорит браузеру о том как отобразить ссылку на экране. В данном случае они совпадают, но можно создать URL тэг выглядящий так: <url url="http://www.linuxdoc.org/" name="LDP"> В визуализированной форме это будет выглядеть как: LDP. Хотя обычно, более корректно указывать URL в качестве имени. Так как при визуализации в Text или RTF, преведущий тэг потеряет своё значение и пользователь не узнает какой URL использовать. В то время как URLы являются великолепным способом сослаться на внешний документ, они не удобны для создания ссылок на информацию внутри самого документа. Для таких ссылок нужно использовать тэги <label> и <ref>. Тэг <label> указывает точку в документе, на которую впоследствии можно ссылаться (метку). Создать <label> просто. Найдите точку на которую вы будете ссылаться в дальнейшем, и вставьте возле неё следующее: <label id="Введение"> Все, вы создали метку на которую вы можете ссылаться так: "Введение". В этом документе такая метка размещена в самом начале. После этого, когда вам необходима сослаться на метку (Например: Введение (Здесь)), вам нужно вставить следующий фрагмент SGML кода в документ: <ref id="Введение" name="Здесь"> и SGML процессор разместит в нужном месте метку с именем "Здесь" (смотрите выше), которая будет ссылаться на секцию введение. Другое применение ссылок - создание индекса. Так как LDP документация обычно публикуется в печатном виде большой коллекцией, то возникает необходимость создание в конце публикации индекса слов и тем. Как и в HTML вы должны защищать многие не алфавитно-цифровые символы, чтобы SGML процессор не интерпретировал их как SGML код. Здесь приведен список часто использующихся SGML кодов для символов. Более полный список есть в sgmltools User's Guide расположенному по адресу http://www.sgmltools.org/guide/guide.html. Используйте &amp; для символа амперсанда (&) Используйте &lt; для символа "меньше чем" (<) Используйте &gt; для символа "больше чем" (>) Используйте &etago; для символа "меньше чем" + обратный слэш (</) Используйте &dollar; для символа доллар ($) Используйте &num; для символа хэш (#) Используйте &percnt; для символа процент (%) Используйте &tilde; для символа тилда (˜) Используйте &quot; и &quot; для кавычек, или &dquot для двойных кавычек. Используйте &shy; для символа дефис (чтобы показать, что в этом месте можно разделить слово при горизонтальном выравнивании). LDP находиться в процессе предоставления CVS доступа авторам. На это есть несколько причин: В CVS всегда будет храниться копия ваших документов. В случае если вы передадите ответственность за свой документ другим авторам, им нужно будет просто получить документ из CVS и продолжить его написание. В случае если вам понадобиться одна из приведущих версий документа, вы всегда сможете получить её. Также CVS будет крайне полезен в случае, если над документом работает несколько человек. Вы сможете узнать какие изменения были сделаны другими авторами и объединить их с вашими. CVS хранит историю изменений. Эту историю (и дату) можно автоматически разместить внутри документа, когда вы используете специальные тэги,обрабатываемые до визуализации документа SGML процессором. C помощью CVS и специальной программы веб сайт LDP может быть автоматически обновлен, когда выкладывается новая документация. Это еще не сделано, но является одной из целей. Если вы никогда не работали с CVS, то вам возможно поможет информация размещенная по следующим адресам. http://www.sourcegear.com/CVS/Docs/blandy https://wroclaw.art.pl/~ser/docs/cvs.html Прежде всего вам необходимо получить аккаунт в CVS репозитарии LDP. Это корневая директория используемая CVS, с различными проектами (HOWTO,mini-HOWTO и т.д.) размещенными в поддиректориях. Вам будет нужно создать зашифрованный пароль и идентификатор пользователя для аккаунта. Зашифрованный пароль можно послать в CVS группу, при этом им не нужно будет знать ваш пароль. Вы можете сделать это с помощью следующих комманд, из bash (или sh): $ echo это_ваш_пароль | perl -e "print crypt(<>, join '',('.', '/', 0..9, 'A'..'Z', 'a'..'z')[rand 64, rand 64]),\"\n\"" Пошлите вывод этой команды вместе с идентификатором пользователя (выберите сами) по адресу cvsadmin@cvslist.linuxdoc.org. Будет создан ваш уникальный CVSROOT и вам будет выслано уведомление по почте. Получив подтверждение, войдите в ваш CVSROOT и убедитесь что все работает правильно: $ export CVSROOT=:pserver:your_userid@cvs.linuxdoc.org:/cvsroot $ cvs -d $CVSROOT login (Замените CVSROOT на то , что было выслано вам по почте). Вас спросят о вашем пароле, и затем вы получите доступ к CVS репозитарию с разрешением на чтение/запись. При первом использовании cvs login и получении доступа к системе, ваш пароль будет сохранен в .cvsroot и вам не придется больше использовать cvs login. Просто установите CVSROOT и продолжайте работу. Вы можете получить весь linuxdoc репозитарий с помощью команды: $ cvs get LDP Или вы можете получить SGML код вашего собственного документа с помощью следующих команд: $ cvs get howto/ВАШЕ-HOWTO.sgml $ cvs get minihowto/ВАШ-ДОКУМЕНТ.sgml Также существует The Commit List, лист рассылки в котором сообщается обо всех изменениях в репозитарии. Будьте осторожны, этот список обладает большим трафиком. Вы можете подписаться послав e-mail по адресу: commits-subscribe@cvslist.linuxdoc.org. Отменить подписку можно послав пустое письмо по адресу commits-unsubscribe@cvslist.linuxdoc.org. Анонимный CVS доступ (только чтение) доступен при помощи следующей команды: $ cvs -d :pserver:cvs@anoncvs.linuxdoc.org:/cvsroot login В качестве пароля используйте cvs. Теперь вы можете получить linuxdoc модули как было показано выше. Заметьте, что изменения в anoncvs сайте могут отставать от основного сайта на полчаса и более. Вы можете получить доступ к CVS репозитарию через веб: http://cvsweb.linuxdoc.org/index.cgi/linuxdoc. Существует несколько графических интерфейсов к CVS, вы можете получить их список по адресу http://freshmeat.net/appindex. Произведите поиск по ключу CVS. CVS имеет специальный тэг, который вы можете использовать для автоматической вставки даты и версии непосредственно в документ. Он выглядит так $Id$. Включив этот тэг в ваш документ вы получите обновление даты, при каждом изменении в документе. Когда вы будете готовы загрузить сделанные вами документы на CVS сервер, используйте команду cvs ci -m "Комментарий" ВАШЕ-HOWTO.sgml. -m "Комментарий" не обязателен, но если вы не включите его, будет запущен ваш любимый текстовый редактор (обычно vi, или редактор на который указывает ваша переменная окружения EDITOR), чтобы вы могли ввести ваш комментарий. Вы можете принять участие в обсуждении CVS в листе ldp-discuss. В настоящий момент, все документы по прежнему нужно посылать по адресу ldp-submit. Перед тем, как вы предложите ваш код миллионам потенциальных читателей, есть несколько вещей, которые нужно сделать. Прежде всего, убедитесь, что вы проверили правописание вашего документа. Большинство утилит, которые используются для написания SGML имеют плагины для проверки орфографии. Если нет, вы всегда можете воспользоваться программой aspell. Во вторых, найдите кого нибудь, кто проверит вашу документацию и сделает комментарии. Документация публикуемая LDP должна быть как можно более корректна, так как её могут прочитать миллионы пользователей Линукс. Если вы являетесь членом какого-нибудь подписного листа, обсуждающего данную проблему, попросите его членов помочь вам. В третьих создайте веб сайт, где вы можете разместить вашу документацию. Это необязательно, но полезно, чтобы люди всегда могли найти оригинальную версию вашего документа. Используя sgmltools, вернее команду nsgmls, вы можете проверить ваш .sgml код на соответвие DTD, чтобы убедиться что он не содержит ошибок. nsgmls -s HOWTO-HOWTO.sgml Если ошибок не встречено, вам просто будет возвращена командная строка. Чтобы ваш документ был принят LDP, он должен быть залицензирован так, чтобы разрешить его свободное (в смысле пива :)) распространение и публикацию. Как автор, вы можете удерживать копирайт и добавлять другие ограничения (например потребовать чтобы работы основанные на вашей или переводы были одобрены вами). Пример лицензии вы можете найти по адресу http://www.linuxdoc.org/COPYRIGHT.html. Если вы выберите полномасштабный копирайт, просто скопируйте его в исходный код в секцию "Copyright and Licenses" или подобную её. Также включите ваш собственный копирайт (так как вы все таки владелец документа). Если вы продолжаете чьё-то HOWTO вы обязаны включить заметки о копирайте приведущих авторов и даты, когда они занимались документом. После того как ваш документ был просмотрен несколькими людьми, и были приняты во внимание их замечания, вы можете опубликовать его в рамках LDP. Пошлите e-mail с SGML кодом в качестве вложения (можете сжать его gzip, если хотите) по адресу ldp-submit@lists.linuxdoc.org. Обязательно включите название вашего HOWTO в строке тема, в теле письма отметьте сделанные изменения и приложите к письму ваше HOWTO. Это позволить людям занимающимся HOWTO, сделать свою работу быстрее и вам не придется ждать, пока ваше HOWTO будет обновлено на веб сайте LDP. Если вы не услышите ничего в течении 7 календарных дней, пошлите письмо, чтобы убедиться, что работа идет. Эта секция описывает некоторые соглашения, которые были приняты LDP, чтобы сделать все LDP документы похожими друг на друга. Вы должны помнить их, когда будете писать документ. Тэг <date> в заголовке вашего документа должен иметь следующий формат: v1.0, 21 Апрель 2000 Самый простой путь - написать документ на какую нибудь тему. Также проверьте брошенные HOWTO, возможно вы знакомы с вопросом освещаемом в одном из них и сможете продолжить его написание. Пожалуйста посмотрите: http://www.linuxdoc.org/COPYRIGHT.html. Заметьте, что это только принципы составления лицензии, для авторов. Свяжитесь с автором документа, или LDP координатором ldp-discuss@lists.linuxdoc.org, расскажите о проблеме и предложите свое решение.