Pull to refresh

JavaScript Tutorial — на Github

Reading time 3 min
Views 2.5K
Всем привет!

Некоторое время назад, я опубликовал топик об альфа-версии современного учебника JavaScript, пока на английском: javascript.info.

В комментариях были высказаны пожелания, в частности:
  • Выложить исходники книги в open source.
  • Сделать оффлайн-версию.
  • Сделать возможность совместной работы над книгой на Github.
Все это сделано. Следующий этап — совместная работа и перевод на русский.


В репозитарии github.com/iliakan/javascript-book находится альфа-верисия уже offline и open-source JavaScript книги, которую можно читать хоть на островах Кука без интернета. И все интерактивные примеры будут работать.

Также можно редактировать ее и присылать обновления, а в частности — переводить.

Хотелось бы поделиться мыслями, почему для развития учебника был принят именно Github.

Вики



Очевидный вариант для совместного редактирования — это вики. В данном случае вики не подходит, т.к. учебник должен быть концептуально целостным.

Это не пачка независимых страниц энциклопедии, а последовательное изложение. То есть, нужен редактор, который держит в уме всю картину, принимает и мержит изменения.

Может быть несколько редакторов, если учебник содержит несколько независимых разделов.

Своя онлайн-система



Следующая идея — сделать систему совместного редактирования, удовлетворяющую требованиям, которые написаны выше.

Эдакое совместное редактирование документации с основной веткой, в которую мержит только основной редактор и редакторы разделов. Это достаточно просто, все необходимые компоненты для таких систем есть.

Однако, особенность учебника в том, что должно быть много примеров HTML/JS/CSS. Желательно, интерактивных. А их удобно писать и тестировать именно оффлайн, на диске — ну никак не онлайн.

Итоговый вариант



В качестве итогового варианта выбран Git-репозитарий и оффлайн-версия учебника, включая все скрипты, примеры, картинки и т.п.

Сложность такого подхода — для редактирования желательно знание Git (для чтения — можно просто архив скачать).

Как минимум, установка Git, чтобы склонировать, а затем делать git diff и присылать изменения. А лучше — полноценное знание для pull requests. Это повышает порог входа для редакторов.

Плюсы — видно, кто что прислал, обсуждение на Github, issues, pull requests — вся инфраструктура.

Основная техническая сложность создания оффлайн-варианта была в том, что книгу надо не только выложить, а еще дать возможность локально просматривать, редактировать и видеть изменения.

Форматирование текста книги — это сложный парсер, гораздо сложнее обычных markdown, rdoc, textile etc. В основном, это из-за подключения интерактивных примеров. Кроме того, есть дополнительные фичи оформления, например, специальное выделение, авто-оглавление и другие. К этому формату я шел некоторое время, и он удобен.

Чтобы дать возможность видеть красивую, полностью рабочую страницу, форматирование было переписано на чистый JS. При этом для подгрузки и подсветки примеров используется локальный XmlHttpRequest + пропатченный Syntaxhighlighter. Версия 3 хайлайтера не умеет врапить строки текста, поэтому версия 2.
Если есть мысли, почему лучше перейти на 3 — буду рад выслушать.

То есть, вьювер загружает соответствующий файл, парсит, подгружает что надо и выводит. Всего примерно полторы тысячи строк кода, и некоторое время на то, чтобы все это закодить.

Единственное исключение — JS не умеет ходить по директориям, поэтому для перегенерации навигации используется подписанный Java Applet. Он запускается только при выборе соответствующего действия. А можно и не перегенерировать навигацию. Апплет достаточно безопасен, его исходники находятся там же.

Сейчас open-source учебник можно скачать, просматривать, редактировать и присылать изменения/перевод на Github github.com/iliakan/javascript-book.

Пишите, если появятся какие-то вопросы или предложения… Да, кстати, там есть readme, буду дополнять.

— С наилучшими пожеланиями,
Илья Кантор
Tags:
Hubs:
+64
Comments 15
Comments Comments 15

Articles