1 files changed, 39 insertions, 19 deletions

diff --git a/documentation/content/en/articles/building-products/_index.adoc b/documentation/content/en/articles/building-products/_index.adoc
index 038feb9c07..b444b4a41e 100644
--- a/documentation/content/en/articles/building-products/_index.adoc
+++ b/documentation/content/en/articles/building-products/_index.adoc
@@ -62,7 +62,8 @@ toc::[]
 FreeBSD today is well-known as a high-performance server operating system.
 It is deployed on millions of web servers and internet-facing hosts worldwide.
 FreeBSD code also forms an integral part of many products, ranging from appliances such as network routers, firewalls, and storage devices, to personal computers.
-Portions of FreeBSD have also been used in commercial shrink-wrapped software (see <<freebsd-intro>>).
+Portions of FreeBSD have also been used in commercial shrink-wrapped software
+(see crossref:building-products[freebsd-intro]).
 
 In this article we look at the link:https://www.FreeBSD.org/[FreeBSD project] as a software engineering resource-as a collection of building blocks and processes which you can use to build products.
 
@@ -95,21 +96,24 @@ After reading this article you should have:
 
 The rest of the article is structured as follows:
 
-* <<freebsd-intro>> introduces the FreeBSD project, explores its organizational structure, key technologies and release engineering processes.
-* <<freebsd-collaboration>> describes ways to collaborate with the FreeBSD project. It examines common pitfalls encountered by corporates working with voluntary projects like FreeBSD.
-* <<conclusion>> concludes.
+* crossref:building-products[freebsd-intro] introduces the FreeBSD project, explores its organizational structure, key technologies and release engineering processes.
+* crossref:building-products[freebsd-collaboration] describes ways to collaborate with the FreeBSD project. It examines common pitfalls encountered by corporates working with voluntary projects like FreeBSD.
+* crossref:building-products[conclusion] concludes.
 
 [[freebsd-intro]]
 == FreeBSD as a set of building blocks
 
 FreeBSD makes an excellent foundation on which to build products:
 
-* FreeBSD source code is distributed under a liberal BSD license facilitating its adoption in commercial products <<Mon2005>> with minimum hassle.
+* FreeBSD source code is distributed under a liberal BSD license facilitating
+  its adoption in commercial products crossref:building-products[Mon2005] with minimum hassle.
 * The FreeBSD project has excellent engineering practices that can be leveraged.
 * The project offers exceptional transparency into its workings, allowing organizations using its code to plan effectively for the future.
-* The culture of the FreeBSD project, carried over from the Computer Science Research Group at The University of California, Berkeley <<McKu1999-1>>, fosters high-quality work. Some features in FreeBSD define the state of the art.
+* The culture of the FreeBSD project, carried over from the Computer Science
+  Research Group at The University of California, Berkeley
+  crossref:building-products[McKu1999-1], fosters high-quality work. Some features in FreeBSD define the state of the art.
 
-<<GoldGab2005>> examines the business reasons for using open-source in greater detail.
+crossref:building-products[GoldGab2005] examines the business reasons for using open-source in greater detail.
 For organizations, the benefits of using FreeBSD components in their products include a shorter time to market, lower development costs and lower development risks. 
 
 === Building with FreeBSD
@@ -157,7 +161,9 @@ A selection of these are listed below:
 FreeBSD's in-kernel Netgraph (man:netgraph[4]) framework allows kernel networking modules to be connected together in flexible ways.
 * Support for storage technologies: Fibre Channel, SCSI, software and hardware RAID, ATA and SATA.
 +
-FreeBSD supports a number of filesystems, and its native UFS2 filesystem supports soft updates, snapshots and very large filesystem sizes (16TB per filesystem) <<McKu1999>>.
+FreeBSD supports a number of filesystems, and its native UFS2 filesystem
+supports soft updates, snapshots and very large filesystem sizes (16TB per
+		filesystem) crossref:building-products[McKu1999].
 +
 FreeBSD's in-kernel GEOM (man:geom[4]) framework allows kernel storage modules to be composed in flexible ways.
 * Over {numports} ported applications, both commercial and open-source, managed via the FreeBSD ports collection.
@@ -179,14 +185,17 @@ Conflict resolution is performed by a nine member "Core Team" that is elected fr
 
 FreeBSD does not have "corporate" committers.
 Individual committers are required to take responsibility for the changes they introduce to the code.
-The extref:{committers-guide}[FreeBSD Committer's guide] <<ComGuide>> documents the rules and responsibilities for committers.
+The extref:{committers-guide}[FreeBSD Committer's guide]
+crossref:building-products[ComGuide] documents the rules and responsibilities for committers.
 
-FreeBSD's project model is examined in detail in <<Nik2005>>.
+FreeBSD's project model is examined in detail in
+crossref:building-products[Nik2005].
 
 === FreeBSD Release Engineering Processes
 
 FreeBSD's release engineering processes play a major role in ensuring that its released versions are of a high quality.
-At any point of time, FreeBSD's volunteers support multiple code lines (<<fig-freebsd-branches, FreeBSD Release Branches>>):
+At any point of time, FreeBSD's volunteers support multiple code lines
+(crossref:building-products[fig-freebsd-branches, FreeBSD Release Branches]):
 
 * New features and disruptive code enters on the development branch, also known as the _-CURRENT_ branch.
 * _-STABLE_ branches are code lines that are branched from HEAD at regular intervals. Only tested code is allowed onto a -STABLE branch. New features are allowed once they have been tested and stabilized in the -CURRENT branch.
@@ -204,7 +213,8 @@ The list of extref:{committers-guide}[supported architectures, archs] is part of
 The release engineering team publishes a link:https://www.FreeBSD.org/releng/[road map] for future releases of FreeBSD on the project's web site.
 The dates laid down in the road map are not deadlines; FreeBSD is released when its code and documentation are ready.
 
-FreeBSD's release engineering processes are described in <<RelEngDoc>>.
+FreeBSD's release engineering processes are described in
+crossref:building-products[RelEngDoc].
 
 [[freebsd-collaboration]]
 == Collaborating with FreeBSD
@@ -217,7 +227,7 @@ Using open-source code is best viewed not as a one-off activity, but as an __ong
 The best projects to collaborate with are the ones that are __live__; i.e., with an active community, clear goals and a transparent working style.
 
 * FreeBSD has an active developer community around it. At the time of writing there are many thousands of contributors from every populated continent in the world and over 300 individuals with write access to the project's source repositories.
-* The goals of the FreeBSD project are <<Hub1994>>:
+* The goals of the FreeBSD project are crossref:building-products[Hub1994]:
 
 ** To develop a high-quality operating system for popular computer hardware, and,
 ** To make our work available to all under a liberal license.
@@ -232,18 +242,24 @@ To be able to work effectively with the FreeBSD project, you need to understand
 Volunteer driven projects operate under different rules than for-profit corporates.
 A common mistake that companies make when venturing into the open-source world is that of underplaying these differences.
 
-*Motivation.* Most contributions to FreeBSD are done voluntarily without monetary rewards entering the picture. The factors that motivate individuals are complex, ranging from altruism, to an interest in solving the kinds of problems that FreeBSD attempts to solve. In this environment, "elegance is never optional"<<Nor1993>>.
+*Motivation.* Most contributions to FreeBSD are done voluntarily without
+monetary rewards entering the picture. The factors that motivate individuals are
+complex, ranging from altruism, to an interest in solving the kinds of problems
+that FreeBSD attempts to solve. In this environment, "elegance is never
+optional"crossref:building-products[Nor1993].
 
 *The Long Term View.* FreeBSD traces its roots back nearly twenty years to the work of the Computer Science Research Group at the University of California Berkeley.footnote:[FreeBSD's source repository contains a history of the project since its inception, and there are CDROMs available that contain earlier code from the CSRG.] A number of the original CSRG developers remain associated with the project.
 
-The project values long-term perspectives <<Nor2001>>. A frequent acronym encountered in the project is DTRT, which stands for "Do The Right Thing".
+The project values long-term perspectives crossref:building-products[Nor2001]. A frequent acronym encountered in the project is DTRT, which stands for "Do The Right Thing".
 
 *Development Processes.* Computer programs are tools for communication: at one level programmers communicate their intentions using a precise notation to a tool (a compiler) that translates their instructions to executable code.
 At another level, the same notation is used for communication of intent between two programmers.
 
 Formal specifications and design documents are seldom used in the project.
-Clear and well-written code and well-written change logs (<<fig-change-log, A sample change log entry>>) are used in their place.
-FreeBSD development happens by "rough consensus and running code"<<Carp1996>>.
+Clear and well-written code and well-written change logs
+(crossref:building-products[fig-change-log, A sample change log entry]) are used in their place.
+FreeBSD development happens by "rough consensus and running
+code"crossref:building-products[Carp1996].
 
 [.programlisting]
 ....
@@ -281,7 +297,10 @@ For example:
 +
 *Track FreeBSD source code.* The project makes it easy to mirror its SVN repository using extref:{committers-guide}[svnsync, svn-advanced-use-setting-up-svnsync]. Having the complete history of the source is useful when debugging complex problems and offers valuable insight into the intentions of the original developers. Use a capable source control system that allows you to easily merge changes between the upstream FreeBSD code base and your own in-house code.
 +
-<<fig-svn-blame, An annotated source listing generated using `svn blame`>> shows a portion of an annotated listing of the file referenced by the change log in <<fig-change-log, A sample change log entry>>.
+crossref:building-products[fig-svn-blame, An annotated source listing generated
+using `svn blame`] shows a portion of an annotated listing of the file
+referenced by the change log in crossref:building-products[fig-change-log, A
+sample change log entry].
 The ancestry of each line of the source is clearly visible.
 Annotated listings showing the history of every file that is part of FreeBSD are https://svnweb.freebsd.org/[available on the web].
 +
@@ -325,7 +344,8 @@ The FreeBSD project maintains a link:https://www.FreeBSD.org/commercial/consult_
 The http://www.bsdcertification.org/[BSD Certification Group] offers certification for all the major BSD derived OSes.
 +
 For less critical needs, you can ask for help on the link:https://lists.freebsd.org/[project mailing lists].
-A useful guide to follow when asking for help is given in <<Ray2004>>. 
+A useful guide to follow when asking for help is given in
+crossref:building-products[Ray2004].
 Publicize your involvement::
 You are not required to publicize your use of FreeBSD, but doing so helps both your effort as well as that of the project.
 +