Rename 'link-args' to 'advanced-linking', add intro

diff --git a/src/doc/trpl/SUMMARY.md b/src/doc/trpl/SUMMARY.md
index ca3381ffba465d61a0da1f6742f4b2ce2ee7fdf4..f1e51591aea0eb30a4e77467f4d568cca3144094 100644 (file)
--- a/src/doc/trpl/SUMMARY.md
+++ b/src/doc/trpl/SUMMARY.md
@@ -63,7 +63,7 @@
     * [No stdlib](no-stdlib.md)
     * [Intrinsics](intrinsics.md)
     * [Lang items](lang-items.md)
-    * [Link args](link-args.md)
+    * [Advanced linking](advanced-linking.md)
     * [Benchmark Tests](benchmark-tests.md)
     * [Box Syntax and Patterns](box-syntax-and-patterns.md)
     * [Slice Patterns](slice-patterns.md)

diff --git a/src/doc/trpl/advanced-linking.md b/src/doc/trpl/advanced-linking.md
new file mode 100644 (file)
index 0000000..f54799d
--- /dev/null
+++ b/src/doc/trpl/advanced-linking.md
@@ -0,0 +1,32 @@
+% Advanced Linking
+
+The common cases of linking with Rust have been covered earlier in this book,
+but supporting the range of linking possibilities made available by other
+languages is important for Rust to achieve seamless interaction with native
+libraries.
+
+# Link args
+
+There is one other way to tell `rustc` how to customize linking, and that is via
+the `link_args` attribute. This attribute is applied to `extern` blocks and
+specifies raw flags which need to get passed to the linker when producing an
+artifact. An example usage would be:
+
+``` no_run
+#![feature(link_args)]
+
+#[link_args = "-foo -bar -baz"]
+extern {}
+# fn main() {}
+```
+
+Note that this feature is currently hidden behind the `feature(link_args)` gate
+because this is not a sanctioned way of performing linking. Right now `rustc`
+shells out to the system linker, so it makes sense to provide extra command line
+arguments, but this will not always be the case. In the future `rustc` may use
+LLVM directly to link native libraries, in which case `link_args` will have no
+meaning.
+
+It is highly recommended to *not* use this attribute, and rather use the more
+formal `#[link(...)]` attribute on `extern` blocks instead.
+

diff --git a/src/doc/trpl/link-args.md b/src/doc/trpl/link-args.md
deleted file mode 100644 (file)
index cdaef6c..0000000
--- a/src/doc/trpl/link-args.md
+++ /dev/null
@@ -1,25 +0,0 @@
-% Link args
-
-There is one other way to tell rustc how to customize linking, and that is via
-the `link_args` attribute. This attribute is applied to `extern` blocks and
-specifies raw flags which need to get passed to the linker when producing an
-artifact. An example usage would be:
-
-``` no_run
-#![feature(link_args)]
-
-#[link_args = "-foo -bar -baz"]
-extern {}
-# fn main() {}
-```
-
-Note that this feature is currently hidden behind the `feature(link_args)` gate
-because this is not a sanctioned way of performing linking. Right now rustc
-shells out to the system linker, so it makes sense to provide extra command line
-arguments, but this will not always be the case. In the future rustc may use
-LLVM directly to link native libraries, in which case `link_args` will have no
-meaning.
-
-It is highly recommended to *not* use this attribute, and rather use the more
-formal `#[link(...)]` attribute on `extern` blocks instead.
-