resolves asciidoctor/asciidoctor-documentation-planning#18 corrects c…

…opycss info

- corrects copycss documentation in user manual, render, and theme docs
- corrects linkcss documentation in user manual, render, and theme docs
- corrects link reference between documentation
- adds code and image examples for rendering and stylesheets
- adds include files for each section of rendering a document
- introduces the magical, mystical wolpertinger

docs/_includes/html-code-styles.adoc

@@ -0,0 +1,21 @@
+////
+HTML output section
+
+=== CodeRay and Pygments stylesheets
+
+This document is included in render-documents and the user-manual. 
+////
+
+Asciidoctor will also embed the theme stylesheet for the CodeRay or Pygments syntax highlighter.
+
+.CodeRay
+If the +source-highlighter+ attribute is +coderay+ and the +coderay-css+ attribute is +class+, the CodeRay stylesheet is:
+
+* _embedded_ by default
+* _copied_ to the file [file]_asciidoctor-coderay.css_ inside the +stylesdir+ folder within the output directory if +linkcss+ is set
+
+.Pygments
+If the +source-highlighter+ attribute is +pygments+ and the +pygments-css+ attribute is +class+, the Pygments stylesheet is:
+
+* _embedded_ by default
+* _copied_ to the file [file]_asciidoctor-pygments.css_ inside the +stylesdir+ folder within the output directory if +linkcss+ is set

docs/_includes/html-command-line.adoc

@@ -0,0 +1,47 @@
+////
+HTML output section
+
+== Using a command line tool
+
+This document is included in render-documents and the user-manual.
+////
+
+In this section, we'll create a sample document, then process and render it with Asciidoctor's +html5+ backend.
+
+. Create an AsciiDoc file like the one below
+. Save the file as +mysample.adoc+
+
+----
+include::mysample.adoc[]
+----
+
+To convert +mysample.adoc+ to HTML from the command line:
+
+. Open a console
+. Switch to the directory that contains the +mysample.adoc+ document
+. Call the Asciidoctor processor with the +asciidoctor+ command, followed by the name of the document you want to render
+
+//^
+
+ $> asciidoctor mysample.adoc
+
+Remember, Asciidoctor's default backend is +html5+, so it isn't necessary to specify it with the +-b+ command.
+
+You won't see any messages printed to the console.
+If you type +ls+ or view the directory in a file manager, there is a new file named +mysample.html+.
+
+ $> ls
+ mysample.adoc  mysample.html
+
+Asciidoctor derives the name of the output document from the name of the input document.
+
+Open +mysample.html+ in your web browser.
+Your document should look like the image below.
+
+====
+image::mysample.png[]
+====
+
+The document's text, titles, and link is styled by the default Asciidoctor stylesheet, which is embedded in the HTML output.
+As a result, you could save +mysample.html+ to any computer and it will look the same.
+

docs/_includes/html-manage-images.adoc

@@ -0,0 +1,23 @@
+////
+HTML output section
+
+=== Managing images
+
+This document is included in render-documents and the user-manual. 
+////
+
+Images are not embedded in the HTML output by default.
+If you have image references in your document, you'll have to save the image files in the same directory as your rendered document.
+Or, by passing the +data-uri+ attribute to the processor, you can embed the images into the document.
+
+To embed images into the HTML output, set +data-uri+ on the command line or in the document's header.
+
+ $> asciidoctor -a data-uri mysample.adoc
+
+----
+include::mysample-data-uri.adoc[]
+----
+
+====
+image::mysample-data-uri.png[]
+====

docs/_includes/html-ruby-api.adoc

@@ -0,0 +1,25 @@
+////
+HTML output section
+
+== Using the Ruby API
+
+This document is included in render-documents and the user-manual.
+TODO: expand this section 
+////
+
+Asciidoctor also includes a Ruby API that lets you generate an HTML document directly from a Ruby application.
+
+[source,ruby]
+----
+require 'asciidoctor'
+
+Asciidoctor.render_file('mysample.adoc', :in_place => true)
+----
+
+Alternatively, you can capture the HTML output in a variable instead of writing it to a file.
+
+[source,ruby]
+----
+html = Asciidoctor.render_file('mysample.adoc', :header_footer => true)
+puts html
+----

docs/_includes/html-styles.adoc

@@ -0,0 +1,87 @@
+////
+HTML output section
+
+=== Styling the HTML with CSS
+
+This document is included in render-documents and the user-manual. 
+////
+
+Asciidoctor uses CSS for HTML document styling and JavaScript for generating document attributes such as a table of contents and footnotes.
+It comes bundled with a fresh, modern stylesheet, named +asciidoctor.css+.
+When you generate a document with the +html5+ backend, the +asciidoctor.css+ stylesheet is embedded into the HTML output by default.
+
+However, you can link to the stylesheet instead of embedding it.
+To have your document link to the default stylesheet, set the +linkcss+ attribute in the document's header.
+
+----
+include::mysample-link.adoc[]
+----
+
+You can also set +linkcss+ with the CLI.
+
+ $> asciidoctor -a linkcss mysample.adoc
+ 
+Now, when you view the directory, you should see the file +asciidoctor.css+ in addition to +mysample.adoc+ and +mysample.html+.
+The +linkcss+ attribute automatically copies +asciidoctor.css+ to the output directory.
+Additionally, you can inspect +mysample.html+ in your browser and see +<link rel="stylesheet" href="./asciidoctor.css">+ inside the +<head>+ tags.
+
+====
+image::mysample-link.png[]
+====
+
+If you don't want any styles applied to the HTML output of your document, unset the +stylesheet+ attribute.
+
+ $> asciidoctor -a stylesheet! mysample.adoc
+
+One of Asciidoctor's strengths is the ease in which you can swap the default stylesheet for your own custom stylesheet or alternative Asciidoctor themes.
+
+If you want to apply your own stylesheet to the rendered HTML, using the CLI:
+
+. Save your custom stylesheet in the same directory as +mysample.adoc+
+. Call the +asciidoctor+ processor
+. Add the +stylesheet+ attribute with +-a+ (+--attribute+)
+. Include the stylesheet file's name
+
+//end
+
+ $> asciidoctor -a stylesheet=mystyles.css mysample.adoc
+ 
+Alternatively, let's set the +stylesheet+ attribute in the header of +mysample.adoc+.
+
+----
+include::mysample-stylesheet.adoc[]
+----
+
+====
+image::mysample-stylesheet.png[]
+====
+
+Stylesheets can also be stored in a directory other than the directory where your document is saved; you just need to tell Asciidoctor where to look for them using the +stylesdir+ attribute.
+Let's store the +mystyles.css+ stylesheet in +mydocuments/mystylesheets/+.
+Our AsciiDoc document, +mysample.adoc+, is saved in the +mydocuments/+ directory.
+
+----
+include::mysample-stylesdir.adoc[]
+----
+
+When you process +mysample.adoc+, the HTML output (+mysample.html+) is saved in the +mydocuments/+ directory.
+ 
+====
+image::mysample-stylesdir-dir.png[]
+====
+
+You can also set +stylesdir+ in the CLI.
+
+ $> asciidoctor -a stylesdir=mystylesheets/ -a stylesheet=mystyles.css mysample.adoc
+
+If you don't want to embed the +mystyles.css+ stylesheet into your HTML output, make sure to set +linkcss+.
+
+----
+include::mysample-stylesdir-link.adoc[]
+----
+
+After your document is rendered, notice that a copy of +mystyles.css+ was not created in the +mydocuments/+ directory.
+Unlike when you link to the default Asciidoctor stylesheet, any custom stylesheets you link to are not copied to the directory where your output is saved.
+
+CAUTION: The +copycss+ attribute, which would copy a custom stylesheet when a document is rendered, is broken.
+Watch https://github.com/asciidoctor/asciidoctor/issues/300[Issue #300] for updates. 

docs/_includes/mysample-data-uri.adoc

@@ -0,0 +1,15 @@
+= My First Experience with the Dangers of Documentation
+:imagesdir: myimages
+:data-uri:
+
+In my world, we don't have to worry about mutant, script-injecting warlocks.
+No.
+We have something far worse.
+We're plagued by Wolpertingers.
+
+== Origins
+
+[.left.text-center]
+image::wolpertinger.jpg[Wolpertinger]
+
+You may not be familiar with these http://en.wikipedia.org/wiki/Wolpertinger[ravenous beasts], but, trust me, they'll eat your shorts and suck the loops from your code.

docs/_includes/mysample-link.adoc

@@ -0,0 +1,11 @@
+= My First Experience with the Dangers of Documentation
+:linkcss:
+
+In my world, we don't have to worry about mutant, script-injecting warlocks.
+No.
+We have something far worse.
+We're plagued by Wolpertingers.
+
+== Origins
+
+You may not be familiar with these http://en.wikipedia.org/wiki/Wolpertinger[ravenous beasts], but, trust me, they'll eat your shorts and suck the loops from your code.

docs/_includes/mysample-stylesdir-link.adoc

@@ -0,0 +1,13 @@
+= My First Experience with the Dangers of Documentation
+:stylesdir: mystylesheets/
+:stylesheet: mystyles.css
+:linkcss:
+
+In my world, we don't have to worry about mutant, script-injecting warlocks.
+No.
+We have something far worse.
+We're plagued by Wolpertingers.
+
+== Origins
+
+You may not be familiar with these http://en.wikipedia.org/wiki/Wolpertinger[ravenous beasts], but, trust me, they'll eat your shorts and suck the loops from your code.

docs/_includes/mysample-stylesdir.adoc

@@ -0,0 +1,12 @@
+= My First Experience with the Dangers of Documentation
+:stylesdir: mystylesheets/
+:stylesheet: mystyles.css
+
+In my world, we don't have to worry about mutant, script-injecting warlocks.
+No.
+We have something far worse.
+We're plagued by Wolpertingers.
+
+== Origins
+
+You may not be familiar with these http://en.wikipedia.org/wiki/Wolpertinger[ravenous beasts], but, trust me, they'll eat your shorts and suck the loops from your code.

docs/_includes/mysample-stylesheet.adoc

@@ -0,0 +1,11 @@
+= My First Experience with the Dangers of Documentation
+:stylesheet: mystyles.css
+
+In my world, we don't have to worry about mutant, script-injecting warlocks.
+No.
+We have something far worse.
+We're plagued by Wolpertingers.
+
+== Origins
+
+You may not be familiar with these http://en.wikipedia.org/wiki/Wolpertinger[ravenous beasts], but, trust me, they'll eat your shorts and suck the loops from your code.

docs/_includes/mysample.adoc

@@ -0,0 +1,10 @@
+= My First Experience with the Dangers of Documentation
+
+In my world, we don't have to worry about mutant, script-injecting warlocks.
+No.
+We have something far worse.
+We're plagued by Wolpertingers.
+
+== Origins
+
+You may not be familiar with these http://en.wikipedia.org/wiki/Wolpertinger[ravenous beasts], but, trust me, they'll eat your shorts and suck the loops from your code.

docs/install-toolchain.adoc

@@ -15,7 +15,7 @@ Dan Allen
 :quick-ref: {docref}/asciidoc-syntax-quick-reference
 :user-ref: {docref}/user-manual
 :render-ref: {docref}/render-documents
-:build-ref: http://github.com/asciidoctor/asciidoctor-stylesheet-factory/blob/master/README.adoc
+:build-ref: {docref}/produce-custom-themes-using-asciidoctor-stylesheet-factory/
 :mailinglist: http://discuss.asciidoctor.org
 
 // Bruce Wolfe bwolfe@redhat.com 2013-04-26 Issue #284 - Asciidoctor update instructions

docs/produce-custom-themes-using-asciidoctor-stylesheet-factory.adoc

@@ -2,28 +2,28 @@
 Dan Allen; Sarah White
 :awestruct-layout: base
 :toc:
+:icons: font
+:source-highlighter: coderay
+:docref: link:/docs
 :repo-ref: http://github.com/asciidoctor/asciidoctor-stylesheet-factory
-:issues-ref: http://github.com/asciidoctor/asciidoctor-stylesheet-factory/issues
 :showcase-ref: http://themes.asciidoctor.org/preview/
-:asciidoc-ref: http://asciidoc.org
-:docs-ref: link:/docs
-:toolchain-ref: link:/docs/install-toolchain
-:render-ref: link:/docs/render-documents
 :compass-ref: http://compass-style.org
 :sass-ref: http://sass-lang.com
 :foundation-ref: http://foundation.zurb.com
+:get-ruby-ref: http://www.ruby-lang.org/en/downloads
 :bundler-ref: http://rubygems.org/gems/bundler
+:render-ref: {docref}/render-documents
+:quick-ref: {docref}/asciidoc-syntax-quick-reference
+:user-ref: {docref}/user-manual
+:deckjs-ref: {docref}/docs/install-and-use-deckjs-backend/
 :discuss-ref: http://discuss.asciidoctor.org/
-:get-ruby-ref: http://www.ruby-lang.org/en/downloads
 
-The {repo-ref}[Asciidoctor stylesheet factory] is where themes are developed for styling your {asciidoc-ref}[AsciiDoc] documentation.
+The {repo-ref}[Asciidoctor stylesheet factory] is where themes are developed for styling your documents.
 Specifically, these stylesheets can be used to quickly customize the look and feel of HTML 5 documents generated by Asciidoctor.
 
 To view the Asciidoctor themes in action, visit the {showcase-ref}[theme showcase].
 
-WARNING: The Asciidoctor stylesheet factory is currently only compatible with {toolchain-ref}[Asciidoctor 0.1.2].
-
-toc::[levels=1]
+WARNING: The Asciidoctor stylesheet factory is currently only compatible with Asciidoctor 0.1.2 and greater.
 
 == Setting up the factory
 
@@ -120,12 +120,9 @@ If you inspect the [path]'sample.html' document, you should see that the stylesh
 
  <link rel="stylesheet" href="../stylesheets/colony.css">
 
-If you prefer to embed the [path]'colony.css' stylesheet into the generated HTML output, unset the +linkcss+ attribute when you render the document.
+If you prefer to link the [path]'colony.css' stylesheet to the generated HTML output, set the +linkcss+ attribute when you render the document.
 
- $ asciidoctor -a linkcss! -a stylesheet=colony.css -a stylesdir=../stylesheets sample.adoc
-
-IMPORTANT: Unlike in AsciiDoc, Asciidoctor sets +linkcss+ by default.
-We believe linking to the stylesheet is more manageable, and it is the accepted practice on the web.
+ $ asciidoctor -a linkcss -a stylesheet=colony.css -a stylesdir=../stylesheets sample.adoc
 
 .Stylesheet images
 ****
@@ -180,16 +177,29 @@ Here's a minimal version of [path]'sass/hipster.scss':
 
 NOTE: You don't have to include the underscore prefix when importing files.
 
-NOTE: The +awesome-icons+ component is only applicable to HTML generated by Asciidoctor > 0.1.2 with the +icons+ attribute set to +font+.
+NOTE: The +awesome-icons+ component is only applicable to HTML generated by Asciidoctor 0.1.2 or greater versions with the +icons+ attribute set to +font+.
 
 You can add any explicit customizations below the import lines.
 
 The variables you can set in [path]'sass/settings/_hipster.scss' are a combination of the {repo-ref}/blob/master/sass/settings/_settings.scss.dist[Foundation 4 built-in global settings] and {repo-ref}/blob/master/sass/settings/_defaults.scss[global settings and imports for the AsciiDoc components].
 
 Happy theming!
 
-== Resources
+== Resources and help
+
+Now that you have applied a custom theme to your AsciiDoc document, you may want to learn more about the AsciiDoc syntax and the growing variety of integrations, backends, and customizations the Asciidoctor project is developing.
+
+Need an overview of the AsciiDoc syntax?
+
+* {quick-ref}[AsciiDoc Quick Reference]
+
+Want to dive deep into all of Asciidoctor's features?
+
+* {user-ref}[Asciidoctor User's Manual]
+
+Interested in writing your next presentation with Asciidoctor?
 
-Also, don't forget to join the {discuss-ref}[Asciidoctor discussion list], where you can ask questions and leave comments.
+* {deckjs-ref}[Create a presentation with the Asciidoctor deck.js backend]
 
-To file an issue related to the default Asciidoctor stylesheet (generated by the stylesheet factory), visit the {issues-ref}[Asciidoctor issue tracker].
+Additional guides are listed on the {docref}[Documentation] page.
+Also, don't forget to join the {discuss-ref}[Asciidoctor mailing list], where you can ask questions and leave comments.