Using FanFicFare with NonVisual Desktop Access (NVDA) - JimmXinu/FanFicFare GitHub Wiki

Introduction

NonVisual Desktop Access (NVDA) is "a free, open source, globally accessible screen reader for the blind and vision impaired."

NVDA URL: https://www.nvaccess.org/

This guide will hopefully help NVDA users be able to install and use FanFicFare in Calibre in a basic way. I also hope that NVDA users will contribute to this page for the benefit of all.

Note that it appears NVDA does not read text in the same line after a link. For that reason, I have avoided in-line links in this guide.

There are two versions of FanFicFare. Both require other software to run. One version is a GUI plugin for the Calibre e-book management software.

Calibre URL: https://calibre-ebook.com/

Generally, I recommend the plugin for most users. However, it is not my intention to make an NVDA guide to all of Calibre.

FanFicFare Calibre Plugin

This guide is based on a discussion from the FFF Google Group in late 2020. Not all of it is in the same 'Conversation' due to changing subjects and replies to other posts.

Discussion URL: https://groups.google.com/g/fanfic-downloader/c/uVnhJ0xbhbY/m/_birPSx0CAAJ

This guide gives shortcut keys, AKA hot keys for Calibre on Windows; other operating systems may vary. Mac users should generally use Command key instead of Control.

Calibre

The FanFicFare Calibre Plugin first requires that you have the Calibre e-book management software installed.

Calibre download URL: https://calibre-ebook.com/download

Calibre NVDA Addon

This guide also assumes you have installed the Calibre NVDA Addon. It provides the hot key F10 to access Calibre's main toolbar, where FanFicFare will appear by default.

Calibre NVDA Addon URL: https://addons.nvda-project.org/addons/calibre.en.html

Installing FanFicFare Plugin

Installing FanFicFare for the first time after installing and opening Calibre:

  1. Go into Preferences with Control-P. The Preferences window will open, it has five rows of buttons each with a group header. The bottom row is the Advanced group and the left most button is Plugins. I'm not aware of any way to get there by hot key, but mousing down, NVDA will read off the buttons and headers. For the Plugins button it reports: "Plugins. Add/remove/customize various bits of calibre functionality."
  2. Click Plugins to open the Plugins window. This window contains a grouped tree list of most of Calibre's functions, including installed plugins. What we're interested in right now is the 'Get New Plugins' button.
  3. Press Alt-N twice to move focus to the 'Get New Plugins' button, then press Enter. The User plugins window will open. By default, this window lists the available plugins that you don't already have installed.
  4. The plugin list already has focus when the User plugins window opens. If this is your first time installing FanFicFare, you can start typing f a n f i c f a r e and focus will move to that row. Don't pause too long between letters or the search will restart with the next key pressed. You can also arrow down to it.
  5. Once you have FanFicFare selected, press Enter install it. A confirmation dialog will open warning you about the possible dangers of plugin code. Click Yes, or press Enter or Alt-Y to accept it.
  6. The first time you install FanFicFare a dialog will open offering to add FanFicFare to toolbars or menus. By default, Calibre will add FanFicFare to the main toolbar. The Calibre NVDA addon makes accessing the toolbar with hot key F10 possible. Press Enter to accept.
  7. Another confirmation dialog will open, telling you that Calibre needs to be restarted after installing a plugin. Mouse, tab or arrow to the 'Restart calibre now' button, click it, or press Enter or press Alt-R.
  8. Wait for Calibre to restart.

Adding FanFicFare Plugin to Calibre's Menubar

Calibre is initially configured with the main toolbar showing. The main toolbar by default has many buttons on it and FanFicFare should now be the right most one. The Calibre NVDA Addon allows you to access Calibre's toolbar with hot key F10.

However, because the toolbar has so many buttons by default, it is easier to use FanFicFare if you configure it to also appear in Calibre's menubar.

  1. Go into Preferences with Control-P. The Preferences window will open, it has five rows of buttons each with a group header. The top row is the Interface group and the fourth button from the left is Toolbars & menus. I'm not aware of any way to get there by hot key, but mousing down and over, NVDA will read off the buttons and headers. For the Toolbars & menus button it reports: "Toolbars & menus. Customize the toolbars and context menus, changing which actions are available in each."
  2. Click Toolbars & menus to open the Toolbars & menus window.
  3. Press Tab three times to bring focus to 'Combo box: Click to choose toolbar or menu to customize'. Press Down Arrow four times to select 'The menubar'.
  4. Press Tab once to bring focus to the 'Available actions grouping' list. You can start typing f a n f i c f a r e and focus will move to that row. Don't pause too long between letters or the search will restart with the next key pressed. You can also arrow down to it. Arrowing up and down will cause NVDA to read the rows, searching doesn't seem to.
  5. Press Tab once to bring focus to 'Button: Add selected actions to toolbar' Press Space to invoke the add button.
  6. Press Tab eight times to bring focus to the Apply button. Press Space to Apply. Press Escape to exit Preferences.

Note that when a device, such as an Amazon Kindle, is attached to your computer Calibre uses a different menubar so that users can customize what tools are available then. To make FanFicFare available on the menubar when a device is attached, repeat the steps above, but when in 'Combo box: Click to choose toolbar or menu to customize', press Down Arrow five times to select 'The menubar when a device is connected'.

Using FanFicFare Plugin

  1. Copy the story URL.
  2. Open Calibre.
  3. Assuming you added FanFicFare to the menubar, press the Alt key to bring focus to the menubar, then Down Arrow to open the FanFicFare menu. Alternatively, using the toolbar:
    1. Press F10 and then Space to bring up the whole main toolbar. (Commonly the window will be too narrow to show all the toolbar buttons. NVDA indicates that by reporting 'check box not checked'. Pressing Space reveals the rest of the toolbar.)
    2. Assuming FanFicFare was the last plugin installed, Left Arrow should bring focus to FanFicFare, press Enter to bring focus and mouse pointer to FanFicFare.
    3. Right Click the mouse and then press Control-Enter to open FanFicFare's dropdown menu.
  4. From either toolbar or menubar, now press D for 'Download from URLs'. If you already had the story URL copied as suggested, it's already populated and you can just press Enter to start the download.
  5. The download will run in Calibre Jobs in the background. This can take anywhere from a minute to hours depending on the site and size of the story. When it finishes, Calibre presents a 'Proceed to update your library' dialog in the lower right corner. Unfortunately, this dialog doesn't appear to be one NVDA can recognize.
  6. After starting the download, press Alt-Shift-J to open Calibre's Jobs window that shows what's running in the background and whether it has finished. The FanFicFare job should be named 'Download 1 Fanfiction Book(s)' in the first column and the second column is status, which will be 'Finished' when it's done.
  7. Once the job is Finished, the 'Proceed to update your library' dialog should be open in the main Calibre window. Close the Jobs window, and once back in the main Calibre window, press Alt-Y to accept the 'Proceed to update your library' dialog.

Note that you can copy more than one story URL into FanFicFare to download at the same time. The job will only finish when all of them are done.

Opening the Downloaded Ebook

At that point, the downloaded book is in Calibre, as an epub format ebook by default.

You can select the downloaded book in the Calibre list and press the V hot key to open it in Calibre's book reader.

The S hot key will prompt you to save the ebook somewhere else if you want to.

The O hot key will open a Windows file browser showing where Calibre stores the file if you just want to open it in a different program from there. However, don't move or rename anything in Calibre's library directory. Use S to save it somewhere else in that case.

After Downloading

When viewing the Jobs window, all of the download jobs you've run since starting Calibre will be shown by default. However, there are buttons at the bottom for hiding and showing jobs.

It doesn't look like you can tab from the job list to those buttons, but pressing Alt-H twice brings focus to the 'Hide all jobs' button for me. And once focus is on one of the buttons, you can tab to the others.

Worst case, restarting Calibre (Ctrl-R hot key) will clear the jobs list.

FYI, new jobs are on top of the list, so the most recent job is always the one on top.

Installing FanFicFare Test Version

The procedure for updating Calibre and Calibre plugins when new versions are released is more properly documented by Calibre itself.

The FanFicFare Plugin is released roughly once a month. However, it is common for new FanFicFare features and bug fixes to be made available in a test version much more frequently. If you have a problem with FanFicFare, depending on what it is, it may be already fixed in the test version long before the next official release. But to use it, you have to manually download it and install it in Calibre first.

The latest FanFicFare Plugin test version is always attached to the same Mobile Read forum post in the FanFicFare thread. It is attached as FanFicFare.zip. (I'm not sure how you get there with NVDA and the attachment URL changes each time a new version is uploaded.)

Test Version Post URL: https://www.mobileread.com/forums/showthread.php?p=3084025&postcount=2

  1. Download and save the FanFicFare.zip file somewhere on your computer you can find it, but do not unzip it.
  2. Open Calibre.
  3. Go into Preferences with Control-P. The Preferences window will open, it has five rows of buttons each with a group header. The bottom row is the Advanced group and the left most button is Plugins. I'm not aware of any way to get there by hot key.
  4. Click Plugins to open the Plugins window. This window contains a grouped tree list of most of Calibre's functions. What we're interested in right now is the 'Load plugin from file' button.
  5. Press Alt-L to invoke the 'Load plugin from file' button. A file selector dialog will open.
  6. Navigate to where you saved the FanFicFare.zip file and select it. A confirmation dialog will open warning you about the possible dangers of plugin code. Click Yes or press Enter or Alt-Y to accept it.
  7. Another confirmation dialog will open, telling you that Calibre needs to be restarted after installing a plugin. For some reason, this one does not offer an option to restart immediately. Click Ok or press Enter.
  8. Press Escape twice to back out of the Plugins window and Preferences window back to Calibre's main screen.
  9. Press Control-R to restart Calibre.
  10. Wait for Calibre to restart.

FanFicFare Command Line

The command line version of FanFicFare requires the Python language runtime and is installed and run from a command prompt. The command line version is for users who are already comfortable with command prompt and plan to manage their e-book collection manually.

There are basic instructions on installing the command line version on the wiki home page:

Command Line Version URL: https://github.com/JimmXinu/FanFicFare/wiki#command-line-interface-cli-version