Архив рубрики: Linux

Подготовка технической документации с использованием asciidoc и DocBook

Это мой конспект для выступления на семинаре, проводившемся нашей LUG. См. также презентацию к докладу.

Глава 1. Актуальность, цели и задачи

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

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

  • Полная документация к большому продукту будет большой. Поэтому необходимо обеспечить автору документации простые и удобные средства для её подготовки, стараться не тратить время автора на посторонние вещи типа оформления этой документации или тонкостей xml-разметки;
  • Пользователи у продукта, возможно, будут разные, а потому документацию необходимо предоставлять в разных форматах; самые популярные форматы — PDF, HTML и CHM;
  • Так как пользователи разные, разной должна быть комплектация документации. В одних случаях нужно только руководство пользователя, в других — только руководство программиста, в третьих — и то, и другое.

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

Глава 2. Обзор технологий

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

  • MS Word и подобные системы;
  • Системы «единого источника»:

    • Help&Manual и аналоги;
    • DocBook;
    • DITA;
    • и другие.

Рассмотрим некоторые из этих технологий несколько подробнее.

Глава 3. Help&Manual

Главным плюсом этой системы часто является то, что она уже внедрена и работает. Также несомненный плюс — это система единого источника, т.е. из одного текста можно получить документ в разных форматах. Особенность этой программы и аналогов: это WISIWYG-системы. Насчёт того, является ли эта особенность плюсом или минусом, по сей день не утихают споры. Плюс WISIWYG-технологий очевиден, он заложен в названии: можно сразу видеть, как будет выглядеть текст в результате. К минусам WISIWYG относят следующие пункты:

  • Есть такое высказывание: если система предоставляет возможность что-нибудь настраивать, она, фактически, заставляет вас это настраивать. В данном случае это относится к тому, что автор тратит время не только на написание текста, но и на его оформление, хотя это, по идее, не его задача.
  • Такие системы склонны порождать совершенно дикую и нечитаемую разметку при конвертировании в HTML, LaTeX и другие подобные форматы. Например, легко можно получить разметку наподобие: разметка. Это сказывается, как только появляется необходимость поправить такую разметку «руками».
  • При работе в таких системах люди склонны использовать не логическую, а физическую разметку (например, помечать кусок текста жирным шрифтом, вместо того чтобы отмечать этот текст как заголовок). Что интересно, большинство таких систем предоставляют возможность использования логической разметки, иногда даже удобную, но по каким-то психологическим соображениям люди не склонны её использовать. Это приводит к проблемам при изменении общего стиля оформления документа, а также зачастую при конвертировании в другие форматы.

В связи с послед

Python 3: Импорт и юникод

Третий питон с рождения замечательно поддерживает юникод. Собственно говоря, это одна из самых заметных его особенностей.

Русские идентификаторы

Чуть меньше бросается в глаза тот факт, что идентификаторы тоже стали юникодными. Уважаемые читатели, если вы используете третий питон и недостаточно хорошо владеете английским — пишите по русски. Это выглядит гораздо лучше, чем убогое средство под названием «транслитерация». Оцените сами:

def функция(агрумент):
коэффициент = 5
return агрумент * коэффициент

Это на самом деле здорово!

Еще один не вполне очевидный момент: имена модулей тоже могут быть в юникоде:

from . import вспомогательный_модуль

Тоже выглядит неплохо, верно? Есть только одна небольшая проблема: это не всегда работает. Вернее, на Windows возможны неприятности. И не нужно заявлять, что вопросы, касающиеся самой популярной на сегодняшний день операционной системы — никого не волнуют. Подавляющее большинство разработчиков самого Питона Windows не используют — и тем не менее Питон обязан на ней работать, и работать хорошо.

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

Юникод в C API

В Python 2 немалая часть Python C API принимала char * там, где требовалась строка. Поскольку str и был последовательностью байт — сложностей не возникало.

При переносе кода на Python 3 нужно было с этим что-то делать: strстал юникодным типом, последовательностью символов.

Но в С нет удобного типа для unicode! Вернее, существует стандартный тип wchar_t, который обременен множеством проблем. Главные из них: в разных реализациях этот тип имеет различный размер: 16 бит для UCS-2 и 32 бита для UCS-4. К тому же Windows (о, снова она) не поддерживает UCS-2 в полной мере (UCS-4 не поддерживает совсем).

Хуже всего то, что на некоторых платформах этот wchar_t попросту не определен.

Таким образом, использовать wchar_t в Python C API нельзя.

Сам Питон вводит тип Py_UNICODE для этих целей. Но и тут не все гладко. Этот тип не входит в Limited API (PEP 384).

Кроме того, разработчики не хотели радикально заменить все char * на что-то другое.

Есть еще и вопрос практического удобства: ведь очень здорово писать

ret = PyObject_GetAttrString(obj, "attribute");

Для wchar_t все гораздо сложнее, далеко не все компиляторы поддерживают строковые юникодные константы.

В свете вышеописанных причин Python C API продолжает использовать char *, считая, что эти строки имеют кодировку UTF-8 если явно не указано иное. Т.е. прототипы функций C API выглядят как:

PyObject *
PyImport_ImportModuleLevel(char *name, PyObject *globals,
PyObject *locals, PyObject *fromlist,
int level);

Это — импорт модуля с именем name, которое передается как UTF-8строка, аналог питоновской функции __import__.

И эта функция — лишь верхушка используемого механизма. В процессе импорта вызываются довольно много внутренних закрытых функций — и везде используются переменные вроде char *name в качестве имен модулей. В кодировке UTF-8, еще раз напомню.

А ведь имя модуля транслируется в путь к файлу! А кодировака файловой системы может отличаться от UTF-8. Счастливые пользователи Linux давно об этом забыли — в подавляющем большинстве систем по умолчанию как кодировка пользователя (переменная окружения LANG) так и файловой системы установлены в UTF-8 и проблем нет совсем. Но в общем случае это не всегда так.

Кодировки по умолчанию

Чуть-чуть о кодировках. Для определения используемых по умолчанию кодировок в питоне существуют три функции: sys.getdefaultencoding, sys.getfilesystemencoding и locale.getpreferredencoding.

  • sys.getdefaultencoding() — кодировка по умолчанию, используемая в питоновских исходниках. Для третьего питона всегда равна UTF-8. Это — та самая кодировка, которую можно перекрыть написав в начале файла

    # -*- encoding: utf-8 -*-
  • sys.getfilesystemencoding() — кодировка файловой системы. Например, для

    f = open('path/to/file', 'r')

    значение 'path/to/file' имеет тип str (юникод). Лежащая в основе функция из clib имеет прототип

    int open(const char *pathname, int flags, mode_t mode);

    Значит, 'path/to/file' должен быть преобразован в char *используя к
    одировку sys.getfilesystemencoding(). Конечно, в Python C API есть специальные функции для этого.

  • locale.getpreferredencoding() — предпочтительная для пользователя кодировка. Она устанавливается в региональных настройках и к файловой системе прямого отношения не имеет.

Теперь снова вспомним нашу горячо любимую Windows.

locale.getpreferredencoding() возвращает 'cp1251' — Windows настроена на русский язык. Кодировка для консоли (sys.stdout.encoding) другая, это 'cp866' — что добавляет сумбура в и без того запутанную проблему. Ну да ладно, не будем отвлекаться.

sys.getfilesystemencoding() возвращает 'mbcs'. И вот здесь начинаются основные чудеса. Обратите внимание, mbcs — это не cp1251. Равно как и не cp1252 или какая другая кодировка. mbcs — это нечто совершенно особенное!

Multibyte character set (кодировка MBCS)

При преобразовании mbcs -> unicode используется кодировка из locale.getpreferredencoding(), преобразование однозначное и проблем не вызывает.

Для обратного преобразования unicode -> mbcs тоже используется locale.getpreferredencoding() (cp1251 в нашем случае). Но cp1251 не может описать любой юникодный символ. А mbcs — хитрый и коварный. Если для символа не существует точного преобразования — используется ближайший похожий по начертанию.

Это непросто понять без примера. Давайте возьмем французское слово comédie и попробуем преобразовать его в mbcs, имея руский язык cp1251 в настройках по умолчанию.

Возьмем Python 3.1:

>>> b = b'comxc3xa9die'
>>> s = b.decode('utf8')
>>> s.encode('mbcs')
b'comedie'

Посмотрите, какая прелесть! Для символа é в русской раскладке cp1251 нет подходящего аналога. Но ведь английская буква e так похожа: нужно лишь убрать умляут (англ. umlaut, французы зовут этот знак accent aigu). Так и получили преобразование comédie -> comedie без единой ошибки.

А теперь представьте, что это — имя файла. Результат будет следующим: файл на диске есть, и так как в Windows файловая система юникодная, имя файла будет записано правильно, по французски. Но преобразование unicode -> mbcs даст несколько другое имя, которого на диске нет.

В результате получается изумительная по своей красоте ситуация:

f = open('comédie', 'r')

будет говорить, что файла нет — а на самом деле вот же он, красавец!

Справедливости ради нужно упомянуть, что в Python 3.2 поведение mbcsнемного поменялось, и 'comédie'.encode('mbcs') вызовет UnicodeEncodeError. Дело в том, что mbcs стал использовать режим strict по умолчанию. Чтобы повторить функциональность 3.1 следует указывать режим replace: 'comédie'.encode('mbcs', 'replace')

Юникодная файловая система

С mbcs мы разобрались и выяснили, что для работы с файловой системой эта кодировка в общем случае непригодна. Т.е. если я буду использовать русские имена файлов на русской Windows — всё будет хорошо. Но открыть этот файл у американца или голландца не выйдет. Что же делать?

В Windows помимо open есть еще и функция

FILE *_wfopen(const wchar_t *filename, const wchar_t *mode);

которая принимает wchar_t * и позволяет использовать оригинальное юникодное имя файла без всяких преобразований. Существует целый набор, начинающийся с _w — на все случаи жизни.

Значит, нужно делать следующее: для Windows использовать юникодные версии функций работы с файлами, а для всех остальных операционных систем применять .encode(sys.getfilesystemencoding()).

Реализация модуля io начиная с версии 3.1 так и поступает.

И снова импорт русских названий

Всё отлично за одним маленьким исключением — механизм импорта не использует io! Исторически сложилось так, что имя импортируемого модуля довольно быстро преобразовывается в sys.getfilesystemencoding() (с возможными ошибками и потерями, о которых я писал выше) и в таком виде пронизывает весь очень непростой и громоздкий код, чтобы попасть в функции стандартной библиотеки C.

Добавьте к этому довольно большой объем платформозависимого кода (на Маке все работает совсем не так, как на Linux) и проблему обратной совместимости (даже после объявления части API устаревшей она должна поддерживаться как минимум в двух следующих выпусках) — и вы сможете представить сложность и объемность задачи.

Так вот, после трехлетнего труда (с небольшими перерывами, естественно — это же добровольный некоммерческий Open Source) Victor Stinner завершил требуемое нелегкое преобразование. Дов
ольно незаметный, но очень важный шаг!

Файловые пути стали храниться в PyObject* (на самом деле это, конечно, strPyUnicodeObject), работающая с ними часть C APIимеет суффикс Object. Например:

PyObject *
PyImport_ImportModuleLevelObject(PyObject *name, PyObject *globals,
PyObject *locals, PyObject *fromlist,
int level);

Сравните с PyImport_ImportModuleLevel. Все функции из старого APIстали тонкими обертками над новыми вариантами. Так, PyImport_ImportModuleLevel создает PyObject из name и вызывает PyImport_ImportModuleLevelObject.

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

Если быть честным, именно Windows поддержка чуть-чуть не готова — но до выхода Python 3.3 еще очень много времени. Достаточно, чтобы закончить работу и навести полный порядок.

Заключение

Я написал этот довольно длинный текст преследуя несколько целей:

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

  • Вторая — продемонстрировать, как работают кодировки применительно к файловой системе.

  • Третья — напомнить, что можно использовать русские буквы в идентификаторах. Комментарии излишни.

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

Автор: Andrew Svetlov

Дистрибутивы Linux. Часть II

Хоть Virens частично и раскрыл эту тему в своем последнем посте, пост, приведенный ниже уже был наполовину готов. И я подумал — а не буду я отменять выкладывание этого поста. Что лучше, что хуже пусть судят остальные ;). Вопросы, касающиеся пакетного менеджмента я, в свое время, тоже опишу.

В первой части были рассмотрены основные определения, касающиеся понимания дистрибутива Linux. Теперь, собственно, я попытаюсь собрать это все воедино.

Как получается очередной дистрибутив Linux?
Читать

Из чего состоят дистрибутивы Linux. Часть I

 

Дистрибутивов Linux огромное количество. Откуда они берутся, как получаются и почему именно такие — этому и посвящена статья. Статья адресована прежде всего новичкам в мире Linux, поскольку большинство из тех, кто начинал им пользоваться раньше появления Ubuntu, обычно знают все, что приведено ниже.

Представьте себе огромное количество разного ПО от маленьких (но важных) проектов по отдельным библиотекам до огромных типа KDE, GNOME, Libre- и OpenOffice, ядра Linux. Все эти отдельные проекты развиваются каждый сам по себе, иногда с оглядкой на остальные, иногда нет. Конечно, каждый может собрать это все ПО вместе и объявить дистрибутивом Linux, но в случае серьезных дистрибутивов (я к ним отношу те, что занимают первые 10 мест в рейтинге Distrowatch) все обычно гораздо сложнее.


Немного о терминах.
Разработчиками дистрибутива (или майнтейнерами) обычно называют тех, кто берет какое-то ПО и упаковывает его в пакет для конкретного дистрибутива (пакетная система, для чего она нужна и что делает — отдельный большой вопрос).
Место, откуда это ПО берется — называется апстрим (от английского upstream). Адекватного перевода на русский язык я пока не нашел, да и слово апстрим стало уже устоявшимся термином. Для серьезных дистрибутивов апстримом являются конкретные проекты свободного (и не очень) ПО. Для производных дистрибутивов — другие дистрибутивы Linux. Например, для CentOS — апстримом является Red Hat Enterpise Linux, для Ubuntu — Debian, для Debian — оригинальные разработчики ПО. Еще раз — апстрим это или разработчик конкретной программы, или родительский дистрибутив.
Пакетом называется отдельный атом дистрибутива (в смысле неделимости), который несет в себе конкретную программу (или набор программ), библиотеку (или набор библиотек), документацию, темы оформления или что-то еще. Короче говоря, все, что составляет дистрибутив Linux — это меньшее или большее количество пакетов. Пакет — это обычно:

  • архив дерева файлов в том виде, в котором они должны лежать на диске после установки;
  • набор метаданных, содержащих информацию о пакете (имя майнтейнера, описание пакета, зависимости);
  • набор скриптов, облегчающих установку пакета для пользователя и/или производящих те или иные настройки.

Пакетная система — то, что помогает пользователям дистрибутива искать, ставить, обновлять пакеты и автоматически отслеживать зависимости между ними. Пакетные системы в мире Linux делятся на три больших и хорошо очерченных класса:

  • пакетная система Debian и ее deb-пакеты.
  • пакетная система rpm, придуманная в свое время Red Hat и теперь имеющая не всегда совместимые между собой пакеты разных rpm-дистрибутивов (Red Hat/Fedora, SUSE, Mandriva и т.п.). Имеется в виду, что, например, пакет для Mandriva может и встанет на SUSE (зависит от положения звезд на небе), но работать скорее всего откажется.
  • все остальные пакетные системы. В качестве примера сюда можно отнести и пакеты ArchLinux, и Slackware, и отчасти Gentoo.

Важный составляющих элемент пакетной системы — менеджер пакетов. Это программа, позволяющая управлять пакетами на конкретной машине. И обычно она имеет только текстовый интерфейс, но разработчики большинства дистрибутивов, как правило, поставляют графические утилиты, взаимодействующие с пакетным менеджером и таким образом значительно облегчающие жизнь тех, кто еще не познакомился с консолью Linux или не хочет с ней знакомится вовсе.
Вопрос какая пакетная система лучше, какая хуже — относится к сфере личных пристрастий и потому спорный. Желающие могут в этом убедиться, открыв на каком-нибудь Linux-форуме тему «Что лучше rpm или deb?». Если Вас сразу не забанят модераторы форума за провокац
ию, то флейм по этому поводу займет не один десяток страниц.

Зависимости — это следующая непонятная новичкам штука. Бывают жесткие и мягкие. Жесткая зависимость в общем виде — это все то, без чего содержимое пакета работать не будет. Обычно это какие-то библиотеки, обеспечивающие функционал конкретной программы. Мягкая зависимость — это то, что обеспечивает дополнительный функционал для программы. Такой тип зависимостей есть, по большому счету, только в deb-пакетах.
Следующее непонятное определение — репозиторий пакетов. Это место, откуда пользователи берут ПО для своего дистрибутива. Обычно это некое сетевое (но может быть и локальным) хранилище пакета, в котором помимо собственно пакетов для дистрибутива находится набор метаданных, которые используются пакетным менеджером для управления ПО на машине пользователя. Именно благодаря этим метаданным пользователям достаточно легко найти нужные пакеты в репозитории, а пакетному менеджеру выяснить, какое ПО требует обновлений.
По способу поддержки репозитория можно выделить три типа дистрибутивов:

  1. Дистрибутивы со скользящим релизом (или безрелизные). На английском они обычно называются rolling release. Типичный (и достаточно популярный) тут — Archlinux. В таких дистрибутивах после обычно малого периода тестирования пакеты попадают к пользователям практически сразу после релиза конкретного пакета его разработчиком. Главное преимущество таких дистрибутивов — то, что в репозитории находится очень свежее ПО. Это имеет и обратную сторону (за все в жизни приходится платить) — в этом ПО зачастую имеются ошибки, которые с переменным успехом отлавливаются пользователями такого дистрибутива. По причине того, что большая часть проектов развивается без оглядки друг на друга, иногда встречается какая-либо несовместимость между какими-то пакетами, вызывающая неработоспособность определенной программы. Иногда (при серьезных изменениях) меняется формат конфигурационного файла программы или демона, что требует работы руками. Но те, кто используют такие дистрибутивы, обычно знают, на что идут, и достаточно квалифицированы для того, чтобы решить все возникающие проблемы. Тут из всех дистрибутивов, на мой взгляд, самый выдержанный подход у Gentoo, который представляет собой дистрибутив с rolling release-моделью, но тем не менее все пакеты попадают в его стабильную ветвь после значительного периода тестирования, что обеспечивает достаточно высокую надежность его работы.
  2. Дистрибутивы с релизной моделью. Проблема получения стабильного дистрибутива давно уже решена и используется большинством разработчиков разных дистрибутивов Linux, таких как Debian, Ubuntu, Red Hat, SUSE и проч. У таких дистрибутивов есть обычно тестовая ветвь с rolling release-моделью, на которой обкатываются (и решаются) разные проблемы несовместимости и нестабильной работы конкретного ПО. Периодически эту ветвь замораживают, блокируя попадание туда новых пакетов. Затем в таком репозитории вычищают по максимуму все имеющиеся в нем проблемы и ошибки. Когда ошибок, по мнению разработчиков, уже достаточно малое количество, выпускается очередной релиз, на протяжении жизни которого в нем не будут уже меняться версии имеющегося ПО. Обновления такого дистрибутива включают в себя исправление оставшихся ошибок и устранение возникающих время от времени уязвимостей. Иногда ошибки устраняют и разработчики апстрима. Тогда задача майнтейнера пакета проанализировать исходный код разработчиков ПО (он же открыт) и выделить из него только те изменения, которые отвечают за исправление ошибок. Затем эти изменения накладываются на те программы и библиотеки, которые находятся в стабильном релизе. Благодаря этому получается, что версия ПО в стабильном дистрибутиве старая, но тем не менее в ней исправлено большинство уязвимостей, найденных к этому моменту. Другое дело, что длительная поддержка ПО по такой схеме — вещь трудная. Ведь чем больше проходит времени с момента релиза, тем более высокая квалификация требуется от разработчика, чтобы выделить только то, что исправляет ошибки и ни в коем случае не ломает совместимость с другими программами и библиотеками. Именно по этой причине длительную поддержку релиза могут позволить себе немногие. По сути лишь те, кто
    имеет большое количество квалифицированных программистов, то есть коммерческие компании Red Hat и Novell. Такие дистрибутивы прекрасно подходят для консервативной корпоративной среды, где редко происходят сильные изменения и поэтому нужна высокая стабильность работы.
  3. Дистрибутивы со смешанным циклом. В таких дистрибутивах стабилизируется (замораживается) только одна часть репозитория. Как правило, это все, что относится к сборочной среде, — компилятор, библиотека C, разные важные библиотеки, ядро Linux. А ПО, относящееся к десктопам (типа Firefox, OpenOffice, разные игры), обновляется регулярно (но обязательно после продолжительного тестирования).

Для таких популярных дистрибутивов как openSUSE и Ubuntu есть выбор — либо использовать стабильную базу конкретного релиза их дистрибутива, или подключить дополнительные репозитории (репозитории OBS для SUSE и ppa для Ubuntu), получая таким образом более свежее ПО для своей системы.
Вроде как все, что хотелось бы сказать по данному поводу. Если что осталось неясно, постараюсь ответить в комментариях на вопросы, касающиеся данной статьи. В меру сил и наличия свободного времени постараюсь внести все необходимые изменения, если потребуется в приведенный текст статьи.

Автор: stranger

Система инициализации Systemd. Часть II

Это продолжение начатого тут.

Собираем все вместе — systemd

Выше я объяснил, что должен делать хороший процесс с PID 1 и как работают существующие системы инициализации. Перед тем как перейти к самому главному, давайте сделаем еще паузу. Сходите налейте себе еще кружечку кофе. Это того стоит.

Читать

Система инициализации Systemd. Часть I

Наверное, все уже слышали о новой системе инициализации systemd, которая разрабатывается под опекой Red Hat и Novell. Я решил перевести описание работы этой системы от ее автора из его же блога. Сама статья оказалась слишком большой, поэтому выкладываю пока только ее первую часть. Вторую часть я выложу в течение пары дней. Ссылка на оригинал традиционно приведена в конце поста. Также традиционно, мои комментарии по тексту приведены курсивом.

Читать