Metadata-Version: 2.1
Name: gla11y
Version: 0.4
Summary: Automatic check of accessibility of .ui files
Home-page: https://github.com/hypra/gla11y
Author: Samuel Thibault
Author-email: sthibault@hypra.fr
License: UNKNOWN
Description: GLA11Y (glade accessibility)
        ======
        
        This tool checks accessibility of GtkBuilder .ui files
        produced e.g. by glade.
        It looks for various issues, and notably missing or bogus labelling
        relations.
        
        It can for instance be used in Continous Integration checks to make sure not to
        introduce accessibility regressions.
        
        
        This file describes the tool itself.
        
        The HOWTO.md file describes how to fix the warnings raised by the tool.
        
        
        Installation
        ------------
        
        Just run
        
        	make install
        
        and gla11y will be installed in /usr/local/bin/ by default (can be changed by
        appending prefix=... on the make command line).
        
        
        Basic use
        ---------
        
        The typical use is running
        
        	gla11y $(find . -name \*.ui)
        
        which will emit all kinds of warnings.
        
        
        Using suppressions
        ------------------
        
        If there are a lot of warnings for existing issues, it may be preferrable for a
        start to only show new warnings: run once
        
        	gla11y -g suppressions $(find . -name \*.ui)
        
        to create a `suppressions' file which contains rules to suppress the warnings
        found at the time of generation, and after that,
        
        	gla11y -s suppressions $(find . -name \*.ui)
        
        will only display warnings for new issues.
        
        If the paths given to the tool are absolute, the -P option allows to remove a
        prefix from the paths.
        
        
        Application-specific widgets
        ----------------------------
        
        By default, gla11y knows about Gtk standard widgets.  If the application has
        its own self-baked widgets, it may be useful to teach gla11y their role, for
        instance:
        
        	gla11y --widgets-ignored +myVBox,myHBox --widgets-needlabel +myEntry $(find . -name \*.ui)
        
        The default list of recognized widgets can be obtained with --widgets-print.
        
        
        Enabling/Disabling warnings
        ---------------------------
        
        Especially when starting running gla11y over a very big project with a lot
        of existing warnings, it is useful to enable warnings progressively. The
        --enable/disable options can be used to that end. Their effect accumulate, i.e.
        each --enable/disable option overrides the effect of previous options. For
        instance:
        
        	gla11y --disable-all --enable-type undeclared-target $(find . -name \*.ui)
        
        will only enable the undeclared-target warning type, while
        
        	gla11y --enable-all --disable-specific no-labelled-by,GtkSpinner $(find . -name \*.ui)
        
        will enable all warnings, except no-labelled-by for GtkSpinner widgets.
        
        
        Fatal errors/warnings
        ---------------------
        
        By default, only errors are fatal.  One can however fine-tune this, for instance:
        
        	gla11y --fatal-all --not-fatal-widgets myWidget $(find . -name \*.ui)
        
        makes all warnings (and errors) fatal except for myWiget widgets.  Conversely
        
        	gla11y --not-fatal-all --fatal-type undeclared-target $(find . -name \*.ui)
        
        makes all warnings and errors non-fatal, except error undeclared-target.
        
        
        False positives
        ---------------
        
        We have taken great care to avoid false positives, but sometimes they just can't
        be detected automatically :) The simplest way to avoid them is then to blacklist
        them. The -f option can be used like -s to suppress warnings, except that they
        will not be reported at all any more.
        
        This means that after creating a suppression file that silents the existing
        errors to concentrate first on avoiding new accessibility issues, one can work
        on warnings for existing issues by either fixing them, or moving the suppression
        line from the suppression file passed to the -s option to the suppression file
        passed to the -f option.
        
        
        Integration in a build system
        -----------------------------
        
        To integrate the use of gla11y in a build system, you can for instance add to
        configure.ac:
        
        	AC_PATH_PROG([GLA11Y], [gla11y], [true])
        
        and introduce a new Makefile.am rule to trigger a call to gla11y:
        
        	ui_files = foo.ui bar.ui
        
        	GLA11Y_OUTPUT = ui-a11y.err
        	GLA11Y_SUPPR  = ui-a11y.suppr
        	GLA11Y_FALSE  = ui-a11y.false
        
        	GLA11Y_V = $(GLA11Y_V_@AM_V@)
        	GLA11Y_V_ = $(GLA11Y_V_@AM_DEFAULT_V@)
        	GLA11Y_V_0 = @echo "  GLA11Y  " $@;
        	GLA11Y_V_1 = 
        
        	all-local: $(GLA11Y_OUTPUT)
        	$(GLA11Y_OUTPUT): $(ui_files)
        		$(GLA11Y_V) $(GLA11Y) -P $(srcdir)/ -f $(srcdir)/$(GLA11Y_FALSE) -s $(srcdir)/$(GLA11Y_SUPPR) -o $@ $(ui_files:%=$(srcdir)/%)
        
        	CLEANFILES += $(GLA11Y_OUTPUT)
        	EXTRA_DIST += $(GLA11Y_SUPPR) $(GLA11Y_FALSE)
        
        and you can generate ui-a11y.suppr from an initial call to gla11y from the
        source tree:
        
        	gla11y -g ui-a11y.suppr foo.ui bar.ui
        
        in order to ignore the existing warnings for a start.
        
        
        From then on, the gla11y call will error out if new fatal warnings are produced,
        thus avoiding the corresponding accessibility regressions.  The existing
        warnings can then be worked on progressively, removing the corresponding
        suppression rules from the .suppr files accordingly.  In case of false positives
        from the tool, they can be transferred from the .suppr file to the .false file.
        See HOWTO.md for more details on the methodology, which you can point developers
        to.
        
        
        Credits
        -------
        
        Gla11y was developped by Hypra (http://hypra.fr/) and Martin Pieuchot under
        the funding of The Document Foundation tender to implement accessibility
        improvements (#201704-01)
        
Platform: UNKNOWN
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: ISC License (ISCL)
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Quality Assurance
Description-Content-Type: text/markdown
