Использование¶

Пакет ged2doc может использоваться либо как отдельное приложение командной строки с тем же именем ged2doc или как библиотека/пакет Python, которая может быть импортирована другими пакетами. Основная функция ged2doc — проанализировать данные GEDCOM и преобразовать их в формат документа для печати или просмотра. Для анализа GEDCOM ged2doc использует пакет ged4py, если Вам нужно только проанализировать GEDCOM и не нужно создавать выходные документы, то пакет ged4py это хорошее место для начала.

Командная строка¶

Приложение ged2doc является основным пользовательским интерфейсом, оно считывает и анализирует GEDCOM файл и создает документ в одном из поддерживаемых форматов (в настоящее время HTML и OpenDocument Text/OTD).

ged2doc - это приложение командной строки, который запускается из терминала, он имеет большое количество опций, которые контролируют содержимое и представление подготовленного выходного документа. Чтобы получить краткое описание всех параметров запустите команду с опцией --help или -h:

% ged2doc --help
usage: ged2doc [-h] [-v] [--log PATH] [--version] [-i PATH] [-p PATTERN]
            [--encoding ENCODING] [--encoding-errors MODE] [-t {html,odt}]
            [-l LANG_CODE] [-d FMT] [-s ORDER] [--locale LOCALE]
            [--no-missing-date] [--no-image] [--no-toc] [--no-stat]
            [-w NUMBER] [--name-surname-first] [--name-comma]
            [--name-maiden] [--name-maiden-only] [--name-capital]
            [--html-page-width SIZE] [--html-image-width SIZE]
            [--html-image-height SIZE] [-u] [--odt-page-width SIZE]
            [--odt-page-height SIZE] [--odt-margin-left SIZE]
            [--odt-margin-right SIZE] [--odt-margin-top SIZE]
            [--odt-margin-bottom SIZE] [--odt-image-width SIZE]
            [--odt-image-height SIZE] [--first-page NUMBER]
            [--odt-tree-type FORMAT]
            input output

Convert GEDCOM file into document.

positional arguments:
  input                 Location of input file, input file can be either
                        GEDCOM file or ZIP archive which can also include
                        images.
  output                Location of output file.

optional arguments:
  -h, --help            show this help message and exit
  -v, --verbose         Print some info to standard output, -vv prints debug
                        info.
  --log PATH            Produces log file with debugging information.
  --version             Print version information and exit

... description of all other options ...

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

Входной файл¶

Первый позиционный аргумент — это входной файл, который может быть либо файлом GEDCOM или ZIP-архивом. Если указан ZIP-архив, он должен содержат файл GEDCOM и также может содержать файлы изображений, на которые ссылается GEDCOM файл. ged2doc может обрабатывать только один файл GEDCOM за один раз, даже если ZIP архив содержит несколько файлов GEDCOM. Приложение пытается угадать, какой файл в ZIP-архиве — файл GEDCOM, используя совпадении шаблонов, по умолчанию используется шаблон *.ged*, который соответствует именам типа file.ged или file.gedcom. Файл в архиве может быть расположен в любой директории, весь ZIP-архив будет просканирован для поиска совпадающих файлов.

Если файл GEDCOM в архиве имеет другое расширение, или если есть больше чем один файл соответствующий шаблону по умолчанию, тогда следует использовать опцию -p PATTERN для указания более точного соответствия, например:

$ unzip -l archive.zip
  Length      Date    Time    Name
---------  ---------- -----   ----
        0  2017-10-30 22:28   folder1/
    77279  2017-10-30 22:28   folder1/file1.ged
        0  2017-10-30 22:28   folder2/
    79999  2017-10-30 22:28   folder2/file2.ged

$ ged2doc -p file1.ged archive.zip output.html

Файл GEDCOM может содержать ссылки на изображения, которые могут быть включены в выходной документ (в текущей реализации включается только одно основное изображение на человека). ged2doc пытается найти файл изображения, сначала используя оригинальное имя непосредственно из файла GEDCOM (если путь относительный, то он разрешается относительно текущей директории). Если файл изображения не найден и дана опция -i PATH тогда ged2doc пытается найти изображение, используя только базовое имя файла изображения путем рекурсивного сканирования PATH указанного в опции -i. Если входной файл является архивом, тогда сначала изображения ищется в архиве используя базовое имя пути из файла GEDCOM, если изображение не найдено в архиве, то тогда используется поиск изображения на диске как описано выше.

Выходной файл¶

ged2doc сохраняет выходной документ в файле, указанном как второй позиционный аргумент. В настоящее время ged2doc может генерировать либо одностраничный HTML с включенными изображениями или формат OpenDocument Text (ODT). Формат HTML лучше подходит для онлайн-просмотра, так как содержит навигационные ссылки, формат ODT лучше для печати (после модификации в OpenOffice/LibreOffice).

Тип созданного документа определяется по умолчанию из расширения файла — если расширение - .htm или .html, то создается формат HTML, если расширение - .odt, тогда сохраняется формат ODT. Если файл имеет другое расширение то необходимо указать опцию -t или --type для указания формата документа:

$ ged2doc -t html archive.zip output.txt
$ ged2doc --type=odt archive.zip output.opendoc

Кодировка файла GEDCOM¶

Правильный файл GEDCOM должен иметь достаточную информацию в нем для автоматического определения его кодировки. В некоторых случаях может потребоваться явно указать кодировку файла или изменить способ обработки ошибок декодирования. По умолчанию ged2doc пытается определить кодировку файла из содержимого файла и программа останавливается при любых ошибках, связанных с кодировкой. Вы можете использовать опцию --encoding чтобы указать другую кодировку и опцию -encoding-errors для управления обработкой ошибок. Аргументом опции --encoding является имя кодировки, такое как utf-8, iso-8859-1 и т. д. Аргументом для опции --encoding-errors является одно из ключевых слов:

strict: Поведение по умолчанию, прерывание приложения в случае ошибок
ignore: Приложение удаляет проблемные закодированные символы
replace: Приложение заменяет проблемные кодированные символы специальными символ замены (�)

Ниже приведен пример команды, которая принудительно устанавливает кодировку utf-8, но заменяет неправильно закодированные данные:

$ ged2doc --encoding=utf-8 --encoding-errors=replace file.ged out.html

Общие опции вывода¶

Языки¶

ged2doc может создавать выходной документ на разных языках (в настоящее время поддерживаются английский, русский, польский и чешский языки). По умолчанию язык определяется из системного окружения, но это может не всегда работать надежно. Чтобы указать выходной язык явно используйте опцию -l CODE, CODE - это код языка (en для английского, ru для русского, pl для польского, cz для чешского).

Формат дат¶

Данные GEDCOM могут включать даты, которые могут быть точными или приблизительными. ged2doc пытается представить все возможные даты в выходном документе в разумном виде согласно правилам выбранного языка. Формат даты по умолчанию определяется языком документа, но его также можно изменить с помощью опции -d FMT (или --date-format=FMT, FMT может быть одним из:

YMD: Год, месяц и день, разделенные пробелом, например: 2000 Дек 31; 2017 Дек; 2017
MDY: Месяц, год и день, разделенные пробелом, например: Дек 31 2000; Дек 2017; 2017
DMY: День, месяц и год, разделенные пробелом, например: 31 Дек 2000; Дек 2017; 2017
Y-M-D: Год, месяц и день, разделенные дефисом, например: 2000-Дек-31; 2017-Дек; 2017
D-M-Y: День, месяц и год, разделенные дефисом, например: 31-Дек-2000; Дек-2017; 2017
Y/M/D: Год, номер месяца и день, разделенные косой чертой, например: 2000/12/31; 2017/12; 2017
M/D/Y: Номер месяца, день и год, разделенные косой чертой, например: 12/31/2000; 12/2017; 2017.
Y.M.D: Год, номер месяца и день, разделенные точкой, например: 2000.12.31; 2017.12; 2017
D.M.Y: День, номер месяца и год, разделенные точкой, например: 31.12.2000; 12.2017; 2017. Этот формат используется по умолчанию для языка ru.
MD,Y: Месяц, день с запятой, год, например: Dec 31, 2000; Dec 2017; 2017. Этот формат используется по умолчанию для языка en.

Сортировка персон¶

Порядок персон в выходном документе контролируется опцией --sort-order=ORDER, ORDER может быть одним из:

last+first: Персоны упорядочены в соответствии с фамилией (в браке) и именем, этот порядок используется по умолчанию.
first+last: Персоны упорядочены в соответствии с именем и фамилией (в браке).
maiden+first: Персоны упорядочены в соответствии с фамилией (до брака) и именем.
first+maiden: Персоны упорядочены в соответствии с именем и фамилией (до брака).

По умолчанию упорядочение имен выполняется в соответствии с правилами сопоставления текущего языка системы (локаль). Если локаль системы не соответствуют языку документа то возможно указать альтернативную локаль используя опцию --locale=LOCALE. LOCALE - название локали, оно обычно зависит от системы, например имя может быть Russian или Czech в Windows или ru_RU.UTF-8 или cs_CZ.UTF-8 в Linux. В Linux также можно изменить локаль, используя переменные среды LC_ALL или LC_COLLATE. Проверьте системную документацию на предмет того, как устанавливать и определять локали.

События без дат¶

По умолчанию ged2doc выводит все события, относящиеся к персоне, включая события, для которых не определены даты (события выводятся с префиксом «Дата неизвестна»). Чтобы отключить вывод таких событий используйте опцию --no-missing-date.

Изображения¶

По умолчанию ged2doc добавляет изображение для каждой персоны (если он может найти его на диске). Это можно изменить используя опцию --no-image, которая отключает все изображения в выходном файле.

Оглавление¶

Оглавление добавляется по умолчанию к каждому документу, опция --no-toc может использоваться для отключения оглавлений.

Статистика¶

Некоторая статистическая информация обычно добавляется к каждому документу (например, частота имен), опция --no-stat может использоваться для ее отключения.

Ширина дерева¶

Для каждого человека ged2doc добавляет небольшое встроенное графическое представление дерева предков, по умолчанию в дереве представлены четыре поколения. Опция -w NUMBER (--tree-width NUMBER) может использоваться для изменения количества поколений в этом дереве.

Формат имен¶

В разных локальностях используются разные правила представления имен, которые могут быть довольно сложными. По умолчанию ged2doc представляет имена людей как имя (в GEDCOM имя может включать отчество) за которым следует фамилия (в браке), например, «Дарья Иванова», но есть также несколько опций, которые могут изменить это представление:

--name-surname-first: Фамилия в лидирующей позиции, например Иванова Дарья
--name-comma: Фамилия, за которой следует запятая (только если фамилия находится в лидирующей позиции), например Иванова, Дарья
--name-maiden: Фамилия в браке и фамилию до брака в скобках, например Дарья Иванова (Сидорова)
--name-maiden-only: Фамилия до брака, например Дарья Сидорова
--name-capital: Фамилия заглавными буквам, например Дарья ИВАНОВА

Комбинация этих опций должна приводить к ожидаемому эффекту, например --name-surname-first -name-comma -name-capital должна произвести что-то вроде «ИВАНОВА (СИДОРОВА), Дарья».

Спецификация размеров¶

Некоторые опции ниже принимают размер как значение, размер может быть указан в различных единицах. Единицы могут быть основаны на экранных координатах (пиксели) или на основе печатных размеров (дюймы/пойнты/мм). Вы можете указать размеры в любой форме, формат выходных документов определяет фактический тип используемых единиц. Когда ged2doc необходимо преобразовать единицы одного типа в другой он использует фиксированный коэффициент преобразования 96 DPI (пикселей на дюйм).

Поддерживаемые типы единиц:

px: Размер задается в пикселях, обычно используется для экранных представлений, таких как HTML. Пример: 100px.
pt: Размер задается в пойнтах, обычно используется для размеров печати, один пойнт составляет 1/72 дюйма. Пример: 72pt.
in: Размер задается в дюймах, обычно используется для размеров печати. Пример: 8.5in.
mm: Размер задается в милиметрах, обычно используется для размеров печати, 1 in = 25.4 mm. Пример: 105mm.
cm: Размер задается в сантиметрах, обычно используется для размеров печати, 1 in = 2.54 cm. Пример: 10.5cm.

Параметры, которые принимают размер как значение, имеют тип единиц по умолчанию, например, если тип единиц для опции - пиксели, значение 300 соответствует с 300px.

Опции HTML¶

Несколько опций специфичны для выходного формата HTML, для всех опций размеров тип единицы по умолчанию — пиксели:

--html-page-width SIZE: Ширина страницы HTML; значение по умолчанию: 800px
--html-image-width SIZE: Ширина изображения; значение по умолчанию: 300px
--html-image-height SIZE: Высота изображения; значение по умолчанию: 300px
-u, --html-image-upscale: Масштабировать изображения размер которых меньше, чем размер, заданный опциями выше. Без этой опции небольшие изображения будут отображаться в их фактическом размере без увеличения.

Опции ODT¶

Опции, специфичные для выходного формата ODT, для всех опций размеров тип единицы по умолчанию — дюймы:

--odt-page-width SIZE: Ширина страницы; значение по умолчанию: 6in
--odt-page-height SIZE: Высота страницы; значение по умолчанию: 9in
--odt-margin-left SIZE: Отступ слева; значение по умолчанию: 0.5in
--odt-margin-right SIZE: Отступ справа; значение по умолчанию: 0.5in
--odt-margin-top SIZE: Отступ сверху; значение по умолчанию: 0.5in
--odt-margin-bottom SIZE: Отступ снизу; значение по умолчанию: 0.25in
--odt-image-width SIZE: Ширина изображения; значение по умолчанию: 2in
--odt-image-height SIZE: Высота изображения; значение по умолчанию: 2in
--first-page NUMBER: Номер первой страницы; по умолчанию 1. Можно изменить на другое значение, если вы планируете добавлять дополнительные страницы в начале при печати окончательного документа.
--odt-tree-type FORMAT: Формат изображения для дерева предков, emf или svg, по умолчанию emf.

Диагностика¶

В случае сбоя приложения или получения неправильного или неожиданного вывода желательно сгенерировать журнальный файл с диагностикой и переслать его автору (чтобы сообщить об ошибках см. Contributing). Для создания журнального файла используйте опцию --log, например:

$ ged2doc --log=log.txt input.ged page.html

что создаст файл log.txt в текущем рабочем каталоге.

Примеры¶

Чтобы создать HTML-страницу из файла GEDCOM с настройками по умолчанию:

$ ged2doc input.ged page.html

Указать путь к изображениям, на которые ссылается файл GEDCOM (имена файлов в стиле UNIX):

$ ged2doc -i /home/joe/gedcom_images input.ged page.html

То же самое, но выходной формат OpenDocument Text:

$ ged2doc -i /home/joe/gedcom_images input.ged output.odt

Если GEDCOM файл называется gedcom.dump и находится в ZIP-архиве (вместе со всеми изображениями):

$ ged2doc -p gedcom.dump input.zip page.html

Если Вам нужно указать другой язык вывода:

$ ged2doc -l ru input.zip page.html

Чтобы изменить представление даты:

$ ged2doc -d Y-M-D input.zip page.html

Чтобы изменить представление имен:

$ ged2doc --name-surname-first --name-comma --name-maiden input.zip page.html

Чтобы изменить размер страниц документа ODT:

$ ged2doc --odt-page-width=8.5in --odt-page-height=11in input.zip page.odt

Using Python modules¶

Смотрите англо-язычную документацию.

Детали выходных форматов¶

Детали HTML¶

ged2doc создает одностраничный HTML-документ, который включает всю графику (фотографии и графы деревьев, являющиеся структурами SVG). Размер полученного документа может быть довольно большим. Большие изображения уменьшаются до указанного размера. Изображения, размер которых меньше указанного размера, масштабируются только если задана опция --html-image-upscale.

Детали ODT¶

ged2doc не содержит логики для правильной разбивки выходного документа на страницы и назначения номера страниц для оглавления. Вместо этого ged2doc зависит от внешних инструментов, таких как LibreOffice, для завершения и публикации документа. Когда документ загружен в LibreOffice его оглавление необходимо обновить - перейдите к меню Tools/Сервис, затем Update/Обновить и Indexes and Tables/Указатели и таблицы - это должно перестроить все ссылки в файле ODT.

ODT файлы могут быть открыты с помощью приложения MS Office (Word), но совместимость MS Office с форматом ODT недостаточно полная, есть некоторые известные проблемы с MS Word при редактировании документов произведенных ged2doc:

Изображения в формате SVG не полностью поддерживаются MS Office, для визуализации дерева предков в MS Office они должны быть созданы в формате EMF. ged2doc поддерживает EMF начиная с версии 0.3, где EMF является форматом по умолчанию (это может быть изменено с помощью опции --odt-tree-type=svg). ged2doc до версии 0.3 невозможно использовать для вывода в формате EMF.
Если файл с деревьями предков в формате EMF был открыт и сохранен LibreOffice то MS Office не сможет отобразить эти изображения деревьев. Нет надежной совместимости между MS Office и LibreOffice, документы должны редактироваться одним и тем же приложением.
Содержание не отображается при открытии файла ODT в MS Office, если требуется оглавление в документе, оно должно быть добавлено вручную.