1
Developer's documentation, part 1: Books
	Matti Niemenmaa, 2007-10-19

3
This is the first part of the developer documentation, explaining how books
work and can be written. Note that this book is written in such a way that it
should be read with a text editor, not in-game. Of course, it is perfectly
legible in-game, but metadata, for instance, isn't visible there. Also, like
all developer documentation, the book is structured in such a way that it
should be read in order, which doesn't match the way books are read in-game.
Keywords like "part-1" are provided to aid in this endeavour.

Let's get to the point: this is the description of the book. It is shown when
picking up a book for the first time, and might provide a summary of the
contents, a description of what the book physically looks like, or some such.
Every book has a description.

Prior to this, you should see the title. Basically, the title could be only part
of the description, but the importance of the title is that in-game, one can
search for books based on terms appearing in their title. To find the rest of
the developer's documentation, searching for "dev" should suffice, for instance.
Every book has a title as well.

4
4
*Part-1*
========
You may be wondering about the numbers that appear every now and then. We'll
have to cover some terminology first:
	- A *paragraph* is something separated by blank lines.
	- A *section* is a sequence of paragraphs.

For instance, the list above and the text after the number comprise one
paragraph, and this sentence is part of another paragraph. They are both in the
same section.

Now, the numbers. It's simple. Every section is preceded by a number which
appears on a line of its own and represents the number of paragraphs in that
section. For instance, the title had only one paragraph while the description
had three paragraphs.

So why is this section preceded by two numbers? The prior number simply
indicates the number of sections in the book - excluding the title and
description. The title and description are present in every book, which is why
they are not included in the number and the number appears after them.

8
*Part-2*
========
The most important part about books is the keywords. Using keywords, the player
can read the contents of books. The player can do any of the following:
	- Retrieve a listing of books whose titles contain a given keyword.
	- Retrieve a listing of books containing a given keyword. (*Footnote* 1)
	- Retrieve a listing of keywords within a given book. (*Footnote* 2)
	- Retrieve a listing of sections within a given book containing a given
	  keyword. Based on this, the player may be read sections within a book.

The latter is the only way of reading the contents of a book, apart from the
title and description. The player can view a snippet of the text surrounding the
keyword he searched for and thereby choose to look at the whole section. When
snippets are created, only the first instance of a keyword is used: there is no
need nor point in repeating a keyword within a section.

So, how are keywords used? There are three different notations, which are all
equivalent: *keyword*, _keyword_, and /keyword/. Now the word "keyword" is a
keyword appearing in this section, which enables the player to find this section
by browsing for "keyword".

If one wishes to use the asterisk, underscore, or forward slash within the text,
one must simply double it: **keyword** is not a keyword, it is the word
"keyword" surrounded by asterisks. In-game, that looks exactly the same as
*keyword*, however, so such use is discouraged. Confusing the player
intentionally with something like **notakeyword_keyword_**notakeyword// is not
the point. (A sophisticated UI may choose to display keywords with stylized
text, such as bolding, underlining, or italics, but one must not assume that is
the case.)

The title and description are not scanned for keywords, so the keyword
delimiters are treated as ordinary text therein.

One should note that multiword keywords, such as *key word*, are allowed, and
result in a keyword for each individual word as well as the whole phrase. *key
word* is three keywords: "key", "word", and "key word".

Keywords are case insensitive: *keyword* and *KeYworD* are equivalent. Also,
whitespace is translated to spaces: *key
word*, *key        word*, and *key word* are all equivalent.

Would that real books were this easy to use!

2
*Footnote*s
===========

1. This behaviour may be disabled with the *metadata* notation NOT__REFERENCED.
2. This behaviour may be disabled with the metadata notation NO__INDEX.

4
*Part-3*
========
One last topic remains, that of *metadata*. After all the sections in a book,
metadata may or may not appear. Currently, four possible items exist:
	- NO__INDEX. (With only one underscore: remember keywords!) This prevents the
	  player from retrieving a listing of keywords within a book, and is meant
	  to prevent players from simply browsing books randomly without knowing what
	  they're looking for.
	- NOT__REFERENCED. Similar to the above, it prevents finding the book by
	  searching for a keyword.
	- SANREQ and SANCOST, both of which are followed by a number. The SANREQ is
	  the minimum sanity required to read the book, while the SANCOST is the
	  amount of sanity lost upon reading.

	  The numbers are to be in the range -128 to 127 (Java's "byte" type), but
	  keep in mind that since the player's maximum sanity is 99, a cost greater
	  than or equal to that will kill instantly, while a requirement greater
	  than that leads to an unreadable book.

	  Every book has a SANREQ and a SANCOST of 0 if they are unspecified.

Below, you may see the actual metadata of this book. Note that the SANREQ 0 is
unnecessary, as it is the default.

SANREQ 0
SANCOST -100
