Books

Knowledge base articles can be displayed as a structured book with chapter navigation. The book can also be printed as a PDF file with a cover sheet.

4.1 Characteristics of books

By default, books are created as a "general book". General books have the following characteristics:

• They povide a chapter navigation.
• On book pages, the book navigation is displayed instead of the main navigation.
• A wiki page that belongs to a general book is identified by a <bookshelf /> tag in the source code.
• Each page can only be included in one general book.
• Books can be printed completely or partially as a PDF with a cover sheet.
• They are listed alphabetically on the bookshelf. It is not possible to hide individual books.
• The bookshelf can be reached via the main navigation.

4.2 Creating a book

Books are created from the page Special:BookshelfBookManager. This page can be reached from the Global actions menu under Management > Books.

File:Manual:book-manager.png

Book manager

To create a book:

1. Click the +-button.
2. Enter a Book title.
3. Select "General books" as type of the book.
   File:Manual:create-book.png

   Create a book
4. Click Done. The book editor loads next.

Important!The book is only created in the wiki when at least one page has been saved in the book.

4.2.1 Adding pages

You are now in the book editing mode.

File:Manual:bookshelf-schaltflächen.png

Book edit buttons

1. Click the Plus button (1). A dialog window opens.
2. Search for a page in the wiki and select it. Soll in der Buchnavigation ein anderer Name angezeigt werden so können Sie ienen Anzeigetitle angeben (optional).
3. Click Done.
4. Add additional pages.

1. Click the arrow of the Save button and select Save and add chapter navigation. This process inserts the <bookshelf /> tag into the source code of all wiki pages in the book. This causes a revision of the pages.
   File:Manual:save chapternavigation.png

   Add chapter navigation

Tip:You can click a page title of a book page before adding a new book page. This is then inserted as a sub-chapter. You can move pages to the desired position later using drag & drop with the mouse.

The book is now displayed on the wiki bookshelf. The bookshelf can be reached via the entry links in the main navigation.

Note:There is no option to go directly from the bookshelf to the book manager.

4.2.2 Mass-adding of pages

After clicking "Mass add", a dialog is opened. It contains different criteria for page selection:

• All pages of a category
• All subpages of a certain page
• From a page collection - page collections are lists of pages located in the MediaWiki namespace. They are usually created from search results.
• By a semantic property - pages can be selected based on the value of a certain semantic property.

After adding your book pages click Save at the bottom of the page. Now you have created a page in the namespace Book. It simply contains the list of pages that have been added to the book.

4.3 Adding metadata

While editing a book (adding or removing pages), meta-data for the book can be added. References to these metadata can be included in the PDF template. To edit metadata, select the top-most node of the book (first page) and click the wrench icon. A dialog will be opened where various meta-data can be added or removed:

• Title
• Subtitle
• Author 1 and 2
• Document-ID
• Document type
• Department
• Version
• Template (PDF): If you maintain multiple PDF templates for books, you can select one of them here.
• Table of Contents (Only article titles, or Embed article TOCs)

4.4 Adding a cover image

To add a cover photo for the book, add a metadata item Bookshelf image. Select this option from the dropdown and click Add. Once the meta data is added enter the name of the image in the value field. Any image currently uploaded to the wiki can be used. Type the name without the "File:" prefix (enter the image name and file extension).

4.5 Types of books

Type	Description	Chapter navigation
General books	Visible to all users. Only general books can have a chapter navigation. In almost all cases a book is set up as a "general book".	Yes
Own books	An own book is only visible in the bookshelf to the user who created the book. Such a book does not have a chapter navigation. Own books are usually created to export wiki pages as a PDF with a cover sheet.	No
Temporary books	This selection is also available to wiki users who are not logged into the wiki and is therefore mainly useful for public wikis. These books are only temporarily stored in the user's browser and not in the wiki itself. If the browser cache is deleted or the user switches to another browser, the book is no longer available. The main aim of temporary books is so that users can collectively print out wiki pages as PDFs.	No

4.6 Exporting a book

Books, individual chapters or even individual book pages can be exported as PDF files:

1. Open the book in the book manager.
2. Select each of the pages or chapters to export by clicking the appropriate check boxes. Sub-chapters are selected automatically.
3. Click the Export Selections drop-down menu to open a list of the available formats.
   

4.7 Actions in the book manager

Der Link Verwaltung > Bücher im Menü Globale Aktionen lädt die Seite Spezial:Bücherverwaltung. Hier können Sie Ihre Bücher bearbeiten.

File:Manual:book-manager-actions-EN.png

Book manager actions

• Edit (1): Links to the Book editor where you can edit the book contents and metadata.
• Delete (2): Deletes the book page in the namespace Book without deleting the wiki pages.
• Duplicate (3): Duplicates this book, including all the pages of the book to a different namespace.
• Export (4): Exports all wiki pages in this book to PDF.
• Assign (5): Assigns the book to designated users. These users are the responsible editors of the book.

4.8 Configuration

4.8.2 Export

Wiki-Administratoren können folgende Anpassungen für den Buchexport vornehmen:

4.8.3 Configuring the file size limits (server)

By default, the book export is limited to 50MB in file size. To adjust this value, complete the following steps:

1. In Apache Tomcat, open the file web.xml:

   sudo -s
   nano /opt/tomcat/webapps/manager/WEB-INF/web.xml
   

2. Look for the following lines and adjust the value (e.g. for 250MB=26214400)

   <max-file-size>262144000</max-file-size>
   <max-request-size>262144000</max-request-size>
   

3. The web app BShtml2PDF also has a setting that needs to be adjusted:

   nano /opt/tomcat/webapps/BShtml2PDF/WEB-INF
   

4. Enter your values in the following lines:

   <param-name>maxMemSize</param-name> <param-value>26214400</param-value>
   <param-name>maxFileize</param-name> <param-value>26214400</param-value>
   

5. Apache Tomcat neu starten

   service tomcat restart
   

4.9 Deleting a book

When you delete a book, you only remove the book page of the book (that is, the table of contents) in the "Book" namespace. However, the wiki pages in the book are not deleted. Before deleting the book, a pop-up menu informs you that the bookshelf-tag will not be automatically removed from the pages.

The bookshelf tags have no effect on the wiki pages after deleting the book page. If you want to remove them manually, you can go to the page Special:ReplaceText and do a "find and replace".

4.10 Duplicating a book

You can create an entire copy of the book by duplicating it:

To duplicate a book:

1. Enter a target name: The default value is the book name with the suffix (copy). Change this to create a different book title.
2. Select a namespace: Choose a namespace that is different from the original namespace.

If you are not careful, you might experience some unintended consequences. By creating a new book, you also create copies of all the wiki pages in the original book. Since a namespace cannot contain the same page twice, you have to copy the files to a different namespace.

About the duplicated files:

• Book page: A new page in the namespace book. If you don't enter a new title, the book will be created with the same title and the suffix (Copy). E.g. Employee Manual (Copy). This file includes a copy of the structure of your original book with the corresponding links to the duplicated pages in the new copy.
• Wiki pages: All pages contained in the original book are duplicated. The following scenarios are possible:
  • Same namespace: If you duplicate a book in the same namespace, no actual duplicates of the actual wiki are created. Instead, the bookshelf tag is updated to point to the copy of the book. For example, if your original book contains the page HR:Quality assurance (the book is in the namespace HR), the Quality assurance page now contains the bookshelf tag .
  • Different namespace: If you create the book copy in a different namespace, the bookshelf tag in the original files remains unchanged. The new pages in the different namespace are created with a bookshelf tag for the new book copy. This is most likely the scenario you want.

4.11 Permissions

To create and edit books, users need edit rights in Book namespace. Additionally, a user can only add pages to the book that that user can read. If a user tries to export a book to PDF that contains pages for which the user does not have permissions, the user will get an error message.

4.12 Tips for working with books

• Use a competent team to decide on the content that should be transferred into an online book.
• Decide on how to handle existing numerations or references.
• Seize the opportunity: Get rid of unnecessary content (or don't include it in your book).
• Decide on standards for documents: When does it make sense to link documents in the wiki? When is is sensible to include the document's content into a wiki article?
• Decide on a fitting course of action: Do you want to create the articles in the wiki first, and compile them in a book structure afterwards, or do you want to create the book structure first, and create and edit the articles contained gradually?