jump-dev · odow · Mar 9, 2021 · Mar 9, 2021 · Mar 9, 2021
diff --git a/docs/make.jl b/docs/make.jl
@@ -19,9 +19,16 @@ makedocs(
     doctest = _FIX ? :fix : true,
     pages = [
         "Introduction" => "index.md",
+        "Background" => [
+            "background/motivation.md",
+            "background/duality.md",
+        ],
         "Manual" => [
+            "manual/standard_form.md",
+            "manual/constraints.md",
+            "manual/status.md",
+            "manual/modification.md",
             "manual/basic_usage.md",
-            "manual/advanced_usage.md",
             "manual/implementing.md",
         ],
         "API Reference" => "reference/reference.md",

diff --git a/docs/src/manual/advanced_usage.md → docs/src/background/duality.md b/docs/src/manual/advanced_usage.md → docs/src/background/duality.md
@@ -7,9 +7,7 @@ end
 DocTestFilters = [r"MathOptInterface|MOI"]
 ```
 
-# Advanced usage
-
-## Duality
+# Duality
 
 Conic duality is the starting point for MOI's duality conventions. When all
 functions are affine (or coordinate projections), and all constraint sets are
@@ -109,11 +107,11 @@ and similarly, the dual is:
 \end{align}
 ```
 
-!!! warn
+!!! warning
     For the LP case is that the signs of the feasible duals depend only on the
     sense of the inequality and not on the objective sense.
 
-### Duality and scalar product
+## Duality and scalar product
 
 The scalar product is different from the canonical one for the sets
 [`PositiveSemidefiniteConeTriangle`](@ref), [`LogDetConeTriangle`](@ref),
@@ -125,7 +123,7 @@ twice the value of the `coefficients` field in the [`VectorAffineFunction`](@ref
 for the corresponding rows. See [`PositiveSemidefiniteConeTriangle`](@ref) for
 details.
 
-### Dual for problems with quadratic functions
+## Dual for problems with quadratic functions
 
 Given a problem with quadratic functions:
 ```math

diff --git a/docs/src/background/motivation.md b/docs/src/background/motivation.md
@@ -0,0 +1,30 @@
+# Motivation
+
+MOI has been designed to replace [MathProgBase](https://github.com/JuliaOpt/MathProgBase.jl),
+which was been used by modeling packages such as [JuMP](https://github.com/jump-dev/JuMP.jl)
+and [Convex.jl](https://github.com/jump-dev/Convex.jl).
+
+This second-generation abstraction layer addresses a number of limitations of
+MathProgBase.
+
+MOI is designed to:
+- Be simple and extensible, unifying linear, quadratic, and conic optimization,
+  and seamlessly facilitate extensions to essentially arbitrary constraints and
+  functions (e.g., indicator constraints, complementarity constraints, and
+  piecewise-linear functions)
+- Be fast by allowing access to a solver's in-memory representation of a problem
+  without writing intermediate files (when possible) and by using multiple
+  dispatch and avoiding requiring containers of nonconcrete types
+- Allow a solver to return multiple results (e.g., a pool of solutions)
+- Allow a solver to return extra arbitrary information via attributes (e.g.,
+  variable- and constraint-wise membership in an irreducible inconsistent subset
+  for infeasibility analysis)
+- Provide a greatly expanded set of status codes explaining what happened during
+  the optimization procedure
+- Enable a solver to more precisely specify which problem classes it supports
+- Enable both primal and dual warm starts
+- Enable adding and removing both variables and constraints by indices that are
+  not required to be consecutive
+- Enable any modification that the solver supports to an existing model
+- Avoid requiring the solver wrapper to store an additional copy of the problem
+  data
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -12,15 +12,21 @@ optimization solvers so that users do not need to understand multiple
 solver-specific APIs.
 
 !!! tip
-    While MOI can be used directly, we encourage you instead to use MOI through
-    a higher-level modeling interface like [JuMP](https://github.com/jump-dev/JuMP.jl)
-    or [Convex.jl](https://github.com/jump-dev/Convex.jl).
+    This documentation is aimed at developers writing software interfaces to
+    solvers and modeling languages using the MathOptInterface API. If you are a
+    user interested in solving optimization problems, we encourage you instead
+    to use MOI through a higher-level modeling interface like
+    [JuMP](https://github.com/jump-dev/JuMP.jl) or
+    [Convex.jl](https://github.com/jump-dev/Convex.jl).
 
 ## How the documentation is structured
 
 Having a high-level overview of how this documentation is structured will help
 you know where to look for certain things.
 
+* The **Background** section contains articles on the motivation and theory
+  behind MathOptInterface. Look here if you want to understand _why_, rather
+  than _how_.
 * The **Manual** contains short code-snippets that explain how to use the MOI
   API. Look here if you want to write a model in MOI.
 * The **API Reference** contains a complete list of functions and types that
@@ -30,35 +36,6 @@ you know where to look for certain things.
   submodules within MOI. These submodules are not required to interface a solver
   with MOI, but they make the job much easier.
 
-## Background
-
-MOI has been designed to replace [MathProgBase](https://github.com/JuliaOpt/MathProgBase.jl),
-which was been used by modeling packages such as [JuMP](https://github.com/jump-dev/JuMP.jl)
-and [Convex.jl](https://github.com/jump-dev/Convex.jl).
-
-This second-generation abstraction layer addresses a number of limitations of
-MathProgBase. MOI is designed to:
-- Be simple and extensible, unifying linear, quadratic, and conic optimization,
-  and seamlessly facilitate extensions to essentially arbitrary constraints and
-  functions (e.g., indicator constraints, complementarity constraints, and
-  piecewise-linear functions)
-- Be fast by allowing access to a solver's in-memory representation of a problem
-  without writing intermediate files (when possible) and by using multiple
-  dispatch and avoiding requiring containers of nonconcrete types
-- Allow a solver to return multiple results (e.g., a pool of solutions)
-- Allow a solver to return extra arbitrary information via attributes (e.g.,
-  variable- and constraint-wise membership in an irreducible inconsistent subset
-  for infeasibility analysis)
-- Provide a greatly expanded set of status codes explaining what happened during
-  the optimization procedure
-- Enable a solver to more precisely specify which problem classes it supports
-- Enable both primal and dual warm starts
-- Enable adding and removing both variables and constraints by indices that are
-  not required to be consecutive
-- Enable any modification that the solver supports to an existing model
-- Avoid requiring the solver wrapper to store an additional copy of the problem
-  data
-
 ## Citing JuMP
 
 A [paper describing the design and features of MathOptInterface](https://arxiv.org/abs/2002.03447)