Creating a book

The only thing required to publish a book is a book definition.

Quickly trying it out

To create (publish) a book based on existing content:

Create a book definition document: create a document as usual but choose the "Book Definition" document type. Add some section nodes to it, or alternatively use the import node to import the structure of an existing navigation tree.
In the menu, select Tools > Book publishing. If you're logged in, you'll see a link "Publish a book".

Creating a new book from scratch

Usually, you will simply set up a Daisy Wiki site for the purpose of creating/editing the book content. However, instead of using a navigation tree definition, you will use a book definition.

Assuming you have no existing content yet, these are the steps to set up a new book (described in more detail below):

Creating a collection which will contain the documents for the books
Create a first document to include in the book
Create a book definition, for now just containing a reference to the document created in the previous step
Define a new Wiki site, with as home page the created document and as navigation tree the book definition.
Verify the site works
Try to publish the book

You will need Administrator access (to create the collection) and access to the machine on which the Daisy Wiki is running (to define the new site, there is no GUI for this yet).

Now lets run over these steps in more detail.

Creating a collection

In the Daisy Wiki, go to the Administration pages.

The Administration link is only visible if you have the "Administrator" role selected.

Over there, create a new collection (this should point itself out). Write down the ID of the created collection, we will need it later on.

Create a first document

In the Daisy Wiki, browse to some existing site, and create a new document (usually of type "Simple Document"). Type some initial dummy text in the document (like "hello world!"). Switch to the collections tab and add the document to the newly created collection, and remove it from any other collections.

Save the document. Write down the ID of the document (which you can see in the URL or else by selecting the "Document Info" link).

Create a book definition

Again in the Daisy Wiki, create a new document but this time of type "Book Definition". As name for the document, enter something like "First Book" or an appropriate name.

In the first part ("Book Definition Description"), click on the icon to insert a new section node, and fill in the ID of the document created in the previous step. Alternatively, if the GUI editor does not work in your browser, you can copy and paste the following XML:

<?xml version='1.0' ?>
<b:book  xmlns:b="http://outerx.org/daisy/1.0#bookdef">
  <b:content>
    <b:section documentId="xyz"/>
  </b:content>
</b:book>

Replace the xyz in the above XML with the ID of the document created in the previous step.

Then switch to the part "Book Metadata", and edit the title of the book to something appropriate.

Now save this document, and again write down its ID.

Define a new Wiki site

On the computer on which the Daisy Wiki is installed, go to the following directory:

<wikidata directory>/sites

In there, create a new subdirectory, with some name of your choice (without spaces). For example, "firstbook".

In this newly created directory, create a file called siteconf.xml with the following content:

<siteconf xmlns="http://outerx.org/daisy/1.0#siteconf">
  <title>First Book</title>
  <description>My first book</description>
  <skin>default</skin>
  <navigationDocId>book_def_id</navigationDocId>
  <homepageDocId>first_doc_id</homepageDocId>
  <collectionId>collection_id</collectionId>
  <contextualizedTree>true</contextualizedTree>
  <branch>main</branch>
  <language>default</language>
  <defaultDocumentType>SimpleDocument</defaultDocumentType>
  <newVersionStateDefault>publish</newVersionStateDefault>
  <locking>
    <automatic lockType='pessimistic' defaultTime='15' autoExtend='true'/>
  </locking>
</siteconf>

In this XML, replace the highlighted strings "book_def_id", "first_doc_id" and "collection_id" with the correct IDs of the items created in the previous steps. Then save this file.

Verify the site works

Go to the site index page (in the Daisy Wiki, the "Daisy Home" link in the right top). You should see the new site ("First Book") appear in the list. If you do not see it, wait ten seconds and refresh the page (it can take up to 10 seconds before the new site gets detected). If it does still not appear, it is usually because there is some error in the site definition. In that case, check the following log file:

<wikidata directory>/logs/error.log

Another reason a site might not appear is because you don't have read access to its home page. However, since you just created these documents, this is unlikely.

Click on the site link, you should see the usual layout with the navigation tree containing your first document.

Try to publish the book

Go to the following URL:

http://localhost:8888/daisy/books

(or equivalent according to your setup)

Choose the link "Publish a book". You get a page that shows the available book definitions. At this point, probably only the one you just created. Click on the "Publish" link next to it.

You get a form asking some parameters, you can just press "Next" there.
Then you get a form asking for the publication types. There is a drop down there containing the items "PDF", "HTML" and "HTML (chunked)". Choose each of them and press the add link. Then press "Next" to go to the next page.
You get a form asking for the ACL for the published book. By default, the ACL is configured so that only you will see it. Press the button "Start book publication".
You now see a page showing the progress of the book publishing. The book publishing happens as a background process, so you could close your browser and check back later. However, for now, just leave it as is. After a little while, the book publishing will be done and you will be presented with links to the created books. If something went wrong, you will not see those links, and you will need to look at the publication log to see what went wrong.

You can consult your published books at any later time by surfing again to the books URL:

http://localhost:8888/daisy/books

There you can also adjust the ACL so that others can see the book, or delete it.

Notes

About the book definition and book structure:

The name of a document included in a book will become a section title in the book.

In the book definition, sections can be nested. To nested sections, header-shifting will be applied. This means that a section that is normally h1 would become a h2 if the document is nested one level deep
To have a section without a number, enter "anonymous" in the type field of the section (in XML mode, add the attribute type="anonymous" to its <b:section/> element).
Similarly, if you want to have appendixes, set the type to "appendix".
In the book definition you can also define sections that just insert a title, and do not correspond to a document (a bit like group nodes in navigation trees).
The book definition can also contain queries, like in navigation trees.
See also the book definition XML formats description.

To avoid having to re-select the publication types, you can define default settings in the book definition in the part "Default book publications". See also the book definition XML formats description. The same is true for the book ACL.
Publication types can be customised through properties. When adding the publication types in the book publication wizard, you can see the default properties and give them other values. For example, "toc.depth" might be one you might to change. You can also change the numbering patterns of the sections through these properties. See the description of the addNumbering task for more info.
Other things you might want to try out are:

assigning a caption to figures and/or tables, then you will get a list of figures or list of tables in the book (this can be disabled by modifying the "list-of-figures/tables.include-types" attributes).
cross references: in the document editor, assign an ID to a header, image or table. Then insert a cross-reference somewhere that points to it. (There are buttons on the toolbars for these actions).
index: index entries are inserted in a document by using a toolbar button.

To modify the look of the rendered books, you can create your own publication types.

Converting an existing Daisy Wiki site to a book

If you have a site which you would like to publish as a book, and the navigation tree of the site represents the content of the book, you can easily transform the existing navigation tree to a book definition using an XSL, as follows:

download the existing navigation tree XML in a file: choose the "Go to navigation document" link, right-click on the download link next to "Navigation Description", choose "Save link as" (or similar), and save the file in a directory of your choice and with a name like "navigation.xml" (or whatever).
similarly, download this XSLT (text/x-xslt, 622 bytes, info) as nav2book.xsl
then transform the navigation.xml using the nav2book.xsl. In Linux, if you have libxslt installed, you can do this as follows:
```
xsltproc nav2book.xsl navigation.xml > bookdef.xml
```
There are of course various other XSLT processors you can use, sometimes they are integrated in XML editors. Or you can do the conversion manually.
Create a new document of type "Book Definition". In the "Book Definition Description" part, copy and paste the content of the bookdef.xml file.
In the "Book Metadata" part, copy and paste the following:
```
<metadata>
  <entry key="title">My Book</entry>
  <entry key="locale">en</entry>
</metadata>
```
Change the title to something of your choice.
Now save the book definition.

Optionally, you can edit the siteconf.xml of the Daisy Wiki site and change the content of the <navigationDocId> element to point directly to the book definition (the book definition can serve as a replacement of the navigation tree).

Now you can publish your book as described above under the heading "Try to publish the book".

Comments (0)