Welcome to Picardy 1.0!
Picardy is free, freely-distributable software for editing and formatting back-of-the-book indexes.
“Picardy” stands for “Index CARDs in PYthon, which is the programming
language that the software was developed in. Also a region in France!
Overview
The Picardy editing model is based on the idea that most of the time, index entries can be represented using a simple plain text notation. For example, a book on wildlife could contain entries such as the following:
bears, 25
grizzly, 33
ursines (see bears)
pandas, 67 (see also bears)
teddy bears (see under bears)
koalas, 92 (see also under bears)
Each of these can, respectively, be expressed in Picardy’s notation:
bears#25 bears>grizzly#33 ursines=bears pandas#67 pandas+bears teddy bears<bears koalas#92 koalas<<bears
As you can see, the ‘#’ character separates the heading part of the index entry from the page number. Similarly, ‘=’ indicates “see’, ‘+’ means “see also”, and so forth. If there is more than one level of heading, the headings are separated by the greater-than (‘>’) character.
Users who find this way of entering data copacetic can write an entire index just using plain text. For users who prefer a more graphical environment, Picardy provides editing dialog boxes and other editing tools.
The Picardy window consists of two panes: the Edit pane on the right is for entering raw plain text input, which, taking some liberties, will be referred to as index “cards.” The format for these cards, such as those in the examples you just saw, is described in detail below. You can type directly in the Edit pane or click the adjacent New… (or Ctrl+K) and Edit… (or Ctrl+E) buttons
to enter content via dialogs.
The Preview pane on the left shows a formatted, sorted, and collated version of the index. Since final formatting of indexes is generally carried out by the client publisher, the preview cannot show exactly what the finished index looks like, but it can give an approximation of its form and structure. Click Preview or press Ctrl+I to refresh the preview. The preview will refresh automatically if you press Enter, delete a card (Edit > Delete Card), create a new card, or delete a line.
Click Save to save the raw input, and Export… to save the formatted index in one or more formats. The available formats are HTML, RTF (styled and unstyled), plain text, Cindex™ IXML, and SKY Index™ 8.0 (.txtsky8). These are the formats in which the finished index may be submitted to your client or publisher.
View > Settings enables you to specify how the index will be formatted: indented or run-in, letter-by-letter or word-by-word alphabetization, reference format, and so forth. You can also select the export formats.
The Edit pane has Notepad-like capabilities, but Picardy also provides a set of tools to enhance editing.
- You can right-click in either pane to jump to the corresponding location in the other pane.
- Tools > Character Map facilitates entering characters in various languages and scripts.
- You can find and replace (Edit > Find) in the Edit pane and find content in the Preview pane.
- Input can be validated (Tools > Validate) to detect errors such as invalid characters and page ranges.
- You can set some styles (View > Styles) of the two panes such as font and font size, and display the special characters (>, <, #, =, +) in the input pane in a different color to make them stand out from the headings.
- Press Ctrl+1 to flip a heading with the one below it.
- Press Ctrl+2 to duplicate the current heading.
- Press Ctrl+3 to replace a “See” entry with an equivalent double-post entry.
- Edit > Collapse will reduce the current card to the main heading plus the page numbers or reference. Edit > Collapse All Like This will collapse all cards that have the current main heading.
- Check for undifferentiated locators (the default maximum is six) with Tools > Check Undifferentiated.
- You can enter notes associated with the index in a scratchpad (View > Scratchpad).
- Spell-checking is available (Tools > Check Spelling or press F2)
in English and five other languages. - Various macros manipulate the contents of the clipboard and paste the results to the Edit pane.
- You can highlight (Tools > Highlight or press F7) text in colors of your choice. These highlights persist after you close the file.
- As you type in the Edit pane, Picardy will attempt to autocomplete the current word, using words that you have already entered. To cycle through the available choices, press Esc; to accept the current suggestion, press Tab.
- Edit > Capitalize (or uncapitalize) main headings and references.
- Edit > Paste Formatted will paste bold and italic text copied from
Microsoft Word or a web browser into the Edit pane using Picardy’s formatting markup (Windows only).
If you have an existing index in Cindex™ IXML format or SKY Index™ 8.0 (.txtsky8) you can import it into Picardy using File > Import.
Creating an index
The input for Picardy consists of a plain text file. The Edit pane provides an environment for creating this file but you can also do so with standard Windows tools such as Notepad and Wordpad and paste the results in the Edit pane for further processing. Notepad++ is a recommended Windows freeware third-party text editor that provides a fully-featured editing environment.
You can get an idea of what the raw index input file looks like by opening Samples/sample.txt in the folder where you installed Picardy.
Note: Feel free to modify the sample file if you want to experiment, but if you want to save it on Windows you’ll have to do so in a different folder, such as somewhere underneath your Documents folder.
New… and Edit…
You can use New… and Edit… and not have to worry about the syntax described below.
You can enter up to three levels of headings and the page number or reference. New entries can be inserted after the current insertion point or at the bottom of the pane.
Working in the Edit pane
This section describes the plain text notation for entering cards. It’s up to
you whether you use this format or the editing dialogs above.
To create a main heading for “bears” referring to page 25:
bears#25
The heading is separated from the page number by the ‘#’ symbol.
You can specify more than one page number, or a range, separated by commas:
bears#25,27,30-35
You can use lowercase roman numerals:
bears#ii,xv-xix
You don’t have to put all of the page numbers for a heading on the same line:
bears#25 ... bears#27,30-25 ... bears#100-102,107
You don’t have to put all the lines with the same headings together in the input, and the numbers don’t have to be in increasing order:
bears#25 bulls#26 swans#27 bears#30 bears#iv swans#19 bulls#6
You can enter the page ranges in any order:
bears#107,100-102,25
If you are using two-part page numbers, separate the pages in a range using a forward slash (/) instead of a hyphen:
ursines#1-6/1-9,2-10/2-16
Annotations
Single page numbers can have annotations such as n, n2, ff. etc. Page ranges can have the annotation passim.
bears#27n1,32fig,77ff.,110-130passim
The special annotation tbd (in any case combination) can be used to designate a placeholder card, for when you know you want to index a certain term but don’t yet have the specific page number(s). It is processed like any other annotation, but you will get a warning in the export report if such an annotation is still present.
bears#99tbd
Overlapping ranges
Overlapping pages and page ranges will be combined. For example:
bears#15-20 bears#20-25
This will be interpreted as:
bears, 15-25
Similarly:
bears#20 bears#23 bears#20-25
Produces:
bears, 20-25
Annotated pages are an exception to this:
bears#23n1 bears#20-25
This will produce:
bears, 20-25,23n1
Adjacent but non-overlapping ranges will not be combined by default, but you can turn this on in the Settings dialog.
bears, 15-19,20-25,26
Sub-headings
To create a sub-heading, separate it from the main heading with a ‘>’ (greater-than) symbol.
bears>grizzly#34 ... bears>Kodiak#92-95
You can have up to three levels of headings.
bears>grizzly>geographic range#38 bears>grizzly>hibernation#40
“See” references
To create a “See” reference, use the “=” symbol:
bruins=bears bears>teddy=Winnie the Pooh
This produces entries like:
bruins (See bears)
bears
teddy (See Winnie the Pooh)
“See also” references
To create a ‘See also” reference:
bears#25 bears+stock market
This will create an entry like:
bears, 25 (see also stock market)
“See (also) under” references
Similarly, you can create “See under” and “See also under” references.
Use ‘<’ (less-than) to indicate “See under”:
teddy bears<bears
Use ‘<<’ (two less-than symbols) to indicate “See also under”:
teddy bears<<stuffed animals
Formatting
You can add some basic formatting to headings.
Surround text with underscores “_” to italicize it:
_Setting Free the Bears_ (novel)#99
This will produce:
Setting Free the Bears (novel), 99
Surround text with asterisks “*” to bold it:
*The Bad News Bears* (film)#134
The Bad News Bears (film), 134
For bold-italic formatting, you can combine asterisks and underscores:
_*The Bad News Bears*_ (film)#134
Or surround the text with percent signs:
%The Bad News Bears% (film)#134
Similarly, you can apply formatting to individual single-part or two-part page numbers (but not ranges) to
denote pages with figures, tables, etc.:
bears#25,_26_ cats#*2-11*, 3-6
(To apply bold-italic to page numbers, you must use the ‘%’ notation.)
Ignored input
A line starting with a number sign “#” will be ignored.
#Chicago Bears (sports team)<bears
In the Edit pane you can toggle this on and off for the current card by pressing Ctrl+Q
Blank lines in the input will be ignored.
In the Settings > Export tab you can choose to include ignored cards in the index.
To delete ignored and blank cards, click Edit > Delete Ignored/Blank Cards (Ctrl+4).
Inherited headings
If you group similar entries together you can take advantage of a shortcut that can save some typing. A heading that is left blank will, if possible, be inherited from the previous line:
bears#25 >grizzly#38
In this example the missing main heading will be assumed to be “bears”, so these lines are equivalent to:
bears#25 bears>grizzly#38
The main heading is also inherited in this example:
bears>black#25 >grizzly#38
This is the same as:
bears>black#25 bears>grizzly#38
Sub-entries can also be inherited:
bears>grizzly#32 >>Canadian#37
Both the main heading (“bears”) and sub-heading (“bears”) are inherited in the second line.
You can continue the inheritance as long as you need to:
bears>grizzly#32 >brown#42 >>North American#43 >in the air#44
This is equivalent to:
bears>grizzly#32 bears>brown#42 bears>brown>North American#43 bears>in the air#44
It is an error if a heading is omitted that cannot be inferred from preceding content:
bears#35 >>Arctic
In this case the first sub-heading cannot be inferred in the second line.
Abbreviations
You can define abbreviations to make it easier to enter frequently used text such as names. For example, “ob” could represent “Obama, Barack”. To use the abbreviation in an index card, you would enter a dot followed by the abbreviation:
.ob>presidency#28-40
To define abbreviations, click Tools>Abbreviations.
Picardy uses two sets of abbreviations, system and index-specific. If there is no current index or the current index is untitled, only the system abbreviations are available; these can be used for all indexes, and any changes you make will be saved to the system abbreviations. If the current index has a title, then you can also define, edit and use index-specific abbreviations; the system abbreviations cannot be edited in this case.
Click Add to define a new abbreviation. To delete an abbreviation, you can click the corresponding Delete checkbox and then click Delete Marked. Alternatively, any abbreviations that are marked for deletion or that have a blank name or definition will be deleted when you click Save or Close.
You can use an abbreviation to get around the prohibition on the characters #><+=_* appearing in headings. For example, you could define an abbreviation cpp to represent the name of the programming language C++ and then create a card as follows:
programming languages>.cpp#29
If you don’t remember an abbreviation, you can right-click in the Edit pane and click Insert Abbreviation from the pop-up menu to see a dialog box of available abbreviations.
Realphabetizations
You may want to override the default alphabetization of certain headings such as those that start with a number or special character. By default, all of these will be grouped before any headings that start with a letter—that is, before the A’s. There are a number of realphabetizations that you can use.
To alphabetize numbers as if they were spelled out, click Alphabetize numbers as words in the Alphabetization tab of the Settings dialog.
This realphabetization may not always give you the result you want, however. The heading “24 Sussex Drive” will be grouped with the T’s as expected, but “1600 Pennsylvania Ave” will be grouped with the O’s (one thousand six hundred). If you want “1600” to be read as “sixteen hundred”, you can define a custom realphabetization.
Click Tools > Realphabetizations:
As with abbreviations, there are both system and index-specific realphabetizations. Adding and deleting realphabetization terms works the same as with abbreviations.
Note: Custom alphabetization must be turned on explicitly in the Settings > Alphabetization tab.
Since realphabetizations are processed after abbreviations, you can also control the alphabetization of content expressed in an abbreviation, including text containing one or more of the #><+=_* characters. The realphabetization must be applied to the abbreviation definition, not the abbreviation itself. To continue the C++ example above, you could realphabetize it as cplusplus, which couldproduce the following ordering in the index:
cats, 33
C++, 19
You can insert one-time inline realphabetizations in the Edit pane. To ignore characters in the alphabetization, enclose them in curly braces:
{Mr. }Rogers#34
This entry will be alphabetized with the R’s.
You can enter text that will be used for alphabetization but not appear in the index by surrounding it with carets:
^Señor^{Mr. }Rogers#34
This entry will be alphabetized with the S’s but will appear as Mr. Rogers, 34.
Function words
You can configure Picardy’s alphabetization to ignore certain words (such as in and of) at the beginning of subheadings. Picardy’s default configuration specifies the following words:
in, of, for, with, after, and, by, as, a, an, the
You can add or delete words by clicking Tools > Function Words. As with abbreviations, there are both system and index-specific function words. Adding and deleting function words works the same as with abbreviations.
Note: Function words are ignored by default. You can change this behavior in the
Settings > Alphabetization tab.
Macros
Macros are functions that carry out some manipulations of the contents of the Windows or Linux clipboard and paste the results in the Edit pane. Typically, the clipboard is expected to contain one or more personal names or a title.
Macros are accessible in the Macros menu and/or via keyboard shortcuts.
Invert (Ctrl+F1) puts the last word (name) in the clipboard first, followed by
a comma and then the other names. For example, George Walker Bush will become:
Bush, George Walker#
Notice that the page number indicator, ‘#’, has been inserted after the name.
You could add a page number immediately or do it later.
Invert and Initialize (Ctrl+F2) also inverts the contents, but converts all names except the last one to initials. The example above would become:
Bush, G. W.#
Invert and Initialize (no dots) (Ctrl+F3) does the same, but doesn’t insert dots and runs the initials together:
Bush, GW#
Split at Commas (Ctrl+F4) processes a comma-separated list of names or phrases and creates a separate index card for each. The text London, New York, Toronto, Paris, and Tokyo will become:
London# New York# Toronto# Paris# Tokyo#
Split at Commas and Invert (Ctrl+F5) processes a comma-separated list of names, inverts them, and creates a separate index card for each. The text Bill Clinton, Pierre Trudeau, Ronald Reagan, Jean Chrétien, and Barack Obama will become:
Clinton, Bill# Trudeau, Pierre# Reagan, Ronald# Chrétien, Jean# Obama, Barack#
The following are available from the keyboard only:
Split at Commas and Ask Page (Ctrl+F6) is similar to Split at Commas but it also shows a dialog asking for an (optional) page number. If you supply one, it will
be added to each of the index cards:
London#72 New York#72 Toronto#72 Paris#72 Tokyo#72
Split at Commas, Invert, and Ask Page (Ctrl+F7) is similar to Split at Commas and Invert but asks for a page number.
Clinton, Bill#88 Trudeau, Pierre#88 Reagan, Ronald#88 Chrétien, Jean#88 Obama, Barack#88
Surround with Double Quotes (Ctrl+” on Windows, Ctrl+Shift+Q on Linux)
surrounds the clipboard contents with double quotes
Surround with Single Quotes (Ctrl+’ on Windows, Ctrl+Shift+U on Linux)
surrounds the clipboard contents with single quotes
Italicize (Ctrl+Shift+I) italicizes the clipboard contents
_The Birds_#
Embolden (Ctrl+Shift+B) bolds the clipboard contents
*animals*#
Picardy settings
There are a number of settings to configure the output and input.
Click View > Settings:
There are system and index-specific settings. System settings will apply if the current index is untitled; any settings that you make in this case will be saved to the system settings.
General settings
Here you can choose the overall style of the index—indented or run-in. If you choose a run-in index and there are three-level entries in the input, then the second-level headings will be indented, but only for sub-entries of the corresponding main heading.
Page numbers can be single-part or two-part. For two-part numbers, choose the separator between the chapter and page number. Chapter numbers can be numbers or uppercase letters.
Typical subheading order is alphabetical, but you can change it to page number order or use a custom ordering. Custom ordering is implemented by clicking Custom in the General tab, and in the input, prefixing the subheadings with the notation !n: where n indicates the order. When the index is processed, the special characters will be stripped out and the headings will follow the ordering specified.
Jams O'Donnell>!1:birth#25 Jams O'Donnell>!2:marriage#50 Jams O'Donnell>!3:prison term#22 Jams O'Donnell>!4:death#11
If you are using custom ordering and don’t specify a specific ordering, ordinary alphabetic order willbe used.
By default page numbers will be output in full, but you can choose Chicago Manual or Oxford Guide (also known as Hart’s) compression instead.
Note: The specifications for these styles are taken from Nancy Mulvany’s “Indexing Books”, Second Edition, chapter four.
You can also compress the page ranges in your input. The compression style is “modified Oxford” whereby any digits omitted in the endpoint of the range will simply be replaced by the corresponding digits in the starting point. So, for example, 9871-5 will be interpreted as 9871-9875; 9871-89 will be interpreted as 9871-9889.
Note: Input and output page compression is available for single-part numbers only.
You can choose to conflate consecutive page numbers on output, so that, for example 23,24,25 will become 23–25. This works for two-part numbers as well, but only numbers within the same chapter will be conflated.
The maximum undifferentiated locators setting will control the Tools > Check Undifferentiated menu item. The default maximum is six; in this case seven or more locators for the same heading will be flagged. This does not
prohibit you from using more locators if you choose to.
Alphabetization settings
By default headings are alphabetized letter-by-letter, but you can change this to word-by-word.
You can choose to alphabetize roman numerals as-is (“XX Century” will be alphabetized with the X’s), as decimal numbers (“XX” is treated as “20”), or spelled out (“XX” is treated as “twenty”).
Function words in subheadings will be ignored in alphabetization; click Alphabetize function words to change this.
Alphabetize numbers as words will cause numbers to be alphabetized as if they were written out in English.
Names starting with Mc can be alphabetized as if they start with Mac (so McAndrew would precede macaroni, for example.
Custom alphabetizations override the defaults and may be useful for headings starting with numbers or other non-alphabetic characters. See the section Alphabetizations above for more information.
Alphabetizing Unicode characters as ASCII will cause words with “accented” characters to be treated as their a-z equivalents, so “François” will be ordered like “Francois” and will come before “Frank”. Additionally, words written in other scripts (such as Cyrillic) will be processed in their Latinized form.
Leading articles (a, an, the) will by default be ignored in alphabetization.
Reference settings
See, See also, See under, and See also under references can be formatted in any of three ways:
bruins (see bears)
bruins. See bears
bruins, see bears
These correspond to the settings Parenthesized, Uppercase, and Lowercase, respectively.
“See also” and “See also under” are placed at the beginning of a list of page numbers and/or subentries; you can change this toplace them at the end.
Export settings
You can export the index in six formats: plain text, HTML, RTF, plain RTF, Cindex™ IXML, and SKY Index™ 8.0 (.txtsky8).
Plain RTF is an RTF file in which no styles have been applied.
By default, headings are followed by a comma, but this can be suppressed
Plain text and plain RTF can be double-spaced.
You can choose to include ignored cards (those starting with a ‘#’ in the exported output.
Spell-checking settings
Choose the language for spell-checking.