[docs] Re: on olinking

[Oleg A. Paraschenko]

  Привет,

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

> On Mon, 17 Nov 2003 14:39:11 +0300
> "Oleg A. Paraschenko" <olpa на xmlhack.ru> wrote:
> 
> <skipped/>
> 
> >   Я правильно понимаю, что 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>
> > --------
> > 
> >   ?
> 
> Примерно так.

  Продолжаем мысленный эксперимент. Теперь у нас есть
"DOCS_ROOT/devel/make/make.xml", имеющий внутреннюю olink-ссылку
(обозначим её "O") на "devel.make.install". Оба файла, "admin.xml" и
"devel.xml" через xinclude подхватывают "make.xml", а это значит, что и в
"admin.xml", и в "devel.xml" есть один и тот же элемент "O" с одним и тем
же значением "targetdoc".

  Если в "targetdoc" написано "devel", то обиженным получается "admin";
если в "targetdoc" написано "admin", то обиженным получается "devel".

...

> 
> > > Наличие битых ссылок нужно проверять в любом случае.
> > > 
> > > olink не обязательно преобразовывается в xref - это может
> > > быть и link, а дублировать логику работы с olink из
> > > оригинальных стилей- лишняя работа.
> > 
> >   А ведь действительно -- лишняя работа. Замечание принято. Эта
> > функциональность должна быть непосредственно в
> > docbook-style-xsl. Надо будет Бобу написать.
> 
> Скепсис - раньше DocBook V5 такой функциональности не будет, и
> скорее всего, что не будет вообще. Она не вписывается в идеологию
> DocBook, а локальные фичи предлагается делать через customization
> layers.

  Тут, кажется, дело интереснее, чем локальная фича. Надо доосмыслить, что
происходит и расписать наш use case для olink. Думаю, другим тоже будет
интересно.

...

> > > 
> > > Стремительно, конечно, не будет. Но мне бы не хотелось
> > > допускать то, что потом может оказаться ошибкой дизайна.
> > 
> >   Именно поэтому предлагаю устроить развлечение: я буду
> >   придумывать противоречия и проблемы, а ты объяснять, почему
> >   их нет.
> 
> У меня это развлечение каждый день с 9.30 до 20.00 :) Предлагаю
> лучше снова выбраться в Морфей.

  Не, это далеко и надолго.

> 
> <skipped/>
> 
> > > > > Чтобы менять семантику olink, нужны веские причины.
> > > > 
> > > >   В данном случае семантика уже поменена, ибо сейчас база
> > > >   olink-ссылок
> > > > создаётся не из тех документов, в которые ведут ссылки, а
> > > > из самого документа, из которого ведут ссылки.
> > > 
> > > Это не так. База создаётся (должна создаваться) для каждого
> > > раздела независимо.
> > 
> >   Я правильно понимаю, что на самом деле "для каждого раздела"
> >   -- это "для каждой бумажной книжки"?
> 
> Я имею в виду, что в $CVSROOT есть несколько каталогов с
> документами, разбитыми по тематике - admin, user, install,
> junior. Каждый из них я называю отдельным разделом.
> 
> Готовые книги (бумажные и html-версии) собираются (должны
> собираться) из фрагментов одного или нескольких разделов. Отсюда
> и books/junior-2.2 и т.п.

  Понятно, но возникает другой вопрос. Как будет выглядеть физическое
проявление разделов? Вот имею я книжку, которая в xml ссылается куда-то в
devel. Куда будет указывать эта ссылка из pdf?


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

  На самом деле, я понял решение задачи. Оба подхода замечательно
состыковываются. И получается именно так, как должно быть.

> 
> > Кроме того, я уже понял, что замену на "xref" надо
> > вводить в родные стили docbook.
> 
> Они слишком консервативны. Но попробовать можно :)
> 
> В общем, итог - я против убийства текущей схемы, но не против
> добавления новой.

  Переработанный подход:

* На этапе тюнинга olink-ссылки по возможности заменяются
  на xref или ulink.
* Если теги "olink" остались, то это значит, что в документе есть внешние
  ссылки. Тогда:

+ Документ module-targetset.xml стандартным образом подключает базы данных
  ссылок внешних модулей.

+ В Makefile установлена переменная OLINK_DATABASES, в которой перечислены
  базы данных ссылок внешних модулей, от которых зависит
  "module-targetset.xml", например:

    OLINK_DATABASES := ../devel/devel-targets.olinkdb \
         ../some/where/where-targets.olinkdb

+ make, прежде чем преобразовывать документ в html, fo или ещё что-то,
  проверяет список OLINK_DATABASES и пересоздаёт базы ссылок, если они
  устарели.

  Теперь, вроде бы, всё сходится. Делаю?


  И ещё комментарии.

--

  Если убрать переписывание ссылок во время тюнинга, а в OLINK_DATABASES
добавить базу ссылок собираемого документа (самого себя), то получится в
точности то, что было раньше.

--

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

  Кроме того, судя по примеру в начале письма, заодно решились некоторые
неизвестные пока проблемы.

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


-- 
Oleg