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]
Dear reader,
**Thank you** for buying this book!
[.chapter]
[##Introduction]
[.article]
This book is an example.
[.chapter][▼imprint]
[##Imprint and Legal Notice]
[.article]
Copyright © 2018 - Material published in this electronic book is protected by copyright. All rights reserved.
[.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]
[.internal-link][!More...][►chapt_03]
[.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": [ { "type": "text", "text": "1" } ],
"lead": [],
"level": 1,
"isProgress": true,
},
...
}
<bit type="chapter" format="text">
<title>Chapter Title</title>
<item>1</item>
<lead></lead>
<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": [ { "type": "text", "text": "B23" } ],
"lead": [ { "type": "text", "text": "Exercise" } ],
"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. | |
[.bit-alias][►com.firstpub.09823409h44] |
.internal-link
bitmark allows you to create internal links within a Book. 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. |