diff options
author | Federico Mena Quintero <federico@gnome.org> | 2021-11-22 16:59:29 -0600 |
---|---|---|
committer | Federico Mena Quintero <federico@gnome.org> | 2021-11-22 17:15:43 -0600 |
commit | e1a163130d835ed0c887c5e196a824c96f06ab45 (patch) | |
tree | e609c94f0ca0db4140c6a6b4e1b6b1f897644408 /README.md | |
parent | 69a2116998c7eb2e74a6ed9dcd63f28cc0bd3348 (diff) | |
download | at-spi2-core-e1a163130d835ed0c887c5e196a824c96f06ab45.tar.gz |
Refresh the main README.md
Update links, and make it not sound like the conversion to DBus is the
hot new thing :)
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 143 |
1 files changed, 50 insertions, 93 deletions
@@ -1,112 +1,69 @@ -D-Bus AT-SPI ------------- +# Assistive Technology Service Provider Interface (AT-SPI) -This version of at-spi is a major break from version 1.x. -It has been completely rewritten to use D-Bus rather than -ORBIT / CORBA for its transport protocol. +This repository contains the [DBus][DBus] interface definitions for AT-SPI, the Assistive +Technology Service Provider Interface — the core of an accessibility stack for free +software systems. It also contains the basic daemons of the accessibility stack. -An outdated page including instructions for testing, project status and -TODO items is at: +The version control repository and bug tracker are at https://gitlab.gnome.org/GNOME/at-spi2-core/ - https://wiki.linuxfoundation.org/accessibility/atk/at-spi/at-spi_on_d-bus +The code in this repository is not intended for application programmers. To write +accessible applications, look into [ATK][ATK] or your programming language's bindings for +the `xml` DBus interfaces mentioned below. -The mailing list used for general questions is: - - https://lists.linuxfoundation.org/mailman/listinfo/accessibility-atspi - -For bug reports, feature requests, patches or enhancements please use: - - https://gitlab.gnome.org/GNOME/at-spi2-core/ - -A git repository with the latest development code is available at: - - https://gitlab.gnome.org/GNOME/at-spi2-core/ - -More information ----------------- - -The project was started with a D-Bus performance review -the results of which are available on the GNOME wiki. Keep in -mind that the D-Bus AT-SPI design documents on this page -have not been kept up to date. - - https://wiki.gnome.org/Accessibility/Documentation/GNOME2/ATSPI2-Investigation - -Other sources of relevant information about AT-SPI and Accessibility +While this module started within the [GNOME][GNOME] project's umbrella, it is not used +only in GNOME. Other sources of relevant information about AT-SPI and Accessibility include: - https://wiki.gnome.org/Accessibility - https://community.kde.org/Accessibility - - -Contents of this package ------------------------- - -This package includes the protocol definitions for the new D-Bus -at-spi. +* [GNOME Accessibility wiki][gnome-a11y-wiki] +* [KDE Accessibility wiki][kde-a11y-wiki] +* [Accessibility documentation for GNOME users][docs-users] -Also included is the daemon necessary for forwarding device events -and registering accessible applicaitions. +## Summary of this repository's contents -Directory structure -------------------- +* `xml` - DBus interfaces for accessibility, described in DBus's XML introspection format. + Ideally, your programming language's implementation of DBus makes use of these files to + generate callable bindings. + +* `bus` - Launcher for the session's accessibility bus; see its [README.md](bus/README.md) + for details. -The directories within this package are arranged as follows: +* `registryd` - Daemon that keeps track of accessible applications in the user's session, + and lets them talk to each other and to assistive technologies (ATs) like screen + readers. - xml +* `atspi` - Hand-written binding for the `xml` DBus interface above, for use from C with + [GObject][GObject]. This is not normally what you would use; use a language-specific + binding instead. This module is for use mainly by [`at-spi2-atk`][at-spi2-atk]. - This directory contains XML documents describing - the D-Bus protocol in the format used for D-Bus introspection. +* `dbind` - DBus utilities for use by `atspi` above. `atspi` was written before the more + modern C bindings like [GDBusConnection][GDBus] were available, so there is a lot of + hand-written IPC here. - idl +## Historical note - The D-Bus specification in an idl-like format. This is likely not - parseable by any existing tools, is not entirely up-to-date, and may - by removed in a future release. +Versions 1.x of AT-SPI were based on [CORBA][CORBA] for inter-process communication (IPC), +using GNOME's ORBit implementation thereof. During the GNOME 2 and 3 release series, +CORBA was phased out in favor of [DBus][DBus], a more modern IPC mechanism. - registryd +The original CORBA interfaces for AT-SPI were based on Java's implementation of +accessibility. Later, these CORBA interfaces were translated to DBus. This is why the +interfaces sometimes have a 1990s feeling to them. - The registry daemon code. The registry daemon - keeps a register of accessible applications and presents - this to clients (ATs). - It is also responsible for delivering device events. +The project was started with a D-Bus performance review, the results of which are available +on the GNOME wiki. Keep in mind that the D-Bus AT-SPI design documents on this page have +not been kept up to date. - dbind - - Library to ease making D-Bus method calls, contains - marshalling code to convert function arguments - and a provided D-Bus signature into a D-Bus message. - - Used by libatspi. - - atspi - - C library for use by ATs. Wraps the various D-Bus calls, provides - an interface for listening to events, and caches some information about - accessible objects. Also contains some functions used by at-spi2-atk. - - bus - - A server that sits on the session bus and provides an interface - allowing applications to find the accessibility bus daemon, launching - it as needed. The accessibility bus is separate from the session bus - because it may in fact span user sessions if a user, for instance, - runs an application that escalates to run as root. The accessibility - bus is thus tied to the X session rather than the D-Bus session. - - doc - - Contains infrastructure for creating libatspi documentation. - - test - - Contains files that may be useful for testing AT-SPI. - - m4 - - Some macros used for building the module. + https://wiki.gnome.org/Accessibility/Documentation/GNOME2/ATSPI2-Investigation - po - Infrastructure used for translation. +[CORBA]: https://en.wikipedia.org/wiki/Common_Object_Request_Broker_Architecture +[DBus]: https://www.freedesktop.org/wiki/Software/dbus/ +[GObject]: https://docs.gtk.org/gobject/ +[at-spi2-atk]: https://gitlab.gnome.org/GNOME/at-spi2-atk +[GDBus]: https://docs.gtk.org/gio/class.DBusConnection.html +[ATK]: https://gitlab.gnome.org/GNOME/atk/ +[GNOME]: https://www.gnome.org +[docs-users]: https://help.gnome.org/users/gnome-help/stable/a11y.html +[gnome-a11y-wiki]: https://wiki.gnome.org/Accessibility +[kde-a11y-wiki]: https://community.kde.org/Accessibility |