| Проект Документация за FreeBSD - Учебник за нови участници | ||
|---|---|---|
| Prev | Chapter 6 Структуриране на документи в doc/ | Next |
Тази секция съдържа информация за определени документи на FDP.
Наръчника е написан в съответствие с FreeBSD DocBook разширените DTD.
Наръчника е организиран като DocBook <book> (книга). Разделен е на няколко <part> (части), всяка от които съдържа няколко <chapter>-и (глави). <chapter>-те са подразделени на секции (<sect1>) и подсекции (<sect2>, <sect3>) и т.н.
Повечето от файловете и поддиректориите са в handbook директория.
Note: организацията на Наръчника може да се променя от време на време и този документ може да не е достатъчно актуален. Ако имате въпроси за начина по който е организиран Наръчника, моля свържете се с FreeBSD documentation project mailing list <freebsd-doc@FreeBSD.org>.
Makefile дефинира някои променливи които определят как SGML кода се конвертира към други формати и описва различните файлове от които се състои Наръчника. Също включва стандартния doc.project.mk файл, и описва необходимото за конвертирането на един формат към друг.
Това е основното ниво в Наръчника. То съдържа DOCTYPE декларации също така и елементите описващи структурата на Наръчника.
book.sgml използва параметрични заглавия за зареждане на файлове с .ent разширение. Тези файлове (описвани по-късно) дефинират основни (генерални) озаглавявания използвани в останалата част на Наръчника.
Всяка глава в Наръчника е записана във файл наречен chapter.sgml в различна от останалите глави директория. Всяка директория е именувана според стойността на id атрибута на <chapter> елемент.
Например, ако една от главите съдържа:
<chapter id="kernelconfiguration"> ... </chapter>
тогава ще бъде наречена chapter.sgml в kernelconfiguration директория. Общо взето цялото съдържание на главата ще се съдържа в този файл.
При генерирането на HTML версия на Наръчника, това ще предизвика създаването на kernelconfiguration.html. Това е поради id стойността и няма нищо общо с името на директорията.
В по-раншна версия на Наръчника файловете бяха в една директория с book.sgml и именувани според стойността на id атрибута на <chapter> елемента. Преместването им в различни директории подготвя Наръчника за бъдещи подобрения, като включването на графични файлове във всяка глава. По-добре е всеки графичен файл да бъде в една директория с текста на съответната глава вместо всички текстове и графични файлове в една обща директория. Проблеми с еднакви имена са неизбежни, пък и е много по-лесно да се работи с няколко директории с по няколко файла вместо с една директория с много файлове в нея.
Ако погледнете ще видите, че има няколко директории с chapter.sgml файлове, например basics/chapter.sgml, introduction/chapter.sgml и printing/chapter.sgml.
Important: Главите и/или директориите не трябва да бъдат именувани по начин, който е зависим от подредбата им в Наръчника. Тази подредба може да се променя от време на време когато съдържанието на Наръчника се реорганизира; при тези промени не трябва да се налага преименуване на файлове и директории.
Всеки chapter.sgml файл не трябва да бъде завършен SGML документ. Те не трябва да съдържат техен собствен DOCTYPE ред в началото на файла.
Това не е много добре, т.като така те не могат да бъдат третирани като стандартни SGML файлове и от тях не може директно да се генерират HTML, RTF, PS и други формати. Това принуждава да се генерира целият наръчник всеки път когато се налага да се види резултатът от промени в дори само една глава.
Този и други документи можете да намерите в ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.
За въпроси отностно FreeBSD, прочетете
документацията
преди да попитате в <questions@FreeBSD.org>.
За въпроси отностно този документ, e-mail <doc@FreeBSD.org>.