# bitmark Book

## Introduction

bitmark Book is used to describe a whole Book. bitmark Book adds several book specific Bits to the standard like .book, .summary or .chapter, just to name a few. It describes the structure and meta data of a Book and its content (the Bits). Bits can be defined as you are used to or embedded via references (.bit-alias).

## Book

Example

[.book:book]
[#Title]
[##Subtitle]
[@subject:German as a Foreign Language]

[.toc]

[.summary]
[#Summary of this Book]
This is the summary of this book. It is often  used outside the book like in an online book store, or as a short description for a rich link.

[.chapter]
[#]
[@isProgress:false]

[.chapter]
[##Preface]
[@isProgress:false]

[.article]
**Thank you** for buying this book!

[.chapter]
[##Introduction]

[.article]
This book is an example.

[.chapter][▼imprint]
[##Imprint and Legal Notice]

[.article]

[.chapter]
[#Chapter One]
[%1]

[.summary]
[#Summary of Chapter One]
This is a summary of chapter 1.

[.bit-alias][►com.firstpub.09823409h22]
[.bit-alias][►com.firstpub.09823409h23]
[.bit-alias][►com.firstpub.09823409h24]
[.bit-alias][►com.firstpub.09823409h25]

[.chapter]
[#Chapter Two]
[%2]

[.summary]
[#Chapter Two Summary]
This is a summary of chapter 2.

[.bit-alias][►com.firstpub.09823409h42]
[.bit-alias][►com.firstpub.09823409h43]
[.bit-alias][►com.firstpub.09823409h44]
[.bit-alias][►com.firstpub.09823409h45]
[.bit-alias][►com.firstpub.09823409h47]

[.chapter]
[@level:2]

[.bit-alias][►com.firstpub.09823409h43]

[.chapter][▼chapt_03]
[##Chapter Three]
[%3]

[.bit-alias][►com.firstpub.09823409h50][▼b1_c03]
[.bit-alias][►com.firstpub.09823409h54]
[.bit-alias][►com.firstpub.09823409h56]


### .book

Defines a book. It's the root Bit of every book.

book Types                       Description, Example
[.book:book] Full Featured Book
[.book:collection] Simple, linear Collection of Bits (think of an Array of Bits), no Chapters, no Links
See bitmark JSON for all supported types
.book Markup                  Description, Example
[#...] Book Title, bitmark--
[##...] Book Subtitle, bitmark--
[@...] See bitmark JSON for all supported properties

### .toc

The .toc bit shows the table of content. A bitmark reader/viewer is free to ignore this Bit, if it implements the table of content as a menu. Another possibility would be to show an additional button here to open the table of content menu.

A bitmark to print converter, on the other side, would insert a full table of content including page numbers here.

### .summary

Defines a summary for book or chapter. The summary is not displayed as part of the book content to the user. It can be used whereever a summary of the chapter is needed. For example in an online book shop as a short description of the book or more its content more in depth when using chapter summaries, in search, ...

Markup Tags                  Description, Example
[#...] Title of the Summary, bitmark--

### .chapter

Status: Release Candidate v1

Defines a chapter.

[.chapter]
[#Chapter Title]
[%1]

{
...
"bit": {
"type": "chapter",
"format": "text",
"title": "Chapter Title",
"item": "1",
"level": 1,
"isProgress": true,
},
...
}

<bit type="chapter" format="text">
<title>Chapter Title</title>
<item>1</item>
<level>1</level>
<isProgress>true</isProgress>
</bit>

Markup Tags                      JSON Properties, Description, Example
[#...] title, string,
level, number
Defines the title and level of the chapter
[#...] is the highest level for a title (1). This is comparable to <h1> in html. [##...] is level 2, [###...} is level 3, ... for a title. Max. supported level is 7.
To avoid any misunderstandings: This is not the number of the chapter.
[%...] item, string
The property item contains the "chapter number" (alphanumeric characters accepted)
[%1.2] or [%Kapitel A]
[@isProgress:...] isProgress, boolean, default true
isProgress indicates, if the content of this chapter is considered as relevant (true) for the reading/learning progress of the user
Chapters like "Preface", "Imprint and Legal Notice", "Index", ... are usually not considered as relevant to the user's learning progress.
[@isProgress:false]

### .set

Status: Idea
Open Question: Does a set need a type? Like "folder", "exercise", ...
Open Question: Does a set need a duration property?

Defines a set of bits. A set is a collection of bits. It cannot contain neither chapter, nor other set bits (no sub-sets).

Bits inside a set do not appear in the table of content in a reader app. Sets are often opened in a new window, often with a specific UI. For example to provide a set of questions as coherent exercise.

A set ends with an "empty" set bit (no title, not item, ...) or with a chapter bit.

Every bit belonging to a a set contains a set propertry.

[.set]
[%B23][%Exercise]
[#Set Title]
[@setId:b23-42343-S]

{
...
"bit": {
"type": "set",
"format": "text",
"setId": "b23-42343-S",
"item": "B23",
"title": "Set Title",
},
...
}

Markup Tags                      JSON Properties, Description, Example
[#...] title, string
Defines the title of the set
[%...][%...] item and (optional) lead, string
The item contains the "set number" (alphanumeric characters accepted)
[%1.2] or [%A47][%Exercise]
[@setId:...] id of the set, string

### .bit-alias

Embed referenced Bit

Markup Tags                 Description, Example
[.bit-alias][►...] Include (embed) an existing Bit, where "..." is the id of the referenced Bit.
The bit with id "com.firstpub.09823409h44" must be retrievable from the REST API endpoint /bits/{id}
[.bit-alias][►com.firstpub.09823409h44]

bitmark allows you to create internal links within a Book to its Bits (including chapter Bits). Bits need to be marked by an anchor to be referenced. On the book level, you cannot reference on a more granular level like to a text block inside a Bit.

Clients are free to choose how they display reference Bits. However, it's highly recommended that internal links should be clearly distinguishable from external links (that open an embedded or external browser).

Tip

It is best practice to use internal references economically and show them as buttons to the user.

Markup                                  Description, Example
[.internal-link][!...][►...] Internal Link Bit
Link to the anchor named "Ref4.2.34". [.internal-link][!More examples and quizzes...][►Ref4.2.34]
Unlike html links, links are defined as Bits and are therefore block elements. They are only recognized when positioned at the start of a line. They cannot be placed within a text.

### Anchor [▼...]

Markup                                  Description, Example
[▼...] Anchor
Anchors have no visual representation. You are completely free, how you name your anchors.