JavaScript Tutorial - on Github
Hello!
Some time ago, I published a topic about the alpha version of a modern JavaScript tutorial, while in English: javascript.info .
Comments were expressed in the comments, in particular:
')
In the github.com/iliakan/javascript-book repository there is an alpha version already offline and an open source JavaScript book that can be read even on the Cook Islands without the Internet. And all the interactive examples will work.
You can also edit it and send updates, and in particular - translate.
I would like to share my thoughts on why Github was adopted for the development of the textbook.
The obvious option for collaborative editing is the wiki. In this case, the wiki is not suitable, because The textbook must be conceptually holistic.
This is not a bundle of independent pages of the encyclopedia, but a consistent presentation. That is, we need an editor that keeps the whole picture in mind, accepts and merges the changes.
There may be several editors if the textbook contains several independent sections.
The next idea is to make a collaborative editing system that satisfies the requirements that are written above.
Joint editing of documentation with the main branch, in which only the main editor and editors of sections merge. It is quite simple, all the necessary components for such systems are.
However, the feature of the tutorial is that there should be many examples of HTML / JS / CSS. Desirable interactive. And it is convenient to write and test them offline, on the disk - well, not online at all.
Git-repository and offline version of the tutorial, including all scripts, examples, images, etc., was chosen as the final version.
The complexity of this approach is that Git knowledge is desirable for editing (for reading, you can simply download the archive).
At a minimum, installing Git to clone, and then do
Pros - you can see who sent what, discussion on Github, issues, pull requests - all infrastructure.
The main technical difficulty of creating an offline version was that the book should not only be uploaded, but also given the opportunity to locally view, edit and see the changes.
Formatting the text of a book is a complex parser, much more complicated than the usual markdown, rdoc, textile etc. This is mainly due to the connection of interactive examples. In addition, there are additional design features, for example, a special selection, auto-table of contents and others. I went to this format for a while, and it is convenient.
To give the chance to see beautiful, completely working page, formatting was rewritten on pure JS. At the same time, local XmlHttpRequest + patched Syntaxhighlighter is used to load and highlight examples. Version 3 highlighter does not know how to string text, so version 2.
If you have thoughts, why it is better to switch to 3 - I will be glad to hear.
That is, the viewer loads the corresponding file, parsit, loads what is needed and outputs. Only about one and a half thousand lines of code, and some time to encode it all.
The only exception is that JS does not know how to navigate through directories, so a signed Java Applet is used to regenerate navigation. It starts only when you select the appropriate action. Or you can not regenerate the navigation. The applet is fairly secure, its source is also there.
Now the open-source tutorial can be downloaded, viewed, edited, and submitted changes / translations to Github github.com/iliakan/javascript-book .
Write, if there are any questions or suggestions ... Yes, by the way, there is a readme, I will supplement.
- Best wishes,
Ilya Kantor
Some time ago, I published a topic about the alpha version of a modern JavaScript tutorial, while in English: javascript.info .
Comments were expressed in the comments, in particular:
- Put the source code of the book in open source.
- Make an offline version.
- Make it possible to collaborate on a book on Github.
')
In the github.com/iliakan/javascript-book repository there is an alpha version already offline and an open source JavaScript book that can be read even on the Cook Islands without the Internet. And all the interactive examples will work.
You can also edit it and send updates, and in particular - translate.
I would like to share my thoughts on why Github was adopted for the development of the textbook.
Wiki
The obvious option for collaborative editing is the wiki. In this case, the wiki is not suitable, because The textbook must be conceptually holistic.
This is not a bundle of independent pages of the encyclopedia, but a consistent presentation. That is, we need an editor that keeps the whole picture in mind, accepts and merges the changes.
There may be several editors if the textbook contains several independent sections.
Own online system
The next idea is to make a collaborative editing system that satisfies the requirements that are written above.
Joint editing of documentation with the main branch, in which only the main editor and editors of sections merge. It is quite simple, all the necessary components for such systems are.
However, the feature of the tutorial is that there should be many examples of HTML / JS / CSS. Desirable interactive. And it is convenient to write and test them offline, on the disk - well, not online at all.
Final option
Git-repository and offline version of the tutorial, including all scripts, examples, images, etc., was chosen as the final version.
The complexity of this approach is that Git knowledge is desirable for editing (for reading, you can simply download the archive).
At a minimum, installing Git to clone, and then do
git diff and send changes. And better - full knowledge for pull requests. This raises the entry threshold for editors.Pros - you can see who sent what, discussion on Github, issues, pull requests - all infrastructure.
The main technical difficulty of creating an offline version was that the book should not only be uploaded, but also given the opportunity to locally view, edit and see the changes.
Formatting the text of a book is a complex parser, much more complicated than the usual markdown, rdoc, textile etc. This is mainly due to the connection of interactive examples. In addition, there are additional design features, for example, a special selection, auto-table of contents and others. I went to this format for a while, and it is convenient.
To give the chance to see beautiful, completely working page, formatting was rewritten on pure JS. At the same time, local XmlHttpRequest + patched Syntaxhighlighter is used to load and highlight examples. Version 3 highlighter does not know how to string text, so version 2.
If you have thoughts, why it is better to switch to 3 - I will be glad to hear.
That is, the viewer loads the corresponding file, parsit, loads what is needed and outputs. Only about one and a half thousand lines of code, and some time to encode it all.
The only exception is that JS does not know how to navigate through directories, so a signed Java Applet is used to regenerate navigation. It starts only when you select the appropriate action. Or you can not regenerate the navigation. The applet is fairly secure, its source is also there.
Now the open-source tutorial can be downloaded, viewed, edited, and submitted changes / translations to Github github.com/iliakan/javascript-book .
Write, if there are any questions or suggestions ... Yes, by the way, there is a readme, I will supplement.
- Best wishes,
Ilya Kantor
Source: https://habr.com/ru/post/121219/
All Articles