Format updates to Library Naming topic (#568)

user-guide/modules/ROOT/pages/library-naming.adoc

@@ -9,6 +9,15 @@ Official repository: https://github.com/boostorg/website-v2-docs
 = Library Names and Organization
 :navtitle: Library Names and Organization
 
+* <<Introduction>>
+* <<Library Name Elements>>
+* <<Installed Library Names>>
+* <<The Boost Distribution>>
+* <<Footnotes>>
+* <<See Also>>
+
+== Introduction
+
 If your compiler supports auto-linking, such as Visual C++, then there is no need to understand the details of library binary naming. 
 
 However, if auto-linking is not supported by your compiler, then, in order to choose the right binary for your build configuration you
@@ -16,60 +25,41 @@ need to know how Boost binaries are named.
 
 == Library Name Elements
 
-Each library filename is
+Each library filename is composed of a common sequence of elements that describe how it was built. For example, `libboost_regex-vc71-mt-d-x86-1_34.lib`  can be broken down into the following elements:
-composed of a common sequence of elements that describe how it was
-built. For example, `libboost_regex-vc71-mt-d-x86-1_34.lib`  can
-be broken down into the following elements:
 
 [#footnote1-location]
-`lib`::
+* `lib`:  _Prefix_: except on Microsoft Windows, every Boost library name begins with this string. On Windows, only ordinary static libraries use the `lib` prefix; import libraries and DLLs do not. link:#footnote1[(1)]
-  _Prefix_: except on Microsoft Windows, every Boost library name begins
-  with this string. On Windows, only ordinary static libraries use the
-  `lib` prefix; import libraries and DLLs do not. link:#footnote1[(1)]
 
-`boost_regex`::
+* `boost_regex`:  _Library name_: all boost library filenames begin with `boost_`.
-  _Library name_: all boost library filenames begin with `boost_`.
 
-`-vc71`::
+* `-vc71`:  _Toolset tag_: identifies the xref:header-organization-compilation.adoc#toolset[toolset] and version used to build the binary.
-  _Toolset tag_: identifies the xref:header-organization-compilation.adoc#toolset[toolset] and version used to build the binary.
 
-`-mt`::
+* `-mt`:  _Threading tag_: indicates that the library was built with multithreading support enabled. Libraries built without multithreading support can be identified by the absence of `-mt` .
-  _Threading tag_: indicates that the library was built with
-  multithreading support enabled. Libraries built without multithreading
-  support can be identified by the absence of `-mt` .
 
 [#footnote2-location]
-`-d`::
+* `-d`:  _ABI tag_: encodes details that affect the library's interoperability with other compiled code. For each such feature, a single letter is added to the tag:
-  _ABI tag_: encodes details that affect the library's interoperability
++
-  with other compiled code. For each such feature, a single letter is
+[cols="1,5,2",options="header",stripes=even,frame=none]
-  added to the tag:
-
-[cols="1,5,2",options="header",stripes=even]
 |===
-|Key |Use this library when: |B2 option
+|Key |Use Case |B2 Option
-|`s` |linking statically to the C++ standard library and compiler
+|`s` |Linking statically to the C++ standard library and compiler
 runtime support libraries. |`runtime-link=static`
-|`g` |using debug versions of the standard and runtime support
+|`g` |Using debug versions of the standard and runtime support
 libraries. |`runtime-debugging=on`
-|`y` |using a special https://www.boost.org/doc/libs/1_58_0/libs/python/doc/building.html[debug build of Python]. |`python-debugging=on`
+|`y` |Using a special https://www.boost.org/doc/libs/1_58_0/libs/python/doc/building.html[debug build of Python]. |`python-debugging=on`
-|`d` |building a debug version of your code. link:#footnote2[(2)]
+|`d` |Building a debug version of your code. link:#footnote2[(2)]
 |`variant=debug`
-|`p` |using the STLPort standard library rather than the default one
+|`p` |Using the STLPort standard library rather than the default one
 supplied with your compiler. |`stdlib=stlport`
 |===
++
+For example, if you build a debug version of your code for use with debug versions of the static runtime library and the STLPort standard library, the tag would be: `-sgdp` . If none of the above apply, the ABI tag is omitted.
 
-For example, if you build a debug version of your code for use with
+* `-x86`: _Architecture and address model tag_: in the first letter, encodes the architecture as follows:
-debug versions of the static runtime library and the STLPort standard
++
-library, the tag would be: `-sgdp` . If none of the above
+[width="100%",cols="1,3,4",options="header",stripes=even,frame=none]
-apply, the ABI tag is omitted.
-
-`-x86`::
-  _Architecture and address model tag_: in the first letter, encodes the
-  architecture as follows:
-
-[width="100%",cols="1,3,4",options="header",stripes=even]
 |===
-|Key |Architecture |B2 option
+|Key |Architecture |B2 Option
 |`x` |x86-32, x86-64 | `architecture=x86`
 |`a` |ARM |`architecture=arm`
 |`i` |IA-64 |`architecture=ia64`
@@ -77,30 +67,19 @@ apply, the ABI tag is omitted.
 |`m` |MIPS/SGI |`architecture=mips*`
 |`p` |RS/6000 & PowerPC |`architecture=power`
 |===
-
++
-The two digits following the letter encode the address model as
+The two digits following the letter encode the address model as follows:
-follows:
++
-
+[width="100%",cols="1,3,4",options="header",stripes=even,frame=none]
-[width="100%",cols="1,3,4",options="header",stripes=even]
 |===
-|Key |Address model |B2 option
+|Key |Address Model |B2 Option
 |`32` |32 bit |`address-model=32`
 |`64` |64 bit |`address-model=64`
 |===
 
-`-1_34`::
+* `-1_34`: _Version tag_: the full Boost release number, with periods replaced by underscores. For example, version 1.31.1 would be tagged as `-1_31_1`.
-_Version tag_: the full Boost release number, with periods replaced by
-underscores. For example, version 1.31.1 would be tagged as `-1_31_1`.
 
-`.lib`::
+* `.lib`: _Extension_: determined according to the operating system's usual convention. On most unix-style platforms the extensions are `.a` and `.so` for static libraries (archives) and shared libraries, respectively. On Windows, `.dll` indicates a shared library and `.lib` indicates a static or import library. Where supported by toolsets on unix variants, a full version extension is added (e.g. ".so.1.34") and a symbolic link to the library file, named without the trailing version number, will also be created.
-_Extension_: determined according to the operating system's usual
-convention. On most unix-style platforms the extensions are `.a` and
-`.so` for static libraries (archives) and shared libraries,
-respectively. On Windows, `.dll` indicates a shared library and `.lib`
-indicates a static or import library. Where supported by toolsets on
-unix variants, a full version extension is added (e.g. ".so.1.34") and
-a symbolic link to the library file, named without the trailing
-version number, will also be created.
 
 == Installed Library Names
 
@@ -108,9 +87,9 @@ When libraries are installed using the B2 app, the actual name can vary from the
 
 The `--layout=<layout>` option determines how the library name is handled, and the appropriate header locations so that multiple versions of Boost, or multiple compilers, can be used on the same system.
 
-[cols="1,3,1",options="header",stripes=even]
+[cols="1,3,1",options="header",stripes=even,frame=none]
 |===
-|Layout |Description | Default on
+|Layout |Description | Default On
 |`versioned` | The names of Boost binaries include the Boost version number, name and version of the compiler, and encoded build properties. Boost headers are installed in a subdirectory of `<HDRDIR>` whose name contains the Boost version number. | Windows
 |`tagged` | Names of boost binaries include the encoded build properties such as variant and threading, but do not including compiler name and version, or Boost version. This option is useful if you build several variants of Boost, using the same compiler. | none
 |`system` | Binaries names do not include the Boost version number or the name and version number of the compiler. Boost headers are installed directly into `<HDRDIR>`. This option is intended for system integrators building distribution packages. | Unix
@@ -120,7 +99,7 @@ The `--layout=<layout>` option determines how the library name is handled, and t
 
 After installing Boost, this is the resulting directory structure, in the *boost_1_82_0* root:
 
-[cols="1,1,4",options="header",stripes=even]
+[cols="1,1,4",options="header",stripes=even,frame=none]
 |===
 |Root Level |Lower Level | Description
 |*bin.v2*| *libs* | Mainly contains the compiled binaries for those libraries that require compilation.
@@ -131,27 +110,19 @@ After installing Boost, this is the resulting directory structure, in the *boost
 |*stage* | *lib* | CMake files for each library
 |*status*| | Boost-wide test suite
 |*tools* | tool folders |Utilities: B2, quickbook, bcp, etc.
-|b2.exe| | Boost install app, and supporting files
+|`b2.exe`| | Boost install app, and supporting files
-|index.htm | | A copy of www.boost.org starts here
+|`index.htm` | | A copy of www.boost.org starts here
 |===
 
 == Footnotes
 
 [#footnote1]
-link:#footnote1-location[(1)]::
+link:#footnote1-location[(1)] This convention distinguishes the static version of a Boost library from the import library for an identically-configured Boost DLL, which would otherwise have the same name.
-This convention distinguishes the static version of a
-Boost library from the import library for an identically-configured
-Boost DLL, which would otherwise have the same name.
 
 [#footnote2]
-link:#footnote2-location[(2)]::
+link:#footnote2-location[(2)] These libraries were compiled without optimization or inlining, with full debug symbols enabled, and without `#define NDEBUG`. Although it's true that sometimes these choices don't affect binary compatibility with other compiled code, you can't count on that with Boost libraries.
-These libraries were compiled without optimization or
-inlining, with full debug symbols enabled, and without `#define NDEBUG`. Although it's true that sometimes these choices don't affect
-binary compatibility with other compiled code, you can't count on that
-with Boost libraries.
 
 == See Also
 
-[square]
 * xref:header-organization-compilation.adoc[]