Help by translating
We would like to encourage you to contribute by translating pages in the wiki to a language they have not yet been translated to, or update translated pages. Read more on translating wiki articles.
To efficiently use this wiki, it is important for you to understand its structure. The wiki is categorized by core concepts of the engine, that being core functionality, page elements and plugins.
the core of the engine is the basic book functionality. Imagine a book with empty pages. You have (empty) chapters, pages, you can flip through the book, see if it's a hardcover book or not, and so on.
the page elements in a book represent content that goes onto the pages. This can be text and images, but also sound and even video.
finally, plugins represent additional features that make working with the book easier, e.g. reading glasses, bookmarks, etc.
These metaphors are, obviously, a little stretched at times, but it should help you get a feeling for what's what, and how some expressions may to be understood.
When searching for a certain piece of information in the wiki, first try to think in which of those categories your problem fits. For example, if you want to set the background color of a page, that's certainly found in the core category. If you wonder how to change the size of a loaded image, it's the page elements category.
Categories contain general articles related to the topic, but also ones representing objects 'defining' that category, so to speak. The core category contains articles on chapters and pages. In those articles all possible settings to change the behavior / look of those are described. So when you look for something, think what object you would have to change to get the desired effect, then look for a wiki article on that object. For the examples just mentioned, that'd be page@bgcolor and img@width / img@height.
Finally: the most important article of all may be the book article, as this contains general parameters that can be used to customize the behavior of a book.
For a quick overview of the elements and most important plugins, see below.
When editing, we would ask you to stick to the following guidelines:
do not write information about version 1.x of the engine, if this information is no longer correct for engine 2.x. For information on the old engine, please use the forum, or explicitly state that the information is only relevant to the old engine version.
link terms that are or can be explained in further detail in another article (at least their first occurrence on a page). E.g. when talking about plugins or a specific element such as the img element.
do not misuse the wiki as a platform to ask questions. Use the forum for that.
contribute by making articles more informative and easier to understand.
only write something down if you are sure it is correct. Users should not be misinformed by the wiki. If in doubt, please verify it yourself, or ask in the forum to make sure.
Support: Where to begin?
In case you are looking for an answer for a specific problem, have a look at the FAQ, the frequently asked questions.
If that does not help, have a look at the element and plugins documentation. Try using the search functionality of the wiki.
Still no luck? Try the forum. Please use the search functionality of the forum before posting your question! It might have already been answered once before. Still no luck? Go ahead and ask in the forum.
After you have your answer, it would be very appreciated if you would contribute to clarify the parts of the wiki that could/should have answered you question, or, for "common" problems (yeah, that's vague, I know), consider adding an entry to the FAQ, thank you!
If you just want to check out the possibilites, there's a list of available elements and plugins. Also have a look at the demo data of the book (the demo which can be found on the home page), which is available as a downloadable package on the main project homepage.
Here are some quick links to ease the navigation through the wiki. The following are the basics for building a book. Links to advanced topics follow below.
This article corresponds to the book node in a book's definition file. Here you can set common settings for the book, such as page size and color. All possible attributes of this node can be found in this article.
Note: plugins (e.g. the navigation bar and gallery) often define additional settings by handling attributes of the book. The names of those attributes are documented in the plugins' respective articles.
Like the book's article corresponds to the book node, this corresponds to the chapter node. Chapters can be used to group pages and override some settings such as the page color for a whole block in the book.
Containing the documentation of the page tag, here you can look up page specific settings. Like in the chapter, some settings can be overridden, such as the page color. Also, have a look at spread pages.
A page element is one of the existing object types that can be added to a page node, and are then considered the content of that page. It is possible to add multiple elements to a page, allowing flexible definition of a book's content.
Plugins offer a simple approach to adding more functionality to a book. In this category you will find a list of available plugins. Each plugin has its own article in which the functionality it provides is documented, along with settings the plugin introduces and element attributes it handles.
ASUL is the GUI definition "language" used by the engine. It allows the definition of interface components in XML files, making the GUI extremely flexible, as it is (in most cases) not necessary to touch the actual engine code at all.
ASUL offers a lot of flexibility, but may be overwhelming on the first look. To get started, consider having a look at the existing definitions in the repository - as opposed to the ones packed with the releases they are not 'compressed' and therefore easier to read and understand.
Please see the category for available components and how to use them. To learn how to define and use ASUL, consider having a look at the writing a plugin tutorial, which covers the part of creating an ASUL file, as well as how to use it in actual program code.
Finally, a small example.
<boxanchors="0, 0, pw, ph"background="gradient(linear-vertical, 0xEEEEFF, 0xAAAADD)"><boxanchors="25, 25, pw-25, ph-25"background="color(0x7F000099)"filter="dropshadow(2,45,0x000000,1,3,3,0.5,2)"><textanchors="10, 10, pw-10, ph-45"background="color(0xEFEFFF)"input="true"selectable="true"font="_sans"multiline="true"value="You can enter some text here..."/><buttonanchors="10, ph-35, pw-10, ph-10"><boxname="$up$"anchors="0, 0, pw, ph"background="color(0x9999DD)"><textvalue="OK"anchors="0,3,pw,ph"color="0xFFFFFF"align="center"font="_sans"bold="true"/></box><boxname="$over$"anchors="0, 0, pw, ph"background="color(0xAAAADD)"><textvalue="OK"anchors="0,3,pw,ph"color="0xFFFFFF"align="center"font="_sans"bold="true"filter="glow(0xFFFFFF)"/></box><boxname="$down$"anchors="0, 0, pw, ph"background="color(0xCCCCEE)"><textvalue="OK"anchors="1,4,pw,ph"color="0x000066"align="center"font="_sans"bold="true"filter="glow(0xFFFFFF)"/></box></button></box></box>