So, I’m forcing myself to write this chapter on APT, and I’m taking a look at the official document. It appears to have been written by someone intent on making APT very painful to understand, here’s the lead-in:
In the following section, boxes containing text in typewriter-like font are examples of APT source.
A short APT document is contained in a single text file. A longer document may be contained in a ordered list of text files. For instance, first text file contains section 1, second text file contains section 2, and so on.
Note: Splitting the APT document in several text files on a section boundary is not mandatory. The split may occur anywhere. However doing so is recommended because a text file containing a section is by itself a valid APT document.
A file contains a sequence of paragraphs and “displays” (non paragraphs such as tables) separated by open lines.
A paragraph is simply a sequence of consecutive text lines.
Seriously, who wrote this? This is awful bordering on offensive. It feels like it was written by a computer, and whoever screwed up the Maven CSS last week decided to do fun things like center the APT markup examples for text. Here’s an example of the suckage:
A title block is indented (centering it is nicer)
The following example is used for a document with an title and a date but with no declared author.
The last line is ignored. It is just there to make the block nicer.
That’s my favorite quote of the entire document “It is just there to make the block nicer”. Yeah, thanks, those six hyphens really make that date block look much nicer. “centering it is nicer”. Someone needs to be publicly ridiculed for this.