[docs] on olinking

[Alexander Bokovoy]

On Mon, Nov 17, 2003 at 12:00:36AM +0300, Oleg A. Paraschenko wrote:
> Решение?
> 
>   Предлагаю такой подход к обработке olink-ссылок:
> 
> * на этапе тюнинга, для каждой olink-ссылки:
>     если targetptr указывает на id, существующий в самом документе,
>       то olink-ссылка превращается в обычную xref-ссылку
>   (для реальных книг, думаю, должно быть в 99.9% случаев);
> 
> * базу данных ссылок вести вручную (да, именно вручную, никакой
>   автоматики). Учитывая, что межбуквенных ссылок должно быть мало, это
>   не должно быть большой проблемой.
> 
>   Достоинства:
> 
> * такая схема работает;
> * проста в понимании;
> * тривиальна в реализации.
> 
> 
>   Ваши мнения?
Давайте отойдем от того, что есть в CVS docs и рассмотрим другой пример
сильно пересеченного документа и разрезанного на куски документа, в
котором тоже можно было бы применить olinks -- это поможет понять,
насколько тот или иной подход будет адекватен двум (несколько разным)
задачам.

Возьмем в качестве примера smb.conf(5) из документации к Самбе. Это 
335 исходных XML документов, в которых сейчас около 320 взаимных ссылок,
оформленных в виде <link linkend="...."/>. Сами по себе эти linkends не
валидны в исходных документах, поскольку исходные документы по отдельности
не используются -- они все включаются через xinclude в основной документ
(которых в ближайшем будущем будет более одного, с возможным выделением в
подгруппы логически связанных компонент).

В текущей реализации <link linkend="...."/> реально используется только
как ссылка, однако мне думается, что может иметь смысл перейти здесь на
olinks для того, чтобы можно было не перегружать функциональное содержимое
<link/> неимеющими отношение к чистому Docbook XML вещами -- планируется в
описание опций добавлять метаинформацию в виде ссылок на те опции, поведение 
которых меняется при изменении конкретной опции. Думаю, что olinks в этом случае 
будут осмысленным применением, поскольку сами по себе представляют
некоторую ссылочную абстракцию, а функциональное различие можно указывать,
например, при помощи ролевого атрибута (или есть что-нибудь более
пригодное?).

Теперь касательно предложенной схемы. Да, замена targetptr имеет смысл --
на сущность, адекватную результирующему документу, который может быть не
только валидным Docbook XML, но и, например, чистой выборкой
мета-информации. Так что только xref тут не обойтись, но это довольно
простая "проблема", которую ясно как решать.

А вот что касается автоматики, то тут не так все просто. Для больших
ссылающихся друг на друга поддокументов -- как в случае с описаниями опций
smb.conf(5), где каждый XML-файл содержит описание отдельной опции вместе
с мета-информацией о ней и ее зависимостях -- ручное ведение базы ссылок
будет неоправданной тратой. Фактически, оно вернет нас к ситуации, которая
была до перевода smb.conf(5) на Docbook XML и выделения описания опций в
отдельные поддокументы, со всеми вытекающими сложностями в поддержке.

Для примера можно посмотреть, например, 
http://us3.samba.org/samba/ftp/samba-docs-20031411.tar.bz2 (3.3M),
содержимое каталога docbook/smbdotconf/*.
-- 
/ Alexander Bokovoy
Samba Team                      http://www.samba.org/
ALT Linux Team                  http://www.altlinux.org/
Midgard Project Ry              http://www.midgard-project.org/