Устройство xml файла списка слов

Список слов представляет из себя набор записей, каждая из которых в общем случае может иметь следующий вид:

<List>
    ...
    <article id="899101">
        <wl-name>the Underground</wl-name>
    </article>
    <Level sort="1" type="normal" depth="1">
        <article id="32167">
            <wl-name>the Underground</wl-name>  <!-- ключ сортировки (sortkey) -->
            <wl-name>underground</wl-name>      <!-- заголовок (show) -->
            <alt-name>subway</alt-name>         <!-- альтернативный поисковый ключ -->
            <img url="icon.png" />                <!-- иконка для отображения в списке -->
            <sound url="subway.spx" />            <!-- звуковой файл, привязанный к заголовку -->
            <scene_3d url="some_3d_scene" />
            <video url="some_video.mp4" />
            <id shift="15">32167</id>           <!-- id статьи с текстом перевода -->
        </article>
        ...
        <article id="8675309">
            <wl-name>Reveal</wl-name>
            <id>8675309</id>                    <!-- id записей в другом списке, для формирования выборок -->
            <id>101111</id>
        </article>
        <Level depth="2">
            ...
        </Level>
    </Level>
</List>

• <article> – запись списка слов. Обычно это некий элемент который ссылается на текст статьи (в этом случае его можно считать заголовком) или на другие элементы (в другом словарном списке) – эта привязка осуществляется за счет значения вложенных тегов <id>. Если же после тега <article> идет тег <Level>, группирующий вложенные статьи в папку (описан ниже), то <article> является заголовком этой папки. При этом папка тоже может иметь перевод (открывается на планшете/десктопе по одиночному нажатию; а по двойному – список вложенных элементов), а может не иметь (как в примере). Это более частый вариант, потому что в приложениях для телефонов на экране показывается только список слов без окна перевода. При нажатии на папку есть неопределенность, что открыть: список вложенных элементов или связанную с папкой статью. Разрешением подобной неопределенности обычно занимается логика приложения в рамках конкретного проекта.
  Значение атрибута “id” (он же list entry id) при этом является уникальной в пределах словаря меткой, по которой можно строить взаимосвязи между записями
• <wl-name> – один из связанных с записью смысловых элементов (вариантов написания). Если мы хотим дать краткую характеристику статье (для отображения списка), то необходимо добавить один <wl-name> – сам заголовок. Иногда может добавляться дополнительно часть речи или вещи, влияющие на:
  • расположение этой статьи в списке (ключ для сортировки, который может отличаться от заголовка);
  • поведение при нажатии на заголовок, чтобы открывать статью не сначала, а сразу скроллить в нужное место;

Поскольку<wl-name>-ов у записи может быть несколько, то важно, чтобы у всех записей списка их было одинаковое количество (нужно добавлять пустые <wl-name> там, где значение для данной статьи неизвестно). wl-name может содержать как обычный текст, так и стилизованный (если нужно настроить размер и цвет шрифта, добавить курсив и т.п) – подробнее про это можно почитать в тематической статье. 

• <id> – вложенный в <article> тег <id> служит для создания взаимосвязей, смысл которых основан на типе списка.
  Например, <id> у записи в списке с типом Dictionary есть идентификатор текста-перевода (т.к. сам список Dictionary посвящен переводам); если таких тегов несколько – у заголовка есть несколько разных статей с переводом. Если запись с несколькими <id> находится в списке с типом “FullTextSearch_Headwords”, то она символизирует одно слово, которое мы можем поискать среди заголовков словаря. При этом все его <id> – это идентификаторы записей в других списках, в которых это слово встречается (см.подробнее – в разделе про полнотекстовый поиск). Аналогично (несколько <id> из других списков) может настраиваться линковка записей и не для полнотекстового поиска – (смысл при этом остается схожим – “слово X из списка 1, ссылается на слова Y и Z из списка 2 и слово K из списка 3”)
• Атрибут “shift” – deprecated. Изначально хранил смещение от начала статьи, которое нужно применить при загрузке; единицы измерения смещения интерпретировались на основе ShiftType в FTS настройках списка. Сейчас такой функционал реализуется через метки <label> в тексте статьи и варианте написания.
• <Level> – позволяет группировать вложенные в него записи. Теги можно вкладывать друг в друга и чередовать с обычными статьями, создавая дерево каталогов
  • “depth” содержит значение глубины вложенных в эту папку узлов. Т.е. самый верхний уровень списка можно считать имеющим depth=0, папки верхнего уровня имеют depth=1, вложенные в них – 2 и так далее. Разработчик должен самостоятельно следить за тем, чтобы значение атрибута у вложенных папок увеличивалось
  • “sort” указывает, нужно ли при сборке базы отсортировать статьи внутри этого уровня. Возможные значения – “1” или “y”
  • “type” содержит тип поведения папки при первом отображении – будет она обычной папкой (текст с иконкой, содержимое не видно) или сразу при отрисовке списка нужно видеть содержимое и т.п. Все возможные варианты можно посмотреть здесь.
• <alt-name> – альтернативный заголовок слова; по тексту этого варианта можно будет найти нужную запись, но он не будет отображаться в самом словарном индексе. Поиск будет успешен только в случае ввода полного alt-name’a; по частичному совпадению (например, началу текста) подмотки не будет. Самих тегов <alt-name> у статьи может быть несколько – тогда она будет искаться по любому из них

• <img> – картинка, которую нужно отображать у записи в списке. Используется как для добавления иконок в словарях и разговорниках, так и для создания внешних баз картинок, которые состоят из заголовков-ключей и связанных с ними изображений. В процессе работы приложение заранее узнает ключ-заголовок и по нему вытаскивает картинку для своих нужд. Список поддерживаемых форматов – в описании метаданных-картинок
  Единственный атрибут “url” содержит имя файла добавляемой картинки. Путь к папке, в которой нужно искать файлы, настраивается в списке слов. При этом и само имя файла тоже может содержать путь – это позволяет вместо одной папки с десятками тысяч файлов сделать корневую папку и дать ссылку на нее в настройках списка в sproj , а внутри этой папки создать иерархию подпапок с файлами (и путь к каждому файлу прописывать в <img url=”…” />)
• <sound> – звуковой файл, который проигрывается по нажатию на иконку рядом с заголовком. По аналогии с картинками, звуки иногда встраиваются в саму базу, а иногда создаются отдельные базы “ключ->звук”. Список поддерживаемых форматов – в описании метаданных про звуки
  Атрибут “url” здесь работает так же, как и в случае с<img> (описано выше). При этом при добавлении звука часто есть необходимость предварительно его обработать (а не добавлять .wav as is). Детально предобработка и разметка звуков разобрана здесь