improve example 7.

Clean up example 1, and other tweaks. Ref #12453.

examples/ex01_inputfile/ex01.i

@@ -1,4 +1,6 @@
 [Mesh]
+  # We use a pre-generated mesh file (in exodus format).
+  # This mesh file has 'top' and 'bottom' named boundaries defined inside it.
   file = mug.e
 []
 
@@ -17,24 +19,25 @@
 []
 
 [BCs]
-  [./bottom]
+  [./bottom] # arbitrary user-chosen name
     type = DirichletBC
     variable = diffused
-    boundary = 'bottom'
+    boundary = 'bottom' # This must match a named boundary in the mesh file
     value = 1
   [../]
 
-  [./top]
+  [./top] # arbitrary user-chosen name
     type = DirichletBC
     variable = diffused
-    boundary = 'top'
+    boundary = 'top' # This must match a named boundary in the mesh file
     value = 0
   [../]
 []
 
 [Executioner]
   type = Steady
   solve_type = 'PJFNK'
+  file_base = 'out'
 []
 
 [Outputs]

examples/ex07_ics/src/ics/ExampleIC.C

@@ -25,14 +25,11 @@ ExampleIC::ExampleIC(const InputParameters & parameters)
 {
 }
 
+// This is the primary function custom ICs must implement.
 Real
 ExampleIC::value(const Point & p)
 {
-  /**
-   * _value * x
-   * The Point class is defined in libMesh.  The spatial
-   * coordinates x,y,z can be accessed individually using
-   * the parenthesis operator and a numeric index from 0..2
-   */
+  // The Point class is defined in libMesh.  The spatial coordinates x,y,z can be accessed
+  // individually using the parenthesis operator and a numeric index from 0..2
   return 2. * _coefficient * std::abs(p(0));
 }

examples/ex07_ics/transient.i

@@ -40,7 +40,7 @@
     type = DirichletBC
     variable = diffused
     boundary = 'bottom'
-    value = 10
+    value = 8
   [../]
 []
 

examples/ex08_materials/ex08.i

@@ -12,13 +12,13 @@
   [./diffused]
     order = FIRST
     family = LAGRANGE
-    initial_condition = 0.5
+    initial_condition = 0.5 # shortcut/convenience for setting constant initial condition
   [../]
 
   [./convected]
     order = FIRST
     family = LAGRANGE
-    initial_condition = 0.0
+    initial_condition = 0.0 # shortcut/convenience for setting constant initial condition
   [../]
 []
 

modules/doc/content/examples/ex01_inputfile.md

@@ -48,14 +48,7 @@ file itself:
 In this simple problem, a single variable, 'diffused,' is defined, which represents $$u$$ from the
 continuous problem.  The 'diffused' variable is approximated with linear Lagrange shape functions.
 
-```text
-[Variables]
-  [./diffused]
-    order = FIRST
-    family = LAGRANGE
-  [../]
-[]
-```
+!listing examples/ex01_inputfile/ex01.i block=Variables
 
 ### Kernels
 
@@ -65,37 +58,15 @@ the `Diffusion` Kernel is already defined in MOOSE.  To use a particular Kernel
 file sub-section is defined, labeled "diff" (this is an arbitrary user-defined name), that
 utilizes the `Diffusion` `Kernel` and acts on the previously defined variable "diffused".
 
-```text
-[Kernels]
-  [./diff]
-    type = Diffusion
-    variable = diffused
-  [../]
-[]
-```
+!listing examples/ex01_inputfile/ex01.i block=Kernels
 
 ### Boundary Conditions (BCs)
 
 Boundary conditions are defined in a manner similar to `Kernels`.  For this problem two Dirichlet
 boundary conditions are required.  In the input file the two boundary conditions are specified
 each using the `DirichletBC` object provided by MOOSE.
 
-```text
-[BCs]
-  [./bottom]
-    type = DirichletBC
-    variable = diffused
-    boundary = 'bottom'
-    value = 1
-  [../]
-  [./top]
-    type = DirichletBC
-    variable = diffused
-    boundary = 'top'
-    value = 0
-  [../]
-[]
-```
+!listing examples/ex01_inputfile/ex01.i block=BCs
 
 Within each of the two sub-section, named "top" and "bottom" by the user, the boundary conditions
 are linked to their associated variable(s) (i.e. "diffused" in this case) and boundaries.  In this
@@ -114,26 +85,15 @@ The type of problem to solve and the method for solving it is defined within the
 block.  This problem is steady-state and will use the `Steady` Executioner and will use the
 default solving method Preconditioned Jacobain Free Newton Krylov.
 
-```text
-[Executioner]
-  type = Steady
-  solve_type = 'PJFNK'
-[]
-```
+!listing examples/ex01_inputfile/ex01.i block=Executioner
 
 ### Outputs
 
 Here two types of outputs are enabled: output to the screen (console) and output to an Exodus II
 file (exodus).  Setting the "file_base" parameter is optional, in this example it forces the
 output file to be named "out.e" ("e" is the extension used for the Exodus II format).
 
-```text
-[Outputs]
-  file_base = out
-  screen = true
-  exodus = true
-[]
-```
+!listing examples/ex01_inputfile/ex01.i block=Outputs
 
 ## Running the Problem
 
@@ -155,15 +115,6 @@ Peacock or an external application that supports the Exodus II format (e.g., Par
        caption= Example 1 Results
        style=width:50%;display:block;margin-left:auto;margin-right:auto;
 
-## Complete Source Files
-
-- [ex01.i](https://github.com/idaholab/moose/blob/devel/examples/ex01_inputfile/ex01.i)
-- [main.C](https://github.com/idaholab/moose/blob/devel/examples/ex01_inputfile/src/main.C)
-- [ExampleApp.h](https://github.com/idaholab/moose/blob/devel/examples/ex01_inputfile/include/base/ExampleApp.h)
-- [ExampleApp.C](https://github.com/idaholab/moose/blob/devel/examples/ex01_inputfile/src/base/ExampleApp.C)
-- [Diffusion.h](https://github.com/idaholab/moose/blob/devel/framework/include/kernels/Diffusion.h)
-- [Diffusion.C](https://github.com/idaholab/moose/blob/devel/framework/src/kernels/Diffusion.C)
-
 ## Next Steps
 
 Although the Diffusion kernel is the only "physics" in the MOOSE framework, a large set of physics
@@ -174,3 +125,14 @@ implement your own physics, you will need to understand the following:
   the "weak" form of for PDEs
 - [C++](help/c++/index.md) and object-oriented design
 - [The Anatomy of a MOOSE Object](http://mooseframework.org/wiki/MooseTraining/MooseObject/)
+- Check out more [examples](examples/index.md)
+
+## Complete Source Files
+
+- [ex01.i](https://github.com/idaholab/moose/blob/devel/examples/ex01_inputfile/ex01.i)
+- [main.C](https://github.com/idaholab/moose/blob/devel/examples/ex01_inputfile/src/main.C)
+- [ExampleApp.h](https://github.com/idaholab/moose/blob/devel/examples/ex01_inputfile/include/base/ExampleApp.h)
+- [ExampleApp.C](https://github.com/idaholab/moose/blob/devel/examples/ex01_inputfile/src/base/ExampleApp.C)
+- [Diffusion.h](https://github.com/idaholab/moose/blob/devel/framework/include/kernels/Diffusion.h)
+- [Diffusion.C](https://github.com/idaholab/moose/blob/devel/framework/src/kernels/Diffusion.C)
+

modules/doc/content/examples/ex07_ics.md

@@ -1,19 +1,69 @@
 # Example 07 : Custom Initial Conditions
 
+MOOSE provides several ways to specify initial conditions (ICs) for transient problems.  The same
+functionality can be used to specify initial guesses for steady-state problems.  Custom methods
+can be created in addition to using any of many built-in methods for specifying initial
+conditions.  Detailed information for all the built-in initial conditions available can be found
+on the [Initial Condition System Documentation](syntax/ICs/index.md)
 
+This example demonstrates creating and using a custom class+object for setting the following
+initial condition:
+
+\begin{equation}
+\begin{aligned}
+    u(t=t_0, x, y, z) = 2 C x
+\end{aligned}
+\end{equation}
+
+where $C$ is a user-chosen coefficient. To accomplish this, we will need to create our own
+subclass of MOOSE's `InitialCondition` class and then specify the IC in our input file.
+
+## Creating a Custom IC
+
+We create a header file and subclass the `InitialCondition` class and add a `Real` (i.e. floating
+point number) member variable to hold the user-specified coefficient - see
+[examples/ex07_ics/include/ics/ExampleIC.h] for details. The `.C` file defines an input parameter
+named `coefficient`, stores its value in a member variable in the constructor, and uses that value
+to compute the IC.
+
+!listing examples/ex07_ics/src/ics/ExampleIC.C max-height=10000
+
+## Using ICs in an Input File
+
+The input file [examples/ex07_ics/transient.i] sets up a simple transient diffusion problem with
+initial conditions specified in the `Variables` block:
+
+!listing examples/ex07_ics/transient.i block=Variables
+
+We can also use the initial condition when running steady-state problems (i.e. with the `Steady`
+Executioner); this effectively functions as an initial guess for the solver - usually not
+necesary, but occasionally useful.  For steady cases, the IC is specified in exactly the same way
+- see e.g. [examples/ex07_ics/steady.i].
 
 # Results
 
-!media large_media/examples/ex7-1-out.png
-       style=width:50%;
+These results are from running the `transient.i` file. At $t=0$, we can see that the initial
+condition defines the solution to be zero at $x=0$ (along the rear surface of the half-cylinder)
+and increasing linearly toward us (out of the page).  At the final time, we see that diffusion has
+overcome our IC and our Dirichlet BCs have dictated the solution along the top and bottom
+surfaces.
+
+!media large_media/examples/ex07/transient_t0.png
+       style=width:33%;display:inline-flex;
+       caption=Initial state (t = 0)
 
-!media large_media/examples/ex7-2-out.png
-       style=width:50%;
+!media large_media/examples/ex07/transient_tmid.png
+       style=width:33%;display:inline-flex;
+       caption=Intermediate diffused state (t = .1)
+
+!media large_media/examples/ex07/transient_tend.png
+       style=width:33%;display:inline-flex;
+       caption=Final equilibrium state (t = 1 )
 
 ## Complete Source Files
 
-- [examples/ex07_ics/transient.i]
 - [examples/ex07_ics/include/ics/ExampleIC.h]
 - [examples/ex07_ics/src/ics/ExampleIC.C]
-- [examples/ex07_ics/src/base/ExampleApp.C]
+- [examples/ex07_ics/transient.i]
+- [examples/ex07_ics/steady.i]
 

modules/doc/content/examples/ex09_stateful_materials.md

@@ -1,25 +1,6 @@
 # Example 09 : Stateful Materials Properties
 
-[](---)
-
-## Complete Source Files
-
-[ex09.i](https://github.com/idaholab/moose/blob/devel/examples/ex09_stateful_materials/ex09.i)
-
-
-[](---)
-
-## Stateful Example Material
-
-[ExampleMaterial.h](https://github.com/idaholab/moose/blob/devel/examples/ex09_stateful_materials/include/materials/ExampleMaterial.h)
-
-[ExampleMaterial.C](https://github.com/idaholab/moose/blob/devel/examples/ex09_stateful_materials/src/materials/ExampleMaterial.C)
-
-[ExampleApp.C](https://github.com/idaholab/moose/blob/devel/examples/ex09_stateful_materials/src/base/ExampleApp.C)
-
-[](---)
-
-## Outputs
+## Results
 
 !media large_media/examples/ex9-out1.png
        caption=Beginning
@@ -29,3 +10,8 @@
        caption=End 
        style=width:50%;
 
+## Complete Source Files
+
+- [examples/ex09_stateful_materials/ex09.i]
+- [examples/ex09_stateful_materials/include/materials/ExampleMaterial.h]
+- [examples/ex09_stateful_materials/src/materials/ExampleMaterial.C]