Book Versions User Manual
Concept
Book
The Book Versions application allows users to create a group of pages in a form of a book that can be published as a versioned document.
Versioned books are defined by :
- Title
- Description
- List of versions used for versioning the book's content
- List of variants used for creating conditional content
- List of languages to be able to internationalize the book
- Tree of versioned pages
They are also defined by
- A master, that is the location where users can edit the book and manage its attributes
- List of published versions of the book, with different variants and on different languages
Library
Similarly, the Book Versions application allows users to create libraries that can be published as a shared resource, also versioned, between multiple books.
Versioned libraries are defined by :
- Title
- Description
- List of versions used for versioning the library's content
They are also defined by
- A master, that is the location where users can edit the library and manage its attributes
- List of published versions of the library
Book/Library versions
A book/library can have multiple versions that are used at publishing.
A book/library version is an indicator of a certain the state of the book/library content.
It can be set to be preceded by another version in the current book/library. This system is used for knowing how to display the content of pages based on the selected version.
Book/library pages can be set to either be associated to a certain version, or to inherit from the preceding/previous version, or to not be versioned at all.
Book variants
Book variants are ways to create conditional content. Either a book page itself can be associated to a variant, or just a piece of the page's content.
Book master
The master of the book is the location where users can collaborate on defining and managing the book.
Creating a book
To create a new book, click on the Create button and select the Book template :
Then, choose the title, select the Book template and click on the Create button to start creating the book :
Adjust the title if needed, fill in the description of the book and save the page :
You can modify these elements anytime, as long as you have the required rights on the book.
Now that the book has been created, you can create and manage book versions, variants and libraries.
Managing versions
Create versions to start versioning the book's content.
Under the Versions menu and click on the Versions sub-item :
You will be redirected to the administration section where you can manage (create, view, edit, delete) the versions of the current book :
The versions can be ordered by configuring the previous version attribute. This order will be used for versioned content inheritance. This concept is detailed in the Creating content section.
After saving the version, it is possible to configure which library and library version will be used by it. This topic will be tackled in Managing libraries in books.
Managing variants
Create variants to enable viewing and publishing of conditional content. Only pages and conditional content with matching attributes set will be displayed when a variant is selected.
You will be redirected to the administration section where you can manage (create, view, edit, delete) the variants of the current book :
The attribute Exclude pages that are not explicitly attached to this variant will have the consequence of publishing only pages related to the variant, if checked.
When choosing to show associated pages for a selected variant, the list pages with conditional content associated with the selected variant will be displayed :
Managing libraries in books
Libraries associated to a book are configured for each one of the book's versions. Each version of the book can be associated to multiple libraries, each with a specific version.
To start managing libraries for the current book, use the Versions menu and click on Versions. Once in the Versions administration, click a version name to edit its libraries' configuration.
In the version page, click the Add new configuration button:
Then set the library by clicking the pen icon next to Library Reference, selecting the library in the list, and save by clicking the tick icon. Do the same after with Library Version Reference for selecting the version of the library to be used in this version of the book.
To analyse the libraries used in the current book, use the Versions menu and click on Libraries :
This page displays the list of all libraries configured for the current book:
Clicking Show associated pages will list all pages which include library content, for each library:
Managing languages
To manage the support of multiple languages in the book, in the Versions menu select Languages:
Enable it by clicking the pen icon next to Support multiple translation languages, then select Yes and validate with the tick icon. Then do the same for selecting the supported languages with Enabled translation languages.
Overview
To see an overview of all the statuses of a book you can visit the Versions administration page by clicking on Overview in the Manage section of the Versions menu.
The table is displaying every page in the book, with their versions, their status and their variants if the page has been fully associated to some. Most column can be filtered and/or sorted.
The status property can be edited from within the table, by hovering over the property and clicking the pencil icon.
Batch changing status is available by checking boxes to the left of the table, selecting the status in the New status list, and clicking on Change status on selected pages.
Navigation
Switching between versions
You can switch between versions of the book in order to load the content that is specific to a version. The version selector is available on the root of the book and also on book pages :
By default, the latest book version is used for loading the content of a page.
When a version is selected, all the pages in the book will be loaded in the UI with the content that is set to be associated with that version.
Switching between variants
You can switch between variants to load the associated conditional content:
If no variant is selected in the variant selector, all the conditional content will be displayed.
The user can link the page at the selected version with the selected variant :
Switching between translations
You can switch between language thanks to the selector:
If not selected, the default language of the wiki (Administration menu, Content, Localization, Default language) will be displayed. Content which is not in a Translated content macro will be also displayed.
Navigation panel
The navigation panel contains the tree of pages in the current book.
It uses the selected version or the latest book version if none was selected, to filter the book pages that are displayed in the tree.
For the following structure:
The panel will display the following pages:
Libraries
Libraries are shared resources between books. They are independent of books and are defined by a group of versioned keys that can be used in multiple books pages. The values of the keys are being displayed based on the association between book versions and library versions.
A key is a library's page's name (≠ page's title).
The key value is the actual page's content, be it a unique word or a full page rich content.
To create a library, use the Library template :
Manage library versions
As for books, use the Versions menu to start managing the library versions :
Then manage (create, edit, delete) the versions of the current library :
Create versioned keys in libraries
From the library, or from an existing key, click on the New page button :
Then, fill in the key attributes : title and status (versioned / unversioned) :
If the key is versioned, then, when using it in book pages, the content of the key will be displayed based on the selected version.
Page management
These actions are the same for book pages and library keys.
Statuses
Setting a status to a page helps to know how close the page is ready for publication. Three statuses are available, Draft, Review and Complete. By default, a page doesn't have any status.
The only functional role of statuses is related to an option at publication, to be able to publish only pages with Complete status.
To change the status of a page click the pen icon on the right of the Status field in the top menu.
Then select a status from the list, and validate by clicking the tick icon on the right of the Status field.
Versioned / Unversioned pages
A book page can be :
- Versioned (the content of the page will be used at publishing for the selected book version, or from a version inheriting it)
- By default, when creating a new book page, its content will be associated with the current selected version
- Unversioned (no version is associated with the content of the page and its latest content will be used at publication)
The type of page can be defined at creation, but it can be changed anytime in the future, through the Versions menu and Convert to unversioned/versioned :
When switching from unversioned to versioned, the content of the page will be associated with the selected book version, or with the latest version if none was selected.
If there is no content for a book page that is associated to the selected version, then the content to be displayed and considered for publishing the book at the selected version will be inherited from the preceding version :
The user has the option to create the content associated with the selected version, if it does not exist yet and the inheritance is not the desired option :
Mark as deleted
A page can be marked as deleted. This will:
- change there appearance and title to convey the Marked as deleted state,
- prevent it from being published,
- remove its previously published version, in case of re-publishing the book.
To switch the page between the normal state and Marked as deleted, go in the Versions menu, and select Mark as deleted / Unmark as deleted:
The page will then be displayed with a warning and the title will be prefixed by DELETED:
Delete page
Three options are provided to delete a page through the Versions menu:
- If the page is versioned:
- Delete this version, to only delete the currently displayed page,
- Delete all versions, to delete completely the page,
- If the page is unversioned: Delete this page
In the Delete all versions case, Affect children needs to be checked in the confirmation dialogue:
Page content
Most of the chapters here are not applying for library pages.
Creating content
You can create new book pages from the root of the book and from book pages. Click on the Create page button to start creating the page :
Then, fill in the page attributes to start creating the page :
Including library keys
For adding a key in a book content, you can use the Include Library macro. Depending on the configuration previously done to associate the book's versions to libraries, library keys will be proposed in the macro.
The content provided by the macro is affected by the Library's own version's inheritance.
Consider the following example:
- Library Foo
- Versions:
- L1, initial version,
- L2, with L1 as preceding version,
- Keys:
- K1, versioned with content for versions L1 and L2,
- K2, versioned with content for version L1,
- K3, unversioned,
- Versions:
- Book Bar
- Version:
- B1, configured to use Library Foo in its version L2,
- Page:
- P1, using the Include Library macro.
- Version:
If P1 points to the key:
- K1, the content of K1 for L2 will be provided,
- K2, the content of K2 for L1 will be provided, because L2 is inheriting content from L1,
- K3, the content of K3 will be provided.
Excerpt include library
Including an excerpt (a part of the content) of a library key is possible, with a behaviour similar to the one described in Including library keys, thanks to the Excerpt Include Library macro. It is also using the book's configuration of library versions.
Excerpt in the used library have first to be defined. In the key of the library, add as many Excerpt macros as required, and give to each of them a dedicated name:
Then, in the book page, use the Excerpt include library macro, define the Library key to point to, and then provide a Name of the desired excerpt:
Conditional content
The content of a page can be associated with a variant.
Instead of a whole page, only a paragraph of the content can be set to be used in one or multiple variants, by adding the Variant content macro in the content of the page.
When loading the page, the content in the variant macros is displayed or not, based on the selected variant.
Translated content
Each page's version will hold all of its translations. To add a translation to a page, add a Content translation macro. Add as much macro as needed, one per language of the page.
The Title can be of the page can be translated by filling the Title field.
The Status can be selected between Not translated, Outdated and Translated. Only translations with the Translated status are published.
Is default can be set to display a specific language by default on this page.
Include sibling book page
To include the content of a page from the same book, use the Include Sibling Book Page macro, by providing the reference of that page.
The content provided by the macro is affected by inheritance from the version currently selected for display.
Consider the following example:
- Book
- Version:
- B1, initial version,
- B2, inheriting from B1,
- B3, inheriting from B2,
- Page:
- P1, versioned with content for versions B1, B2 and B3,
- P2, versioned with content for version B1,
- P3, unversioned,
- P4, versioned with content for version B2, using the macro.
- Version:
If P4, displayed with version B2, points to the reference of:
- P1, the content of P1 for B2 will be provided,
- P2, the content of P2 for B1 will be provided, because B2 is inheriting content from B1,
- P3, the content of P3 will be provided.
If P4, displayed with version B3, points to the reference of:
- P1, the content of P1 for B3 will be provided,
- P2, the content of P2 for B1 will be provided, because B3 inherits from B2, inheriting from B1,
- P3, the content of P3 will be provided.
Publication
Publication of books/libraries are handled in the menu Versions, Publication:
From the Publication administration page, you can create new configuration of publication, or open previously created ones to use them for publication.
A published book/library will be tied to a version. All the pages will be published in the selected version if they have a specific content for it, or they will inherit their content. In the pages themselves, the content displayed by macros in the master, will keep the same behaviour as described in Page Content.
Configuration
To add a new configuration, click Add publication configuration in the Publication administration page:
The first three fields to fill are mandatory:
- Source page: It defines the root of the tree of pages to be published, this one included. By default, it is set to the root of the book/library. It is then possible to publish only a fraction of a book/library.
- Destination page: It defines the page where the publication will start. The Source page will be published here. It can be an already existing page, or a new one if the field Name of the space is filled.
- Version: It selects the version in which the book/library will be published. Inheritance of content will apply based on this version. Unversioned content is published as well.
The next two fields, only available when publishing a book, can be used to filter the content:
- Variant: It defines the variant to be published.
- Depending on the configuration of the selected variant, the pages not explicitly tied to the variant may be excluded from publication.
- If no value is selected all pages not associated to a variant are published. No content of a Variant content macro is published.
- Language: It defines the language to be published.
- Only pages using Content translation macro are published. From these, only the content with status "Translated" corresponding to the selected language, and the content outside the Content translation macros, are published.
- If no value is selected all pages are published, and for the one which uses Content translation macro, only the "Translated" status content is published. This can be used for publishing all languages in the same destination.
The three following fields change the behaviour of the publication:
- Publish only "Complete" pages: If enabled, only pages with the "Complete" status will be published. All pages are published if disabled.
- Publish page order: If enabled, the display order of (pinned) pages is also published. If disabled, the natural order of page's name (≠ page's title) is kept.
- Publication behaviour: Which behaviour to adopt when the target space is already populated:
- "Cancel" for stopping publication
- "Update" to update existing pages, add new pages from source but leave page deleted from source in the destination.
- Pages published which are marked as deleted in source will be removed from destination.
- "Re-publish" to reset the destination space before publication.
The last two fields are:
- Destination title: The custom title which will be set on the destination's page. If empty, the title of the source page will be used.
- Description: The description of the configuration
After saving the configuration, the Preview and Publish buttons will be displayed.
Preview
The preview displays what should happen at publication. It checks the used libraries' publication and if the pages will be published or skipped.
A Publish button is provided at the bottom of the page.
Publish
The publication works in background because it can be long. A log is displaying the progress of the process.
Warnings (in orange by default) warns the user of potential trouble, errors (in red by default) are showing that something unexpected happened.
At the bottom of the page, a link to the published content is provided.
