README.adoc in hyla-1.0.1 vs README.adoc in hyla-1.0.2

- old
+ new

@@ -1,18 +1,57 @@ -image:https://raw.github.com/cmoulliard/asciidoctor-hyla/master/hyla_frog.jpg[Hyla, 100, 100, role="left"] **Hyla** is a command line tool to create a new documentation/training/blog/static web site project, add artefacts (articles, blog, audio, video, content, code source, ...), render it in HTML, SlideShow using asciidoc(tro) as markup language. It also support to watch files and render them on the fly for browser configured with Livereload. The content generated is served by a HTTP server. +:icons: font +:date-uri: +:linkatts: -The Hyla project name comes from an arborical http://en.wikipedia.org/wiki/Hyla[frog] living in equatorial regions of Europe, Asia or Americas. Its name was inspired by the companion of Hercule (Hylas) in Greek mythology. +image:https://raw.github.com/cmoulliard/hyla/master/documentation/image/hyla_frog.jpg[Hyla, 100, 100, role="left"] **Hyla** is a Ruby command line tool to create a new +documentation/training/blog/static web site project, add artefacts (articles, blog, audio, video, content, code source, ...), render it in HTML, SlideShow, ... using asciidoc(tor) as markup language. +Until now, hyla looks like asciidoctor client but is is more similar to Jekyll on the principle but here we support 'asciidoc, asciidoctor' formats and not markdown. + +The tool allows to : + +- Generate slideshow presentations (deckJs, RevealJS) - https://twitter.com/cmoulliard/status/421587832159756288, +- Setup a blank project, +- Setup a project from template (book, training, training-exercises, documentation/training content, ... +- Create a documentation/training project (including directories + files) from a Table of Content +- Generate a one HTML file (= sum of all the asciidoc files) for slideshow (or trainer presentation) using index files (= file containing links to include other files) +- Render html content from asciidoc (http://asciidoctor.org/docs/user-manual) +- Render html using different styles +- Watch files (LiveReload - WebSocket) and render them if a modification has been detected or file added +... + +It is not a replacement or a concurrent of 'awestruct'. Idea is to package in hyla css styles, backends, samples (article, image, table, audio, video, book, report) +and collection of templates (blog, static web site, awestruct, training, documentation = collection of modules, ... ) to boost process to develop documentation, +training content (reason why hyla will assist you to create from a Table of content the structure of directories + asciidoc files (a file = a chapter =a module)), +blog web, book, articles, static web site site ... without the need to install git projects (everything is packaged in one tool like jekyll). + +Reason / Motivation about the packaging : many end users are not developers/engineers and they enjoy to have one tool to use and not a procedure they should clone git repo, build, copy resources manually +to finally build a documentation/training/blog .... + +hyla should be released regularly and will contain last releases of styles/backends/awestructs ... +hyla will reuse stylesheets created from 'asciidoctor-stylesheet-factory' and 'asciidoctor-backends' for HTML5, RevealJS, DeckJS, DockBook ... +hyla will include 'awestruct' + +The Hyla project name comes from an arboreal http://en.wikipedia.org/wiki/Hyla[frog] living in equatorial regions of Europe, Asia or Americas. Its name was inspired by the companion of Hercule (Hylas) in Greek mythology. + == Prerequisites - https://www.ruby-lang.org/en/[Ruby] > 1.9.3 - http://guides.rubygems.org/[RubyGems] to install Ruby Applications +- https://github.com/sstephenson/rbenv[rbenv] to manage different versions of Ruby == Installation -Add this line to your application's Gemfile: +Use `gem install` command to deploy Hyla : + $ gem install hyla -y + +NOTE : The option `-y` will tell to rubyGems to deploy the gem but also the dependencies required + + +An alternative is to create a Gemfile and add this line : + gem 'hyla' And then execute: $ bundle @@ -47,91 +86,12 @@ More info about options and commands available can be find by running the `command line tool` hyla --help -Here are some examples of commands to create a new project, add artefacts (asciidoc files) watch resources and serve it using HTTP Server +== Documentation -=== New project - -A Blank project - - hyla new --blank ~/Temp/MyBlankProject - - -A Sample Project using as template --> training - - hyla new --template_type training ~/Temp/MyTrainingProject - - -=== Add an artefact to a project - -Asciidoc(tor) documents - - hyla create --t asciidoc --a article --d ~/Temp/MyBlankProject - hyla create --t asciidoc --a audio --d ~/Temp/MyBlankProject - hyla create --t asciidoc --a video --d ~/Temp/MyBlankProject - hyla create --t asciidoc --a source_highlight --d ~/Temp/MyBlankProject - -Slideshow - - hyla create --t slideshow --a deckjs --d ~/Temp/MyBlankProject - -=== Generate Asciidoctor project from a Table of Content - -The entry point of a Documention site, Training, Publication or Book will consist most of the time to create -a Table Of Content which is a collection of modules with chapters that we will develop. As this process to elaborate -the structure of the project will consume lot of time/effort, Hyla will simplify your life as it allows from a TOC file - - - = A. Introduction module - >> This is the module 'A. Introduction' - == 1. Chapter - This is a chapter about ... - == 2. Chapter - This is a Chapter about ... - === 2.1. Section - ... - = B. Instruction module - >> This is the module 'B. Instruction module' - == 1. Chapter - This is a Chapter about ...` - -to generate a collection of folders (= modules) containing files which represent the chapters (== Titles of the TOC ). -For each module (= Module), an index file is also created including the files listed in a module. That can be serve to generate a -slideshow presentation using as backend (DeckJS, DZSlides, ...) later on - - hyla generate --p my-project --d ~/Temp/TocProject/ --r toc2html --toc ~/MyProjects/hyla/data/toc.adoc - - >> Project Name : my-project << - >> Directory created : ~/Temp/MyBookProject/A_Introduction_module << - = File created : 1_Chapter - = File created : 2_Chapter - = File created : 3_Chapter - >> Directory created : ~/Temp/MyBookProject/B_Instruction_module << - = File created : 1_Chapter - >> Directory created : /Users/chmoulli/Temp/MyBookProject/C_Installation_module << - = File created : 1_Chapter - = File created : 2_Chapter - -=== Generate HTML pages from Asciidoc - - hyla generate --s ~/Temp/MyTocProject/ --d ~/Temp/MyToCProject/generated_content/ --r adoc2html - -=== Watch content Live - -While you develop asciidoc(tor) documents, it is interesting to consult the files rendered in HTML. Hyla supports such option with LiverReload -as a WebSocket server is exposed for the browser. To watch files and let's asciidoctor to render them, simply open a terminal and provide as - parameter the source directory containing the files to be watched. - - hyla watch --s ~/Temp/MyTocProject/ --d ~/Temp/MyTocProject/generated_content/ - -=== Serve your content locally - -To simplify your life, a simple HTTP Server can be started by Hyla and will allow to consult/browse HTML files generated. In this case, start this -Hyla command in another Terminal - - hyla serve -P 4000 -H localhost --out_dir ~/Temp/MyTrainingProject/generated_content/ -b /hyla/ +The `hyla`documentation is available at the link:documentation/introduction.adoc[following address]