$Id: readme.txt,v 1.7 2008/11/20 18:24:19 ygreks Exp $

Докуменатция к SPF devel
========================

Предлагаю размещать в docs/
Возможно docbook файлы стоит складывать в подкаталог в tools чтобы они не
попадали в дистр, а только уже сгенерированная документация.

Как оформлять форт код
======================
(чтобы получать максимально классную доку автоматом)

Пример:

\ файл определяет слово qua
\ может быть полезен если вам нужно квакание

\ делает то-то и то-то
\ в частности квакает если a1 = a2
: qua ( a1 a2 -- a u )
\ этот коммент тоже попадет в доку
 = IF
 S" qua"
 \ а этот - нет
 ELSE
 S" cant qua" THEN ;

 1. В доку попадут комментарии в начале файла в качестве описания либы
 2. Имена слов которые экспортируются в словарь FORTH (т.е. не скрытые внутри
    MODULE:, т.к. незачем в доке описание внутренних деталей либы)
 3. К этим именам слов :
  - стековая нотация (должна быть на той же строке что и имя слова, в общепринятом виде)
  - строки однострочных комментариев идущие подряд _сразу_ за определением словом
  - строки идущие непосредственно _до_ определения слова

 (4) Возможно стоит сделать :
  - то что в конце файла после \EOF в качестве примера..

Что надо если вы хотите генерировать документацию
=================================================

GNU make <http://mingw.org/download.shtml> <http://www.gnu.org/software/make/>
libxml2, iconv, libxslt <http://www.zlatkovic.com/pub/libxml/>
docbook-xsl <http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608>
docbook-xml <http://www.oasis-open.org/docbook/xml/4.5/docbook-xml-4.5.zip>
rm.exe который понимает список аргументов без запятых и с прямыми слешами - не помню где брал :(
hhc <http://go.microsoft.com/fwlink/?LinkId=14188>

xsltproc make spf и hhc должны запускаться по имени (без указания пути).

Процесс
=======

Генерация доки автоматически
----------------------------

1. Добавить путь к форт-коду в Makefile в переменную forthcode
2. Добавить entity в devel.docbook и вставить ссылку в соотвествующий chapter там же
3. Выполнить make (или make force)

Генерация шаблона для последующего ручного редактирования
---------------------------------------------------------

Из большинства исходников автоматическим образом документации получается очень
мало, поэтому есть два варианта
- если вы автор данной либы - добавить в неё комментариев чтобы получить доку автоматом
- иначе сгенерировать docbook один раз и вручную добить до приемлимого
состояния, используя полученный шаблон.

1. Выполнить make template source=~user/file.f
2. Добавить entity в devel.docbook и вставить ссылку в соотвествующий chapter там же
2a. Проверить что все entity использованы - скриптом check-entities.f
3. Выполнить make (или make force)

На CVS следует коммитить только файлы docbook, которые после генерации
набивались вручную.

Каталоги XML
============

Для того чтобы иметь возможность ссылаться на файлы xsl, dtd не зависимо от
структуры каталогов на конкретной машине введено понятие XML каталогов. В
принципе и без этого будет работать если лень заморачиваться. Только тогда
придётся указать абсолютные пути в Makefile к docbook-xsl скриптам.
Но по-хорошему надо создать переменную окружения XML_CATALOG_FILES
И присвоить ей пути к файлу-каталогу docbook-xsl, схем DTD для
docbook, и к самодельному файлу для xsl, перечисляя через пробел
У меня эти пути -
file:///D:/WORK/docbook/docbook-xsl-1.71.1/catalog.xml
file:///D:/WORK/docbook/docbook-xml-4.5/catalog.xml
file:///D:/WORK/docbook/xslcatalog.xml

Последний файл я создавал сам, он выглядит так

<?xml version="1.0"?>
<!DOCTYPE catalog
   PUBLIC "-//OASIS/DTD Entity Resolution XML Catalog V1.0//EN"
   "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
    <uri
        name="html/docbook.xsl"
        uri="file:///D:/WORK/docbook/docbook-xsl-1.71.1/html/docbook.xsl"/>
    <uri
        name="htmlhelp/htmlhelp.xsl"
        uri="file:///D:/WORK/docbook/docbook-xsl-1.71.1/htmlhelp/htmlhelp.xsl"/>
    <uri
        name="html/chunk.xsl"
        uri="file:///D:/WORK/docbook/docbook-xsl-1.71.1/html/chunk.xsl"/>
</catalog>


Если будут проблемы - определить переменную XML_DEBUG_CATALOG для отладки