Sometimes in nonfiction writing we need a cross reference between one part of the book to another part of the book. We can easily add cross references using AsciiDoc plain text.
First, I’ll show you an example of the cross reference start point. In this book, in the "Gotchas" chapter, I have cross referenced to the audio review chapter. Here is the cross reference start point in this book’s AsciiDoc source text.
When using audio review (see <<audioReview>>), if you hear (1)
The cross reference start point is a code of your choosing surrounded by double angle brackets.
Next, I’ll show you how to add the cross reference target.
[[audioReview]] (1) == The Secret to Nearly Free Reviews (2)
The cross reference target is a code of your choosing surrounded by double square brackets.
The location of the cross reference target should be near where you want the reader to link. Here I added it immediately before the chapter title.
|If the code you type for the cross reference start point doesn’t exactly match the cross reference target, the cross reference link will be broken because the rendering app won’t know where to make the link. This link code must also be the exact same case (UPPER case or lower case letters).|
Rather than complicated codes, I just use a phrase for the target and jam the words all together and use what’s called camel case. This means the first word is lowercase and each additional word is initial cap.
|In many apps programming rules apply, meaning that adding spaces in codes or link identifiers causes problems. To avoid this group of problems I avoid spaces in identifiers for cross references. Camel case removes the spaces.|
So, for example if my target is about dogs being cute, then I might want to use the phrase "Dogs are cute" and I’d translate it to "dogAreCute" as my cross reference code.
You can use whatever you’d like to use as long as the two codes match so the rendering app can link between the start point and the target or end point.
The preceding example renders as follows.