Ascii​Doc

= AsciiDoc Package for Sublime Text
:experimental:

This is a link:https://www.sublimetext.com[Sublime Text] package
for link:https://asciidoc.org[AsciiDoc].
It adds syntax highlighting and snippets
for the AsciiDoc language to Sublime Text.


== Installation

=== Package Control
Find the package on Package Control
under the name link:https://packagecontrol.io/packages/AsciiDoc[AsciiDoc].


=== Manual
To install the package manually, follow these steps:

* Download the zip containing source files.
* Open your Sublime Text [role="filename"]`Packages` folder:
Windows::
[role="filename"]`+%AppData%\Sublime Text\Packages+`
OS X::
[role="filename"]`+~/Library/Application Support/Sublime Text/Packages+`
Linux::
[role="filename"]`+~/.config/sublime-text/Packages+`
Portable Installation::
[role="filename"]`Sublime Text/Data`
* Create or open an [role="filename"]`AsciiDoc` folder there.
* Extract the files to it.
* Close all instances of Sublime Text and relaunch the editor.

If successful, you should see an *AsciiDoc* entry under menu:View[Syntax] and under menu:Tools[Snippets].

NOTE: Snippets may take few seconds to load under Windows.


== Configure Variables: `TM_FULLNAME`, `TM_EMAIL`, etc.

The Article snippet loads certain values
from the TextMate standard for environment variables,
like many other features of Sublime.
These are configured
in the [role="filename"]`Default.tmPreferences` file.

. Edit [role="filename"]`Default.tmPreferences`.
. Replace "My Full Name", "My Email", and "My Company"
with your actual name, email address, and company name.
. Update the definition of `TM_YEAR`.
. Test the Article snippet.
(Create a new AsciiDoc file, type `ar` and hit kbd:[Tab].)


== Configure the AsciiDoc Build System

Sublime has a build system for compiling source code like AsciiDoc source.
A file called [role="filename"]`asciidoc.sublime-build` is provided here
to allow you to take advantage of the build system,
but it needs to be told where you have installed Python and AsciiDoc:

. Edit [role="filename"]`asciidoc.sublime-build`.
. Change the `working_dir` from `/path/to/asciidoc-8.6.8`
to the actual location where you have AsciiDoc installed
(e.g. [role="filename"]`+C:\prgs\asciidoc-8.6.8+`)
. Change the first parameter of `cmd`
from `/path/to/python` to the actual name and location of your Python engine
(e.g. [role="filename"]`+C:\Python39\python.exe+`)

NOTE: See below about kbd:[Ctrl+B] no longer being the shortcut key for the build system.


== Usage

* Create a new file, and save it as [role="filename"]`<filename>.adoc`.
* Start typing AsciiDoc!


== Snippets

Snippets can be inserted anywhere by using the menu command
menu:Tools[Snippets > AsciiDoc] or by typing two initial characters
and hitting tab to complete.
A few tab completion examples are:

* Start a new article (type `ar` kbd:[Tab])
* Comments (type `//` kbd:[Tab])
* Headings (type `h1` kbd:[Tab] to `h4` kbd:[Tab] for one-liner versions)
* Table generation (type `|=` kbd:[Tab])
* Tab expansion for blocks (type `==` kbd:[Tab])
* Sidebar block (type `**` kbd:[Tab])
* Add a definition to a glossary (type `::` kbd:[Tab])
* Refer to a glossary definition elsewhere (type `<<` kbd:[Tab])

=== Article
* When you first invoke the Article snippet, "Title" will be highlighted.
* Type over it with the actual title you want.
(Notice that the new title will be automatically underlined to length.)
* Hit kbd:[Tab] to move off the title,
and the backend choices will be highlighted.
These are only the 3 most popular backends.
Either delete 2 of them, or type over the whole thing
with a 4th choice (e.g. manpage).
* Hit kbd:[Tab] to move to the end.

=== Definition and Definition Link
Use these to create glossary definitions
with anchors and corresponding references to them.
Note how the anchor tags will be automatically composed
as you type the name of the term being defined,
and also how any non-alphanumeric characters are
automatically left out of the tag.


=== Keyboard Shortcuts
Basic support for some handy shortcuts are now available:

*Bold* selection::
Select some text and then press kbd:[Ctrl+B].
_Italicize_ selection::
Select some text and then press kbd:[Ctrl+I].
Mark selection as Code literal::
Select some text and then press kbd:[Ctrl+K], kbd:[Ctrl+K].
Mark selection as filename::
Select some text and then press kbd:[Ctrl+K], kbd:[Ctrl+F].

NOTE: kbd:[Ctrl+B] overrides the standard key binding
of menu:Tools[Build System].
If this bothers you, you can edit the `.sublime-keymap` files
under the [role="filename"]`Packages/AsciiDoc` folder.

If you come upon something useful, feel free to submit a patch!


=== Enhancements
The following are planned enhancements for the package:

* [x] Add keyboard shortcuts for various commands
such as bold text, italics, blocks etc.
* [x] Adding Build system to preview as HTML or PDF.

Your suggestions are welcome.


== Author & Credits
* Created by Hrusikesh Panda.
* Syntax rewrite by Michael Lyons.
* Credit goes to Christian Zuckschwerdt for his original work
on the
link:https://github.com/zuckschwerdt/asciidoc.tmbundle[AsciiDoc TextMate bundle].
* The Article, Definition, and Definition Link snippets were written by Craig Jones.