Wiki code for ASCIIdocs Quick Start Guide

Hide Line numbers
1: {{{
2: 
3: ASCIIdoc is an extensive Python script that takes simple text files and
4: converts them into other formats. Three document types are supported. 
5:   article (the default)
6:   book
7:   manpage
8: ASCIIdoc uses .txt files by default.
9: 
10: The default output of ASCIIdoc is an HTML file (xhtml11).
11: 
12: The document types supported by ASCIIdoc are:
13: 	article - short documents, articles, and general documentation
14: 	book - similar to articles, but include level 0 book part sections
15: 	manpage - used to generate UNIX manual pages
16: 
17: Man pages are created by converting the ASCIIdoc text files to DocBook 
18: refentry files, and then to standard roff man pages.
19: 
20: ASCIIdoc uses backend configuration files to output:
21: 	DocBook XML (docbook)
22: 	XHTML 1.1 with CCS2 (xhtml11; the default)
23: 	HTML 4.01 - unstyled (html4)
24: 	linuxdoc (no longer actively supported)
25: The backend configurations are called using the -b  option.
26: 
27: Other tools can convert the docbook output ( -b docbook ) to:
28: 	PostScript
29: 	HTML
30: 	PDF
31: 	DVI
32: 	roff (man page source)
33: 	HTMLHelp
34: 	JavaHelp
35: 	text
36: 	etc. 
37: 
38: ASCIIdoc has a DocBook Toolchain wrapper called a2x. You will need xsltproc,
39: DocBook XSL stylesheets, and optionally FOP (for PDF output) or lynx (for text
40: output) to benefit from its abilities, but it makes conversion very easy. 
41: As an example:
42: 	a2x -f pdf .txt
43: 
44: xslfproc is in /usr/bin on OpenSolaris. FOP must be downloaded from the 
45: Apache site (http://xml.apache.org/fop/) and installed.
46: 
47: 	gunzip fop-0.20.5-bin.tar.gz
48: 	tar xf fop-0.20.5-bin.tar
49: 	cd fop-0.20.5
50: 	cp fop.sh ../bin/
51: 	vi ~/bin/fop.sh
52: 		Set FOP_HOME
53: 	cd
54: 	ln -s fop-0.20.5 fop
55: 	unzip jimi1_0.zip
56: 	cd Jimi
57: 	unzip JimiProClasses.zip
58: 	cp ./examples/AppletDemo/JimiProClasses.jar ../fop-0.20.5/lib/
59: 	export JAVA_HOME=/usr/j2se
60: 
61: (I currently get an error "Exception in thread "main" 
62: java.lang.NoClassDefFoundError: org/apache/fop/apps/Fop" using fop.)
63: 
64: You can use the -verbose switch to see the executed toolchain commands.
65: 
66: Formatting rules for the text file are fairly straight-forward though 
67: there are a large number of "tags" used. The tags are much simpler than 
68: HTML or XML tags; the purpose of ASCIIdoc is to let you concentrate on 
69: text entry, not on tag entry and formatting.
70: 
71: Formatting text follows simple rules.
72: 
73: Emphasized text is enclosed in single quotes: ’emphasized’
74: Strong text (usually bold) in enclosed in asterisks: *strong*
75: Monospaced text is enclosed in backtick characters: `monospaced`
76: Quoted text is enclosed in doublee-quotes: "quoted"
77:  - quoted text must not be flanked by alphanumeric characters
78:  - quoting cannot be overlapped
79:  - different quoting types can be nested
80:  - to suppress quoted text formatting, place a backslash character before 
81: the leading quote character(s). In the case of ambiguity between escaped 
82: and non-escaped text you will need to escape both leading and trailing 
83: quotes, in the case of multi-character quotes you may even need to escape
84: individual characters.
85: Put carets on either side of text to be superscripted: ^super^
86: Put tildes on either side of text to be subscripted: ~sub~
87: By default, tabs are replaced by 8 spaces. This can be over-ridden.
88: 
89: The following replacements are defined in the default AsciiDoc configuration:
90: (C) copyright, (TM) trademark, (R) registered trademark, ~-- em dash, 
91: ...  ellipsis.
92: 
93: Line breaks (HTML/XHTML) are forced by a space followed by the "+" character 
94: at the end of a line.
95: Rulers (HTML/XHTML) are generated by a line of three or more apostrophe
96: characters.
97: 
98: Headers consist of titles, equal signs, an author line, and a date line, 
99: like this:
100: 
101: This Is A Title
102: 
103: {{{===============}}}
104: John Doe
105: v0.1 April 2006
106: 
107: There are five regular section levels supported. Book documents can have 
108: level 0 sections; all documents can have level 1 through 4 sections. 
109: Section levels are delineated by the section titles, which can either be
110: one-line or two-line titles:
111: 
112: One Line:
113: The number of equals signs (=) indicate the section level:
114:  = Document Title (level 0)
115:  == Section Title (level 1)
116:  === Section Title (level 2)
117:  ==== Section Title (level 3)
118:  ===== Section Title (level 4)
119: 
120: Two Lines:
121: Two-line titles consist of a title line (starting against the left margin), 
122: and an underline. Section underlines consist of different underline 
123: characters spanning the width of the title line:
124:  === Level 0 (top)
125:  ~--- Level 1
126:  ~~~ Level 2
127:  ^^^ Level 3
128:  +++ Level 4
129: 
130: Paragraphs are delimited by a blank line, the end of the file, or the start 
131: of a DelimitedBlock.
132: 
133: ASCIIdoc supports a wide range of other formatting codes, such as numerous 
134: block styles, lists, paragrasph styles, callouts, and on and on. For all of 
135: the features and codes, read the main manual that comes with the package
136: ~--chances are that what you need is already there.
137: 
138: For working examples see the article.txt and book.txt documents in the 
139: AsciiDoc ./doc distribution directory.
140: 
141: The asciidoc(1) command has a ~--help option which prints help topics to 
142: stdout. The default topic summarizes asciidoc(1) usage:
143:  $ asciidoc ~--help
144: To print a list of help topics:
145:  $ asciidoc ~--help=3Dtopics
146: To print a help topic specify the topic name as a command argument.
147: Examples:
148:  $ asciidoc ~--help=3Dmanpage
149:  $ asciidoc ~--help=3Dsyntax
150: 
151: Here is a rundown of some of the more common items you may need.
152: 
153: AsciiDoc can process UTF-8 character sets but there are some things you 
154: need to be aware of:
155:  * Admonition captions, example block title prefixes, table title prefixes 
156:    and image block title prefixes default to English. You can customise 
157:    these captions and prefixes with the caption attribute.  Alternatively 
158:    you could override the related AsciiDoc configuration file entries with 
159:    a custom configuration file.
160:     Note: The caption attribute only applies if you are using the xhtml11 
161:           or html4 backends - if you are going the DocBook route you will 
162:           need to configure the XSL Stylesheets for your language.
163:  * Some character sets display double-width characters (for example 
164:    Japanese). As far as title underlines are concerned they should be 
165:    treated as single character. If you think this looks untidy so you may 
166:    prefer to use the single line title format.
167: 
168: ListingBlocks are rendered verbatim in a monospaced font, they retain line 
169: and whitespace formatting and AsciiDoc User Guide often distinguished by a
170: background or border. There is no text formatting or substitutions within 
171: Listing blocks apart from Special Characters and Callouts. Listing blocks 
172: are often used for code and file listings.
173: 
174: Here’s an example:
175: ~--------------------------------------
176: #include 
177: int main() {
178: printf("Hello World!\n");
179: exit(0);
180: }
181: ~--------------------------------------
182: 
183: A sidebar is a short piece of text presented outside the narrative flow of 
184: the main text. The sidebar is normally presented inside a bordered box to 
185: set it apart from the main text.
186: 
187: The sidebar body is treated like a normal section body.
188: Here’s an example:
189: 
190: An Example Sidebar
191: ************************************************
192: Any AsciiDoc SectionBody element (apart from
193: SidebarBlocks) can be placed inside a sidebar.
194: ************************************************
195: 
196: The contents of CommentBlocks are not processed; they are useful for 
197: annotations and for excluding new or outdated content that you don’t want 
198: displayed. Here’s an example:
199: 
200: //////////////////////////////////////////
201: CommentBlock contents are not processed by
202: asciidoc(1).
203: //////////////////////////////////////////
204: 
205: ExampleBlocks encapsulate the DocBook Example element and are used for, 
206: well, examples. Example blocks can be titled by preceding them with a 
207: BlockTitle. DocBook toolchains normally number examples and generate a 
208: List of Examples backmatter section.
209: Example blocks are delimited by lines of equals characters and you can put 
210: any block elements apart from Titles, BlockTitles and Sidebars) inside an 
211: example block. For example:
212: 
213: An example
214: 
215: {{{=======================================================================}}}
216: Qui in magna commodo, est labitur dolorum an. Est ne magna primis
217: adolescens.
218: 
219: {{{=======================================================================}}}
220: 
221: The ExampleBlock definition includes a set of admonition styles (NOTE, TIP, 
222: IMPORTANT, WARNING, CAUTION) for generating admonition blocks (admonitions 
223: containing more than just a simple paragraph). Just precede the ExampleBlock 
224: with an attribute list containing the admonition style name. For example:
225: 
226: [NOTE]
227: A NOTE block
228: 
229: {{{=======================================================================}}}
230: Qui in magna commodo, est labitur dolorum an. Est ne magna primis
231: adolescens.
232:  Fusce euismod commodo velit.
233:  Vivamus fringilla mi eu lacus.
234: . Fusce euismod commodo velit.
235: . Vivamus fringilla mi eu lacus.
236:  Donec eget arcu bibendum
237: nunc consequat lobortis.
238: 
239: {{{=======================================================================}}}
240: 
241: Bulleted list items start with a dash or an asterisk followed by a space or 
242: tab character. Bulleted list
243: syntaxes are:
244: - List item.
245: * List item.
246: Numbered list items start with an optional number or letter followed by a 
247: period followed by a space or tab character. List numbering is optional. 
248: Numbered list syntaxes are:
249: 
250:  Integer numbered list item.
251: 1. Integer numbered list item with optional numbering.
252: . Lowercase letter numbered list item.
253: a. Lowercase letter numbered list item with optional numbering.
254: 
255: AsciiDoc comes pre-configured with a labeled list (:- label delimiter) for 
256: generating DocBook glossary lists. Example:
257: 
258: A glossary term:-
259:   The corresponding definition.
260: A second glossary term:-
261:   The corresponding definition.
262: 
263: AsciiDoc comes with a predefined itemized list (+ item bullet) for 
264: generating bibliography entries.
265: Example:
266: 
267: + [[[taoup]]] Eric Steven Raymond. ’The Art of UNIX Programming’. 
268: Addison-Wesley. ISBN 0-13-142901-9.
269: + [[[walsh-muellner]]] Norman Walsh & Leonard Muellner. ’DocBook - The 
270: Definitive Guide’. O’Reilly & Associates. 1999. ISBN 1-56592-580-7.
271: 
272: The [[[]]] syntax is a bibliography entry anchor, it generates 
273: an anchor named  and additionally displays [] at 
274: the anchor position. For example
275: 
276: [[[taoup]]] generates an anchor named taoup that displays [taoup] at the 
277: anchor position. Cite the reference from elsewhere your document using 
278: <>, this displays a hyperlink ([taoup]) to the corresponding 
279: bibliography entry anchor.
280: 
281: The shipped AsciiDoc configuration includes the footnote:[] inline 
282: macro for generating footnotes. The footnote text can span multiple lines. 
283: Example footnote:
284: 
285:   A footnote footnote:[An example footnote.]
286: 
287: Footnotes are primarily useful when generating DocBook output - 
288: DocBook conversion programs render footnote outside the primary text flow.
289: 
290: The shipped AsciiDoc configuration includes the inline macros for generating 
291: document index entries.
292: 
293: indexterm:[,,] ,
294: ++,,++ ,
295: This inline macro generates an index term (the  and  
296: attributes are optional).
297: For example indexterm:[Tigers,Big cats] (or, using the alternative syntax 
298: ++Tigers,Big cats++. Index terms that have secondary and tertiary entries 
299: also generate separate index terms for the secondary and tertiary entries.
300: The index terms appear in the index, not the primary text flow.
301: indexterm2:[] , ++ ,
302: This inline macro generates an index term that appears in both the index and 
303: the primary text flow.
304: The  should not be padded to the left or right with white space 
305: characters.
306: 
307: Two AsciiDoc inline macros are provided for creating hypertext links within 
308: an AsciiDoc document. You can use either the standard macro syntax or the 
309: (preferred) alternative.
310: 
311: anchor
312: Used to specify hypertext link targets:
313: [[,]]
314: anchor:[]
315: The  is a unique identifier that must begin with a letter. The optional 
316:  is the text to be displayed by captionless xref macros that refer 
317: to this anchor. The optional  is only really useful when 
318: generating DocBook output. Example anchor:
319: 
320: [[X1]]
321: You may have noticed that the syntax of this inline element is the same as 
322: that of the BlockId block element, this is no coincidence since they are 
323: functionally equivalent.
324: 
325: xref
326: Creates a hypertext link to a document anchor.
327: <<,>>
328: xref:[]
329: The  refers to an existing anchor . The optional  is the 
330: link’s displayed text. If  is not specified then the , enclosed 
331: in square brackets, is displayed. Example:
332: <>
333: Inline images are inserted into the output document using the image macro. 
334: The inline syntax is:
335: image:[]
336: The contents of the image file  is displayed. To display the image 
337: it’s file format must be supported by the target backend application. HTML 
338: and DocBook applications normally support PNG or JPG files.
339:  file name paths are relative to the location of the referring 
340: document.
341: Tables are the most complex AsciiDoc elements; read the (long) Tables 
342: section in the main document. AsciiDoc generates nice HTML tables, but the 
343: current crop of DocBook toolchains render tables with varying degrees of 
344: success. Use tables only when really necessary.
345: MANPAGE DOCUMENTS
346: Sooner or later, you may need to write a man page. By observing a couple 
347: of additional conventions you can compose AsciiDoc files that will translate 
348: to a DocBook refentry (man page) document. The resulting DocBook file can 
349: then be translated to the native roff man page format (or other formats).
350: For example, the asciidoc.1.txt file in the AsciiDoc distribution ./doc 
351: directory was used to generate both the asciidoc.1.css-embedded.html HTML 
352: file the asciidoc.1 roff formatted asciidoc(1) man page.
353:  Document Header
354:   A document Header is mandatory. The title line contains the man page 
355:   name followed immediately by the manual section number in brackets, for 
356:   example ASCIIDOC(1). The title name should not contain white space and 
357:   the manual section number is a single digit optionally followed by a 
358:   single character.
359:   The NAME Section
360:   The first manpage section is mandatory, must be titled NAME and must 
361:   contain a single paragraph (usually a single line) consisting of a list 
362:   of one or more comma separated command name(s) separated from the command 
363:   purpose by a dash character. The dash must have at least one white space 
364:   character on either side. For example:
365:   printf, fprintf, sprintf - print formatted output
366:   The SYNOPSIS Section
367:   The second manpage section is mandatory and must be titled SYNOPSIS.
368: 
369: }}}
OpenSolaris

Top Menu

Wiki code for ASCIIdocs Quick Start Guide

Search

Collectives

Community Group

Project

User Group

Subsites

Community Group documentation Pages
