Implementation of book editor for PillarHub application
Hello everyone! My name is Maxim Skripnik and I'm going to introduce you my third year prebachelor work. It is connected with Pharo and web application programming so I hope you will find it interesting.
1. What do we have
Last year there was developed web-application called "PillarHub" that is designed to work with documents.
By document we mean a text that was written on Pillar language and includes meta-information such as "name", "author", "publication date" and "categories".Г
Today PillarHub (further - PH) contains two main modules.
First is Article editor. Using PH you may create, edit and delete your documents by using Pillar markup. Editor page lets you write text on the one, left window and preview it on the second, right window. It is very simple to edit here since preview updates in a real time.
Second is Article viewer This module lets you view a list of documents created by other people. You may sort articles there by different tags if you want to find a certain theme or by hubs if you're interested in author's texts.
The reason why PH was created is that we dicided to give people opportunity to work with Pillar just to edit articles or books by using web-application, not to build sites like most services suggests. For example, you may use PH to show documentation to your awesome framework for Pharo. It's goal is to make work with Pillar more comfortable, open and shared.
You may find source code and more information about PH here.
There is a list of features that we want to implement in order to improve PH's functionality in order to cater more of it's users needs at working with Pillar.
Here is a list itself from the link above:
- Shared hubs
- Versioning and merging
- GitHub integration
- Book compilation
- Export to PDF
- Design
- RSS-feed
To my mind the most important point from that list is implementation of book compiler.
2. Book module for PillarHub
So you must be asking
- What is book compiler itself?
- Why do we need it?
2.1. Definition of the book
Let us start from explaining what would book be in PillarHub context.
Book in PH is entity that represents a tree-like container which includes set of articles. Articles are to be in folders. Those, in turn, are nested in higher level folders and so forth. Folder here is much like an ordinary folder in operation systems. Each article can be easy found by unique path that contains of parent-objects i.e. folders.
Imagine a book in this context as root of a tree. Book contains huge parts that divide whole book on different modules. Each of these modules may have his own children as well so we go for some more forks. On each step of this "growing" we will get a tree that contains only of folders. And then, by hooking articles to each leaf of this tree we finally create our structure with text, each of which has his own path from the root.
Thus, PH's book is not just disordered set of articles but complete organized structure of your documents.
This definition of the book is not unique. In-life examples of such books you may see here:
"Knockout" JavaScript library documentation
Or here:
Seaside documentation, however, use a bit different way to organize their books even though it's similar to previous twos. The key difference is that in their book folders can contain text whereas our definition does not let you do that.
2.2. Book compiler
After we dealt with books, we can move to book compiler description.
Since you have a large amount of semantic related documents written in Pillar, you would probably want to combine them into one book. And there is function of book compiler. It lets you pull together your articles and create an easy-scanned book from them.
But this is not the only thing that new module provides you to do. There are some more functions that are to be implemented in order to create a complete module to work with books using PillarHub.
2.3. Book module use cases
- The first thing that user waits from this module to do is to create and edit books. User will have a special window with list of articles that he wants to insert into his book, list of folders that sorted in right way to ensure navigation over his structure and preview window with a text of currently selected article.
I imagine this part something like this:
- And another possible use case in book module is to view books written by other people or youself using something similar to article viewer that already exists. We'll probably just add books' preview on the main page of PH and let you view selected book and navigate inside it using folders.
Like here, for example. Red areas here show what is new in Article (not only article anymore) viewer. As you can see, there is a new filter by document type here, icons that mark each of those, and the book browser for you to search inside book and see it's articles previews:
But why do we need book editor?
2.4. Advantages of PillarHub book module
Being a fully open web application it lets you share result of your work in web to have an instant feedback. This is why it is better then a desktop analog like GitBook. Moreover, if you don't have internet connection you are still able to use PH just by running local instance in few easy steps.
Nowadays mostly every Pharo documentation is written in Pillar. And this creates a necessity to have a way to work with this markup. Book module for PillarHub provides you wide opportunities to create big documents. But creating is not the end of documentation's life, especially in IT sphere. Since your product expand, changes and evolves, you need to have a simple way to make appropriate changes with the smallest possible amount of effort. And that's why book module for PillarHub is needful. It lets you do all these things in open-source web-application world.
3. What's more?
So I take this as my bachelor work. Of course it all will be open-sourced since PH was build by Pharo and I will use it as well.
But I want you to help me with your feedback. It would be very nice if you suggest me something in case I've missed it.
Thank you for your attention!