You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The in-memory representation of a book is currently really tightly tied into MdBook and has a lot of functionality that it probably doesn't need. This complicates the current library quite a bit, makes testing difficult because you often need to create a temporary book on disk, and makes it hard to implement much-desired features like plugins and alternate renderers.
My thoughts are that a "book" should be a super simple tree data structure which represents the source files making up the book, then contain the chapters' text as a simple string. It shouldn't really have any behaviour, instead it'll use a Loader object (sorry, names are hard 😞 ) which will parse the SUMMARY.md and use it to construct a Book in memory.
This issue should act as an overall tracker for the changes necessary to make working with the book structure easier, dealing with the "book representation" part of #90. I'm planning to make a separate PR for each of the following:
Pulling the book representation out into a separate Book struct
Converting the SUMMARY.md parser to generate a "recipe" which can be used to load source files from disk and populate the Book tree structure
Actually populate the Book tree structure from disk using the Summary found earlier
Updating MdBook so it can use the new Book
Some questions which may need addressing:
How does multi-language support work? My thoughts are that it shouldn't know/care about multi-language, the low level internal representation should consider chapters to be blobs of text and leave differentiating languages to higher layers.
Should the Loader be exposed publicly? This question was raised in Make parse_summary public? #265. I'm of the opinion that it should be, being able to read the SUMMARY.md file will be useful for 3rd party tools.
Are there any other questions which should be addressed, or tasks which may fall under refactoring the internal representation of a book?
The in-memory representation of a book is currently really tightly tied into
MdBook
and has a lot of functionality that it probably doesn't need. This complicates the current library quite a bit, makes testing difficult because you often need to create a temporary book on disk, and makes it hard to implement much-desired features like plugins and alternate renderers.My thoughts are that a "book" should be a super simple tree data structure which represents the source files making up the book, then contain the chapters' text as a simple string. It shouldn't really have any behaviour, instead it'll use a
Loader
object (sorry, names are hard 😞 ) which will parse theSUMMARY.md
and use it to construct aBook
in memory.This issue should act as an overall tracker for the changes necessary to make working with the book structure easier, dealing with the "book representation" part of #90. I'm planning to make a separate PR for each of the following:
Book
structSUMMARY.md
parser to generate a "recipe" which can be used to load source files from disk and populate theBook
tree structureBook
tree structure from disk using theSummary
found earlierMdBook
so it can use the newBook
Some questions which may need addressing:
Loader
be exposed publicly? This question was raised in Make parse_summary public? #265. I'm of the opinion that it should be, being able to read theSUMMARY.md
file will be useful for 3rd party tools.Are there any other questions which should be addressed, or tasks which may fall under refactoring the internal representation of a book?
cc: @azerupi @budziq
The text was updated successfully, but these errors were encountered: