[docs] Re: on olinking

[Oleg A. Paraschenko]

  Привет,

On Mon, 17 Nov 2003 13:19:30 +0300
Vitaly Ostanin <vyt на vzljot.ru> wrote:

> On Mon, 17 Nov 2003 13:04:53 +0300
> "Oleg A. Paraschenko" <olpa на xmlhack.ru> wrote:
> 
> <skipped/>
> 
> > > >   Для того, чтобы olink-ссылки работали, в базу ссылок
> > > >   должны входить все
> > > > модули, соответствующие документам, на которые ведёт
> > > > ссылка.
> > > 
> > > Нет, так как ссылка должна указывать на объединяющий документ
> > > и id внутри него. То есть, если документ intro из admin хочет
> > > сослаться на id="admin.docs", то в качестве модуля должен
> > > быть указан admin.
> > 
> >   Чего-то я начинаю запутываться. Объясни мне лучше на таком
> >   примере:
> > 
> >   Есть документы:
> > 
> > * $DOCS_ROOT/admin.xml
> > * $DOCS_ROOT/devel/cvs/cvs.xml
> > 
> >   Из "admin.xml" я хочу сослаться на установку cvs, описанную в
> >   "cvs.xml"
> > (id=devel.cvs.install). Известно также, что объединённый
> > "admin.xml" не содержит ни строчки текста из "cvs.xml".
> 
> >   Как в таком случае должна выглядеть olink-ссылка?
> 
> <olink targetdoc="devel" targetptr="devel.cvs.install"/>
> 
> Кстати, targetdoc в общем-то не нужен - только для совместимости
> с DTD DocBook.
> 
> При этом target.database.document=docs.xml
> который включает
> devel.target.db

  Я правильно понимаю, что docs.xml должен выглядеть так:

---------
<!DOCTYPE targetset SYSTEM 
"/usr/share/xml/docbook/xsl-stylesheets/common/targetdatabase.dtd"
>

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

  ?

> 
> > ...
> > 
> > > > 
> > > >   Предлагаю такой подход к обработке olink-ссылок:
> > > > 
> > > > * на этапе тюнинга, для каждой olink-ссылки:
> > > >     если targetptr указывает на id, существующий в самом
> > > >     документе,
> > > >       то olink-ссылка превращается в обычную xref-ссылку
> > > >   (для реальных книг, думаю, должно быть в 99.9% случаев);
> > > 
> > > Зачем?
> > 
> >   Потому что для большинства итоговых документов попадание
> >   должно
> > быть 100%, и тогда пляски с OLINKING=yes, созданием targetsets
> > и прочим убираются.
> 
> Targetsets нужны ещё и для независимой пересборки части
> документации. То есть admin может собираться отдельно от install,
> но содержать ссылки на него.

  Или включать его.

> 
> Наличие битых ссылок нужно проверять в любом случае.
> 
> olink не обязательно преобразовывается в xref - это может быть и 
> link, а дублировать логику работы с olink из оригинальных стилей
> - лишняя работа.

  А ведь действительно -- лишняя работа. Замечание принято. Эта
функциональность должна быть непосредственно в docbook-style-xsl.
Надо будет Бобу написать.

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

  Именно поэтому предлагаю устроить развлечение: я буду придумывать
противоречия и проблемы, а ты объяснять, почему их нет.

> 
> > > >   Достоинства:
> > > > 
> > > > * такая схема работает;
> > > > * проста в понимании;
> > > > * тривиальна в реализации.
> > > > 
> > > > 
> > > >   Ваши мнения?
> > > 
> > > Честно говоря, я не понял, зачем это нужно.
> > 
> >   Если что-то можно упростить без потери функциональности --
> >   это надо упростить.
> > 
> > > В текущем варианте
> > > плохо только то, что использование olink нужно указывать явно
> > > - это исправляется тривиальным стилем по результатам
> > > xinclude.
> > 
> >   тривиальный стиль + тривиальный стиль  + тривиальный стиль +
> >   ...
> 
> Это сарказм? На аргумент не тянет. Кстати, ты сам предлагаешь
> написать тривиальный стиль - для замены olink на xref.
> 
> Что-то не нравится в стилях? В их тривиальности?

  Скорее, я просто не понял, что предлагается. Можно не объяснять.

> 
> > > Чтобы менять семантику olink, нужны веские причины.
> > 
> >   В данном случае семантика уже поменена, ибо сейчас база
> >   olink-ссылок
> > создаётся не из тех документов, в которые ведут ссылки, а из
> > самого документа, из которого ведут ссылки.
> 
> Это не так. База создаётся (должна создаваться) для каждого
> раздела независимо.

  Я правильно понимаю, что на самом деле "для каждого раздела" -- это
"для каждой бумажной книжки"?

> 
> > * Это несколько неочевидно, так как собирать надо не так как
> > сейчас.* Предложенная замена "olink" на "xref" делает явным и
> > понятным, что происходит на самом деле.
> 
> Хорошо, пусть будет замена, но не вместо, а дополнительно к
> текущей схеме - они не конфликтуют. Идёт?

  Нет, ни в коем случае. Две похожие "гениальные" идеи одновременно --
это ужасно. Кроме того, я уже понял, что замену на "xref" надо вводить
в родные стили docbook.

> 
> <skipped/>
> 
> -- 
> Regards, Vyt
> mailto:  vyt на vzljot.ru
> JID:     vyt на vzljot.ru


-- 
Oleg