Показать справку для моего приложения Gtkmm без Autotools или Meson

Question

Я написал небольшое приложение с использованием Gtkmm, для которого я хотел бы предоставить документацию для пользователей. Для этого я хотел бы запустить справочную систему Gnome из меню моего приложения (в качестве рабочего примера можно посмотреть gedit).

Сначала я написал минимальную крякву index.page файл:

      <page xmlns="http://projectmallard.org/1.0/"
      type="guide"
      id="index">
<title>Example help</title>
</page>

который я могу просмотреть, вызвав команду yelp help/C/index.page из корневого каталога моего проекта:

Затем я написал небольшое приложение на C++ (Gtkmm 3.22) для вызова справочной системы:

      #include <iostream>
#include <gtkmm.h>

constexpr char HELP_URI[] = "help:myapp";

int main(int argc, char* argv[]) 
{
    auto app = Gtk::Application::create(argc, argv, "bob.morane.question");

    Gtk::Window window;

    // 1. Add the help menu item:
    Gtk::MenuItem helpItem;
    helpItem.set_label("Help");

    Gtk::Menu helpMenu;
    Gtk::MenuItem openHelpItem;
    openHelpItem.set_label("Open help...");

    Gtk::MenuBar menuBar;
    menuBar.append(helpItem);
    helpItem.set_submenu(helpMenu);
    helpMenu.append(openHelpItem);

    window.add(menuBar);
    

    // 2. Link the help menu item to Mallard documentation:
    openHelpItem.signal_activate().connect([&window](){
        const guint32 timestamp = gtk_get_current_event_time();
        GError* error = nullptr;

        // This is the call that triggers gnome help system:
        const bool status = gtk_show_uri_on_window (window.gobj(),
                                                    HELP_URI,
                                                    timestamp,
                                                    &error);
        if(!status)
        {
            std::cout << "Unable to show help : " + std::string{error->message} << std::endl;
            return;
        }
    });

    window.show_all();
    return app->run(window);
}

который я создаю с помощью очень простого Makefile:

      all: main.cpp
    g++ -std=c++17 main.cpp -o myapp `pkg-config gtkmm-3.0 --cflags --libs`

Когда я нажимаю на Open help... пункт меню, я получаю следующее:

Если я изменю первую строку своей программы на: constexpr char HELP_URI[] = "help:gedit";, то справка gedit выскакивает нормально. Использование системы сборки, такой как Meson (например, gedit) или Autotools (как предлагает эта документация Gnome ), было бы для меня сейчас излишним. Я хотел бы иметь возможность показывать свой файл справки без необходимости обрабатывать их (т.е. я хочу продолжать использовать свой Makefile).

* Вопрос: как я могу показать свой собственный файл справки без использования Meson или Autotools?

Answer 1

Файлы справки должны быть где-нибудь, где Yelp сможет их найти. Обычно вы устанавливаете их в /usr/share/help/LANG/APPID/, куда LANG идентификатор языка (или просто C для непереведенных документов) и APPID какой-то идентификатор вашего приложения (соответствующий базовому имени вашего .desktop file - хорошая практика).

Если вы используете автоинструменты, yelp.m4обо всем этом позаботится: http://yelp.io/tools/yelp.m4

Если вы используете мезон, gnome.yelpоб этом позаботится функция: https://mesonbuild.com/Gnome-module.html#gnomeyelp

Но если вы не хотите использовать систему сборки, вам придется самостоятельно управлять получением файлов. Им не обязательно быть в /usr/. Yelp смотрит в help подкаталог каталогов в $XDG_DATA_HOME и $XDG_DATA_DIRSиз спецификации базового каталога XDG. По умолчанию это означает, что он смотрит на ~/.local/share/help/:/usr/local/share/help/:/usr/share/help/. Таким образом, вы можете установить файлы локально в ~/.local/share/ для тестирования.

Или, если вы действительно не хотите никуда устанавливать файлы, вы можете упорядочить дерево исходного кода определенным образом и установить переменную среды. Например, если ваше дерево исходных текстов имеет корень ~/myapp/, затем поместите свои файлы подкачки в ~/myapp/help/C/myapp/, и вызовите свое приложение с помощью XDG_DATA_HOME=~/myapp/ myapp.

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

Answer 2

Что я в итоге сделал: так как я пока не могу перейти к системе сборки, я решил написать небольшой скрипт, чтобы скопировать содержимое моей справки в ~/.local/share в целях тестирования:

      #!/bin/bash

TARGET=~/.local/share

if [[ -d "${TARGET}/" ]]
then
    cp -r ./help ${TARGET}
else
    echo "Error: ${TARGET} does not exist."
fi

Благодаря этому я могу разрабатывать свою справочную документацию без использования системы сборки. Обратите внимание, что для работы этого сценария я добавил свой index.page файл справки в help/C/myapp/index.pageиз корневого каталога моего проекта. Это позволяет мне автоматизировать этот сценарий из моего Makefile, поэтому мне не нужно копировать все вручную или самому вызывать Yelp:

      all: main.cpp
    ./installHelp.sh
    g++ -std=c++17 main.cpp -o myapp `pkg-config gtkmm-3.0 --cflags --libs`

Однако, как заметил Шон МакКэнс, это решение не переносимо, и рано или поздно мне придется перейти на какую-нибудь систему сборки.