ntfc / asciidocs

Playing around with asciidoctor

Asciidoc/asciidoctor experiments

Table of Contents

• 1. TODO
• 2. Introduction
  • 2.1. Examples
    • 2.1.1. A heading
• 3. Convert to HTML
• 4. Convert to PDF
• 5. Convert to PDF with themes

1. TODO

Things that should work:

• evil theme should pick up some default settings

• Tables

  • Borders

  • Multicolumn/multirow

• Headers and footers

  • Company logo on footer/header

  • Borders

• Page margins

• Copyright notices

• Remove Chapter. from the chapter title

• Warning, tips, etc

• Font

• Table of contents

2. Introduction

Lead is the lead paragraph. Output:

This is the lead paragraph.

Note	while asciidoctor-pdf is quite good, it cannot be used in corporate documents because it lacks title_page customization, copyright notices, etc which are fundamental.

These are the results of my experiments with asciidoc for project documentation.

Tip	See #337 for instructions on how to extend asciidoctor-pdf with ruby

Important

To generate corporate documents with custom title_page, copyright notices, etc we will need to write custom extensions to asciidoctor-pdf, while the theming capabilities are not advanced. To run a custom extension: ./asciidoctor-pdf/bin/asciidoctor-pdf -a pdf-stylesdir=resources/themes/ -a pdf-fontsdir=resources/fonts -a pdf-style=evil -r ./pdf-extensions.rb README.adoc # (1) Note that -r expects an executable, hence we have to pass the file with a preceding ./

Revision Date	Sections Revised	Description of Revisions
2015-07-21	First Release	All new content.
2015-10-16	Template.	Changes to the document template.
2015-11-11	Fixed issues	Added list of issues fixed by this Patch. Added list of issues fixed by this Patch. Added list of issues fixed by this Patch. Added list of issues fixed by this Patch.
	Diffenrete Fixed issues	ist of issues fixed by this Patch. Added list of issues fixed by this Patch. Added list of issues fixed by this Patch.

The --- will be a thematic break.

---

And <<< will be a page break:

2.1. Examples

Sample code:

Factorial.java

public class Factorial {

	public static void main(String[] args) {
		final int NUM_FACTS = 100;
		for(int i = 0; i < NUM_FACTS; i++)
			System.out.println( i + "! is " + factorial(i));
	}

	public static int factorial(int n) {
		int result = 1;
		for(int i = 2; i <= n; i++)
			result *= i;
		return result;
	}
}

2.1.1. A heading

Recommended practices.^[1]

3. Convert to HTML

asciidoctor README.adoc

4. Convert to PDF

./asciidoctor-pdf/bin/asciidoctor-pdf README.adoc

5. Convert to PDF with themes

./asciidoctor-pdf/bin/asciidoctor-pdf -a pdf-stylesdir=resources/themes/ -a pdf-fontsdir=resources/fonts -a pdf-style=evil README.adoc

See:

1. https://github.com/asciidoctor/asciidoctor-maven-examples/tree/master/asciidoctor-pdf-example

2. https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc

This is just gibberish:

loremipsum.adoc

contact.adoc

---

1. http://asciidoctor.org/docs/asciidoc-recommended-practices/