README
cfi-notebook/content-map
A strategy for selecting documents from a library of documents and referencing sections or groups of sections.
Definitions
Document
A document is an object that has a title, slug, array of sections, and any other attributes you wish. It has a select function which can select a subset of sections.
Library
A library is an object which has an array of documents and a selector that can both select documents and sections within a selected document.
Section
A group of pages that can be referenced by their ref. For example, ref 3
, or
chapter 3, might be found on pages 54
through 69
, and ref 5-3-1
might be
found on pages 121
through 121
.
Section Map
The section map is the data structure which maps a ref such as 1-1
to a page
number.
Shorthand Reference
A shorthand reference is a way of using a string to select one or more sections.
For example, 1-1,1-2
would section sections 1-1
and 1-2
. See the usage
examples for more detail.
Selection
A selection is the returned object from the select function on a document. It returns an object with two attributes, the sections array of the selected sections refs, and the pages array with the page numbers of the selection in sequential order.
Reference Types
String
A reference can be a String, for example, 'Preface' is a string reference. String references cannot be incremented.
Chapter
A reference can be a chapter, for example, 2
would reference chapter 2 that
might be found on page 20. The return value is always a string.
Ref-Ref
References such as 1-1
or 6-2-5
are "ref-ref" references. The digits after
the last hyphen are incremented. Endashes and emdashes are replaced with
hyphens.
Sync
Sometimes a document has no section structure so we will revert to using page
numbers as refs. A single shorthand reference of sync
along with the first and
last page is used to denote this situation. For example, sync#1#56
would be
used to sync the section map to pages 1
through 56
.
Usage
Include the library. Intended for use in Node, but it would work in the browser if consumed by something like Webpack to package and transpile via babel.
var ContentMap = require('@cfi-notebook/content-map');
Create Document from Object
var document = ContentMap.create({
title: 'A Generic Handbook',
sections: [
{
ref: '1-1',
start: 1,
end: 1
},
{
ref: '1-2',
start: 2,
end: 2
}
]
});
Create Document from Shorthand
var document = ContentMap.create({
title: 'A Generic Handbook',
sections: [
'1-1#1',
'1-2#2',
'1-3#3#3' // last section must have a start and end
]
});
Create Document Using Sync
var document = ContentMap.create({
title: 'A Generic Handbook',
sections: ['sync#1#50']
});
Create Document from YAML
var filePath = path.resolve(__dirname, 'a-generic-handbook.yml');
var document = ContentMap.createFromYaml(filePath);
Create Library of Documents
var library = ContentMap.createAll([
{
title: 'A Generic Handbook',
sections: ['sync#1#50']
},
{
title: 'Some Other Handbook',
sections: ['sync#1#50']
}
]);
Create Library of Documents From YAML
var filePaths = ['a-generic-handbook.yml', 'some-other-handbook.yml'];
var library = ContentMap.createAllFromYaml(filePaths);
Select Sections of a Document
Single Section
document.select('1-1');
Multiple Sections
document.select('1-1,1-2'); // multiple sections separated by commas
Series of Sections
document.select('1-1...1-2'); // series of section from/to separated by ...
Select Document From Library
var library.select('a-generic-handbook');
Select Document From Library and Sections from Document
var library.select('a-generic-handbook@1-1...1-2');