Skip to content

Latest commit

 

History

History
149 lines (104 loc) · 4.21 KB

technical-writing-and-tools.asc

File metadata and controls

149 lines (104 loc) · 4.21 KB
Raw

Technical writing and tools

Introduction to AsciiDoc and related Tools for technical writing

Patrik Suzzi, December 2015
Copyright ©, 2015
Rev. 0.3, 2025-01-05: First draft

AsciiDoc

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 Home Page

Technical Writing with AsciiDoc

This document provides quick access to most used AsciiDoc web Resources and QuickReference.

Resources

Below I listed my most used resources for AsciiDoc learning and references

Most Used References

Below, a table with my most used references and favorite learning resources

Resource Description

Powerman AsciiDoc cheatsheet

compact cheatsheet

AsciiDoctor syntax quick reference

well organized and complete quick reference

AsciiDoctor writer’s guide

introduction, guide to writing and rendering

AsciiDoctor user manual

a quite coplete user manual for AsciiDoctor

Official AsciiDoc User Guide

A complete, official, user guide

AsciiDoctor Editing AsciiDoc with Live Preview

Overview of different ways to setup live preview

Editing Tools

Below, there are my favorite tools for AsciiDoc editing:

QuickReference

Below there is my list of frequently needed asciidoc examples. For a more extensive list, see AsciiDoc Syntax Quick Reference

Document main title

Below there is an example of how to start a document, providing metadata, Copyright and metadata.

= My AsciiDoc Title
Name Surname <author@asciidoctor.org>
v0.1, {docdate}: First draft
:toc:
:imagesdir: assets/images
:homepage: http://asciidoctor.org

A quick example on how to use this stuffs

*_{author}_* +
Copyright (C) 2015 +
Rev. {revnumber}, {revdate}: {revremark}

Titles

The titles are compared to HTML Headers. At first level we have a Title, rendered with a H1. Then the other titles are

= Title (Header1)
== Title 1 (Header2
=== Title2 (H3) ...

Links

http://www.eclipse.org[Eclipse Home] (1)
link:index.html[index] (2)
link:++https://www.google.com/search?q=java []++[search array](3)

  1. simple link

  2. relative path or windows path

  3. with special chars

Code

[[app-listing-title]]
[source, asciidoc]
----
here my http://www.methods.co.nz/asciidoc/[asciidoc] code
----

Images

image::images/use-asciidocfx.png[]