[doc] use autogenerated names, keep existing links usable (#43027)

inkydragon · web-flow · commit 40ffd6ff3eb7 · 2021-11-17T16:44:38.000-05:00
diff --git a/doc/src/base/base.md b/doc/src/base/base.md
@@ -41,7 +41,7 @@ ans
 Base.active_project
 ```
 
-## [Keywords](@id base-keywords)
+## [Keywords](@id Keywords)
 
 This is the list of reserved keywords in Julia:
 `baremodule`, `begin`, `break`, `catch`, `const`, `continue`, `do`,
diff --git a/doc/src/base/io-network.md b/doc/src/base/io-network.md
@@ -74,7 +74,7 @@ Base.eachline
 Base.displaysize
 ```
 
-## [Multimedia I/O](@id base-multimedia)
+## [Multimedia I/O](@id Multimedia-I/O)
 
 Just as text output is performed by [`print`](@ref) and user-defined types can indicate their textual
 representation by overloading [`show`](@ref), Julia provides a standardized mechanism for rich multimedia
diff --git a/doc/src/base/numbers.md b/doc/src/base/numbers.md
@@ -111,7 +111,7 @@ Base.@int128_str
 Base.@uint128_str
 ```
 
-## [BigFloats and BigInts](@id base-big)
+## [BigFloats and BigInts](@id BigFloats-and-BigInts)
 
 The [`BigFloat`](@ref) and [`BigInt`](@ref) types implements
 arbitrary-precision floating point and integer arithmetic, respectively. For
diff --git a/doc/src/devdocs/ast.md b/doc/src/devdocs/ast.md
@@ -595,7 +595,7 @@ A unique'd container describing the shared metadata for a single method.
 ### MethodInstance
 
 A unique'd container describing a single callable signature for a Method.
-See especially [Proper maintenance and care of multi-threading locks](@ref dev-locks)
+See especially [Proper maintenance and care of multi-threading locks](@ref Proper-maintenance-and-care-of-multi-threading-locks)
 for important details on how to modify these fields safely.
 
   * `specTypes`
diff --git a/doc/src/devdocs/debuggingtips.md b/doc/src/devdocs/debuggingtips.md
@@ -1,4 +1,4 @@
-# [gdb debugging tips](@id dev-debug)
+# [gdb debugging tips](@id gdb-debugging-tips)
 
 ## Displaying Julia variables
 
diff --git a/doc/src/devdocs/functions.md b/doc/src/devdocs/functions.md
@@ -13,7 +13,7 @@ share the same `Complex` type name object.
 All objects in Julia are potentially callable, because every object has a type, which in turn
 has a `TypeName`.
 
-## [Function calls](@id dev-func-call)
+## [Function calls](@id Function-calls)
 
 Given the call `f(x,y)`, the following steps are performed: first, the method table to use is
 accessed as `typeof(f).name.mt`. Second, an argument tuple type is formed, `Tuple{typeof(f), typeof(x), typeof(y)}`.
diff --git a/doc/src/devdocs/init.md b/doc/src/devdocs/init.md
@@ -10,7 +10,7 @@ which loads a few libraries, eventually calling [`repl_entrypoint()` in `src/jla
 
 `repl_entrypoint()` calls [`libsupport_init()`](https://github.com/JuliaLang/julia/blob/master/src/support/libsupportinit.c)
 to set the C library locale and to initialize the "ios" library (see [`ios_init_stdstreams()`](https://github.com/JuliaLang/julia/blob/master/src/support/ios.c)
-and [Legacy `ios.c` library](@ref dev-stdio-ios-c)).
+and [Legacy `ios.c` library](@ref Legacy-ios.c-library)).
 
 Next [`jl_parse_opts()`](https://github.com/JuliaLang/julia/blob/master/src/jloptions.c) is called to process
 command line options. Note that `jl_parse_opts()` only deals with options that affect code generation
@@ -29,7 +29,7 @@ by `main()` and calls [`_julia_init()` in `init.c`](https://github.com/JuliaLang
 to zero the signal handler mask.
 
 [`jl_resolve_sysimg_location()`](https://github.com/JuliaLang/julia/blob/master/src/init.c) searches
-configured paths for the base system image. See [Building the Julia system image](@ref dev-sysimg-build).
+configured paths for the base system image. See [Building the Julia system image](@ref Building-the-Julia-system-image).
 
 [`jl_gc_init()`](https://github.com/JuliaLang/julia/blob/master/src/gc.c) sets up allocation pools
 and lists for weak refs, preserved values and finalization.
@@ -130,14 +130,14 @@ and `main()` calls `repl_entrypoint(argc, (char**)argv)`.
 
 !!! sidebar "sysimg"
     If there is a sysimg file, it contains a pre-cooked image of the `Core` and `Main` modules (and
-    whatever else is created by `boot.jl`). See [Building the Julia system image](@ref dev-sysimg-build).
+    whatever else is created by `boot.jl`). See [Building the Julia system image](@ref Building-the-Julia-system-image).
 
     [`jl_restore_system_image()`](https://github.com/JuliaLang/julia/blob/master/src/staticdata.c) deserializes
     the saved sysimg into the current Julia runtime environment and initialization continues after
     `jl_init_box_caches()` below...
 
     Note: [`jl_restore_system_image()` (and `staticdata.c` in general)](https://github.com/JuliaLang/julia/blob/master/src/staticdata.c)
-    uses the [Legacy `ios.c` library](@ref dev-stdio-ios-c).
+    uses the [Legacy `ios.c` library](@ref Legacy-ios.c-library).
 
 ## `repl_entrypoint()`
 
@@ -174,7 +174,7 @@ and [`Base.print()`](@ref) before arriving at [`write(s::IO, a::Array{T}) where
  which does `ccall(jl_uv_write())`.
 
 [`jl_uv_write()`](https://github.com/JuliaLang/julia/blob/master/src/jl_uv.c) calls `uv_write()`
-to write "Hello World!" to `JL_STDOUT`. See [Libuv wrappers for stdio](@ref dev-stdio-libuv).:
+to write "Hello World!" to `JL_STDOUT`. See [Libuv wrappers for stdio](@ref Libuv-wrappers-for-stdio).:
 
 ```
 Hello World!
diff --git a/doc/src/devdocs/locks.md b/doc/src/devdocs/locks.md
@@ -1,4 +1,4 @@
-# [Proper maintenance and care of multi-threading locks](@id dev-locks)
+# [Proper maintenance and care of multi-threading locks](@id Proper-maintenance-and-care-of-multi-threading-locks)
 
 The following strategies are used to ensure that the code is dead-lock free (generally by addressing
 the 4th Coffman condition: circular wait).
diff --git a/doc/src/devdocs/stdio.md b/doc/src/devdocs/stdio.md
@@ -1,6 +1,6 @@
 # printf() and stdio in the Julia runtime
 
-## [Libuv wrappers for stdio](@id dev-stdio-libuv)
+## [Libuv wrappers for stdio](@id Libuv-wrappers-for-stdio)
 
 `julia.h` defines [libuv](https://docs.libuv.org) wrappers for the `stdio.h` streams:
 
@@ -74,7 +74,7 @@ In `jl_uv.c` the `jl_uv_puts()` function checks its `uv_stream_t* stream` argume
 This allows for uniform use of `jl_printf()` throughout the runtime regardless of whether or not
 any particular piece of code is reachable before initialization is complete.
 
-## [Legacy `ios.c` library](@id dev-stdio-ios-c)
+## [Legacy `ios.c` library](@id Legacy-ios.c-library)
 
 The `src/support/ios.c` library is inherited from [femtolisp](https://github.com/JeffBezanson/femtolisp).
 It provides cross-platform buffered file IO and in-memory temporary buffers.
diff --git a/doc/src/devdocs/sysimg.md b/doc/src/devdocs/sysimg.md
@@ -1,6 +1,6 @@
 # System Image Building
 
-## [Building the Julia system image](@id dev-sysimg-build)
+## [Building the Julia system image](@id Building-the-Julia-system-image)
 
 Julia ships with a preparsed system image containing the contents of the `Base` module, named
 `sys.ji`.  This file is also precompiled into a shared library called `sys.{so,dll,dylib}` on
diff --git a/doc/src/devdocs/types.md b/doc/src/devdocs/types.md
@@ -82,7 +82,7 @@ f3(A::Array{T}) where {T<:Any} = 3
 f4(A::Array{Any}) = 4
 ```
 
-The signature - as described in [Function calls](@ref dev-func-call) - of `f3` is a `UnionAll` type wrapping a tuple type: `Tuple{typeof(f3), Array{T}} where T`.
+The signature - as described in [Function calls](@ref Function-calls) - of `f3` is a `UnionAll` type wrapping a tuple type: `Tuple{typeof(f3), Array{T}} where T`.
 All but `f4` can be called with `a = [1,2]`; all but `f2` can be called with `b = Any[1,2]`.
 
 Let's look at these types a little more closely:
@@ -478,7 +478,7 @@ We have not yet worked out a complete algorithm for this.
 Most operations for dealing with types are found in the files `jltypes.c` and `subtype.c`.
 A good way to start is to watch subtyping in action.
 Build Julia with `make debug` and fire up Julia within a debugger.
-[gdb debugging tips](@ref dev-debug) has some tips which may be useful.
+[gdb debugging tips](@ref gdb-debugging-tips) has some tips which may be useful.
 
 Because the subtyping code is used heavily in the REPL itself -- and hence breakpoints in this
 code get triggered often -- it will be easiest if you make the following definition:
diff --git a/doc/src/manual/functions.md b/doc/src/manual/functions.md
@@ -78,7 +78,7 @@ Argument-type declarations **normally have no impact on performance**: regardles
 * **Correctness:** Type declarations can be useful if your function only returns correct results for certain argument types.  For example, if we omitted argument types and wrote `fib(n) = n ≤ 2 ? one(n) : fib(n-1) + fib(n-2)`, then `fib(1.5)` would silently give us the nonsensical answer `1.0`.
 * **Clarity:** Type declarations can serve as a form of documentation about the expected arguments.
 
-However, it is a **common mistake to overly restrict the argument types**, which can unnecessarily limit the applicability of the function and prevent it from being re-used in circumstances you did not anticipate.    For example, the `fib(n::Integer)` function above works equally well for `Int` arguments (machine integers) and `BigInt` arbitrary-precision integers (see [BigFloats and BigInts](@ref base-big)), which is especially useful because Fibonacci numbers grow exponentially rapidly and will quickly overflow any fixed-precision type like `Int` (see [Overflow behavior](@ref)).  If we had declared our function as `fib(n::Int)`, however, the application to `BigInt` would have been prevented for no reason.   In general, you should use the most general applicable abstract types for arguments, and **when in doubt, omit the argument types**.  You can always add argument-type specifications later if they become necessary, and you don't sacrifice performance or functionality by omitting them.
+However, it is a **common mistake to overly restrict the argument types**, which can unnecessarily limit the applicability of the function and prevent it from being re-used in circumstances you did not anticipate.    For example, the `fib(n::Integer)` function above works equally well for `Int` arguments (machine integers) and `BigInt` arbitrary-precision integers (see [BigFloats and BigInts](@ref BigFloats-and-BigInts)), which is especially useful because Fibonacci numbers grow exponentially rapidly and will quickly overflow any fixed-precision type like `Int` (see [Overflow behavior](@ref)).  If we had declared our function as `fib(n::Int)`, however, the application to `BigInt` would have been prevented for no reason.   In general, you should use the most general applicable abstract types for arguments, and **when in doubt, omit the argument types**.  You can always add argument-type specifications later if they become necessary, and you don't sacrifice performance or functionality by omitting them.
 
 ## The `return` Keyword
 
diff --git a/doc/src/manual/types.md b/doc/src/manual/types.md
@@ -1386,7 +1386,7 @@ REPL and other interactive environments, and also a more compact single-line for
 [`print`](@ref) or for displaying the object as part of another object (e.g. in an array). Although
 by default the `show(io, z)` function is called in both cases, you can define a *different* multi-line
 format for displaying an object by overloading a three-argument form of `show` that takes the
-`text/plain` MIME type as its second argument (see [Multimedia I/O](@ref base-multimedia)), for example:
+`text/plain` MIME type as its second argument (see [Multimedia I/O](@ref Multimedia-I/O)), for example:
 
 ```jldoctest polartype
 julia> Base.show(io::IO, ::MIME"text/plain", z::Polar{T}) where{T} =
@@ -1409,7 +1409,7 @@ julia> [Polar(3, 4.0), Polar(4.0,5.3)]
 where the single-line `show(io, z)` form is still used for an array of `Polar` values.   Technically,
 the REPL calls `display(z)` to display the result of executing a line, which defaults to `show(stdout, MIME("text/plain"), z)`,
 which in turn defaults to `show(stdout, z)`, but you should *not* define new [`display`](@ref)
-methods unless you are defining a new multimedia display handler (see [Multimedia I/O](@ref base-multimedia)).
+methods unless you are defining a new multimedia display handler (see [Multimedia I/O](@ref Multimedia-I/O)).
 
 Moreover, you can also define `show` methods for other MIME types in order to enable richer display
 (HTML, images, etcetera) of objects in environments that support this (e.g. IJulia).   For example,
diff --git a/doc/src/manual/variables.md b/doc/src/manual/variables.md
@@ -123,7 +123,7 @@ julia> y = ___
 ERROR: syntax: all-underscore identifier used as rvalue
 ```
 
-The only explicitly disallowed names for variables are the names of the built-in [Keywords](@ref base-keywords):
+The only explicitly disallowed names for variables are the names of the built-in [Keywords](@ref Keywords):
 
 ```julia-repl
 julia> else = false

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# [gdb debugging tips](@id dev-debug)`
	`1`	`+# [gdb debugging tips](@id gdb-debugging-tips)`
`2`	`2`
`3`	`3`	`## Displaying Julia variables`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# [Proper maintenance and care of multi-threading locks](@id dev-locks)`
	`1`	`+# [Proper maintenance and care of multi-threading locks](@id Proper-maintenance-and-care-of-multi-threading-locks)`
`2`	`2`
`3`	`3`	`The following strategies are used to ensure that the code is dead-lock free (generally by addressing`
`4`	`4`	`the 4th Coffman condition: circular wait).`