AsciiDoc User Guide

PDF Fonts

The Adobe PDF Specification states that the following 14 fonts should be available to every PDF reader: Helvetica (normal, bold, italic, bold italic), Times (normal, bold, italic, bold italic), Courier (normal, bold, italic, bold italic), Symbol and ZapfDingbats. Non-standard fonts should be embedded in the distributed document.

Help Commands

The asciidoc(1) command has a --help option which prints help topics to stdout. The default topic summarizes asciidoc(1) usage:

$ asciidoc --help

To print a list of help topics:

$ asciidoc --help=topics

To print a help topic specify the topic name as a command argument. Examples:

$ asciidoc --help=manpage $ asciidoc --help=syntax

Customizing Help

To change, delete or add your own help topics edit a help.conf file. The file location will depend on whether you want the topics to apply to all users, to a single user or to a single project.

Help topics are stored help.conf text files. The help topic files have the same named section format as other configuration files. The help.conf files are stored in the same locations and loaded in the same order as other configuration files.

When the a --help command-line option is specified AsciiDoc loads the help.conf files and then prints the contents of the section whose name matches the help topic name. If a topic name is not specified default is used. If a matching help file section is not found a list of available topics is printed.

Tips and Tricks

Know Your Editor

Writing AsciiDoc documents will be a whole lot more pleasant if you know your favorite text editor. Learn how to indent and reformat text blocks, paragraphs, lists and sentences. Tips for vim users follow.

Vim Commands for Formatting AsciiDoc

The Vim text editor's gq command is great for reformatting and indenting AsciiDoc paragraphs and lists.

Tip

71

AsciiDoc User Guide

The Vim website (http://www.vim.org) has a wealth of resources, including scripts for automated spell checking and ASCII Art drawing.

Text Wrap Paragraphs

Use the vim :gq command to reformat paragraphs. Setting the textwidth sets the right text wrap margin; for example:

:set textwidth=70

To reformat a paragraph:

1.Position the cursor at the start of the paragraph.

2.Type gq}.

Execute :help gq command to read about the vim gq command.

Tip

Put set commands in your ~/.vimrc file so you don't have to enter them manually.

Format Lists

The :gq command can also be used to format bulleted and numbered lists. First you need to:

1.Set the textwidth right wrap margin.

2.Set the formatoptions n flag to enable numbered list reformatting (this flag also requires the autoindent option be set).

3.Add fb:*,fb:.,fb:+,fb:> to the comments option to assist the Vim :gq command reformat the AsciiDoc bulleted and numbered lists (in the example the C style comments middle part (mb:*) has been dropped to avoid ambiguity). Run the vim :help format-comments command for more about reformatting).

For example:

:set textwidth=70 formatoptions=tcqn autoindent

:set comments=s1:/*,ex:*/,://,b:#,:%,fb:-,fb:*,fb:.,fb:+,fb:>

Now you can format simple lists that use dash, asterisk, period and plus bullets along with numbered ordered lists:

1.Position the cursor at the start of the list.

72