Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Refactor the book structure into its own type #359

Closed
4 tasks done
Michael-F-Bryan opened this issue Jun 24, 2017 · 1 comment
Closed
4 tasks done

Refactor the book structure into its own type #359

Michael-F-Bryan opened this issue Jun 24, 2017 · 1 comment
Labels
A-Internal-representation Area: Internal Representation M-Discussion Meta: Discussion

Comments

@Michael-F-Bryan
Copy link
Contributor

Michael-F-Bryan commented Jun 24, 2017

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 individual chapters contain extra metadata? @gambhiro in [Discussion] Book representation #146 (comment) mentions it may be advantageous to attach metadata like the author, description, or a class to give the end renderer more information. This was also discussed in Allow chapters to have an optional TOML header #277.
  • 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?

cc: @azerupi @budziq

@Michael-F-Bryan
Copy link
Contributor Author

This was fixed in #491.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-Internal-representation Area: Internal Representation M-Discussion Meta: Discussion
Projects
None yet
Development

No branches or pull requests

2 participants