6.2.2 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):

1. Creating a collection which will contain the documents for the books
2. Create a first document to include in the book
3. Create a book definition, for now just containing a reference to the document created in the previous step
4. Define a new Wiki site, with as home page the created document and as navigation tree the book definition.
5. Verify the site works
6. 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.

6.2.2.1 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.

6.2.2.2 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).

6.2.2.3 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.

6.2.2.4 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.

6.2.2.5 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.

6.2.2.6 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.

6.2.2.7 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.