Book Versions User Manual (XWiki.org)

This is the User Manual for the Book Versions application. Also check the [[Administrator Documentation>>Extension.Book Versions Application.WebHome]] and the [[Developer Documentation>>Extension.Book Versions Application.Book Versions Developer Documentation.WebHome]].

3

4

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

12

13

Versioned books are defined by :

* Title

* Description

* List of versions used for versioning the book's content

18

* List of variants used for creating conditional content

19

* List of languages to be able to internationalize the book

20

* Tree of versioned pages

21

22

They are also defined by

23

24

* A master, that is the location where users can edit the book and manage its attributes

25

* List of published versions of the book, with different variants and on different languages

== Library ==

{{diagram reference="Extension.Book Versions Application.Book Versions User Manual.Book Versions library.WebHome"/}}

30

31

Similarly, the Book Versions application allows users to create **libraries** that can be published as a shared resource, also versioned, between multiple books.

32

33

Versioned libraries are defined by :

* Title

* Description

* List of versions used for versioning the library's content

38

39

They are also defined by

40

41

* A master, that is the location where users can edit the library and manage its attributes

42

* List of published versions of the library

43

44

== Book/Library versions ==

45

46

{{diagram reference="Extension.Book Versions Application.Book Versions User Manual.Book Versions versioning.WebHome"/}}

47

48

A book/library can have multiple versions that are used at publishing.

49

50

A book/library version is an indicator of a certain the state of the book/library content.

51

52

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.

53

54

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 ==

{{diagram reference="Extension.Book Versions Application.Book Versions User Manual.Book Versions variant.WebHome"/}}

59

60

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.

65

66

== Creating a book ==

67

68

To create a new book, click on the //Create// button and select the //Book// template :

69

70

(% contenteditable="false" tabindex="-1" %)[[image:BookVersions01.png||data-xwiki-image-style-border="true"]]

71

72

73

Then, choose the title, select the Book template and click on the Create button to start creating the book :

74

75

(% contenteditable="false" tabindex="-1" %)[[image:BookVersions02.png||data-xwiki-image-style-border="true"]]

76

77

78

Adjust the title if needed, fill in the description of the book and save the page :

79

80

(% contenteditable="false" tabindex="-1" %)[[image:BookVersions3.png||data-xwiki-image-style-border="true"]]

81

82

You can modify these elements anytime, as long as you have the required rights on the book.

83

84

Now that the book has been created, you can create and manage book versions, variants and libraries.

85

86

(% class="box warningmessage" %)

87

(((

88

Do not create a book inside another book/library.

89

)))

90

91

== Managing versions ==

92

93

Create versions to start versioning the book's content.

94

95

Under the //Versions// menu and click on //the Versions// sub-item :

96

97

(% contenteditable="false" tabindex="-1" %)[[image:BookVersions041.png||data-xwiki-image-style-border="true"]]

98

99

You will be redirected to the administration section where you can manage (create, view, edit, delete) the versions of the current book :

100

101

(% contenteditable="false" tabindex="-1" %)[[image:BookVersions053.png||data-xwiki-image-style-border="true"]]

102

103

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>>||anchor="HCreatingcontent"]] section.

104

105

[[image:1747746909540-606.png||data-xwiki-image-style-border="true"]]

106

107

(% class="box infomessage" %)

108

(((

109

The first version must have its //preceding version// attribute left empty.

110

)))

111

112

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>>doc:||anchor="HManaginglibrariesinbooks"]].

113

114

(% class="box infomessage" %)

115

(((

116

Deleting a version will also trigger the deletion of pages' versioned content related to it.

117

)))

118

119

== Managing variants ==

120

121

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.

122

123

[[image:BookVersions6.png||data-xwiki-image-style-border="true"]]

124

125

126

You will be redirected to the administration section where you can manage (create, view, edit, delete) the variants of the current book :

127

128

[[image:BookVersions7.png||data-xwiki-image-style-border="true"]]

129

130

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.

131

132

[[image:image1.png||data-xwiki-image-style-border="true"]]

133

134

When choosing to show associated pages for a selected variant, the list pages with conditional content associated with the selected variant will be displayed :

135

136

[[image:1747749671217-310.png||data-xwiki-image-style-border="true"]]

137

138

== Managing libraries in books ==

139

140

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.

141

142

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.

143

144

[[image:image2.png||data-xwiki-image-style-border="true"]]

145

146

In the version page, click the //Add new configuration// button:

147

148

[[image:image3.png||data-xwiki-image-style-border="true"]]

149

150

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.

151

152

[[image:image4.png||data-xwiki-image-style-border="true"]]

153

154

[[image:image5.png||data-xwiki-image-style-border="true"]]

155

156

To analyse the libraries used in the current book, use the //Versions// menu and click on //Libraries// :

157

158

[[image:BookVersions24.png||data-xwiki-image-style-border="true"]]

159

160

This page displays the list of all libraries configured for the current book:

161

162

[[image:1747758398740-872.png||data-xwiki-image-style-border="true"]]

163

164

Clicking Show associated pages will list all pages which include library content, for each library:

165

166

[[image:1747758548004-337.png||data-xwiki-image-style-border="true"]]

167

168

== Managing languages ==

169

170

To manage the support of multiple languages in the book, in the //Versions// menu select //Languages//:

171

172

[[image:image12.png||data-xwiki-image-style-border="true"]]

173

174

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

175

176

[[image:1747836504129-501.png||data-xwiki-image-style-border="true"]]

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

181

[[image:image8.png||height="246" width="333"]]

182

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.

183

184

185

The version column displays:

186

187

* the name of the version's page name for each version of the page, even if the page was changed to unversioned after their creation,

188

* //WebHome//, for unversioned page, even if the page was changed to versioned.

189

190

191

The status property can be edited from within the table, by hovering over the property and clicking the pencil icon.

192

193

[[image:image9.png||data-xwiki-image-style-border="true"]]

194

195

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

196

197

[[image:image10.png||data-xwiki-image-style-border="true"]]

= Navigation =

== Switching between versions ==

202

203

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 :

204

205

[[image:BookVersions11.png||data-xwiki-image-style-border="true"]]

206

207

By default, the latest book version is used for loading the content of a page.

208

209

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.

210

211

(% class="box infomessage" %)

212

(((

213

The selector is hidden as long as no version has been configured.

214

)))

215

216

== Switching between variants ==

217

218

You can switch between variants to load the associated conditional content:

219

220

[[image:BookVersions12.png||data-xwiki-image-style-border="true"]]

221

222

If no variant is selected in the variant selector, all the conditional content will be displayed.

223

224

The user can link the page at the selected version with the selected variant :

225

226

[[image:BookVersions21.png||data-xwiki-image-style-border="true"]]

227

228

(% class="box infomessage" %)

229

(((

230

The selector is hidden as long as no variants have been configured.

231

)))

232

233

== Switching between translations ==

234

235

You can switch between language thanks to the selector:

236

237

[[image:1748963910602-147.png||height="233" width="278"]]

238

239

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.

240

241

(% class="box infomessage" %)

242

(((

243

The selector is hidden as long as multiple languages have not been configured.

244

245

A similar selector is displayed on published book with multiple translated content.

246

)))

247

248

== Navigation panel ==

249

250

The navigation panel contains the tree of pages in the current book.

251

252

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.

253

254

For the following structure:

255

256

[[image:StandardNavPanelForRef.png||data-xwiki-image-style-border="true"]]

257

258

The panel will display the following pages:

259

260

[[image:navPanelV2-selected.png||data-xwiki-image-style-border="true"]]

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

265

266

A **key** is a library's page's name (≠ page's title).

267

268

The key **value** is the actual page's content, be it a unique word or a full page rich content.

269

270

To create a library, use the //Library// template :

271

272

[[image:BookVersions16.png||data-xwiki-image-style-border="true"]]

273

274

(% class="box warningmessage" %)

275

(((

276

Do not create a library inside another book/library.

277

)))

278

279

== Manage library versions ==

280

281

As for books, use the //Versions// menu to start managing the library versions :

282

283

[[image:BookVersions19.png||data-xwiki-image-style-border="true"]]

284

285

Then manage (create, edit, delete) the versions of the current library :

286

287

[[image:BookVersions18.png||data-xwiki-image-style-border="true"]]

288

289

== Create versioned keys in libraries ==

290

291

From the library, or from an existing key, click on the //New page// button :

292

293

[[image:BookVersions22.png||data-xwiki-image-style-border="true"]]

294

295

Then, fill in the key attributes : title and status (versioned / unversioned) :

296

297

[[image:BookVersions23.png||data-xwiki-image-style-border="true"]]

298

299

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.

308

309

The only functional role of statuses is related to an option at publication, to be able to publish only pages with //Complete// status.

310

311

To change the status of a page click the pen icon on the right of the //Status// field in the top menu.

312

313

[[image:image6.png||data-xwiki-image-style-border="true"]]

314

315

Then select a status from the list, and validate by clicking the tick icon on the right of the //Status// field.

316

317

[[image:image7.png||data-xwiki-image-style-border="true"]]

318

319

== 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)

324

** By default, when creating a new book page, its content will be associated with the current selected version

325

* Unversioned (no version is associated with the content of the page and its latest content will be used at publication)

326

327

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// :

328

329

[[image:BookVersions10.png||data-xwiki-image-style-border="true"]]

330

331

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.

332

333

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 :

334

335

[[image:BookVersions13.png||data-xwiki-image-style-border="true"]]

336

337

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 :

338

339

[[image:BookVersions20.png||data-xwiki-image-style-border="true"]]

340

341

342

The versioned content newly created this way will be a copy of the content that was previously displayed.

343

344

345

== Mark as deleted ==

346

347

A page can be marked as deleted. This will:

348

349

* change there appearance and title to convey the //Marked as deleted// state,

350

* prevent it from being published,

351

* remove its previously published version, in case of re-publishing the book.

352

353

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//:

354

355

[[image:image11.png||data-xwiki-image-style-border="true"]]

356

357

The page will then be displayed with a warning and the title will be prefixed by //DELETED~://

358

359

[[image:1747833552973-788.png||data-xwiki-image-style-border="true"]]

== Delete page ==

Three options are provided to delete a page through the //Versions// menu:

364

365

* If the page is versioned:

366

** //Delete this version//, to only delete the currently displayed page,

367

** //Delete all versions//, to delete completely the page,

368

* If the page is unversioned: //Delete this page//

369

370

In the //Delete all versions// case, //Affect children// needs to be checked in the confirmation dialogue:

371

372

[[image:1747834876307-680.png||data-xwiki-image-style-border="true"]]

= Page content =

Most of the chapters here are not applying for library pages.

377

378

== Creating content ==

379

380

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 :

381

382

[[image:BookVersions8.png||data-xwiki-image-style-border="true"]]

383

384

Then, fill in the page attributes to start creating the page :

385

386

[[image:BookVersions9.png||data-xwiki-image-style-border="true"]]

387

388

(% class="box infomessage" %)

389

(((

390

//Unversioned content// is the only option as long no version is defined in the book.

391

)))

392

393

== Including library keys ==

394

395

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.

396

397

[[image:1747814941603-665.png||data-xwiki-image-style-border="true"]]

398

399

The content provided by the macro is affected by the Library's own version's inheritance.

400

401

Consider the following example:

* Library //Foo//

** Versions:

*** L1, initial version,

406

*** L2, with L1 as preceding version,

407

** Keys:

408

*** K1, versioned with content for versions L1 and L2,

409

*** K2, versioned with content for version L1,

*** K3, unversioned,

* Book //Bar//

** Version:

*** B1, configured to use Library //Foo// in its version L2,

414

** Page:

415

*** P1, using the //Include Library// macro.

416

417

If P1 points to the key:

418

419

* K1, the content of K1 for L2 will be provided,

420

* K2, the content of K2 for L1 will be provided, because L2 is inheriting content from L1,

421

* K3, the content of K3 will be provided.

422

423

== Excerpt include library ==

424

425

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>>doc:||anchor="HIncludinglibrarykeys"]], thanks to the //Excerpt Include Library// macro. It is also using the [[book's configuration of library versions>>doc:||anchor="HManaginglibrariesinbooks"]].

426

427

428

To work properly, this macro requires the //Excerpt// and //Excerpt Include// macros from the [[Pro Macros>>https://store.xwiki.com/xwiki/bin/view/Extension/ProMacros/]] paid extension.

429

430

431

(% class="wikigeneratedid" %)

432

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:

433

434

(% class="wikigeneratedid" %)

435

[[image:1748446573350-592.png||data-xwiki-image-style-border="true"]]

436

437

(% class="wikigeneratedid" %)

438

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:

439

440

(% class="wikigeneratedid" %)

441

[[image:1748446897899-143.png||data-xwiki-image-style-border="true"]]

442

443

== Conditional content ==

444

445

The content of a page can be associated with a variant.

446

447

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.

448

449

[[image:1747733062828-228.png||height="557" width="621"]]

450

451

When loading the page, the content in the variant macros is displayed or not, based on the selected variant.

452

453

== Translated content ==

454

455

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.

456

457

The //Title// can be of the page can be translated by filling the Title field.

458

459

The //Status// can be selected between //Not translated//, //Outdated// and //Translated//. Only translations with the //Translated// status are published.

460

461

//Is default// can be set to display a specific language by default on this page.

462

463

[[image:1747837951494-341.png||data-xwiki-image-style-border="true"]]

464

465

(% class="box infomessage" %)

466

(((

467

If no translation in the page is set as default, the default language of XWiki (//Administration menu, Content, Localization, Default language//) will be displayed.

468

)))

469

470

(% class="box infomessage" %)

471

(((

472

Only one macro per language per page is supported.

473

)))

474

475

(% style="break-before: page;" %)

476

== Include sibling book page ==

477

478

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.

479

480

[[image:1748442855261-319.png||data-xwiki-image-style-border="true"]]

481

482

(% class="box warningmessage" %)

483

(((

484

Currently, all pages from the wiki are proposed in the macro. Be sure to select the WebHome page of the book and not a subpage holding the versioned content.

485

)))

486

487

The content provided by the macro is affected by inheritance from the version currently selected for display.

488

489

Consider the following example:

* Book

** Version:

*** B1, initial version,

494

*** B2, inheriting from B1,

495

*** B3, inheriting from B2,

496

** Page:

497

*** P1, versioned with content for versions B1, B2 and B3,

498

*** P2, versioned with content for version B1,

499

*** P3, unversioned,

500

*** P4, versioned with content for version B2, using the macro.

501

502

If P4, displayed with version B2, points to the reference of:

503

504

* P1, the content of P1 for B2 will be provided,

505

* P2, the content of P2 for B1 will be provided, because B2 is inheriting content from B1,

506

* P3, the content of P3 will be provided.

507

508

If P4, displayed with version **B3**, points to the reference of:

509

510

* P1, the content of P1 for **B3** will be provided,

511

* P2, the content of P2 for B1 will be provided, because B3 inherits from B2, inheriting from B1,

512

* P3, the content of P3 will be provided.

= Publication =

Publication of books/libraries are handled in the menu //Versions//, //Publication//:

517

518

[[image:publicationMenu.png||data-xwiki-image-style-border="true"]]

519

520

From the //Publication// administration page, you can create new configuration of publication, or open previously created ones to use them for publication.

521

522

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>>doc:||anchor="HPagecontent"]].

523

524

(% class="box infomessage" %)

525

(((

526

The different libraries versions used by a book will need to be published in the same wiki as the book will be published.

527

528

Even if a book version is configured to use a specific library version, previous library versions might need to be published because of the inheritance mechanism.

)))

== Configuration ==

To add a new configuration, click //Add publication configuration// in the //Publication// administration page:

534

535

[[image:addPublication.png||data-xwiki-image-style-border="true"]]

536

537

The first three fields to fill are mandatory:

538

539

* //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.

540

* //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.

541

* //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.

542

543

[[image:1748859239618-961.png||data-xwiki-image-style-border="true"]]

544

545

The next two fields, only available when publishing a book, can be used to filter the content:

546

547

* //Variant//: It defines the variant to be published.

548

** Depending on the [[configuration>>doc:||anchor="HManagingvariants"]] of the selected variant, the pages not explicitly tied to the variant may be excluded from publication.

549

** If no value is selected all pages not associated to a variant are published. No content of a [[Variant content>>doc:||anchor="HConditionalcontent"]] macro is published.

550

* //Language//: It defines the language to be published.

551

** Only pages using [[Content translation>>doc:||anchor="HTranslatedcontent"]] 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.

552

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

553

554

[[image:1748867918975-251.png||data-xwiki-image-style-border="true"]]

555

556

The three following fields change the behaviour of the publication:

557

558

* //Publish only "Complete" pages//: If enabled, only pages with the "Complete" status will be published. All pages are published if disabled.

559

* //Publish page order//: If enabled, the display order of [[(pinned) pages>>https://www.xwiki.org/xwiki/bin/view/ReleaseNotes/Data/XWiki/16.4.0RC1/Entry001/]] is also published. If disabled, the natural order of page's name (≠ page's title) is kept.

560

* //Publication behaviour//: Which behaviour to adopt when the target space is already populated:

561

** "Cancel" for stopping publication

562

** "Update" to update existing pages, add new pages from source but leave page deleted from source in the destination.

563

*** Pages published which are marked as deleted in source will be removed from destination.

564

** "Re-publish" to reset the destination space before publication.

565

566

[[image:1748959515642-893.png||data-xwiki-image-style-border="true"]]

567

568

The last two fields are:

569

570

* //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.

571

* //Description//: The description of the configuration

572

573

[[image:1748961073271-303.png||data-xwiki-image-style-border="true"]]

574

575

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.

580

581

[[image:1748963050959-837.png||data-xwiki-image-style-border="true"]]

582

583

A //Publish// button is provided at the bottom of the page.

== Publish ==

(% class="box infomessage" %)

588

(((

589

The user needs to have [[Publications Rights>>https://extensions.xwiki.org/xwiki/bin/view/Extension/Book%20Versions%20Application/#HPublicationRights]] set for being able to publish.

590

)))

591

592

The publication works in background because it can be long. A log is displaying the progress of the process.

593

594

Warnings (in orange by default) warns the user of potential trouble, errors (in red by default) are showing that something unexpected happened.

595

596

[[image:1748963314171-862.png||data-xwiki-image-style-border="true"]]

597