[docs] on olinking

[Oleg A. Paraschenko]

  Всем привет,

  предлагаю обсудить проблемы, связанные с olink-ссылками.

  Элемент olink позволяет ссылаться на другой документ с помощью ID
другого документа и ID элемента в нём. Стили xsl-docbook разрешают
(resolve) olink-ссылки с помощью базы ссылок.

  Дополнительные сведения на английском:

http://www.sagehill.net/xml/docbookxsl/Olinking.html
http://www.sagehill.net/OlinkExtended.html

  Нынешняя реализация в alt-docs примерно такая:

----------
From: Vitaly Ostanin <vyt на vzljot.ru>
Subject: [docs] Re: Modular documents (was: Cyrillic HOWTO (russian) в xml
- пригодится) Date: Mon, 09 Sep 2002 14:24:23 +0400

.....

Что-то подобное reftex - не знаю пакета, так что не скажу. Но по 
ссылкам ниже описан способ для ссылок между документами (который 
есть в docbook-style-xsl и доведен до работающего состояния в 
последних версиях), суть:

Существует один глобальный XML документ (например, книга) с базой 
ссылок. Его нужно создавать руками, пример без sitemap, он пока 
не понадобится:

targetset.xml

<?xml version="1.0" encoding="windows-1251"?> 
<!DOCTYPE targetset SYSTEM 
"/usr/share/xml/docbook/xsl-stylesheets/common/targetdatabase.dtd" 
> 

<targetset> 
   <document targetdoc="jabber"> 
     <xi:include 
       href="target.db" 
       xmlns:xi="http://www.w3.org/2001/XInclude"/> 
   </document> 
</targetset>

Этот документ объединяет другие базы ссылок для включаемых 
документов (главы). Эти другие базы генерируются стилями при 
обработке всего документа, здесь это только один документ с базой 
ссылок в 'target.db'.

Для создания базы ссылок (для вывода chunked html) документа 
"jabber" можно использовать цель Makefile вроде:

targetdb: 
         xsltproc --xinclude \ 
         --stringparam base.dir $(HTML_DIR)/ \ 
         --stringparam collect.xref.targets only \ 
         --param default.encoding $(HTML_OUT_ENCODING) \ 
         $(STYLES_DIR)/html/chunk.xsl $(XML)

Обратите внимание, что для указания вывода в подкаталог нужно 
использовать
параметр 'base.dir', так опция '-o' с параметром 
'collect.xref.targets'
не работает.

Этот самый параметр может быть:
'no' - не собирать ссылки в базу
'yes' - собирать (вместе с основной обработкой)
'only' - только собирать ссылки.

После создания корневой базы для ссылок и баз для всех включаемых 
документов (в cvs docs, IMHO, будет корневая база и генерируемые 
базы для каждой книги).

Для обработки указанных ссылок (пример указания
<para>
       Доступен раздел <olink targetdoc="jabber" 
       targetptr="admin.network.jabber-server.install"/>. 
</para> 

)
нужно добавлять в параметры
--stringparam target.database.document 
"/home/vyt/devel/jabber/targetset.xml"

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

html-dir: 
         mkdir -p $(HTML_DIR) 
         xsltproc --xinclude \ 
         --stringparam target.database.document 
"/home/vyt/devel/jabber/targetset.xml" \
         --stringparam base.dir $(HTML_DIR)/ \ 
          --stringparam default.encoding $(HTML_OUT_ENCODING) \ 
         $(STYLES_DIR)/html/chunk.xsl $(XML)

Почему всё так запутано и не готово в cvs docs - потому что пока 
никому не понадобилось. Автор всего этого (Bob Stayton из 
Caldera) был предельно любезен, узнав, что кто-то заинтересовался 
<olink> :)

---------

  Далее снова идут мои комментарии.

  В общем, всё правильно, но "всё так запутано", ибо в описании смешано
генерация базы ссылок и использование базы ссылок.


--

Проблема: "компонентность базы ссылок"

  База ссылок состоит из главного файла и модулей. Каждый модуль -- это
список пар (ID, заголовок), полученный некоего документа.

  Для того, чтобы olink-ссылки работали, в базу ссылок должны входить все
модули, соответствующие документам, на которые ведёт ссылка.

  Значит, для создания полной базы ссылок, требуется создать "target.db"
для всех документов, на которые есть ссылки. Это решаемо, но уже сейчас
"всё так запутано", а будет ещё больше.


--

Проблема: "миграция targetdoc"

  Допустим, есть описание jabber (документ "jabber.xml"), который
ссылается на документ "cvs.xml":

<para>
  ... смотрите описание CVS:
  <olink targetdoc="devel.cvs" targetptr="devel.cvs.description"/>. 
</para> 

  Пока всё логично.

  Теперь допустим, что есть документ "admin.xml", который включает в себя
как описание jabber, так и описание cvs. После сборки xinclude получаем:

<para>
  ... смотрите описание CVS:
  <olink targetdoc="devel.cvs" targetptr="devel.cvs.description"/>. 
</para> 

  Формально всё правильно, но с точки зрения здравого смысла лучше иметь
изменённый targetdoc:

<para>
  ... смотрите описание CVS:
  <olink targetdoc="book.admin" targetptr="devel.cvs.description"/>. 
</para> 


--

Проблема: "разветвление функциональности"

  Обработка документов идёт по-разному в зависимости от того, используются
или нет olink-ссылки. Соответственно, в make-файлы надо прописывать либо
"OLINKING := no" или "OLINKING := yes".

  Почти всюду используется "OLINKING := no". Но может случиться так, что
olink-ссылки появятся в документе неожиданно, например, через включаемый
файл. Тогда указание в make-файле будет не совпадать с реальностью.

==

Решение?

  Предлагаю такой подход к обработке olink-ссылок:

* на этапе тюнинга, для каждой olink-ссылки:
    если targetptr указывает на id, существующий в самом документе,
      то olink-ссылка превращается в обычную xref-ссылку
  (для реальных книг, думаю, должно быть в 99.9% случаев);

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

  Достоинства:

* такая схема работает;
* проста в понимании;
* тривиальна в реализации.


  Ваши мнения?


-- 
Oleg