Merge pull request #1232 from ERGO-Code/fix-1228

Guide now in three sections

docs/make.jl

@@ -49,7 +49,9 @@ Documenter.makedocs(
         "installation.md",
         "Executable" => "executable.md",
         "Guide" => Any[
+            "guide/index.md",
             "guide/basic.md",
+            "guide/further.md",
             "guide/advanced.md"
         ],
 	"Data structures" => Any[

docs/src/guide/advanced.md

@@ -1,4 +1,4 @@
-# Advanced features
+# [Advanced features](@id guide-advanced)
 
 
 ## Simplex tableau data

docs/src/guide/basic.md

@@ -1,24 +1,13 @@
-# Basic features
-
-This guide describes the basic features of HiGHS that are available
-when it is called from [`Python`](@ref python-getting-started),
-[`C++`](@ref cpp-getting-started), [`C`](@ref c-api) and
-[`Fortran`](@ref fortran-api). Although references to methods link to
-`Python` examples, the method names and functionality for other
-interfaces are as close as possible.
-
-This basic guide will be sufficient for most users, and covers all the
-methods in the `Python` interface `highspy`. A guide to more advanced
-methods available via other interfaces is [available](@ref
-Advanced-features).
+# [Basic features](@id guide-basic)
 
 The minimal use of HiGHS has the following three stages.
 
 * [Define a model](@ref Defining-a-model)
 * [Solve the model](@ref Solving-the-model)
 * [Extract results](@ref Extracting-results)
 
-Although its default actions will be sufficient for most users, HiGHS can be controlled by setting [Option values](@ref Option-values).
+Although its default actions will be sufficient for most users, HiGHS
+can be controlled by setting [Option values](@ref Option-values).
 
 _Intro to other basic features_
 
@@ -47,19 +36,21 @@ the method [`readModel`](@ref Read-a-model). HiGHS infers the file type by the e
  * `.mps`: for an MPS file
  * `.lp`: for a CPLEX LP file
 
-HiGHS can read compressed files that end in the `.gz` extension.
+HiGHS can read compressed files that end in the `.gz` extension, but
+not (yet) files that end in the `.zip` extension.
 
 ### Building a model
 
 The model in HiGHS can be built using a sequence of calls to add
 variables and constraints. This is most easily done one-by-one using
-the methods [`addCol` and `addRow`](@ref Build-a-model). Alterntively,
-[`addVar` and `addRow`](@ref Build-a-model) can be used, with
-[`changeColCost`](@ref Build-a-model) used to define each objective
-coefficient.
+the methods [`addCol` and `addRow`](@ref
+Build-a-model). Alternatively, calls to [`addVar`](@ref Build-a-model)
+can be used to add variables, with calls to [`changeColCost`](@ref
+Build-a-model) used to define each objective coefficient.
 
 Addition of multiple variables and constraints can be achieved using
-[`addVars` and `addRows`](@ref Build-a-model), with
+[`addCols` and `addRows`](@ref Build-a-model). Alternatively,
+[`addVars`](@ref Build-a-model) can be used to add variables, with
 [`changeColsCost`](@ref Build-a-model) used to define objective
 coefficients. Note that defining the model in this way requires
 vectors of data and the specification of constraint coefficients as
@@ -71,17 +62,21 @@ matrices.
 
 ### Passing a model
 
-If the entire definition of a model is known, then is can be passed to
+If the entire definition of a model is known, then it can be passed to
 HiGHS via individual data arrays using the method [`passModel`](@ref
 Pass-a-model). In languages where HiGHS data structures can be used,
-an instance of the [`HighsLp`](@ref HighsLp) class can be passed.
+an instance of the [`HighsLp`](@ref HighsLp) class can be populated
+with data and then passed.
 
 ## Solving the model
 
-The incumbent model in HiGHS is solved by a call to the method [run](@ref Solve-the-model).
-By default, HiGHS minimizes the model's objective function. Where possible,
-HiGHS will hot start the solver using solution information obtained on previous
-runs, or supplied by the user.
+The incumbent model in HiGHS is solved by a call to the method
+[run](@ref Solve-the-model). By default, HiGHS minimizes the model's
+objective function, although this can be [changed](@ref
+Modifying-model-data). Where possible, HiGHS will reduce the solution
+time by using data obtained on previous runs, or supplied by the
+user. More information on this process of hot starting solvers is
+given [below](@ref hot-start).
 
 ## Extracting results
 
@@ -133,7 +128,7 @@ data can be extracted using the methods [getCols](@ref Get-model-data),
 
 Specific matrix coefficients obtained using the method [getCoeff](@ref Get-model-data).
 
-### Modifying model data
+## Modifying model data
 
 The most immediate model modification is to change the sense of the objective.
 By default, HiGHS minimizes the model's objective function. The objective sense
@@ -150,8 +145,3 @@ using the methods [changeColsCost](@ref Modify-model-data),
 is [changeRowsBounds](@ref Modify-model-data). An individual matrix coefficient
 is changed by passing its row index, column index and new value to
 [changeCoeff](@ref Modify-model-data).
-
-### Other operations
-
-To run HiGHS from a user-defined solution or basis, this is passed to HiGHS
-using the methods [setSolution](@ref Set-solution) or [setBasis](@ref Set-basis).

docs/src/guide/further.md

@@ -0,0 +1,14 @@
+# [Further features](@id guide-further)
+
+### [Hot start](@id hot-start)
+
+It may be possible for HiGHS to start solving a model using data
+obtained by solving a related model, or supplied by a user. Whether
+this is possible depends on the the class of model being solved, the
+solver to be used, and the modifications (if any) that have been to
+the incumbent model since it was last solved.
+
+#### LP
+
+To run HiGHS from a user-defined solution or basis, this is passed to HiGHS
+using the methods [setSolution](@ref Set-solution) or [setBasis](@ref Set-basis).

docs/src/guide/index.md

@@ -0,0 +1,18 @@
+# [Introduction](@id guide-introduction)
+
+This guide describes the features of HiGHS that are available when it
+is called from [`Python`](@ref python-getting-started), [`C++`](@ref
+cpp-getting-started), [`C`](@ref c-api) and [`Fortran`](@ref
+fortran-api). It is written in three sections: [basic](@ref
+guide-basic), [further](@ref guide-further) and [advanced](@ref
+guide-advanced). 
+
+The [basic](@ref guide-basic) section will be sufficient for most
+users. This and the [further](@ref guide-further) section cover the
+`Python` interface `highspy`.  Although references to methods link to
+`Python` examples, the method names and functionality for other
+interfaces are as close as possible.
+
+The [advanced](@ref guide-advanced) section covers features in the
+[`C++`](@ref cpp-getting-started), [`C`](@ref c-api) and
+[`Fortran`](@ref fortran-api) that are not in highspy`.

docs/src/index.md

@@ -49,7 +49,7 @@ and computer-readable formats.
 
 The HiGHS shared library allows models to be loaded, built and modified. It can
 also be used to extract solution data and perform other operations relating to
-the incumbent model. The basic functionality is introduced via a [`Guide`](@ref Basic-features),
+the incumbent model. The basic functionality is introduced via a [`Guide`](@ref guide-basic),
 with links to examples of its use in the `Python` interface `highspy`. This makes use of the C++
 structures and enums, and is as close as possible to the native C++ library
 calls. These can be studied via the [C++ header file](https://github.com/ERGO-Code/HiGHS/blob/master/src/Highs.h).

docs/src/interfaces/julia/index.md

@@ -59,7 +59,7 @@ and provide a link to the gist in the GitHub issue.
 
 HiGHS.jl is a thin wrapper around the complete [HiGHS C API](@ref c-api).
 
-As a basic example, we solve the problem:
+As a basic example, we solve the model:
 
 ```math
 \begin{aligned}

docs/src/interfaces/python/index.md

@@ -47,7 +47,7 @@ the [examples section](@ref example-py), it is referred to as `status`.
 
 ## First example
 
-The following Python code reads a problem from the file `model.mps`, and then
+The following Python code reads a model from the file `model.mps`, and then
 solves it.
 
 ```python

docs/src/parallel.md

@@ -42,7 +42,7 @@ parallel dual simplex solver is unlikely to be worth using.
 ## MIP
 
 The only parallel computation currently implemented in the MIP solver
-occurs when performing symmetry detection on the problem, and when
+occurs when performing symmetry detection on the model, and when
 querying clique tables. This parallelism is always advantageous, so is
 performed regardless of the value of the
 [parallel](@ref) option.

docs/src/terminology.md

@@ -128,10 +128,10 @@ Any point for which the discrete variables satisfy their requirements,
 is said to be __integer feasible__. The objective value at such a
 point is an upper bound on the optimal objective value. The least such
 bound is known as the __primal bound__. The MIP solver generates a
-sequence of LP problems, each of which has bounds on the variables
-that are tighter than those of the original problem. When unsolved,
-there is a bound on the optimal objective value for each such LP and,
-the greatest such bound is known as the __dual bound__. The optimal
+sequence of LPs, each of which has bounds on the variables that are
+tighter than those of the original model. When unsolved, there is a
+bound on the optimal objective value for each such LP and, the
+greatest such bound is known as the __dual bound__. The optimal
 objective value of the MIP cannot be less than the dual bound. Hence
 the gap between the primal and dual bounds is a measure of progress of
 the MIP solver. Although the absolute gap is of some interest, the gap