Writing in DocBook is just… inhumane
I found I was spending more time fixing syntax errors than I was writing the documentation.
Stuart Rackham
DocBook is a complex language, the markup is difficult to read and even more difficult to write directly — I found I was spending more time typing markup tags, consulting reference manuals and fixing syntax errors, than I was writing the documentation.
Just let me write, dammit!
+yyyyyyyyyyyyyyyyyyyyyyo- `yNNNNNNNNNNNNNNNNNNNNNMMMNo` -:::::::::::::::::::::::`.:dMMN- oNMMMMMMMMMMMMMMMMMMMMMMMMMd/ sMMN` oMMm+:::::::::::::::::::::+MMM: NMM- sMMs MMMo NMM- sMMs MMMo NMM- sMMs `mMMMMMMMMMMMMMMMMMd MMMo NMM- sMMs `++++++++++++++++/` MMMo NMM- sMMs `mMMMMMMMMMMMMMMMMMd MMMo NMM- sMMs .+++++++++++++++++` MMMo NMM- sMMs `dmmmmmmmmmmmmmmmmmh MMMo NMM- sMMs ://///////////////. MMMo NMM- sMMs `hmmmmmmmmmmmmmmmmms MMMo NMM- sMMs //////////////////- MMMo NMM- sMMs `yddddddddddddddddds MMMo NMM- sMMs /yyyyyyyyyyyyyyyys/ MMMo NMM- sMMs `ohhhhhhhhhhhhhhhhho MMMo NMM- sMMs MMMo dMN. sMMs MMMo .` :MMMdhhhhhhhhhhhhhhhhhhhhhdMMN. .shmmmmmmmmmmmmmmmmmmmmmmmho. .o. o8o o8o oooooooooo. .888. `"' `"' `888' `Y8b .8"888. .oooo.o .ooooo. oooo oooo 888 888 .ooooo. .ooooo. .8' `888. d88( "8 d88' `"Y8 `888 `888 888 888 d88' `88b d88' `"Y8 .88ooo8888. `"Y88b. 888 888 888 888 888 888 888 888 .8' `888. o. )88b 888 .o8 888 888 888 d88' 888 888 888 .o8 o88o o8888o 8""888P' `Y8bod8P' o888o o888o o888bood8P' `Y8bod8P' `Y8bod8P'
A lightweight, yet powerful text-based markup language and document generator
…that’s got it all!
AsciiDoc was created by Stuart Rackham, hailing from New Zealand Comparable to Markdown, yet far more complete
Mild punctuation
I’m amazed by AsciiDoc :-) It handles a lot of use cases well, and some other cases are still possible at least.
Anders Nawroth, Neo4j
Document Title
==============
John Doe <john.doe@example.com>
v1.0, 2012-12-01
This is the optional preamble (an untitled section body). Useful for
writing simple sectionless documents consisting only of a preamble.
NOTE: The abstract, preface, appendix, bibliography, glossary and
index section titles are significant ('specialsections').
== First section
Document sections start at level 1 and can nest up to four levels deep.
* Item 1
* Item 2
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<book lang="en">
<bookinfo>
<title>Document Title</title>
<date>2012-12-01</date>
<author>
<firstname>John</firstname>
<surname>Doe</surname>
<email>john.doe@example.com</email>
</author>
<authorinitials>JD</authorinitials>
<revhistory>
<revision>
<revnumber>1.0</revnumber>
<date>2012-12-01</date>
<authorinitials>JD</authorinitials>
</revision>
</revhistory>
</bookinfo>
<preface>
...
...
<simpara>
This is the optional preamble (an untitled section body).
Useful for writing simple sectionless documents consisting
only of a preamble.
</simpara>
<note>
<simpara>
The abstract, preface, appendix, bibliography, glossary
and index section titles are significant
(<emphasis>specialsections</emphasis>).
</simpara>
</note>
</preface>
<chapter id="_first_section">
<title>First section</title>
<simpara>
Document sections start at level 1 and can nest up to
four levels deep.
</simpara>
<itemizedlist>
<listitem>
<simpara>Item 1</simpara>
...
...
</listitem>
<listitem>
<simpara>Item 2</simpara>
</listitem>
</itemizedlist>
</chapter>
</book>
DocBook becomes a distraction to the task of writing the documentation. Your focus is on the tags and how to manage them rather than the text.
I use Markdown to write my documention.
Most developers on github
# Document Title
This is the optional preamble (an untitled section body). Useful for
writing simple sectionless documents consisting only of a preamble.
> **Note**
>
> The abstract, preface, appendix, bibliography, glossary and index
> section titles are significant (*specialsections*).
## First section
Document sections start at level 1 and can nest up to four levels deep.
* Item 1
* Item 2
Hmm, can’t really cover all the requirements :(
Markdown : 1st-grader ::
Asciidoc : PhD student
Title (Level 0)
===============
Level 1
-------
Level 2
~~~~~~~
Level 3
^^^^^^^
Level 4
+++++++
= Title (Level 0) =
== Level 1 ==
=== Level 2 ===
==== Level 3 ====
===== Level 4 =====
= Title (Level 0)
== Level 1
=== Level 2
==== Level 3
===== Level 4
I prefer using prefix, except underline for the title
This paragraph contains 'emphasized', *strong*, `monospaced` text.
This paragraph has fancy `single-quoted' and ``double-quoted'' text.
To get [underline]#underlined# text, you can use a inline role (i.e., class) named underline.
x*x can be written as x^2 and you swim in H~2~O.
We break at the end of this line +
to keep the text from overflowing.
.Look at me!
This paragraph has it's own title. footnote:[A title can help a paragraph stand out.]
....
Renders as pre-formatted, monospaced text
....
.Optional caption
----
public interface Document {}
----
.Optional caption
****
Stuff in here is set off with a different background.
****
[quote, Linus Torvalds, comp.os.minix (1991)]
____
I'm doing a (free) operating system (just a hobby, won't be big and professional like gnu) for 386(486) AT clones.
____
Only 4 consecutive delimeters are required. I recommend using the minimum rather than formatting them to match the line length.
* Linux
** Fedora
** Ubuntu
* Mac OSX
* Windoze
.Vendors
- Asus
- Lenovo
- Samsung
. Wake up
. Go to work
. Write docs!
.. Open your text editor
.. Experience the joy of text
. Eat cake
AsciiDoc:: advanced text-based document generation
DocBook:: keeps a programmer busy for hours
http://asciidoc.org
http://asciidoc.org[AsciiDoc project]
[[anchor]]Deep link
<<anchor,Go to deep link>>
image:images/logo.png[Logo]
image::images/logo.png[Logo]
.Screenshot
image::images/screenshot.png[Screenshot]
include::footer.adoc[]
NOTE: Just a quick note that you should pay attention.
[NOTE]
Perhaps this one is to your liking?
[IMPORTANT]
====
Get the full rich web experience!
* HTML 5, CSS 3 & JavaScript
====
.Optional caption
====
Examples are good. They show you how to use stuff.
====
.Optional caption
[options="header"]
|====================
|Col 1 |Col 2 |Col 3
|1 |Item 1 |a
|2 |Item 2 |b
|3 |Item 3 |c
|====================
.Contacts
[grid="rows",format="csv"]
[options="header",cols="^,<,<,<,>"]
|==========================
ID,First,Last,Address,Phone
1,Allen,Dan,Denver,3035551212
2,Doe,John,"Washington, D.C.",2025551212
|==========================
vim, gedit syntax highlighting support
Tip
|
view docbook with yelp |
Drop the <>, but not the semantics
[macros]
(?su)(?<!\S)[\\]?(?P<name>filename):(?P<target>[\w/])=
[filename-inlinemacro]
ifdef::basebackend-docbook[]
<filename{target@.*/$: class="directory"}>{target}</filename>
endif::basebackend-docbook[]
ifdef::basebackend-html[]
<tt>{target}</tt>
endif::basebackend-html[]
My home directory is filename:/home/dallen/.
Also acronym-macro.conf
† Work is underway on a Ruby port