From 1efa6895177866253a7c20603ce44dbfe359881e Mon Sep 17 00:00:00 2001 From: Andrey Zakhvatov Date: Thu, 5 May 2005 10:43:09 +0000 Subject: [PATCH] Initial import, synchronized with English 1.14 Obtained from: The FreeBSD Russian Documentation Project --- .../books/fdp-primer/doc-build/chapter.sgml | 502 ++++++++++++++++++ 1 file changed, 502 insertions(+) create mode 100644 ru_RU.KOI8-R/books/fdp-primer/doc-build/chapter.sgml diff --git a/ru_RU.KOI8-R/books/fdp-primer/doc-build/chapter.sgml b/ru_RU.KOI8-R/books/fdp-primer/doc-build/chapter.sgml new file mode 100644 index 0000000000..d5573b9d44 --- /dev/null +++ b/ru_RU.KOI8-R/books/fdp-primer/doc-build/chapter.sgml @@ -0,0 +1,502 @@ + + + + + + Процесс построения документации + + Главная цель этой главы заключается в четком описании того, + как организован процесс построения документации, а + также как внести изменения в этот процесс. + + После чтения этой главы вы должны: + + + + Знать, что нужно для построения документации FDP, кроме того, что + описано в главе об инструментах для работы с + SGML. + + + + Уметь читать и понимать make-инструкции, + которые присутствуют в файлах Makefile каждого + документа, а также иметь представление о включаемых операциях из + doc.project.mk. + + + + Уметь настраивать процесс построения при помощи + make-переменных и целей + make. + + + + + Набор инструментов для построения документации FreeBSD + + Вот ваши инструменты. Используйте их любым доступным вам + способом. + + + + Основным инструментом построения, который вам понадобится, + является make, и конкретно + Berkeley Make. + + + + Построение пакаджа выполняется утилитой FreeBSD + pkg_create. Если вы не используете + FreeBSD, вы либо обходитесь без пакаджей, либо компилируете исходные + тексты самостоятельно. + + + + gzip нужен для создания + компрессированных версий документа. Компрессия + bzip2 и архивы + zip также поддерживаются. + tar поддерживается, но он требуется при + построении пакаджа. + + + + install является методом, используемым + по умолчанию для установки документации. Однако есть и + альтернативы. + + + + + Сомнительно, что вы не сможете найти последние утилиты, они + отмечены для полноты. + + + + + Понимание make-файлов в дереве документации + + В дереве Проекта Документирования FreeBSD имеется три основных типа + файлов Makefile. + + + + Makefile в + подкаталоге просто передает команды во вложенные каталоги. + + + + Makefile для + документации описывает документ или документы, которые должны быть + получены из этого каталога. + + + + Включаемые + make-файлы являются тем клеем, что + выполняет построение документации, и обычно представлены в виде + файлов + doc.xxx.mk. + + + + + Make-файлы в подкаталоге + + Эти Makefile обычно имеют такой вид: + + SUBDIR =articles +SUBDIR+=books + +COMPAT_SYMLINK = en + +DOC_PREFIX?= ${.CURDIR}/.. +.include "${DOC_PREFIX}/share/mk/doc.project.mk" + + Обзорно, первые четыре непустые строчки задают + make-переменные, SUBDIR, + COMPAT_SYMLINK и + DOC_PREFIX. + + Первая декларация SUBDIR, как и + COMPAT_SYMLINK, показывает, как присваивать значение + переменной, переопределяя все ранее определенные значения. + + Вторая инструкция SUBDIR показывает, как + значение добавляется к текущему значению переменной. Значение + переменной SUBDIR теперь соответствует + articles books. + + Присвоение DOC_PREFIX показывает, как значение + присваивается переменной, но только если оно еще не определено. Это + полезно, если DOC_PREFIX не соответствует тому, что + полагает об этом Makefile - пользователь может + переопределить это значение и дать правильное значение. + + Так что все это значит? SUBDIR определяет, + в какие вложенные подкаталоги должна быть передана работа по + построению. + + COMPAT_SYMLINK касается исключительно + символических ссылок для достижения совместимости (достаточно + удивительно) языков с их официальной кодировкой + (doc/en должна указывать на + en_US.ISO-8859-1). + + DOC_PREFIX является маршрутом к корню дерева + Проекта Документирования FreeBSD. Его не всегда легко найти и легко + переопределить для достижения гибкости. .CURDIR + является встроенной make-переменной, + хранящей путь к текущему каталогу. + + В последней строке включается системный + make-файл + doc.project.mk Проекта Документирования FreeBSD, + доступный всем проектам, который является связующим звеном, + преобразующим эти переменные во встроенные инструкции. + + + + Make-файлы для документации + + Эти make-файлы задают набор + make-переменных, которые описывают, как + построить документацию, расположенную в этом каталоге. + + Вот пример: + + MAINTAINER=nik@FreeBSD.org + +DOC?= book + +FORMATS?= html-split html + +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= + +# SGML content +SRCS= book.sgml + +DOC_PREFIX?= ${.CURDIR}/../../.. + +.include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk" + + Переменная MAINTAINER очень важна. Эта + переменная дает возможность указать владельца документа в Проекте + Документирования FreeBSD, когда вы становитесь ответственным за его + поддержку. + + DOC является именем (предполагается расширение + .sgml) главного документа, создаваемого в этом + каталоге. В SRCS перечисляются все отдельные файлы, + которые составляют документ. Сюда также должны быть включены важные + файлы, изменение которых должно приводить к перестроению. + + FORMATS указывает используемые по умолчанию + форматы, которые применяются при построении этого документа. + INSTALL_COMPRESSED является списком методов + компрессии, которые должны использоваться при построении документа. + INSTALL_ONLY_COMPRESS, пустая по умолчанию, должна + быть непустой, если требуется построить только скомпрессированные + документы. + + + Назначение опциональных переменных обсуждается в + предыдущем разделе. + + + Переменная DOC_PREFIX у включающие директивы + должны быть вам уже известны. + + + + + Включаемые make-файлы Проекта Документирования FreeBSD + + Лучше всего это описывается при обсуждении кода. Вот системные + включаемые файлы: + + + + doc.project.mk является главным включаемым + файлом проекта, который включает все остальные включаемые файлы, по + мере необходимости. + + + + doc.subdir.mk обрабатывает прохождение по + дереву документов в процессе построения и установки. + + + + doc.install.mk содержит переменные, которые + отражаются на правах доступа и установке документов. + + + + doc.docbook.mk включается, если значением + переменной DOCFORMAT является + docbook и установлена переменная + DOC. + + + + + doc.project.mk + + Рассмотрим пример: + + DOCFORMAT?= docbook +MAINTAINER?= doc@FreeBSD.org + +PREFIX?= /usr/local +PRI_LANG?= en_US.ISO8859-1 + +.if defined(DOC) +.if ${DOCFORMAT} == "docbook" +.include "doc.docbook.mk" +.endif +.endif + +.include "doc.subdir.mk" +.include "doc.install.mk" + + + Переменные + + Переменным DOCFORMAT и + MAINTAINER заданы значения по умолчанию, если они + не установлены в make-файле документа. + + PREFIX является каталогом, под которым + установлены инструменты для построения + документации. При обычной установке портов и пакаджей это + /usr/local. + + PRI_LANG должна быть установлена в значение, + соответствующее языку и кодировке, являющейся естественной для тех + пользователей, кому предназначена документация. По умолчанию это + US English. + + + PRI_LANG не влияет на то, какие документы + могут или будут строиться. Ее основное назначение - создание + ссылок на часто упоминаемые документы в корне установки + документации FreeBSD. + + + + + Условия + + Строка .if defined(DOC) является примером + make-условия, которое, как и в других + программах, определяет дальнейшие действия, если какое-то условие + выполняется или нет. defined является функцией, + которая возвращает информацию о том, определена данная переменная или + нет. + + Затем .if ${DOCFORMAT} == "docbook" проверяет, + является ли значением переменной DOCFORMAT + "docbook", и в этом случае включается файл + doc.docbook.mk. + + Две строки .endif закрывают два вышестоящих + условия, отмечая конец их действия. + + + + + doc.subdir.mk + + Этот файл слишком долго описывать на примерах, вы сможете + разобраться с ним сами на основе знаний, полученных из предыдущих глав + и некоторой вспомогательной информации, дающейся здесь. + + + Переменные + + + + SUBDIR представляет из себя список + подкаталогов, которые должны быть охвачены процессом + построения. + + + + ROOT_SYMLINKS является именами каталогов, + которые должны указывать на корень установки документа + от их действительных положений, если текущий язык является + основным (что задается переменной + PRI_LANG). + + + + COMPAT_SYMLINK описано в разделе о + make-файле подкаталога. + + + + + + Цели и макросы + + Зависимости описываются парами + target: + dependency1 dependency2 ..., и + когда вам нужно построить target, вам необходимо + сначала построить список зависимостей. + + После описательной пары могут следовать инструкции о том, как + построить цель, если процесс преобразования цели к зависимостям ранее + не был определен, или если это конкретное преобразование не совпадает + с применяемым по умолчанию методом. + + Особая зависимость .USE задает эквивалент + макроса. + +_SUBDIRUSE: .USE +.for entry in ${SUBDIR} + @${ECHO} "===> ${DIRPRFX}${entry}" + @(cd ${.CURDIR}/${entry} && \ + ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ ) +.endfor + + В вышеприведенном фрагменте _SUBDIRUSE + теперь является макросом, который будет выполнять заданные команды, + если задан в списке зависимостей. + + Что отличает этот макрос от других целей? В основном то, что + он выполняется после инструкций, данных в + процедуре построения, в качестве зависимости для которой он + перечислен, и это не влияет на .TARGET, которая + является переменной, содержащей название текущей выполняемой + цели. + +clean: _SUBDIRUSE + rm -f ${CLEANFILES} + + В вышеприведенном фрагменте clean будет + использовать макрос _SUBDIRUSE после того, + как выполнит инструкцию rm -f ${CLEANFILES}. В + результате это приведет к тому, что clean + будет углубляться по дереву каталогов, удаляя файлы после перехода + ниже, а не на пути назад. + + + Предопределенные цели + + + + Цели install и + package обе переходят вниз по дереву + каталогов, вызывая собственные выполняющие реальную работу + версии в подкаталогах. (realinstall + и realpackage соответственно) + + + + clean удаляет файлы, созданные в + процессе построения (и тоже переходит вниз по дереву + каталогов). cleandir делает то же + самое и также удаляет каталог, если он есть. + + + + + + + Подробности об условиях + + + + exists является еще одной функцией + условия, которая возвращает истину, если указанный файл + существует. + + + + empty возвращает истину, если данная + переменная имеет пустое значение. + + + + target возвращает истину, если указанная + цель еще не существует. + + + + + + Циклы в make (.for) + + .for дает способ повторить набор инструкций + для каждого элемента списка, заданного в переменной через пробел. Он + делает это, присваивая переменной значение текущего элемента + перебираемого списка. + +_SUBDIRUSE: .USE +.for entry in ${SUBDIR} + @${ECHO} "===> ${DIRPRFX}${entry}" + @(cd ${.CURDIR}/${entry} && \ + ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ ) +.endfor + + В примере выше если переменная SUBDIR пуста, + то не предпринимается никаких действий; если она состоит из одного + или более элементов, то инструкции между .for и + .endfor будут повторены для каждого элемента, + причем entry будет заменена значением текущего + элемента. + + + + + + +