Close

Digital Education team blog

Home

Ideas and reflections from UCL's Digital Education team

Archive for the 'Tyson’s Tyrades' Category

Accessible documents from LaTeX

Jim R Tyson22 July 2020

Note: in this piece, many of the specific LaTeX examples are taken from package vignettes or documentation.  All packages mentioned have CTAN links.

ISD has published good general guidance on producing accessible materials on its Accessibility Fundamentals pages, with links to a host of useful resources.

While it is relatively straightforward to follow the guidelines and meet the standards set for users of Microsoft Office and for web developers, it is still not clear to many of us LaTeX (and I include markdown) users what we should and can (and maybe cannot) do.

I want to make a few points about the what, and then outline a few essential hows.

There are three aims here:

1. get as close as possible to producing ‘tagged PDF’ or PDF/UA documents using LaTeX;
2. produce HTML from LaTeX for screenreader software;
3. produce Microsoft Word from LaTeX for consumers who need to modify a document themselves for accessibility purposes.

These aims are met by using the LaTeX package accessibility and the open source document conversion utility pandoc.

The package accessibility is found on this CTAN page.  To produced structured, tagged PDF include

\usepackage[[tagged, highstructure]]{accessibility}

in the document preamble.

I am not adressing using Beamer here: the same general considerations apply and ordinary LaTeX techniques can be used. Beamer cannot currently be used with the accessibility package mentioned above. To add alternative text to a Beamer presentation you can use the package pdfcomment from this CTAN archive page. At the moment, I can offer no good solution for dealing with existing Beamer presentations, but ISD is looking into what might be doable, including working on the compatibility of the accessibility package and Beamer. I am now using markdown to produce html presentations rather than PDF.

Before I get into specifics, I want to emphasize that where possible, we should try to provide people with documents that they can modify to suit their needs and that therefore in many cases a Microsoft Office or HTML document is more usefully accessible than a PDF. Pandoc makes conversion from LaTeX to HTML very simple and you can use LaTeX mathematics in your documents to be converted to HTML with either MathML or Mathjax options.

Text

LaTeX users producing text documents are probably already covering the need for clearly structured text with headings by using the \section{} family of commands. It is worth considering use the package hyperref so that you can create clickable cross-references in your documents and a clickable table of contents. Screenreader users will find hyperlinked sections and a clickable table of contents very useful.  Hyperref can also take care of the language metadata of your PDF. Programs that access your PDF should be able to determine the language (or main language) of the document.  One way to do this is to include this hyperref command in the preamble (after calling the package hyperref):

\usepackage[pdflang={en-GB}]{hyperref}

Using a sans serif font, like computer modern sans serif will help make your document easier to read. LaTeX users who are typesetting mathematics should note that what research has been published has not – to my knowledge – addressed the issue of font choice for mathematics (or logic, or linguistics, chemistry and so on). Just as important is to use a good size for text. I try to use 12pt body text and 14pt and 16pt headers. The code to change font is as follows and should be in your preamble

\renewcommand{\familydefault}{\sfdefault}

You can use the package setspace to change linespacing in a document to 1.5, with the command

\onehalfspace

Many readers benefit from slightly wider than normal margins.  The default margins for LaTeX documents are already quite generous leading to a line-scan length that is comfortable for most readers.  If you do wish to change the margins, you should use the package geometry from this CTAN archive. There are a number of ways to use geometry.  You can use it with options in your preamble like this:

\usepackage[margin=1.5in]{geometry}

or

\usepackage[total={6.5in,8.75in},top=1.2in, left=0.9in, includefoot]{geometry}

Or you can use the command \geometry{} in your preamble like this:

\geometry{a4paper, margin=2in}

Use bold \textbf{} for emphasis and avoid italic. If you wish to modify an existing document that uses \emph{} (which we have conscientiously preferred for decades) you can include the following code

\makeatletter
 \DeclareRobustCommand{\em}{%
    \@nomath\em \if b\expandafter\@car\f@series\@nil
    \normalfont \else \bfseries \fi}
\makeatother

in the preamble of your document to change the default appearance of emphasis.

You can use the package xcolor available from this TeX archive page and command \pagecolor{Ivory} (for example) to change the background colour of a PDF for electronic use.

Make your hyperlinks clearly distinguishable from text; make them meaningful (don’t use the URL itself or text like ‘click here’; make sure that any colour contrast complies with the guidelines on this WCAG colour contrast guidance page.) If your document is likely to be disseminated in print form, then it is useful to add a short and easily typable URL for print format readers, eg https://tinyurl.com/contrastguidance.

To get a properly presented URL use code like this:

\href{http://www.ucl.ac.uk/isd}{ISD home page.}

To control the colours used with hyperlinks you can include something like the following in your preamble after calling the hyperref package:

\hypersetup{
    colorlinks=true,
    linkcolor=blue,
    filecolor=magenta,
    urlcolor=cyan
}

Images and tables

The package accessibility mentioned earlier, provides a LaTeX command \alt{} which can be used to add alternative text in any float environment.  Unfortunately \alt{} from package accessibility cannot be used with the Beamer presenation package.

While good captioning for images and tables will enhance accessibility, where necessary alternative text should describe not just what data is in a table for example EU GDP by Country 2010 to 2018 but what its relevance is : EU GDP by Country 2018 to 2020 showing the trend of reduced growth over time. The reader may choose to skip the data table sometimes if the alternative text is clear enough. Also be sure to use \lable{} and \ref{} to enable screenreader software to quickly locate relevant data or images.

If you use images which are essentially decorative, then use \alt{} to let the screenreader software know that.

Mathematical content

LaTeX source code including mathematical content can produce screenreader friendly HTML via pandoc. The best result with most modern browsers (including Edge, Safari, Chrome and Firefox) is achieved using the MathJax option on conversion. The instructions to do this are on the pandoc demo page. In all examples so far tested (and we will test more, and more fully) the mathematical content was read semantically rather than typographically so that a fraction is read “fraction with denominator X and numerator y” (with some minor variation, ie sometimes reading “ratio” rather than “fraction”).

Matthew Towers has written a useful page about accessibility and pdf files, although it has been overtaken by events with respect to useful LaTeX packages.

The TeX User Group (tug) web page on PDF accessibility and PDF standards is unfortunately of largely historical interest.

Software for Success

Jim R Tyson3 October 2019

What does it take to succeed in a student research project, or any research project for that matter?

Well, there’s a whole lot of stuff that Digital Skills Development can’t help with, and anyway, you’re all really good at that stuff: the scholarship, the domain knowledge, the research skills.  But, there’s an awful lot that we can offer.

Getting on top of the choices that face you now and planning what tools you will use will allow you to work out what skills you need to acquire and how you are going to acquire them.  And beefing up your digital capability will not only improve your chances of research success, but will add to your capital in an area that employers rate among top desirable job skills.

When people plan research projects, they often forget to work out what software tools and techniques they will use, what skills those tools require, and where they are going to get those skills.  Often, we think it will all just be obvious and somehow it will come together.  Well, in a way it usually does, but with a little planning and foreknowledge, we can transform these decisions from afterthought to opportunity.

Digital Skills Development are showcasing three new demonstration sessions to put you on the road to software success.  Each session introduces tools to tackle specific tasks for your research project.  We’ll look at:

1. writing: is there life beyond Word?  Is there any reason to go there?  How do I cope with fussy formatting requirements?
2. data analysis: is it worth learning to code, or can I cope by wrestling with my data in Excel?  I don’t do numbers, how can software help me?
3. managing literature: imagine a world where your library and database searches link seamlessly  with your citation system and a database of annotated PDFs.  That world can be yours.

If you haven’t thought about what tools you will use for each of these tasks, or if you have thought about it but you’re just not sure what to do, these sessions are for you.  There will be demonstrations of different tools and approaches with guidance and discussion of what tool is best for the job.  If you think you know what software you are going to use, then we invite you to come along and  be challenged: there may be tools on offer that could smooth the way to a successful research project.

For the new year we are adding three In a nutshell sessions.  These are short sessions – usually around lunchtime – which illustrate a specific technique in one or other software package, so for example, we will be looking at importing survey data into Nvivo for analysis.

Now is the time to move beyond those good old coping strategies and tame the software beast.  These sessions will help you do it.  You can reserve your place on our booking system  which you can also find at https://tinyurl.com/s4s-ucl.

Digital evening classes?

Jim R Tyson1 October 2018

This term, for the first time that I know about, the Digital Skills Development team are offering sessions in the evening. I had intended to write a blog post ready for this morning promoting these sessions and encouraging people to sign up. Alas, I fell behind. However, when I logged on this morning to check our schedule of training and bookings, I was delighted to see that the two evening training sessions for R and RStudio have already attracted more bookings than any other session – and this just a few hours after booking opened!

It will be interesting to find out how popular and successful this experiment is. If the demand is there for out of hours sessions in Digital Skills Development then we may be able to increase the offer. Do you find the idea of an evening class in digital skills attractive? Let us know in the comments.

Introducing StepShot Manuals

Jim R Tyson8 February 2018

For a while now, I have been quietly promoting StepShot Manuals (StepShot for short) to my colleagues in ISD. StepShot is a rapid documentation development tool. Which is not nearly as bad as it sounds. StepShot allows you to record an on-screen process – for example, formatting a table in Word or filling out an expenses form – taking screenshots, adding callouts and annotations and writing explanations as you go.

Some key uses for StepShot include

• rapid development of training materials and technical documentation
• developing test scripts for UAT
• recording test results or bugs
• creating knowledgebase articles
• recording process for business analysis and process review

If you have ever done these jobs, then you might have combined several tools, for example

a screenshot tool (Windows has one built in), Word, an image editor (Paint or Photoshop), with a workflow like this: take all your screenshots, insert them into word editing, cropping etc as you go, adding explanatory text.

Stepshot brings all this together in one tool. You set it up to record the activity and select to create a screenshot for mouse clicks or keyboard actions or to use a specific hot key combination for screenshots. As you go through the activity recording images you can also give each a descriptive title and a comment. When you stop recording StepShot opens its editing tool. This latter looks a bit like PowerPoint: your images are listed vertically down the left while the main window allows you to edit an image and add text.

Click to see the animation!

This is already a vast improvement on hacking documents together with separate applications, none of them specifically designed for the job, but wait there’s more! StepShot can export your document when you have finished, as Word, PDF, HTML, XML or DITA and can publish directly to Confluence, SharePoint or WordPress. (If they add a PowerPoint option I’ll throw a party). There are simple built in templates for output and with a little effort you can create a customised or branded template.

So, currently about a dozen people at UCL have taken up a license (UCL staff members can contact ISD Training Administration for licensing information. To use StepShot you do need admin rights on your Windows or Mac PC.). It has been used to create training materials for lecturecast (published on Confluence), it has been used in UAT creating test scripts, it has been used by software testers to record bugs and communicate them to developers. No one currently using it has had more than a two minute informal introduction to the product but people seem to pick up its basic use very quickly. Users report that they enjoy using it as well. The most commone response using it for the first time has been about the immense time savings you can achieve and next about the simplicity of use. One or two people have commented that they don’t really like the look of the output, but this is largely because they haven’t learned how to customise output. I have offered a short workshop on customisation and hope to run it again.

I have created a Microsoft Team site and I will be keeping in touch with people using it since I have been asked to feedback our experience to the developers.

Review: Automate the Boring Stuff with Python

Jim R Tyson4 April 2017

Author: Al Sweigart
Materials:
Book  $29.95 print,$23.95 e-book or from Amazon £15.54 print, £11.39 Kindle.
Website
Youtube fifteen free videos from the Udemy course
Udemy: £50 (Discounted to £10 as at 4/4/2017 ) fifty one lectures following the book

Python is often said to be a fun language to learn. Programming is sometimes said to be fun to learn. The combination ought to be fun too.  My lasting impression of these materials is that they are fun.

Learners often find that resources for beginners self-tuition in programming are either daunting, or badly designed, or too simple minded to be of real help. This set of resources scores highly on all of these.

Automate the Boring Stuff with Python is a book that is accompanied by a website, some youtube videos, and (for pay) a Udemy online course. There are eighteen reasonable length chapters and three appendices. The first ten chapters cover the absolute basics of procedural programming starting with simple interaction with the interpreter (do some sums!) through variables and assignment, flow control, writing functions, complex data structures, strings, input and output and debugging. There are one or two other topics that it was interesting to see dealt with relatively early such as searching with regular expressions and file manipulation – including compression, bulk filename routines – but they are simply explained and they make sense given the intention of the material (automating stuff). The book is well designed and clearly written. The website has the same material but includes an in-line interpreter so that you can type code as you go, make mistakes and correct them, and see the results when, finally, you get it right. I watched the free youtube videos and they were well made with clear explanations as were the other free tasters of the Udemy course.  The youtube videos get a big thumbs up in their comments sections.

Overall, I think these materials are a good start for a beginning programmer who isn’t intending to become a software engineer. It would suit a learner whose aim is to write programs intended mainly for their own use. It doesn’t cover some topics that are increasingly included in early training for programmers, for example version control or test driven development, but for many learners overcoming the initial barrier to writing some effective code is more important than these aspects of best practice. The use of object methods, defensive programming and more can be tackled later.

The second part of the book and course introduces the use of python libraries for some common and useful tasks. This section includes a variety of projects including web scraping, working with spreadsheets and word processor documents, integrating email in programs. In a higher education context you might want to include numpy, scipy, matplotlib but there are good tutorials for these – good at least for someone who already has basic coding skills and is familiar with the use of libraries – exactly where someone would be after finishing this course.  They are good choices if you want to learn scripting to automate the boring stuff, maybe periodically grabbing data from a website or a spreadsheet and transforming it before writing to a new file for example.

It’s particularly nice that the website has an embedded interpreter, but I think you would want learners to move onto an IDE eventually and perhaps in some contexts you might want to replace the use of the in-line interpreter with iPython notebooks.

Overall this is one of the best resources for beginning programmers I have seen and as a suite of resources it could be easily supplemented and adapted to meet an expanded or amended set of objectives.