On 12/5/2012 1:51 AM, ping wrote:
[1] http://mojavelinux.github.com/decks/asciidoc-with-pleasure <http://mojavelinux.github.com/decks/asciidoc-with-pleasure/> [2] https://github.com/mojavelinux/asciidoc-dzslides-backend --
hi Dan: please provide some hint of what happened here. I followed the instructioin to get the backend installed. but I can't generate the same doc as: http://mojavelinux.github.com/decks/asciidoc-with-pleasure/rwx2012/index.html I got these errors: asciidoc -a data-uri -a linkcss! slides.asciidoc.txtasciidoc: WARNING: slides.asciidoc.txt: line 30: include file not found: /home/ping/.asciidoc/backends/dzslides/dzslides/themes/highlight/monokai.min.css asciidoc: WARNING: slides.asciidoc.txt: line 30: include file not found: /home/ping/.asciidoc/backends/dzslides/dzslides/highlight/highlight.min.js asciidoc: WARNING: slides.asciidoc.txt: line 37: missing style: [blockdef-listing]: qrcode
sh: /Dropbox/temp-transfer/images/mild.png: No such file or directoryasciidoc: WARNING: slides.asciidoc.txt: line 139: {sys3:"/usr/bin/python" -u -c "import base64,sys; base64.encode(sys.stdin,sys.stdout)" < "/Dropbox/temp-transfer/imag
es/mild.png"}: non-zero exit status so it looks I'm missing some files in the installation. and attached is what I generated.if you looks at slides after page 16, all highlight is NOT as good as yours -- the text are invisible now, and will only shows if you select them.
So where is the highlight.min.js file? -- You received this message because you are subscribed to the Google Groups "asciidoc" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/asciidoc?hl=en.Title: Drop the angled brackets. Write (Ascii)Docs with pleasure!
Drop the angled brackets. Write (Ascii)Docs with pleasure!
mojavelinux.github.com/decks/asciidoc-with-pleasure
http://mojavelinux.github.com/decks/asciidoc-with-pleasureWriting in DocBook is just… inhumane
I found I was spending more time fixing syntax errors than I was writing the documentation.
Stuart Rackham
Notes
DocBook is a complex language, the markup is difficult to read and even more difficult to write directly — I found I was spending more time typing markup tags, consulting reference manuals and fixing syntax errors, than I was writing the documentation.
Just let me write, dammit!
+yyyyyyyyyyyyyyyyyyyyyyo-
`yNNNNNNNNNNNNNNNNNNNNNMMMNo`
-:::::::::::::::::::::::`.:dMMN-
oNMMMMMMMMMMMMMMMMMMMMMMMMMd/ sMMN`
oMMm+:::::::::::::::::::::+MMM: NMM-
sMMs MMMo NMM-
sMMs MMMo NMM-
sMMs `mMMMMMMMMMMMMMMMMMd MMMo NMM-
sMMs `++++++++++++++++/` MMMo NMM-
sMMs `mMMMMMMMMMMMMMMMMMd MMMo NMM-
sMMs .+++++++++++++++++` MMMo NMM-
sMMs `dmmmmmmmmmmmmmmmmmh MMMo NMM-
sMMs ://///////////////. MMMo NMM-
sMMs `hmmmmmmmmmmmmmmmmms MMMo NMM-
sMMs //////////////////- MMMo NMM-
sMMs `yddddddddddddddddds MMMo NMM-
sMMs /yyyyyyyyyyyyyyyys/ MMMo NMM-
sMMs `ohhhhhhhhhhhhhhhhho MMMo NMM-
sMMs MMMo dMN.
sMMs MMMo .`
:MMMdhhhhhhhhhhhhhhhhhhhhhdMMN.
.shmmmmmmmmmmmmmmmmmmmmmmmho.
.o. o8o o8o oooooooooo.
.888. `"' `"' `888' `Y8b
.8"888. .oooo.o .ooooo. oooo oooo 888 888 .ooooo. .ooooo.
.8' `888. d88( "8 d88' `"Y8 `888 `888 888 888 d88' `88b d88' `"Y8
.88ooo8888. `"Y88b. 888 888 888 888 888 888 888 888
.8' `888. o. )88b 888 .o8 888 888 888 d88' 888 888 888 .o8
o88o o8888o 8""888P' `Y8bod8P' o888o o888o o888bood8P' `Y8bod8P' `Y8bod8P'
A lightweight, yet powerful text-based markup language and document generator
…that’s got it all!
Notes
AsciiDoc was created by Stuart Rackham, hailing from New Zealand Comparable to Markdown, yet far more complete
- Readable
- Agile
- Comprehensive
- Extensible
- Professional
Notes
- Just as capable as DocBook
- Simple editing (move around sections easily)
- Processing pipeline, templates
Mild punctuation
- HTML HTML 4, XHTML 1.1, HTML 5
- DocBook
- PDF fop, dblatex
- ePub
- man
- ODF
- slides deck.js, dzslides
- …and more
Who’s onboard?
- Neo4j
- CDI Specificiation
- JBoss Developer Framework
- Apache Thrift
- Authors git-scribe, Atlas
- GitHub!
I’m amazed by AsciiDoc :-) It handles a lot of use cases well, and some other cases are still possible at least.
Anders Nawroth, Neo4j
Lightweight markup siblings
- Markdown
- Textile
- reStructuredText
- MediaWiki
- Org-mode
Side by side
Compare AsciiDoc…
Document Title
==============
John Doe <[email protected]>
v1.0, 2012-12-01
This is the optional preamble (an untitled section body). Useful for
writing simple sectionless documents consisting only of a preamble.
NOTE: The abstract, preface, appendix, bibliography, glossary and
index section titles are significant ('specialsections').
== First section
Document sections start at level 1 and can nest up to four levels deep.
* Item 1
* Item 2…to DocBook
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<book lang="en">
<bookinfo>
<title>Document Title</title>
<date>2012-12-01</date>
<author>
<firstname>John</firstname>
<surname>Doe</surname>
<email>[email protected]</email>
</author>
<authorinitials>JD</authorinitials>
<revhistory>
<revision>
<revnumber>1.0</revnumber>
<date>2012-12-01</date>
<authorinitials>JD</authorinitials>
</revision>
</revhistory>
</bookinfo>
<preface>
...…to DocBook (con’t)
...
<simpara>
This is the optional preamble (an untitled section body).
Useful for writing simple sectionless documents consisting
only of a preamble.
</simpara>
<note>
<simpara>
The abstract, preface, appendix, bibliography, glossary
and index section titles are significant
(<emphasis>specialsections</emphasis>).
</simpara>
</note>
</preface>
<chapter id="_first_section">
<title>First section</title>
<simpara>
Document sections start at level 1 and can nest up to
four levels deep.
</simpara>
<itemizedlist>
<listitem>
<simpara>Item 1</simpara>
...…to DocBook (and going)
...
</listitem>
<listitem>
<simpara>Item 2</simpara>
</listitem>
</itemizedlist>
</chapter>
</book>Notes
DocBook becomes a distraction to the task of writing the documentation. Your focus is on the tags and how to manage them rather than the text.
I use Markdown to write my documention.
Most developers on github
…to Markdown
# Document Title
This is the optional preamble (an untitled section body). Useful for
writing simple sectionless documents consisting only of a preamble.
> **Note**
>
> The abstract, preface, appendix, bibliography, glossary and index
> section titles are significant (*specialsections*).
## First section
Document sections start at level 1 and can nest up to four levels deep.
* Item 1
* Item 2Hmm, can’t really cover all the requirements :(
Markdown : 1st-grader ::
Asciidoc : PhD student
AsciiDoc markup tour
Heading variants: Underline
Title (Level 0)
===============
Level 1
-------
Level 2
~~~~~~~
Level 3
^^^^^^^
Level 4
+++++++Heading variants: Symmetric
= Title (Level 0) =
== Level 1 ==
=== Level 2 ===
==== Level 3 ====
===== Level 4 =====Heading variants: Prefix
= Title (Level 0)
== Level 1
=== Level 2
==== Level 3
===== Level 4Notes
I prefer using prefix, except underline for the title
Text formatting
This paragraph contains 'emphasized', *strong*, `monospaced` text.
This paragraph has fancy `single-quoted' and ``double-quoted'' text.
To get [underline]#underlined# text, you can use a inline role (i.e., class) named underline.
x*x can be written as x^2 and you swim in H~2~O.
We break at the end of this line +
to keep the text from overflowing.
.Look at me!
This paragraph has it's own title. footnote:[A title can help a paragraph stand out.]Blocks
Literal block
....
Renders as pre-formatted, monospaced text
....Source block
.Optional caption
----
public interface Document {}
----Blocks (con’t)
Sidebar block
.Optional caption
****
Stuff in here is set off with a different background.
****Quote block
[quote, Linus Torvalds, comp.os.minix (1991)]
____
I'm doing a (free) operating system (just a hobby, won't be big and professional like gnu) for 386(486) AT clones.
____Notes
Only 4 consecutive delimeters are required. I recommend using the minimum rather than formatting them to match the line length.
Lists
Unordered list
* Linux
** Fedora
** Ubuntu
* Mac OSX
* WindozeAnother unordered list
.Vendors
- Asus
- Lenovo
- SamsungLists (con’t)
Ordered list
. Wake up
. Go to work
. Write docs!
.. Open your text editor
.. Experience the joy of text
. Eat cakeDefinition list
AsciiDoc:: advanced text-based document generation
DocBook:: keeps a programmer busy for hoursLinks & images
Links
http://methods.co.nz/asciidoc
http://methods.co.nz/asciidoc[AsciiDoc project]
[[anchor]]Deep link
<<anchor,Go to deep link>>Inline image
image:images/logo.png[Logo]Block image
image::images/logo.png[Logo]Block image with caption
.Screenshot
image::images/screenshot.png[Screenshot]Includes
Include file
include::footer.adoc[]Admonitions
One-liner
NOTE: Just a quick note that you should pay attention.Two-liner
[NOTE]
Perhaps this one is to your liking?More expressive
[IMPORTANT]
====
Get the full rich web experience!
* HTML 5, CSS 3 & _javascript_
====Plain example
.Optional caption
====
Examples are good. They show you how to use stuff.
====Source highlighting
- Baked-in source-highlight, pygments
- Client-side highlight.js, rainbow.js, prettify.js
Tables
Basic table
.Optional caption
[options="header"]
|====================
|Col 1 |Col 2 |Col 3
|1 |Item 1 |a
|2 |Item 2 |b
|3 |Item 3 |c
|====================Table from CSV
.Contacts
[grid="rows",format="csv"]
[options="header",cols="^,<,<,<,>"]
|==========================
ID,First,Last,Address,Phone
1,Allen,Dan,Denver,3035551212
2,Doe,John,"Washington, D.C.",2025551212
|==========================- Attributes (i.e., variables)
- Code callouts
- Block in a list item
- Footnotes, indexes, bibliography
- Macros & filters
- Chunking
- Custom backends
Example showcase
- AsciiDoc User Guide
- Java EE Workshop
- JDF TicketMonster Tutorial
- CDI Specification
- This presentation!
Notes
vim, gedit syntax highlighting support
- callouts in code (generate app w/ Forge)
- attributes for link references
- source code / syntax highlighting (+ don’t have to escape XML)
- output styling: html (+ toc), pdf
- view as DocBook using yelp
- shear size (~ 30,000 words, 214 pages, 80 images)
- rendered on jdf site
- anchors (Introduction.ascidoc)
- includes
- comment on the unnecessary spacing and tokens
- converted using docbook2asciidoc
- :numbered: headings
- anchor references (resolve as names in yelp and pdf)
- index entries (events.asciidoc)
- linkcss and data-uri for single document html
- css classes (as roles)
|
Tip
|
view docbook with yelp |
- AsciiDoc → DocBook (built-in)
- DocBook → AsciiDoc (docbook2asciidoc)
Drop the <>, but not the semantics
Custom markup
Definition
[macros]
(?su)(?<!\S)[\\]?(?P<name>filename):(?P<target>[\w/])=
[filename-inlinemacro]
ifdef::basebackend-docbook[]
<filename{target@.*/$: class="directory"}>{target}</filename>
endif::basebackend-docbook[]
ifdef::basebackend-html[]
<tt>{target}</tt>
endif::basebackend-html[]Usage
My home directory is filename:/home/dallen/.Notes
Also acronym-macro.conf
Getting started
-
Online
- Try AsciiDoc
- GitHub / Gist
-
Local
- Python > 2.4
- unzip distribution zip
- add folder to your PATH
Drawbacks
- Less widely supported than Markdown
- Written in Python, not easy to embed †
- Uses a regex-based parser
- Arbitrary and inconsistent commands
† Work is underway on a Ruby port
