Flag of Sweden
Andreas Rejbrand’s Website

Rejbrand BookBase: Documentation

Back to program download page

Introduction

Rejbrand BookBase is a book cataloguing software with HTML and microdata export capabilities. This document describes the basics and the more advanced features of the software.

Basics

Cataloguing

Rejbrand BookBase is used to catalogue books. The program manages one catalogue at a time. A catalogue is a stand-alone collection, or database, of book records. In practice, a catalogue is simply a directory in the file system, and the book records are Rejbrand BookBase files with extension *.book.

A book record describes a particular book and can contain the following information:

All fields are optional. If you do not intend to use the advanced features of BookBase, such as microdata annotation, you may specify the properties using any data formats you like.

Below are two screenshots that show the main interface used for entering and viewing the book records in a particular catalogue.

The main interface (with the "Additional Details" tab open)

The main interface (with the "Language" tab open)

You choose the catalogue using the field in the upper-left corner of the window, and all books found in this catalogue are displayed in the list box along the left side of the window. To create a new book record in the current catalogue, press Ctrl+N, select Books/New Book, or right click the list box and choose New Book.

The Books menu and the context (right-click) menu also include convenient commands to rename, delete, and duplicate book records (*.book files). To delete the currently selected book record (*.book file), you can also press the Delete key when the list box has keyboard focus.

The "Confirm Removal" task dialog.

Report creation

Rejbrand BookBase can create reports of catalogues. A report is a text-based list of all books in the catalogue, including as much per-book information as desired. You can specify the text to be shown at the top of the report, at the bottom of the report, and before and after each book record in the report.

Below is a screenshot of the user interface used to generate reports.

The report generation user interface.

The information contained in the report, as well as the format of the text, is specified using a format, a text string which tells BookBase how to represent a single book record in the report. The text created for a particular book record is equal to the format after special tokens have been replaced by actual book record properties. For instance, each occurrence of the string %T in the format will be replaced by the title of the book.

Formats

Below is a list of all tokens recognised by Rejbrand BookBase:

%A
Author
%Y
Year written
%T
Title
%Q
Subtitle
%F
Full title (title and subtitle)
%E
Edition
%e
Series
%i
Position (of the book in a series of books)
%P
Publisher
%p
Printed (toponym)
%y
Year printed
%N
ISBN
%I
Unformatted ISBN (only digits 0 to 9)
%Lnnn
Database link nnn (e.g. %L001)
%n
Number of pages
%C
Category
%c
Comments
%t
Book type
%B
Binding
%l
Level
%R
Rating
%$
Price
%U
Language
%?
The string "Translation" if the work is a translation, the empty string otherwise.
%O
Original language
%r
Translator
%o
Original title
%%
Percent sign (%)
%(
Left parenthesis
%-
Dash (U+002D: HYPHEN-MINUS)
%.
Period
%,
Comma
%"
(Double) quotation mark (U+0022: QUOTATION MARK)
%NNNN
Unicode character with decimal codepoint NNNN (e.g. %0013%0010 or %0009)
%xNNNN
Unicode character with hexadecimal codepoint NNNN (e.g. %x000D%x000A or %x0009)

Notes:

For example, the format Author: %A%, Title: %T might produce the output Author: Chen, Raymond, Title: The Old New Thing.

For every character A such that %A would print the value of the variable associated with the token A, (A will print a space followed by the value of the variable inside parentheses if the length of the value is non-zero.

Similarly, -A will print a dash followed by the value of the variable if the length of the value is non-zero.

In any case, if %A wouldn't print anything, no spaces, parentheses, or dashes will be output.

In almost the same way, .A will print a period, a space and the value of the variable if the variable is of non-zero length and we are not at the very beginning of the string. In the latter case, the period and space are omitted.

,A works the same way, but using comma instead of period.

Finally, "str"A will print the string str followed by the value of A if the latter is of non-zero length. "pref|suff"A will use both a prefix pref and a suffix suff. You can include double quotation marks (") in the prefix and suffix, but you have to escape them by doubling them. For example, "I ""love"" carrots"A would print the string I "love" carrots followed by the value of A (unless A is empty).

For example, the format %A(Y might print Chen, Raymond (2006) if both the Author and Year written fields are present. If the latter is empty in the book record, the output will be only Chen, Raymond.

Standard formats

You specify the format to be used in a report using the Format combo box in the user interface. The value of the edit field is preserved between BookBase sessions, and you can also tell BookBase always to use a particular format in each catalogue. In addition, BookBase supports a list of global formats that can be selected using the combo box's drop-down list. The global formats can be edited using the Format Manager dialog box accessed via Options/Formats... or Ctrl+F, and the default global formats are

The Format Manager dialog box.

Generating the report

To generate a report, use the button at the bottom-right of the Generate Report tab. By default, the button reads Generate to memo and the command will show the created report in a memo control. Via the drop-down menu of the button, you can change the command to output the report to clipboard or a file instead.

Directory-specific options

Each catalogue can contain a local settings file (*.bb-opts) that contains a catalogue-specific format as well as strings to be put before the report, after the report, before each item (book record), and after each item. To create such a settings file, use Options/Directory-specific Options... or press Ctrl+D to open the Book Directory Options dialog box in which you can enter the desired values. The first time the dialog box is shown in a catalogue with no local settings file, the fields take their values from the report-generation user interface (beneath the dialog box). If there is a local settings file, the values are taken from this instead, each time the dialog opens. When the dialog box is closed using the OK button, the local settings file is created or updated with the values from the dialog box.

Each time you enter (select) a catalogue with a local settings file, the fields in the report-generation user interface will be updated to match the catalogue-specific settings in the local settings file.

A local settings file can be removed using the Book Directory Options dialog box.

The Book Directory Options dialog box.

Rejbrand BookBase allows the user to enter database links. A database link is a link to an external book database (or something technically equivalent) on the World Wide Web. A database link is thus a URL, but it may also contain the tokens described above, e.g. ISBN or book title, so a database link can be combined with a book record to create a hyperlink to the external database's record of the current book. Database links (combined with a particular book record) are displayed in the main interface, and can also be included in reports.

The default database links are

The list of database links can be changed from the Database Links tab in the main interface.

Program settings

You can change program settings using the Settings dialog box, which you reach via Options/Settings... or Ctrl+G. The General tab of the dialog is shown below.

The Settings dialog box.

In the group box named Dashes, you can choose which Unicode character you wish to use as the dash character, inserted using -A tokens in the format. You can enter either the code point or the actual character. You should use either U+2013 (EN DASH) or U+2014 (EM DASH). You can also choose if you want the dash to be surrounded by spaces (U+0020).

In the second group box, named Full titles, you can choose how the full title of a book (%F) is composed from the fields named Title and Subtitle. The default choice is to separate the title from the subtitle using the string :  (that is, a colon followed by a space), but you can choose any separator you like, such as a dash character. If you choose an opening parenthesis, BookBase will automatically add a space in front of it and a matching closing parenthesis after the subtitle. See the following examples.

: 
The Old New Thing: Practical Development Throughout the Evolution of Windows
???
The Old New Thing???Practical Development Throughout the Evolution of Windows
 ??? 
The Old New Thing ??? Practical Development Throughout the Evolution of Windows
???
The Old New Thing???Practical Development Throughout the Evolution of Windows
 ??? 
The Old New Thing ??? Practical Development Throughout the Evolution of Windows
(
The Old New Thing (Practical Development Throughout the Evolution of Windows)

Shelf files

Rejbrand BookBase can create a single file containing all the books in a catalogue. Such a file is called a shelf file and has the file extension *.shelf. You can create a shelf file using Books/Create Shelf.... A shelf file can later be opened with the Rejbrand BookBase Shelf Extractor Utility (pun intended), which is included in BookBase. Simply open (e.g., double-click) a shelf file to enumerate or extract the book files it contains.

Screenshot of the Rejbrand BookBase Shelf Extractor Utility.

In-program help

Finally, most of the information in this document is available within the program. Simply click a help link next to a field to learn more about the field. For instance, clicking the Help on names link in the main interface will display the following message (which covers an advanced topic that we will discuss in the next section of this document):

Screenshot of a help message.

In addition, extensive information is included in tooltips. When the cursor is hovering a control, information about that control is displayed in a popup hint and in the statusbar. (Both features can be disabled using the View menu. Popup hints can also be enabled and disabled using Shift+Ctrl+H.)

Microdata annotation

Rejbrand BookBase can use hypertext markup (XHTML5) in reports. The markup can even be annotated using the http://schema.org/Book vocabulary and microdata. To enable microdata markup, simply check the corresponding check box in the Generate Report tab of the main interface. Before you do so, you should make sure that the Before item, After item, Before report, and After report fields are set properly, e.g. <li>, </li>, <ul>, and </ul>, respectively. When you check the microdata checkbox, the attributes itemscope="" and itemtype="http://schema.org/Book" are added to the Before item field. When the report is created, <span> elements, or more specific elements, are used to add the microdata annotation.

For instance, without the microdata option, the format <p>%A(Y.F(E.P,e(i.p(y". ISBN "N(B(t(U" (| pages)"n" Translated from "O" by "r". Original title: "o</p>"<p class=""comment"">|</p>"c might produce the following output:

<li>
  <p>Bondy, J.A.; Murty, U.S.R. (2008). Graph Theory. Springer, Graduate Texts in Mathematics (244).
    United Kingdom (2010). ISBN 978-1-84628-969-9 (Hardcover) (English) (651 pages)</p>
  <p class="comment">A very nice, comprehensive, and detailed book on graph theory.</p>
</li>

If the microdata option is turned on, the following is produced instead:

<li itemscope="" itemtype="http://schema.org/Book">
  <p>
    <span itemprop="author" itemscope="" itemtype="http://schema.org/Person">
      <span itemprop="familyName">Bondy</span>,
      <span itemprop="givenName">J.A.</span>
    </span>;
    <span itemprop="author" itemscope="" itemtype="http://schema.org/Person">
      <span itemprop="familyName">Murty</span>,
      <span itemprop="givenName">U.S.R.</span>
    </span>
    (<time itemprop="dateCreated">2008</time>).
    <cite itemprop="name">Graph Theory</cite>.
    <span itemprop="publisher" itemscope="" itemtype="http://schema.org/Organization">
      <span itemprop="name">Springer</span>
    </span>,
    <span itemprop="isPartOf" itemscope="" itemtype="http://schema.org/CreativeWork">
      <span itemprop="name">Graduate Texts in Mathematics</span>
    </span>
    (<span itemprop="position">244</span>).
    United Kingdom (2010).
    ISBN <span itemprop="isbn">978-1-84628-969-9</span>
    (<span itemprop="bookFormat">Hardcover</span>)
    (<meta itemprop="inLanguage" content="en" />English)
    (<span itemprop="numberOfPages">651</span> pages)
  </p>
  <p class="comment">A very nice, comprehensive, and detailed book on graph theory.</p>
</li>

Special rules

When you use microdata, you need to be more careful when you enter the fields in book records. The following rules must be obeyed.

Names

You may give a list (of any length) of authors, and each author must be either a person or an organisation. You must separate authors from each other using semicolon (;). Whitespace next to punctuation is optional as all strings are trimmed. When giving the name of a person, you must either give a free-form standard form of the name, such as "John Doe", or specify the first name (given name) and last name (family name) explicitly, in the form "Doe, John" (again, whitespace is optional).

When an author is an organisation, simply write the name of the organisation, followed by an asterisk (*). The asterisk is used to specify that the author is an organisation and not a person.

For example, the string "Doe, John; Mary Smith; IBM *" is a list of three (3) authors: the first one is a person with last name "Doe" and first name "John"; the second one is a person named "Mary Smith" (with no hints on how to parse the name); and the last author is an organisation named "IBM". The output, with microdata, will be

<span itemprop="author" itemscope="" itemtype="http://schema.org/Person">
  <span itemprop="familyName">Doe</span>,
  <span itemprop="givenName">John</span>
</span>;
<span itemprop="author" itemscope="" itemtype="http://schema.org/Person">
  <span itemprop="name">Mary Smith</span>
</span>;
<span itemprop="author" itemscope="" itemtype="http://schema.org/Organization">
  <span itemprop="name">IBM</span>
</span>

Dates

The fields Year written and Year printed are usually years (e.g., 1970, 2014). In this case, the field must be a valid positive integer containing at least four digits. For example, the year AD 30 must be written 0030. The output might be <time itemprop="dateCreated">2014</time>.

It is possible also to specify a month. Then the format must be a year, followed by a dash (U+002D: HYPHEN-MINUS), followed by the month, which must be a two-digit positive integer between 01 and 12. Optionally, you may specify a human-readable string like May 2011. In this case, BookBase will automatically deduce the machine-readable equivalent (in this case 2011-05), and the output will be something like <time itemprop="dateCreated" datetime="2011-05">May 2011</time>. You may specify the month in English, Swedish, German, French, Spanish, or Portuguese.

You can specify a specific date, which should be of the form YYYY-MM-DD. For instance, 2014-11-30 might produce <time itemprop="dateCreated">2014-11-30</time>. Under some circumstances, it is also possible to specify a date in the operating system's long or short date format. For example, on a Swedish Windows machine, 30 november 2014 will give <time itemprop="dateCreated" datetime="2014-11-30">30 november 2014</time>.

Finally, BookBase also recognises the format YYYY-Wnn where nn is the current week of the year, written using two digits. For example, 2014-W20 gives <time itemprop="dateCreated">2014-W20</time>.

In general, BookBase supports all the date formats given in the HTML5 specification that do include the year and do not include the time. BookBase even validates the dates (for instance, the number of weeks in a year varies, as well as the number of days in a month), to reduce the risk of producing non-conforming microdata annotations.

If the specified date is not a supported HTML5 date (as described above), and not in the form "May 2011", BookBase will ask the operating system to try to parse the date. In the operating system succeeds (which does not mean that the result is the one intended), BookBase will convert the result to the form YYYY-MM-DD. The actual book record field will be displayed to the user. For example, 23/10/80 will probably result in the code <time itemprop="dateCreated" datetime="1980-10-23">23/10/80</time> as will 80/10/23. The interpretation of 02/05/01, however, is ambiguous.

If the operating system is unable to parse the date, no semantic annotation will be created. For example, 02/05/40/10 will most likely result in 02/05/40/10.

Book formats

The http://schema.org/Book vocabulary specifies three book formats: Hardcover, Paperback, and EBook. In addition, Rejbrand BookBase allows the user to specify synonyms to these three formats, such as PDF for EBook. Synonyms may be translations (such as inbunden, pocket, and e-bok in Swedish). If a book record has a book format that is a case-sensitive match of one of the three allowed microdata values, this will be used. For example, the value Hardcover will produce <span itemprop="bookFormat">Hardcover</span>. If the given value is a case-insensitive match of a synonym for one of the three microdata values, the given value is displayed in prose, and the machine-readable microdata value is given in a <meta> element. For example, the value PDF will produce <meta itemprop="bookFormat" content="EBook" />PDF. Otherwise, no microdata is added. For example, if runestone does not match any synonym when compared case-insensitively (as is reasonable), the output will be simply runestone. The default synonyms are given below.

Hardcover
Hardcover
inbunden
Paperback
Paperback
pocket
EBook
EBook
electronic
electronic book
electronic text
digital
digital book
digital text
digital file
PDF
PDF file
PDF document
e-book
e-bok
PDF-fil
PDF-dokument

Since the three microdata values are synonyms of themselves, it is possible to specify e.g. paperback and still get microdata annotation (with value Paperback). You can change the synonyms in the Settings dialog box.

Screenshot of the "Synonyms" tab in the Settings dialog box.

Language

When you specify the language of a book, you may enter the name of the language any way you like. However, the microdata value must be given as a BCP 47 tag, such as en (for English), en-UK (for British English), and sv (for Swedish). If you give the name of the language in English, the BCP 47 code will be deduced automatically. For instance, if the language is German, the output (with microdata) will be <meta itemprop="inLanguage" content="de" />German. If you want to specify the BCP code manually (which you have to do unless you use the English name of the language, but might want to do anyway), add it inside parentheses at the end. For instance, British English (en-UK) will produce <meta itemprop="inLanguage" content="en-UK" />British English and Svenska (sv) will produce <meta itemprop="inLanguage" content="sv" />Svenska.

General hypertext

The following sections apply when the result is a hypertext document, even if microdata annotation is not used.

Language of titles

The title (and subtitle and edition) of a book is usually in the same language as the book as a whole. If this language differs from the language of the parent of the report in the DOM tree of the hypertext document, then you should specify the language of the title (and subtitle and edition) explicitly, as in the following example:

(the parent element matches the selector :lang(en))
<ul>
  [...]
  <li itemscope="" itemtype="http://schema.org/Book">
    <p>
      <span itemprop="author" itemscope="" itemtype="http://schema.org/Organization">
        <span itemprop="name">Svenska spr??kn??mnden</span>
      </span>
      (<time itemprop="dateCreated">2005</time>).
      <cite itemprop="name" lang="sv">Spr??kriktighetsboken</cite>
      (<span itemprop="bookEdition" lang="sv">Andra upplagan</span>).
      <span itemprop="publisher" itemscope="" itemtype="http://schema.org/Organization">
        <span itemprop="name">Norstedts</span>
      </span>.
      Norge (2011).
      ISBN <span itemprop="isbn">978-91-1-304370-8</span>
      (<span itemprop="bookFormat">Hardcover</span>)
      (<meta itemprop="inLanguage" content="sv" />Swedish)
      (<span itemprop="numberOfPages">413</span> pages)
    </p>
  </li>
  [...]
</ul>

BookBase can add these attributes automatically, if the BCP 47 code of the book is known (see above). Notice that you generally would not want English-language titles to be marked up with the lang attribute in the above example, since that would be redundant. Hence, BookBase allows the user to add the language attribute only if it is different from the language of the parent node in the DOM tree. Of course, BookBase has no idea what the parent looks like (since you will paste the output of BookBase into the parent document after the report is created), so you need to specify this language explicitly. This is what is called the "Default language of the catalogue", and which can be specified in the report-creation user interface.

BookBase can add language attributes even if there should be no microdata annotation. (Indeed, the two checkboxes in the interface are independent.) For example, the title of the book in the snippet above will be output as in the following table (if the default catalogue language is not sv):

Without microdataWith microdata
Without language attributeSpr??kriktighetsboken<cite itemprop="name">Spr??kriktighetsboken</cite>
With language attribute<span lang="sv">Spr??kriktighetsboken</span><cite itemprop="name" lang="sv">Spr??kriktighetsboken</cite>

HTML escapes

If the target format of the report is an HTML document, you can choose if you want to escape the HTML-specific characters <, >, and &. These will then be replaced by "&lt;", "&gt;", and "&amp;", respectively.

If you escape, you can freely enter any characters in book record fields. The output text will be valid HTML markup and will be displayed properly in an HTML renderer, exactly as in the edit fields. Obviously, you cannot use (effective) HTML markup in the fields; for example, this <em>is</em> good will be displayed literally, with the tags visible.

If you do not escape, you must only use <, >, and & according to the strict HTML rules; otherwise, the markup will not be valid. On the other hand, you can then include effective HTML markup. For instance, this <em>is</em> good will be rendered as three English words only, the middle one (probably) in italics. If you want to display the characters <, >, and & in the text, you must escape them manually.

If the target format of the report is plain text, you should not escape the characters. Indeed, there is no need for HTML markup, and you want all characters to be interpreted literally.

You can enable and disable HTML escape in the Hypertext tab in the Settings dialog box.

Screenshot of the "Hypertext" tab in the Settings dialog box.