KDE PIM/KDE Itinerary: Difference between revisions

From KDE Community Wiki
(Created page with "= KDE Itinerary = == Getting KDE Itinerary == === Android === Nightly build https://binary-factory.kde.org/view/Android/job/Itinerary_android/ (automatic sync to KDE F-Droid...")
 
 
(35 intermediate revisions by 3 users not shown)
Line 1: Line 1:
= KDE Itinerary =
= KDE Itinerary =
== What is KDE Itinerary? ==
KDE Itinerary is a digital travel assistant with a priority on protecting your privacy. See [https://apps.kde.org/itinerary its website] for an overview of its features and a few screenshots.


== Getting KDE Itinerary ==
== Getting KDE Itinerary ==


=== Android ===
=== Application ===
Nightly build https://binary-factory.kde.org/view/Android/job/Itinerary_android/ (automatic sync to KDE F-Droid repo currently broken)


=== Plasma Mobile, Flatpak ===
For release packages, see the [https://apps.kde.org/itinerary download links on the website].
<syntaxhighlight lang="bash">
flatpak remote-add --if-not-exists kdeapps --from https://distribute.kde.org/kdeapps.flatpakrepo
flatpak install kdeapps org.kde.itinerary
</syntaxhighlight>


=== Self-compiled ===
For experimental/continuous builds, see [https://invent.kde.org/pim/itinerary the Itinerary README file].
Make sure you have the ZXing-C++ and Poppler dependencies.


== Getting data into KDE Itinerary ==
=== KMail plug-in ===


=== Direct import ===
Part of [https://invent.kde.org/pim/kdepim-addons kdepim-addons] and usually included with any KMail installation already.


TODO
=== Nextcloud Mail integration ===


=== KMail Itinerary plug-in ===
Part of [https://apps.nextcloud.com/apps/mail Nextcloud Mail] itself and included when installing that via the Nextcloud app store.


TODO
=== Browser Integration ===


Not released yet, see [https://blog.broulik.de/2019/11/taking-itinerary-to-the-next-level/ Kai's blog post].
==  Using KDE Itinerary ==
=== Getting data into KDE Itinerary ===
==== Importing files ====
Use Global drawer > Import... in the app to import data from a file directly. This works for the following file types:
* Supported ticket PDFs.
* Most Apple Wallet pkpass files.
* Supported booking emails (in mbox/eml format).
* .itinerary files exported by another Itinerary instance.
* Screenshots containing supported ticket barcodes.
* iCal files with supported event types.
==== Creating entries from URLs ====
Opening, pasting or dropping URLs to web sites referring to events, hotels or restaurants opens a pre-filled edit page to create a corresponding entry. This works for web sites containing schema.org semantic annotations, that refer to an ActivityPub event or recognized OSM elements.
Examples:
* Conferences listed on [https://foss.events foss.events]
* [https://mobilizon.org/en/ Mobilizon] events, e.g. [https://events.graz.social/events/0e22f342-2cf0-4ff8-97ff-adeb3b4c988e Grazer Linuxtage]
* OpenStreetMap locations, e.g. https://www.openstreetmap.org/way/460329236
==== Importing from online booking systems ====
It's also possible to import directly from some online booking systems (via Import > Import from <vendor>), typically requiring the input of a name and booking reference, for the following vendors:
* Deutsche Bahn
* SCNF
==== Scanning Barcodes ====
Ticket barcodes containing at least basic information about the trip can also be imported by scanning the barcode (Import > Scan Barcode). This is supported for:
* IATA airlines boarding passes
* ERA-standardized European international railway tickets
* Some proprietary railway tickets (e.g. MAV)
If you have alternative ways of importing, prefer those over scanning the barcode. Barcodes tend to only have a very minimal set of information due to the limited storage space, and as such often miss full names of the involved locations, or the exact travel times.
Additionally to importing tickets that way, it's also possible to add scanned barcodes to existing or manually added entries via editing those.
==== Importing from the system calendar ====
When using Akonadi on Linux as well as on Android, it's possible to import from the system calendar. The following content is supported:
* Events representing train/bus trips, flights or hotel reservations with corresponding semantic annotations, as added e.g. by Itinerary, the Itinerary KMail plugin as well as some Apple products.
* Events representing train/bus trips or flights added to the calendar via ics files provided by supported providers.
* Any calendar entry representing an event.
==== KMail Itinerary plug-in ====
For content recognized by the plug-in, there's multiple options:
* Add data directly to a locally installed Itinerary.
* Send data via [[KDE Connect]] and open it in Itinerary there.
* Add data to a (shared) calendar. Itinerary can then import from that calendar (see the above section).
==== Manual entry ====
Manually entering data is also possible in two ways:
* For trains/buses and some ferries/flights: Via online journey searches, available in about 40 countries.
* For hotels, events, restaurants, ferries, flights: By manually filling in all information
=== Sharing data between multiple instances of Itinerary ===
==== Shared Calendar ====
Itinerary can export to and import from the system calendar. Using a shared calendar (e.g. Nextcloud Calendar + DavDroid on Android) thus gives multiple Itinerary instances access to the same data. There are limitations though:
* Android's system calendar doesn't support custom properties or attachments. This means Itinerary cannot export all relevant information on Android. Importing works, but only when using DavDroid for syncing (due to support for its special way of persisting custom properties).
==== KDE Connect ====
Both individual entries and entire trips can be sent via [[KDE Connect]] to a different device, via the Export action.
==== Manually sharing files ====
Individual entries and entire trips can also exported to an .itinerary file that can be transferred to other devices and imported there.
==== Matrix ====
Automatically syncing trips between different devices via Matrix is under development.
== Getting involved ==
New to KDE? See also https://community.kde.org/Get_Involved
=== Communication ===
* [https://matrix.to/#/#itinerary:kde.org #itinerary] on Matrix
* KDE PIM mailing list: https://mail.kde.org/mailman/listinfo/kde-pim:
=== Source Code ===
Relevant code repositories:
* Itinerary app: https://invent.kde.org/pim/itinerary
* Travel document extractor engine: https://invent.kde.org/pim/kitinerary
* Travel document extractor development workbench: https://invent.kde.org/pim/kitinerary-workbench
* Public transport data access: https://invent.kde.org/libraries/kpublictransport
* Indoor map renderer: https://invent.kde.org/libraries/kosmindoormap
* KMail plugin: https://invent.kde.org/pim/kdepim-addons
* Thunderbird plug-in: https://invent.kde.org/broulik/itinerary-travelbird
=== Workboard ===
See https://phabricator.kde.org/project/manage/280/
=== Donating Sample Data ===
Samples can be sent to [email protected] and will not be published.
Anything vaguely looking like flight, train, bus, rental car, hotel, event or restaurant bookings/tickets/confirmations/cancellation/etc is relevant. Such documents are even still relevant when they are seemingly already extracted correctly, in many cases there are non-obvious details we don't cover yet correctly.
Preferably in their original unaltered form, for emails the easiest way is "Forward As Attachment".
=== Switching KDE Itinerary to Development Mode ===
A number of development or diagnostic features useful for improving KDE Itinerary are available in "Development Mode". To activate that tap the version number in About > Version seven times (same way as the development mode of Android devices is activated).
In development mode a number of additional actions are visible in the menus, the "Development" page accessible from the global menu allows you to disable this again.
=== Edit Map Styling ===
Improving the styling of the indoor station maps can be done by editing [https://wiki.openstreetmap.org/wiki/MapCSS/0.2 MapCSS] files defining the visual appearance and content of the map, without the need of recompiling the application. For this place a (modified) copy of any of the built-in styles found [here] in the right location.
* Linux: Place the files in <tt>$PREFIX/share/org.kde.kosmindoormap/assets/css</tt> or <tt>~/.local/share/org.kde.kosmindoormap/assets/css</tt>. If you have a Git checkout of the [https://commits.kde.org/kpublictransport KPublicTransport] repo you can also symlink its <tt>src/map/assets</tt> folder to one of those places entirely. To revert your modifiations, simply remove the files from those locations again, the built-in styles will then be used again.
* Flatpak: '''Copy''' your modified MapCSS files to <tt>~/.var/app/org.kde.itinerary/data/org.kde.kosmindoormap/assets/css/</tt>, symlinks don't work with Flatpak as its isolation system will prevent access to outside data. For removing your modifications again, simply delete those files again.
* Android: On Android this is a bit more complicated unfortunately, due to the app isolation mechanisms ther. Here you have to use the "Import MapCSS" action in the Development page from the global menu (see above for switching on "Development Mode"). "Reset MapCSS" in the same place allows you to revert your changes.
When Development Mode is enabled, the map page also offers context actions to try different style variants. Toggling between styles can also be useful to trigger a reload of a style on changes.


== Troubleshooting ==
== Troubleshooting ==
=== KDE Itinerary isn't importing data from a document ===
* Check About > Version in the global menu, this shows the supported formats the app was built with. This should look as follows, in particular missing support for PDF or barcode decoding is a problem here.
<pre>
Engine version      : 5.13.40
HTML support        : libxml2
PDF support        : poppler (0.83.0)
iCal support        : kcal
Barcode decoder    : zxing
Phone number decoder: libphonenumber
RSA support        : openssl
Extractor scripts  : 53
</pre>
* Try to import the synthetic boarding pass sample: https://github.com/KDE/kitinerary/raw/master/autotests/extractordata/synthetic/iata-bcbp-demo.pdf - does this show up as a flight reservation in September 2019?
* Is the input document supported by KItinerary? See https://community.kde.org/KDE_PIM/KItinerary/Supported_Providers


=== The KMail Itinerary plug-in isn't finding anything ===
=== The KMail Itinerary plug-in isn't finding anything ===


TODO
* Is the itinerary plug-in installed? Check $LIBDIR/plugins/messageviewer/bodypartformatter/messageviewer_bodypartformatter_semantic.so. If you are missing this, it's in the kdepim-addons repository, and can probably found similarly named distro packages.
* Is KItinerary built with Poppler and ZXing? Check the output of `$LIBDIR/libexec/kf5/kitinerary-extractor --capabilities` (19.04 or newer). This should show something like this:
<pre>
HTML support        : libxml2
PDF support        : poppler
iCal support        : kcal
Barcode decoder    : zxing
Phone number decoder: libphonenumber
</pre>
 
* Try to attach the synthetic boarding pass sample (https://github.com/KDE/kitinerary/raw/master/autotests/extractordata/synthetic/iata-bcbp-demo.pdf) to an email and save it as draft - does this show a flight reservation in September 2019 when looking at that draft?
 
* Is the input document supported by KItinerary? See https://community.kde.org/KDE_PIM/KItinerary/Supported_Providers
 
=== KDE Itinerary isn't importing data from my calendar? ===
 
Importing data from the calendar is done via the global menu action "Check Calendar".
 
* Do you have a supported setup? That is:
** The app is running on Android (calendar access on Linux is currently not implemented)
** The events were added to the calendar using the KMail plug-in, from 19.08 or newer.
** Calendar syncing is done using DavDroid, using a version from after Feb 2019.
** The CalDav server you use does retain custom properties on iCal events. Nextcloud is known to work.
 
* Are the events you try to import in the future, but not further away than half a year? (that's a performance optimization on the import code, if that is getting into the way of too many people we can adjust this).
 
* Check About > Version in the global menu, check if this shows "kcal" under "iCal support".
 
Technically, the calendar importing is relying on a custom iCal property "X-KDE-KITINERARY-RESERVATION" containing the JSON-LD representation of the booking. Additionally, the app currently assumes the UID prefix "KIT-" for faster searches.
 
=== How to report bugs? ===
 
Use https://bugs.kde.org, product "KDE Itinerary". If the bug involves sensitive documents that you don't want to publish there, you can send those directly to [email protected].


== Terms ==
== Terms ==

Latest revision as of 15:24, 27 August 2024

KDE Itinerary

What is KDE Itinerary?

KDE Itinerary is a digital travel assistant with a priority on protecting your privacy. See its website for an overview of its features and a few screenshots.

Getting KDE Itinerary

Application

For release packages, see the download links on the website.

For experimental/continuous builds, see the Itinerary README file.

KMail plug-in

Part of kdepim-addons and usually included with any KMail installation already.

Nextcloud Mail integration

Part of Nextcloud Mail itself and included when installing that via the Nextcloud app store.

Browser Integration

Not released yet, see Kai's blog post.

Using KDE Itinerary

Getting data into KDE Itinerary

Importing files

Use Global drawer > Import... in the app to import data from a file directly. This works for the following file types:

  • Supported ticket PDFs.
  • Most Apple Wallet pkpass files.
  • Supported booking emails (in mbox/eml format).
  • .itinerary files exported by another Itinerary instance.
  • Screenshots containing supported ticket barcodes.
  • iCal files with supported event types.

Creating entries from URLs

Opening, pasting or dropping URLs to web sites referring to events, hotels or restaurants opens a pre-filled edit page to create a corresponding entry. This works for web sites containing schema.org semantic annotations, that refer to an ActivityPub event or recognized OSM elements.

Examples:

Importing from online booking systems

It's also possible to import directly from some online booking systems (via Import > Import from <vendor>), typically requiring the input of a name and booking reference, for the following vendors:

  • Deutsche Bahn
  • SCNF

Scanning Barcodes

Ticket barcodes containing at least basic information about the trip can also be imported by scanning the barcode (Import > Scan Barcode). This is supported for:

  • IATA airlines boarding passes
  • ERA-standardized European international railway tickets
  • Some proprietary railway tickets (e.g. MAV)

If you have alternative ways of importing, prefer those over scanning the barcode. Barcodes tend to only have a very minimal set of information due to the limited storage space, and as such often miss full names of the involved locations, or the exact travel times.

Additionally to importing tickets that way, it's also possible to add scanned barcodes to existing or manually added entries via editing those.

Importing from the system calendar

When using Akonadi on Linux as well as on Android, it's possible to import from the system calendar. The following content is supported:

  • Events representing train/bus trips, flights or hotel reservations with corresponding semantic annotations, as added e.g. by Itinerary, the Itinerary KMail plugin as well as some Apple products.
  • Events representing train/bus trips or flights added to the calendar via ics files provided by supported providers.
  • Any calendar entry representing an event.

KMail Itinerary plug-in

For content recognized by the plug-in, there's multiple options:

  • Add data directly to a locally installed Itinerary.
  • Send data via KDE Connect and open it in Itinerary there.
  • Add data to a (shared) calendar. Itinerary can then import from that calendar (see the above section).

Manual entry

Manually entering data is also possible in two ways:

  • For trains/buses and some ferries/flights: Via online journey searches, available in about 40 countries.
  • For hotels, events, restaurants, ferries, flights: By manually filling in all information

Sharing data between multiple instances of Itinerary

Shared Calendar

Itinerary can export to and import from the system calendar. Using a shared calendar (e.g. Nextcloud Calendar + DavDroid on Android) thus gives multiple Itinerary instances access to the same data. There are limitations though:

  • Android's system calendar doesn't support custom properties or attachments. This means Itinerary cannot export all relevant information on Android. Importing works, but only when using DavDroid for syncing (due to support for its special way of persisting custom properties).

KDE Connect

Both individual entries and entire trips can be sent via KDE Connect to a different device, via the Export action.

Manually sharing files

Individual entries and entire trips can also exported to an .itinerary file that can be transferred to other devices and imported there.

Matrix

Automatically syncing trips between different devices via Matrix is under development.

Getting involved

New to KDE? See also https://community.kde.org/Get_Involved

Communication

Source Code

Relevant code repositories:

Workboard

See https://phabricator.kde.org/project/manage/280/

Donating Sample Data

Samples can be sent to [email protected] and will not be published.

Anything vaguely looking like flight, train, bus, rental car, hotel, event or restaurant bookings/tickets/confirmations/cancellation/etc is relevant. Such documents are even still relevant when they are seemingly already extracted correctly, in many cases there are non-obvious details we don't cover yet correctly.

Preferably in their original unaltered form, for emails the easiest way is "Forward As Attachment".

Switching KDE Itinerary to Development Mode

A number of development or diagnostic features useful for improving KDE Itinerary are available in "Development Mode". To activate that tap the version number in About > Version seven times (same way as the development mode of Android devices is activated).

In development mode a number of additional actions are visible in the menus, the "Development" page accessible from the global menu allows you to disable this again.

Edit Map Styling

Improving the styling of the indoor station maps can be done by editing MapCSS files defining the visual appearance and content of the map, without the need of recompiling the application. For this place a (modified) copy of any of the built-in styles found [here] in the right location.

  • Linux: Place the files in $PREFIX/share/org.kde.kosmindoormap/assets/css or ~/.local/share/org.kde.kosmindoormap/assets/css. If you have a Git checkout of the KPublicTransport repo you can also symlink its src/map/assets folder to one of those places entirely. To revert your modifiations, simply remove the files from those locations again, the built-in styles will then be used again.
  • Flatpak: Copy your modified MapCSS files to ~/.var/app/org.kde.itinerary/data/org.kde.kosmindoormap/assets/css/, symlinks don't work with Flatpak as its isolation system will prevent access to outside data. For removing your modifications again, simply delete those files again.
  • Android: On Android this is a bit more complicated unfortunately, due to the app isolation mechanisms ther. Here you have to use the "Import MapCSS" action in the Development page from the global menu (see above for switching on "Development Mode"). "Reset MapCSS" in the same place allows you to revert your changes.

When Development Mode is enabled, the map page also offers context actions to try different style variants. Toggling between styles can also be useful to trigger a reload of a style on changes.

Troubleshooting

KDE Itinerary isn't importing data from a document

  • Check About > Version in the global menu, this shows the supported formats the app was built with. This should look as follows, in particular missing support for PDF or barcode decoding is a problem here.
Engine version      : 5.13.40
HTML support        : libxml2
PDF support         : poppler (0.83.0)
iCal support        : kcal
Barcode decoder     : zxing
Phone number decoder: libphonenumber
RSA support         : openssl
Extractor scripts   : 53

The KMail Itinerary plug-in isn't finding anything

  • Is the itinerary plug-in installed? Check $LIBDIR/plugins/messageviewer/bodypartformatter/messageviewer_bodypartformatter_semantic.so. If you are missing this, it's in the kdepim-addons repository, and can probably found similarly named distro packages.
  • Is KItinerary built with Poppler and ZXing? Check the output of `$LIBDIR/libexec/kf5/kitinerary-extractor --capabilities` (19.04 or newer). This should show something like this:
HTML support        : libxml2
PDF support         : poppler
iCal support        : kcal
Barcode decoder     : zxing
Phone number decoder: libphonenumber

KDE Itinerary isn't importing data from my calendar?

Importing data from the calendar is done via the global menu action "Check Calendar".

  • Do you have a supported setup? That is:
    • The app is running on Android (calendar access on Linux is currently not implemented)
    • The events were added to the calendar using the KMail plug-in, from 19.08 or newer.
    • Calendar syncing is done using DavDroid, using a version from after Feb 2019.
    • The CalDav server you use does retain custom properties on iCal events. Nextcloud is known to work.
  • Are the events you try to import in the future, but not further away than half a year? (that's a performance optimization on the import code, if that is getting into the way of too many people we can adjust this).
  • Check About > Version in the global menu, check if this shows "kcal" under "iCal support".

Technically, the calendar importing is relying on a custom iCal property "X-KDE-KITINERARY-RESERVATION" containing the JSON-LD representation of the booking. Additionally, the app currently assumes the UID prefix "KIT-" for faster searches.

How to report bugs?

Use https://bugs.kde.org, product "KDE Itinerary". If the bug involves sensitive documents that you don't want to publish there, you can send those directly to [email protected].

Terms

  • KDE Itinerary: the mobile app for showing your itinerary.
  • KItinerary: the library providing the data extraction engine (yes, sub-optimal naming considering the above).
  • KMail Itinerary Plug-in: plugin for KMail running the data extractor on the email you are currently looking at and showing a blue framed box at the top with what it found
  • KItinerary Workbench: diagnostic and development tool for the data extractors.
  • Poppler: PDF parsing library, needed by KItinerary in order to process PDF files.
  • ZXing-C++: Barcode decoding library, needed by KItinerary to decode any form of barcode.
Retrieved from "https://community.kde.org/index.php?title=KDE_PIM/KDE_Itinerary&oldid=101389"