Технология единого источника в технической документации

Принцип единого источника в технической документации: вопросы, практические аспекты применения, советы по использованию при разработке ПО и не только.

Автоматизация разработки и сборки технической документации. Рассматриваются: Docbook, DITA, TEI и др. Инструменты: XSL, FOP, PDF, PostScript и др.

Вы не вошли.

#1 14-04-2016 20:54:52

Лэйнариус
Участник
Зарегистрирован: 14-04-2016
Сообщений: 14

Настройка "согласованность содержимого"

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

Прошу, описать как сделать в Serna подрузку данные из одного файла в другой.

Не в сети

#2 14-04-2016 21:05:02

eduardtibet
Administrator
Откуда Saint Petersburg, Russia
Зарегистрирован: 26-09-2015
Сообщений: 26
Сайт

Re: Настройка "согласованность содержимого"

1. Вам надо понять, что функции самого формата и функции реализации этого в конкретных редакторах могут существенно отличаться.

2. Конкретно по Serne не отвечу, т.к. у нее могут быть разные механизмы реализации включений.

3. Я набросаю пример и размещу ссылку здесь. Вы его загрузите (это 3 xml-файла), откроете их у себя в Serna и посмотрите. Также рекомендую посмотреть это любом в текстовом редакторе, чтобы понять логику. Также вы можете воспользоваться бесплатным XMLMind (достаточно старым, но рабочим) отсюда: http://www.xmlmind.com/archive/xmleditor/3.5.2/

P.S. Просто следите за обновлением этого топика.

Не в сети

#3 14-04-2016 21:19:33

eduardtibet
Administrator
Откуда Saint Petersburg, Russia
Зарегистрирован: 26-09-2015
Сообщений: 26
Сайт

Re: Настройка "согласованность содержимого"

1. Скачайте архив с тремя файлами Docbook (v.4.5): ftp://ftp.singlesourcing.ru/forum_files … in_doc.zip

2. Распакуйте, попробуйте открыть в Серне main_*

3. Попробуйте изменить common_*  и обновите в Серне. Содержимое двух main_* файлов должно обновиться.

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

P.S. Как в серне делать подобные документы - я не в курсе (т.е. я не знаю функционала Серны в части создания included doc). Если будет время, то могу посмотреть, но:

- у меня ее нет.

- это будет в течении некоторого времени.

Не в сети

#4 14-04-2016 21:21:08

Лэйнариус
Участник
Зарегистрирован: 14-04-2016
Сообщений: 14

Re: Настройка "согласованность содержимого"

Спасибо скачал.

Странный сайт, поэтому буду вести свой мануал по Syntext Serna тут https://vk.com/topic-51822925_33715296

Изменено Лэйнариус (14-04-2016 21:37:48)

Не в сети

#5 14-04-2016 21:48:20

Лэйнариус
Участник
Зарегистрирован: 14-04-2016
Сообщений: 14

Re: Настройка "согласованность содержимого"

Сразу не заработало, пришлось в файлах main_document_* внести изменения.

    <xi:include href="common_document.xml"
                xmlns:xi="http://www.w3.org/2001/XInclude"
                xpointer="element(common_section)" />

на

    <xi:include href="common_document.xml"
                xmlns:xi="http://www.w3.org/2001/XInclude"
                xpointer="common_section" />

когда изменяется, common_document.xml, Syntext Serna , выдаёт диалоговое окно на обновление страниц main_document_* (в случае их открытия в Serna ).

Вообщем всё хорошо, только интересно как сделать стиль подсветка кода?


Тест BBcode

Изменено eduardtibet (14-04-2016 21:59:45)

Не в сети

#6 14-04-2016 21:55:24

eduardtibet
Administrator
Откуда Saint Petersburg, Russia
Зарегистрирован: 26-09-2015
Сообщений: 26
Сайт

Re: Настройка "согласованность содержимого"

Судя по всему, это особенности реализации xpointer в каждом редакторе.

Ну, если следовать стандарту, то правильный - первый вариант. Т.к. в общем случае (без использования id) он может выглядеть, как:

xpointer="element(/1/3)

Не в сети

#7 14-04-2016 22:01:59

eduardtibet
Administrator
Откуда Saint Petersburg, Russia
Зарегистрирован: 26-09-2015
Сообщений: 26
Сайт

Re: Настройка "согласованность содержимого"

Лэйнариус пишет:

Вообщем всё хорошо, только интересно как сделать стиль подсветка кода?

Вы должны различать содержимое (содержание) и представление.

Это две разные вещи.

Как правило, подсветка кода делается при представлении (например, с помощью вот этой штуки: http://xslthl.sourceforge.net/ )

Как она делается при создании содержимого (контента) - зависит от редактора. Т.к. на уровне содержимого xml присутствует лишь разметка семантической структуры:

<screen language="ini">
# To enable JBOSS startup, remove or comment this variable
#JBOSS_NOT_STARTED=1</screen>

Не в сети

#8 14-04-2016 22:22:17

Лэйнариус
Участник
Зарегистрирован: 14-04-2016
Сообщений: 14

Re: Настройка "согласованность содержимого"

Печаль, буду без подсветки кода, спасибо.

Не в сети

#9 14-04-2016 23:03:43

Лэйнариус
Участник
Зарегистрирован: 14-04-2016
Сообщений: 14

Re: Настройка "согласованность содержимого"

Ещё вопрос, есть элемент пронумерованного/маркированного списка.

<orderedlist>
      <listitem>
        </para>
      </listitem>
      <listitem>
        </para>
      </listitem>
      <listitem>
        </para>
      </listitem>
</orderedlist>

Как внедрить в текст число элементов(количество listitem) из этого списка.

Изменено Лэйнариус (14-04-2016 23:05:06)

Не в сети

#10 14-04-2016 23:48:44

Лэйнариус
Участник
Зарегистрирован: 14-04-2016
Сообщений: 14

Re: Настройка "согласованность содержимого"

На русском есть документация по элементам(listitem, orderedlist и т.д.) ?
В крайнем случае, дайте пожалуйста ссылку на английскую документацию по списку элементов.

Изменено Лэйнариус (14-04-2016 23:49:20)

Не в сети

#11 15-04-2016 12:58:59

Лэйнариус
Участник
Зарегистрирован: 14-04-2016
Сообщений: 14

Re: Настройка "согласованность содержимого"

Так, тут такое дело, из common_document.xml могут только 1 раз определены атрибуты ID в main_document_*, что бы вилидацию пройти, хотя её можно отключить.
А как сделать, чтоб множество раз определить один атрибуты ID в один файл?

Не в сети

#12 15-04-2016 13:03:54

Лэйнариус
Участник
Зарегистрирован: 14-04-2016
Сообщений: 14

Re: Настройка "согласованность содержимого"

Как сделать, что бы несколько </para> представлялись как одна строчка?

Не в сети

#13 15-04-2016 13:31:39

eduardtibet
Administrator
Откуда Saint Petersburg, Russia
Зарегистрирован: 26-09-2015
Сообщений: 26
Сайт

Re: Настройка "согласованность содержимого"

Так, стоп :)

1. Давайте вы будете писать по принципу: одна тема - один топик. Иначе разобрать потом в треде ответы (какой к чему относится) будет сложно. Договорились?

2. Сначала почитайте общий принципы (на русском)
- здесь: http://singlesourcing.ru/sa/index.html
- и здесь: http://singlesourcing.ru/sw/index.html

Если останутся вопросы, можете задавать (но опять же: отдельная тема/вопрос - отдельный топик).

Спасибо.

Не в сети

#14 15-04-2016 13:33:05

eduardtibet
Administrator
Откуда Saint Petersburg, Russia
Зарегистрирован: 26-09-2015
Сообщений: 26
Сайт

Re: Настройка "согласованность содержимого"

Лэйнариус пишет:

Так, тут такое дело, из common_document.xml могут только 1 раз определены атрибуты ID в main_document_*, что бы вилидацию пройти, хотя её можно отключить.
А как сделать, чтоб множество раз определить один атрибуты ID в один файл?

http://www.sagehill.net/docbookxsl/DuplicateIDs.html

Не в сети

#15 15-04-2016 13:33:24

eduardtibet
Administrator
Откуда Saint Petersburg, Russia
Зарегистрирован: 26-09-2015
Сообщений: 26
Сайт

Re: Настройка "согласованность содержимого"

Лэйнариус пишет:

Как сделать, что бы несколько </para> представлялись как одна строчка?

Вопрос совершенно неясен.

Не в сети

#16 15-04-2016 13:34:04

eduardtibet
Administrator
Откуда Saint Petersburg, Russia
Зарегистрирован: 26-09-2015
Сообщений: 26
Сайт

Re: Настройка "согласованность содержимого"

Лэйнариус пишет:

Ещё вопрос, есть элемент пронумерованного/маркированного списка.

<orderedlist>
      <listitem>
        </para>
      </listitem>
      <listitem>
        </para>
      </listitem>
      <listitem>
        </para>
      </listitem>
</orderedlist>

Как внедрить в текст число элементов(количество listitem) из этого списка.

Вопрос также неясен. Поясните подробнее.

Не в сети

#17 15-04-2016 13:35:15

eduardtibet
Administrator
Откуда Saint Petersburg, Russia
Зарегистрирован: 26-09-2015
Сообщений: 26
Сайт

Re: Настройка "согласованность содержимого"

Лэйнариус пишет:

На русском есть документация по элементам(listitem, orderedlist и т.д.) ?
В крайнем случае, дайте пожалуйста ссылку на английскую документацию по списку элементов.

http://www.docbook.org/tdg/en/html/docbook.html

Не в сети

Подвал раздела

Работает на FluxBB (перевод Laravel.ru)