Text based document generation
9 November 2013: AsciiDoc 8.6.9 Released

Read the CHANGELOG for release highlights and a full list of all additions, changes and bug fixes. Changes are documented in the updated User Guide. See the Installation page for downloads and and installation instructions.

Stuart Rackham

Introduction

AsciiDoc is a text document format for writing notes, documentation, articles, books, ebooks, slideshows, web pages, man pages and blogs. AsciiDoc files can be translated to many formats including HTML, PDF, EPUB, man page.

AsciiDoc is highly configurable: both the AsciiDoc source file syntax and the backend output markups (which can be almost any type of SGML/XML markup) can be customized and extended by the user.

AsciiDoc is free software and is licenced under the terms of the GNU General Public License version 2 (GPLv2).

The pages you are reading were written using AsciiDoc, to view the corresponding AsciiDoc source click on the Page Source menu item in the left hand margin.

Overview and Examples

You write an AsciiDoc document the same way you would write a normal text document, there are no markup tags or weird format notations. AsciiDoc files are designed to be viewed, edited and printed directly or translated to other presentation formats using theasciidoc(1) command.

The asciidoc(1) command translates AsciiDoc files to HTML, XHTML and DocBook markups. DocBook can be post-processed to presentation formats such as HTML, PDF, EPUB, DVI, LaTeX, roff, and Postscript using readily available Open Source tools.

Example Articles

Example Books

AsciiDoc markup supports all the standard DocBook frontmatter and backmatter sections (dedication, preface, bibliography, glossary, index, colophon) plus footnotes and index entries.

Example UNIX Man Pages

HTML formatted AsciiDoc man pages with stylesheets and without stylesheets were generated by AsciiDoc from this file.

This roff formatted man page was generated from asciidoc(1) DocBook output using xsltproc(1) and DocBook XSL Stylesheets.

Example Slideshows

The Slidy backend generates HTML slideshows that can be viewed in any web browser. What’s nice is that you can create completely self contained slideshows including embedded images.

Example Web Site

The AsciiDoc website is included in the AsciiDoc distribution (in ./examples/website/) as an example website built using AsciiDoc. See ./examples/website/README-website.txt.

More examples

eBook Publication

The two most popular open eBook formats are EPUB and PDF. The AsciiDoc a2x toolchain wrapper makes it easy to publish EPUB and PDF eBooks with AsciiDoc. See also example books and AsciiDoc EPUB Notes).

Blogpost weblog client

blogpost is a command-line weblog client for publishing AsciiDoc documents to WordPress blog hosts. It creates and updates weblog posts and pages directly from AsciiDoc source documents.

Source code highlighter

AsciiDoc includes a source code highlighter filter that uses GNU source-highlight to highlight HTML outputs. You also have the option of using the Pygments highlighter.

Mathematical Formulae

You can include mathematical formulae in AsciiDoc XHTML documents using ASCIIMathML or LaTeXMathML notation.

The AsciiDoc LaTeX filter translates LaTeX source to a PNG image that is automatically inserted into the AsciiDoc output documents.

AsciiDoc also has latexmath macros for DocBook outputs — they are documented in this PDF file and can be used in AsciiDoc documents processed by dblatex(1).

Editor Support

Try AsciiDoc on the Web

Andrew Koster has written a Web based application to interactively convert and display AsciiDoc source:http://andrewk.webfactional.com/asciidoc.php

External Resources and Applications

Here are resources that I know of, if you know of more drop me a line and I’ll add them to the list.

Please let me know if any of these links need updating.

Documents written using AsciiDoc

Here are some documents I know of, if you know of more drop me a line and I’ll add them to the list.

Please let me know if any of these links need updating.

DocBook 5.0 Backend

Shlomi Fish has begun work on a DocBook 5.0 docbook50.conf backend configuration file, you can find it here. See also:http://groups.google.com/group/asciidoc/browse_thread/thread/4386c7cc053d51a9

LaTeX Backend

An experimental LaTeX backend was written for AsciiDoc in 2006 by Benjamin Klum. Benjamin did a superhuman job (I admit it, I didn’t think this was doable due to AsciiDoc’s SGML/XML bias). Owning to to other commitments, Benjamin was unable to maintain this backend. Here’s Benjamin’s original documentation. Incompatibilities introduced after AsciiDoc 8.2.7 broke the LaTeX backend.

In 2009 Geoff Eddy stepped up and updated the LaTeX backend, thanks to Geoff’s efforts it now works with AsciiDoc 8.4.3. Geoff’s updated latex.conf file shipped with AsciiDoc version 8.4.4. The backend still has limitations and remains experimental (seeGeoff’s notes).

It’s probably also worth pointing out that LaTeX output can be generated by passing AsciiDoc generated DocBook throughdblatex(1).

Patches and bug reports

Patches and bug reports are are encouraged, but please try to follow these guidelines:

  • Post bug reports and patches to the asciidoc discussion list, this keeps things transparent and gives everyone a chance to comment.

  • The email subject line should be a specific and concise topic summary. Commonly accepted subject line prefixes such as [ANN],[PATCH] and [SOLVED] are good.

Bug reports

  • When reporting problems please illustrate the problem with the smallest possible example that replicates the issue (and please test your example before posting). This technique will also help to eliminate red herrings prior to posting.

  • Paste the commands that you executed along with any relevant outputs.

  • Include the version of AsciiDoc and the platform you’re running it on.

  • If you can program please consider writing a patch to fix the problem.

Patches

  • Keep patches small and atomic (one issue per patch) — no patch bombs.

  • If possible test your patch against the current trunk.

  • If your patch adds or modifies functionality include a short example that illustrates the changes.

  • Send patches in diff -u format, inline inside the mail message is usually best; if it is a very long patch then send it as an attachment.

  • Include documentation updates if you’re up to it; otherwise insert TODO comments at relevant places in the documentation.

AsciiDoc的更多相关文章

  1. AsciiDoc Markup Syntax Summary

    AsciiDoc Markup Syntax Summary ============================== A summary of the most commonly used ma ...

  2. Ubuntu 安装asciidoc时默认推荐了巨大的安装包

    $ sudo apt-get install asciidocReading package lists... DoneBuilding dependency tree       Reading s ...

  3. gradle asciidoc 使用

    备注:    次文档参考github 例子   1.环境准备 node npm (yarn) java KindleGen 备注: 具体的安装可以参考网上相关文档,KindleGen 下载地址:htt ...

  4. AsciiDoc Text based document generation

    AsciiDoc Text based document generation    AsciiDoc Home Page http://asciidoc.org/   AsciiDoc is a t ...

  5. AsciiDoc 的相关整理

    Asciidoc Book Editor based on JavaFX 8  Asciidoc FX is a book / document editor to build PDF, Epub, ...

  6. 轻量级标记语言Asciidoc、Markdown

    Asciidoc简介 https://blog.csdn.net/u011411849/article/details/79031718 Asciidoc 比Markdown更简洁强大的文档工具 ht ...

  7. ABP集合贴

    thead>tr>th,.table>tbody>tr>th,.table>tfoot>tr>th,.table>thead>tr>t ...

  8. Android应用性能优化(转)

    人类大脑与眼睛对一个画面的连贯性感知其实是有一个界限的,譬如我们看电影会觉得画面很自然连贯(帧率为24fps),用手机当然也需要感知屏幕操作的连贯性(尤其是动画过度),所以Android索性就把达到这 ...

  9. 【OpenWRT】【RT5350】【一】OpenWrt开发环境搭建

    [宿主机构建] 本人电脑配置如下: CPU: intel 酷睿 i3 3.3G 双核 内存: 金士顿 8G 硬盘:希捷 1TB 7200rpm 操作系统:win7  旗舰版 64位 OpenWrt是在 ...

随机推荐

  1. lintcode:两个数组的交

    题目 返回两个数组的交 样例 nums1 = [1, 2, 2, 1], nums2 = [2, 2], 返回 [2]. 解题 排序后,两指针找相等元素,注意要去除相同的元素 public class ...

  2. iOS开发--控件

    iOS知识点整理-提示器 http://www.jianshu.com/p/ac7e13d36e32 iOS知识点整理-RunLoop http://www.jianshu.com/p/e4fc6ac ...

  3. iOS开发日期处理

    Foundation框架之 日期与时间 #import"ViewController.h"@interfaceViewController() { NSTimer*_timer;/ ...

  4. Spring笔记——Spring+JDBC组合开发

      使用Spring+JDBC集成步骤如下:   1. 配置数据源 2. 配置事务.配置事务时,需要在xml配置文件中引入用于声明事务的tx命名空间,事务的配置方式有两种:注解方式和基于XML配置方式 ...

  5. Android 怎样把光标放在EditText中文本的末尾处?

    EditText et = (EditText)findViewById(R.id.inbox); et.setSelection(et.getText().length());

  6. .NET在EF中使用sql,用动态类吧!

    .NET在EF中使用sql,用动态类吧! 前言 在.NET中使用Entity Framework能快速.方便地结合LINQ来对数据库进行一系列的增删改查操作.但是由于EF根据表达式最后生成通用的sql ...

  7. 【Tech】Cassandra安装和启动

    1.安装 jre,配置系统环境变量: 2.安装python,配置环境变量: 3.下载cassandra,http://cassandra.apache.org/download/: 4.解压,这里我没 ...

  8. Android之网络请求库

    自己学习android也有一段时间了,在实际开发中,频繁的接触网络请求,而网络请求的方式很多,最常见的那么几个也就那么几个.本篇文章对常见的网络请求库进行一个总结. HttpUrlConnection ...

  9. dojo 十二 rest

    从今年8月份开始一直在做以HTML5+CSS3+Dojo实现前端设计,以REST风格实现后台数据请求的项目研发.实践出真知,现在对研发中用到的技术和遇到的问题做一个总结. 后台服务没有采用那些主流的框 ...

  10. sql2000无法打开1433端口及解决方法

    1.如果你是win2003,那么一定要安装sql的补丁sp3a以上版本SP 检查你的SQL有没有打补丁,没有的话要打上补丁,检查的方法是在查询分析器中运行:select @@version如果出来的版 ...