.. _pageformat: Формат хранения страниц ======================= .. contents:: .. _pageformat_intro: Структура дерева заметок ------------------------ При создании программы OutWiker был выбран формат хранения заметок, когда каждая страница представлена папкой в файловой системе с некоторыми служебными файлами. Это решение уменьшает вероятность одновременной порчи всех заметок по сравнению со способом хранением всех заметок в одном файле: если какой-нибудь файл, относящийся к заметке попадет на "битый" сектор жесткого диска, то будет испорчена только эта заметка, а не все дерево заметок. Кроме того, поскольку все записи хранятся в текстовом виде, вы можете просматривать их (а при желании и редактировать) даже не имея под рукой OutWiker. Также такой формат хранения позволяет легко организовать "прикрепленные" к заметке файлы, поэтому OutWiker можно использовать и для каталогизации файлов. Такое хранение заметок подразумевает, что файлы и папки заметок могут быть в любой момент изменены внешними средствами, например, файловыми менеджерами, с помощью них вы можете переносить заметки из одной ветви дерева в другую или даже в другое дерево с заметками, а если вам не хватает возможностей встроенного в OutWiker редактора, то вы можете редактировать заметки с помощью любого текстового редактора, способного открывать и сохранять файлы в кодировке UTF-8, для этого можно воспользоваться плагином ExternalTools_. Однако такой способ хранения, а особенно предположение, что заметки могут изменяться без участия OutWiker, накладывает ряд ограничений. Во-первых, под Windows на данный момент вы ограничены в длине пути до файла, она не может превышать 255 символов (есть пути обхода этого ограничения, возможно, в будущем эта проблема будет преодолена). Во-вторых, поскольку любая заметка может изменяться без участия OutWiker, нет возможности сделать какой-либо кэш с общей информацией обо всех заметках, например, индекс для поиска или информацию о тегах заметок. Поэтому при глобальном поиске приходится каждый раз заново просматривать содержимое каждой заметки, что может занимать достаточно долгое время. Как уже было сказано, каждая заметка - это просто папка с некоторыми служебными файлами внутри другой папки-заметки, поэтому для создания вложенной заметки достаточно создать папку с именем вложенной заметки, а в ней создать два файла: :file:`__page.opt` и :file:`__page.text` (этот файл не нужен для страниц глобального поиска). Формат хранения каждого типа заметок может отличаться, но файл :file:`__page.opt` должен присутствовать всегда, о его формате будет написано :ref:`ниже `. При работе с исходниками OutWiker, например, при создании плагина папки и файлы явно создавать не нужно, для создания заметок и работы с прикрепленными файлами существуют специальные классы внутри API OutWiker (классы, предназначенные для работы со страницами содержатся в файле `src/outwiker/core/tree.py `_. Также в папке с заметкой может храниться значок, установленный для заметки. Файл со значком может записан в различных графических форматах, но рекомендуется использовать формат png. В этом случае файл со значком должен иметь имя :file:`__icon.png`. Изображение значка должно иметь размер 16x16 пикселей и может использовать прозрачность. Чтобы внешний вид заметок не зависел от настроек программы OutWiker на различных компьютерах, файл значков копируется в папку с заметкой. Стиль страниц хранится в файле :file:`__style.html`. Если нужно, в папке :file:`__style` могут находиться дополнительные файлы. Подразумевается, что основные определения стиля хранятся в :file:`__style.html`, а в папке :file:`__style` могут находиться рисунки или скрипты на языке JavaScript, необходимые для отображения стиля. Если для страницы устанавливается стиль по умолчанию, то файл :file:`__style.html` и папка :file:`__style` просто удаляются. .. _pageformat_restriction: Ограничения на имена заметок ---------------------------- На имена заметок накладываются некоторые ограничения. Во-первых, ограничения накладывает файловая система. Если под Linux имя директории не может включать в себя только нулевой символ (\0), а в остальном вы не ограничены, то под Windows вы не можете создать папку (и, соответственно, заметку) с символами >, <, \|, ?, \*, : и ". Если вы работаете под Linux, то при попытке создать заметку, содержащую в имени один из этих символов, вы получите предупреждение, показанное на следующем рисунке, но создать заметку сможете. .. image:: /_static/pageformat/warning.png Под Windows вам этого сделать не удастся. Другое ограничение связано со внутренним устройством OutWiker. Все папки внутри папки с заметками, начинающиеся с символов __ (два символа подчеркивания), программа считает служебными директориями и не отображает в дереве заметок. Например, все прикрепленные файлы содержатся в папке :file:`__attach` внутри каждой заметки (в случае, если прикрепленные файлы есть). Про хранение вложенных файлов будет сказано :ref:`ниже `. Также ограничения выражаются в том, что внутри одной заметки не может быть двух вложенных заметок с одинаковыми именами. Обойти эти ограничения можно с помощью :ref:`псевдонимов `. .. _pageformat_format: Формат файла __page.opt ----------------------- Файл :file:`__page.opt` является основным файлом в папке заметки, именно он определяет формат страницы, а также различные ее настройки, но этот файл не содержит содержимое страницы, которое видит пользователь (для этого служит файл :file:`__page.text`). Файл :file:`__page.opt` является текстовым и представляет собой ini-файл. То есть в нем содержатся разделы, обозначенные квадратными скобками, а за названием раздела расположены параметры в формате "имя=значение". Файл должен быть записан в кодировке UTF-8. Ниже приведен пример файла :file:`__page.opt`, пока не обращайте особого внимания на параметры, мы их рассмотрим ниже. .. code-block:: ini [General] type = wiki tags = html, софт order = 0 datetime = 2014-04-12 12:46:55.170000 cursorposition = 121 uid = __a07bd7a7-2be3-41f7-a17d-1ec3997ee988 alias = Отображаемое имя страницы [Tree] expand = True [wiki] md5_hash = cef7664a01cb932d419a203b2e63b568 [Misc] pageindex = 0 В данном примере содержатся три раздела параметров: `General`, `Tree`, `wiki` и `Misc`. Количество разделов и настроек внутри них зависит от формата страницы, в этом примере приведены параметры для викистраницы. .. _pageformat_common: Параметры, общие для всех видов страниц ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Для начала разберем параметры, общие для всех типов страниц. Начнем с раздела `[General]`. * `type`. Это единственный обязательный параметр среди всех параметров. Именно он определяет тип страницы. На данный момент существуют 4 типа страниц со следующими типами: * `text` - простая текстовая страница. * `html` - страница в формате HTML. * `wiki` - викистраница. * `search` - страница глобального поиска. * `tags`. Этот параметр хранит список меток, которые были применены к странице. Метки перечисляются через запятую (после запятой можно ставить пробел). * `order`. Задает положение заметки в дереве по сравнению с заметками того же уровня. Чем это значение меньше, тем выше располагается заметка в ветви. Если заметки имеют одинаковое значение параметра `order` или оно отсутствует, то такие заметки сортируются по алфавиту. * `datetime`. Дата и время последнего изменения страницы. Дата и время записывается в формате вида "%Y-%m-%d %H:%M:%S.%f". За расшифровкой этих символов можете обратиться к `документации Python `_. * `cursorposition`. Положение курсора, которое было перед закрытием страницы. Это значение используется для того, чтобы при повторном открытии страницы курсор стоял на том же самом месте, как и в тот момент, когда страница закрывалась. * `uid`. Уникальынй идентификатор страницы, который используется для ссылок. В приведенном выше примере идентификатор равен `__a07bd7a7-2be3-41f7-a17d-1ec3997ee988`, это значит, что ссылка на эту страницу будет выглядить как `page://__a07bd7a7-2be3-41f7-a17d-1ec3997ee988`. При создании заметки странице не присваивается никакой идентификатор, и этот параметр отсутствует, он появляется, когда идентификатор впервые запрашивается, например, при копировании ссылки на страницу в буфер обмена с помощью пункта меню :menuselection:`Инструменты --> Копировать ссылку на страницу` или одноименного пункта контекстного меню. * `alias`. Псевдоним страницы или отображаемое имя. Если данный параметр не задан, то в программе OutWiker имя заметки отображается по имени папки, которая содержит данную заметку. Однако, как было написано :ref:`выше `, это накладывает некоторые ограничения на имена заметок. С помощью псевдонима можно обойти эти ограничения. Псевдоним - это строка, содержащая любые символы. Если для страницы установлен псевдоним, то псевдоним будет отображаться везде вместо имени заметки. Таким образом, для имени папки сохраняются прежние ограничения, а отобржаемое имя заметки может быть произвольным. В основном интерфейсе программы OutWiker нет указаний на возможность установки псевдонимов, чтобы не запутать пользователей. Однако, если вы уверенный пользователь, то можете воспользоваться плагином HackPage_, который среди прочего позволяет устанавливать псевдонимы для страниц. * `expand` из раздела `[Tree]`. Этот параметр имеет булевый тип и может принимать значения `True` или `False`. Этот параметр обозначает, должна ли быть развернута ветвь дерева, начинающаяся с этого узла (заметки). Этот параметр используется для того, чтобы при следующем открытии дерева сохранялась "развернутость" всех его узлов. .. _pageformat_icons: Хранение значка страницы ------------------------ Каждая страница может иметь свой значок, который отображается в дереве заметок рядом с заголовком страницы. Пользователь может устанавливать либо один из стандартных значков, который прилагается к программе, либо свои значки. Пользовательские значки добаляются в диалоге настроек в разделе "Значки пользователя", такие значки хранятся в папке :file:`iconset` профиля программы (см. :ref:`ru_faq_dir_settings`). Все стандартные значки расположены в папке :file:`iconset` в папке программы, а их имена начинаются с префикса `__std_`. Если для страницы устновлен один из стандартных значков, то в файл :file:`__page.opt` в раздел `[General]` добавляется параметр `icon`, значение которого равно относительному пути до файла значка, начиная из папки :file:`iconset`. Например, если для страницы установлен значок :file:`__std_envelope.png`, которая расположена непосредственно в папке :file:`iconset`, то в файле :file:`__page.opt` будет такая строка: .. code-block:: ini [General] icon = __std_envelope.png Если для страницы установлен значок :file:`__std_batman.png` из группы "people", то в файле :file:`__page.opt` будет такая строка: .. code-block:: ini [General] icon = people/__std_batman.png Если для страницы установлен пользовательский значок, то из файла :file:`__page.opt` удаляется параметр `icon`, а в папку заметки будет скопирован пользовательский значок с именем :file:`__icon.\*`, расширение которого совпадает с расширением пользовательского значка. То есть, если исходный пользовательский значок имеет имя :file:`myicon.png`, то в папке заметки будет создан файл :file:`__icon.png`. Такой способ хранения заметок сделан для того, чтобы программа могла бы отображать как стандартные значки, так и пользовательские, которые могут быть не установлены на том компьютере, где открывается дерево заметок. .. _pageformat_attach: Хранение вложенных файлов ------------------------- Как уже было сказано выше, прикрепленные к заметке файлы хранятся в папке :file:`__attach`, поэтому для добавления новых файлов вы можете не только использовать интерфейс программы, но и копировать файлы в эту папку, используя любой файловый менеджер. Если вы добавляете файл внешними средствами в выбранную в данный момент заметку, не забудьте нажать кнопку "Обновить" в окне "Прикрепленные файлы", чтобы новые файлы появились в окне программы. Когда новая заметка только была создана, она не имеет папки :file:`__attach`, она будет создана только при первой необходимости - когда вы прикрепите какой-нибудь файл, нажмете кнопку "Открыть папку с прикрепленными файлами" в окне "Прикрепленные файлы" или выберете пункт меню :menuselection:"Инструменты --> Копировать путь до прикрепленных файлов". Внутри папки :file:`__attach` могут находиться и вложенные папки, они даже будут показаны в окне "Прикрепленные файлы" но эта особенность программы OutWiker не особо афишируется, поскольку интерфейс для работы с прикрепленными папками пока не очень развит (надо добавить возможность заходить внутрь прикрепленных папок и некоторые другие функции). Но здесь есть одно ограничение - прикрепленные папки не могут начинаться с символов __ (два подчеркивания), поскольку такие папки считаются служебными и не показываются в списке прикрепленных файлов. Одно из применений таких служебных папок описывается в следующем разделе. .. _pageformat_thumb: Хранение миниатюр ----------------- На :ref:`викистраницах ` есть возможность создавать уменьшенные копии изображений (миниатюры) с помощью команды ``%thumb% ... %%``. При использовании этой команды могут быть заданы размеры создаваемых миниатюр. Поскольку миниатюры иногда могут оказаться полезными сами по себе, то они отображаются не просто с помощью тега со ссылкой на оригинальный файл и с атрибутами width и height, задающими размер, а миниатюра создается в виде отдельного файла. Поскольку в большинстве случаев пользователю незачем видеть созданные миниатюры в списке прикрепленных файлов, а хранить эти файлы где-то надо, для этого в папке :file:`__attach` создается вложенная папка :file:`__thumb`. Так как ее имя начинается символов __, она не отображается в списке прикрепленных файлов. Сами миниатюры хранятся в этой папке и имена их файлов однозначно идентифицируют файл картинки, из которого они были созданы, а также размер миниатюры. Например, если к викистранице прикреплен файл image.png, а на самой странице содержится текст: .. code-block:: text %thumb width=200%Attach:image.png%% %thumb width=400%Attach:image.png%% %thumb height=200%Attach:image.png%% %thumb maxsize=200%Attach:image.png%% то в папке :file:`attach/__thumb/` будут созданы следующий файлы: * :file:`th_width_200_image.png` * :file:`th_width_400_image.png` * :file:`th_height_200_image.png` * :file:`th_maxsize_200_image.png` Таким же образом создаются миниатюры для каждого размера, и в то же время если в тесте страницы встретится еще одно упоминание миниатюры с тем же размером, то оно не будет создано повторно. К тому же имена миниатюр остаются читабельными, можно легко найти нужную миниатюру и скопировать ее с помощью файлового менеджера в другую папку, если этот файл миниатюр понадобится для других целей. .. _pageformat_text: Формат простых текстовых заметок -------------------------------- Формат файла :file:`__page.opt` для простых текстовых заметок не имеет каких-то специфических параметров. При этом параметр `type` в разделе `[General]` должен иметь значение `text`. Текст заметки хранится в файле :file:`__page.text` в том виде, в котором он отображается в окне редактирования. Классы, предназначенные для работы с текстовой страницей расположены в папке `src/outwiker/pages/text/ `_. .. _pageformat_html: Формат страниц в формате HTML ----------------------------- Страница для заметок в формате HTML должна иметь значение параметра `type` равным `html`. Кроме того, этот тип страниц в разделе `[General]` имеет дополнительный параметр `linewrap` булевого типа. Если этот параметр имеет значение `True`, то для данной заметки будет включен режим "Автоматический перенос строк", и для каждого введенного в окне редактора переноса строк будет добавлен тег
. Если этот параметр имеет значение `False`, тогда теги
добавляться не будут, и пользователь сам должен будет писать теги
или

для оформления абзацев. В этом случае введенный код HTML будет интерпретироваться точно так, как он введен. Этот режим может быть удобен, например, для подготовки текста для сайта. Кроме того, у HTML- и :ref:`викистраниц ` есть дополнительный параметр `pageindex` в разделе `[Misc]`, он определяет, какую вкладку на данной странице в последний раз открывал пользователь. Если пользователь завершил работу со страницей на вкладке "HTML", это значение будет равно 0, если на вкладке "Просмотр", то - 1. При работе с OutWiker пользователь вводит только тело HTML, а именно то, что обычно включается в теги ..., после чего программа создает полноценный файл .html, причем есть возможность посмотреть, что же получается в конечном итоге. Результат полного оформления HTML-страницы OutWiker сохраняет в файл :file:`__content.html` в папке страницы. Этот файл содержит полностью завершенную HTML-страницу со всеми стилями оформления, добавленными переносами строк
(если включен режим "Автоматический перенос строк") и т.д. Например, для HTML-страницы, содержащей фразу "Hello World", и использующей стиль страницы по умолчанию, файл :file:`__content.html` будет выглядеть следующим образом: .. code-block:: html Hello world! Классы, предназначенные для работы с HTML-страницей расположены в папке `src/outwiker/pages/html/ `_. .. _pageformat_wiki: Формат викистраниц ------------------ Формат хранения викистраниц во многом напоминает страницы в формате :ref:`HTML `, поскольку в конечном итоге викинотация преобразуется HTML-код, который также сохраняется в файл :file:`__content.html`. Страница, использующая викинотацию, должна иметь значение параметра `type` равным `wiki`. Все выше сказанное относительно файла :file:`__content.html` относится и к викистраницам с учетом того, что от викинотации к HTML-странице текст проходит более сложный путь, и перенос строк на викистраницах работает по своим правилам (нет режима "Автоматический перенос строк"). Кроме того, HTML-код викистраниц проходит дополнительную стадию обработки, чтобы сделать полученный HTML-код более читабельным, расставляя дополнительные переносы строк (не путать с тегом
) после некоторых тегов (за этот процесс отвечает класс `HtmlImprover` из файла `src/outwiker/core/htmlimprover.py `_). Для примера, если викистраница имеет содержимое: .. code-block:: text *Hello World!* ||border=1 || Ячейка таблицы 1 || Ячейка таблицы 2 || || Ячейка таблицы 3 || Ячейка таблицы 4 || полученный в итоге код HTML будет выглядеть следующим образом: .. code-block:: html Hello World!

Ячейка таблицы 1 Ячейка таблицы 2
Ячейка таблицы 3 Ячейка таблицы 4
Плагины, такие как, например, Source_ или TeXEquation_, могут добавлять свои теги между тегами ... , а также перед закрывающимся тегом . Поскольку для очень длинных текстов с викинотацией преобразование в формат HTML может быть сравнительно тяжелой операцией, занимающие единицы секунд, викистраница старается кэшировать полученный результат и не создавать код HTML заново при каждом переключении из вкладки `Вики` на вкладку `Просмотр` или "HTML", как это происходит со страницами в формате :ref:`HTML `. Для того, чтобы определить, изменилась ли страница, OutWiker рассчитывает контрольную сумму по алгоритму `MD5 `_ от строки, полученной склеиванием следующих элементов: * Заголовка страницы. * Текста страницы. * Текущего списка установленных плагинов. * Стиля страницы. * Списка прикрепленных файлов. * Списка дочерних страниц. * Некоторых настроек программы, влияющих на сгенерированный код HTML. Полученный MD5-хэш записывается в параметр `md5_hash` в разделе `[wiki]`. Он может выглядеть, например, следующим образом: .. code-block:: ini [wiki] md5_hash = dd03106a9e3705caeba5ac75a83ce518 Этот параметр не является обязательным, в случае его отсутствия или, если в нем записана неверная строка, ничего страшного не произойдет, просто данная страница при следующем открытии вкладки "Просмотр" или "HTML" заново создаст файл :file:`__content.html`, после чего в данный параметр будет записана новая контрольная сумма MD5. Как и у :ref:`HTML-страниц `, у викистраниц существует параметр `pageindex` в разделе `[Misc]`, он также определяет, какую вкладку на данной странице в последний раз открывал пользователь. Если пользователь завершил работу со страницей на вкладке "Вики", это значение будет равно 0, если на вкладке "Просмотр", то - 1, если на вкладке "HTML", то - 2. Классы, предназначенные для работы с викистраницей расположены в папке `src/outwiker/pages/wiki/ `_. .. _pageformat_search: Формат страниц глобального поиска --------------------------------- Формат страниц глобального поиска несколько отличается от форматов хранения записей другого типа, поскольку этому типу страниц не нужно хранить большой объем текста. Поэтому в папке страницы поиска содержится обязательный файл :file:`__page.opt`, но нет файла :file:`__page.text`. Файл :file:`__page.opt` может иметь следующий вид: .. code-block:: ini [General] type = search tags = проверка, test order = 2 datetime = 2014-04-28 20:56:28.363891 [Search] phrase = искомая фраза tags = test, html strategy = 0 sort = 0 [SearchResults] page_0 = Пример страницы page_1 = Тесты page_2 = Тесты/Проверка page_3 = Тесты/Проверка/Плагины/source page_4 = Тесты/Проверка/Абырвалг page_5 = Тесты/Проверка/Тест page_6 = HTML5 Для данного типа страниц параметр `type` из раздела `[General]` должен быть установлен в значение `search`. Все остальные параметры из этого раздела аналогичны одноименным параметрам страниц, описанных выше. Рассмотрим теперь параметры, специфические для страницы глобального поиска. Начнем с раздела `[Search]`, где хранятся параметры, описывающие последний поиск: * `phrase`. Фраза, которая будет искаться по всем страницам дерева. * `tags`. Метки, которые должны быть проставлены на страницах, чтобы они попали в результат поиска. Теги должны быть разделены запятыми. Если теги не установлены, значит поиск осуществляется по всем страницам дерева. Не путайте этот параметр с одноименным параметром из раздела `[General]`, страница поиска тоже может быть отмечена метками. * `strategy` определяет поведение поиска в случае выбора двух и более меток. Если параметр `strategy` равен 0 или в нем записано ошибочное значение, значит для того, чтобы страница попала в результаты поиска, необходимо, чтобы в ней была проставлена *хотя бы одна* метка из выбранных (хранимых в параметре `tags`). Если параметр `strategy` равен 1, значит для того, чтобы страница попала в результаты поиска, необходимо, чтобы в ней была проставлены `все` выбранные на странице поиска метки. * `sort` определяет способ сортировки найденных результатов. Если параметр `sort` равен 0 или имеет ошибочное значение, сортировка найденных страниц будет осуществляться по алфавиту по заголовку страницы (поведение по умолчанию). Если параметр `sort` равен 1, сортировка найденных страниц будет осуществляться по заголовку страницы в обратном порядке. Если параметр `sort` равен 2, сортировка найденных страниц будет осуществляться по дате последнего изменения страницы, причем страницы с наиболее свежими правками будут располагаться вверху. Если параметр `sort` равен 3, сортировка найденных страниц будет осуществляться по дате последнего изменения страницы, причем страницы с наиболее свежими правками будут располагаться внизу. В разделе `[SearchResults]` сохраняются пути до найденных страниц. Формат хранения результатов поиска видно на приведенном выше примере. Результат сохраняется на тот случай, можно через какое-то время можно было бы вернуться к старому результату поиска без его перезапуска, поскольку эта процедура может быть довольно длительной. Классы, предназначенные для работы со страницей поиска расположены в папке `src/outwiker/pages/search/ `_. .. _pageformat_outro: Заключение ---------- Подводя итоги всего вышесказанного, содержимое папки заметки может выглядеть следующим образом: .. image:: /_static/pageformat/files.png Для страницы со стилем по умолчанию и без прикрепленных файлов папка с заметкой будет выглядеть вот так: .. image:: /_static/pageformat/files_02.png .. _ExternalTools: http://jenyay.net/Outwiker/ExternalTools .. _HackPage: http://jenyay.net/Outwiker/HackPage .. _Source: http://jenyay.net/Outwiker/SourcePlugin .. _TeXEquation: http://jenyay.net/Outwiker/TexEquation