Apply suggestions from code review

Co-authored-by: Manuel Torrilhon <[email protected]>

docs/literate/src/files/first_steps/create_first_setup.jl

@@ -19,8 +19,9 @@
 
 # The first step is to create and open a file with the .jl extension. You can do this with your
 # favorite text editor (if you do not have one, we recommend [VS Code](https://code.visualstudio.com/)).
-# In this file you will create your setup. Alternatively, you can execute each line of the
-# following code one by one in the Julia REPL. This will generate useful output for nearly every
+# In this file you will create your setup and the file can then be executed in Julia using, for example, `trixi_include()`.
+# Alternatively, you can execute each line of the following code one by one in the 
+# Julia REPL. This will generate useful output for nearly every
 # command and improve your comprehension of the process.
 
 # To be able to use functionalities of Trixi.jl, you always need to load Trixi.jl itself
@@ -68,7 +69,7 @@ mesh = TreeMesh(coordinates_min, coordinates_max,
 # The solution in each of the recently defined mesh elements will be approximated by a polynomial
 # of degree `polydeg`. For more information about discontinuous Galerkin methods,
 # check out the [Introduction to DG methods](@ref scalar_linear_advection_1d) tutorial. Per default
-# `DGSEM` initializes the surface flux as central and the volume integral in the weak form.
+# `DGSEM` initializes the surface flux as central and uses no volume flux in the weak form.
 
 solver = DGSEM(polydeg=3)
 
@@ -116,7 +117,8 @@ end
 
 semi = SemidiscretizationHyperbolic(mesh, equations, initial_condition, solver;
                                     source_terms = source_term_exp_sinpi)
-#
+# which leaves us with an ODE problem in time with a span from 0.0 to 1.0.
+# This approach is commonly referred to as the method of lines. 
 tspan = (0.0, 1.0)
 ode = semidiscretize(semi, tspan)
 
@@ -188,7 +190,8 @@ callbacks = CallbackSet(summary_callback, analysis_callback, alive_callback, ste
 # the ODE problem, the ODE solver and the callbacks to the `solve` function. Also, to use
 # `StepsizeCallback`, we must explicitly specify the initial trial time step `dt`, the selected
 # value is not important, because it will be overwritten by the `StepsizeCallback`. And there is no
-# need to save every step of the solution, we are only interested in the final result.
+# need to save every step of the solution, as we are only interested the output provided by 
+# our callback [`SaveSolutionCallback`](@ref).
 
 sol = solve(ode, SSPRK33(); dt = 1.0, save_everystep = false, callback = callbacks);
 

docs/literate/src/files/first_steps/getting_started.jl

@@ -32,8 +32,7 @@
 #   ```shell
 #   winget install julia -s msstore
 #   ```
-#   Note: This installation method requires the use of MS Store, therefore, an MS Store account
-#   is necessary to proceed.
+#   Note: For this installation an MS Store account is necessary to proceed.
 # - Verify the successful installation of Julia by executing the following command in the terminal:
 #   ```shell
 #   julia
@@ -73,15 +72,15 @@
 # - Open a terminal and start Julia.
 # - Execute the following commands to install all mentioned packages. Please note that the
 #   installation process involves downloading and precompiling the source code, which may take
-#   approximately 30 minutes.
+#   some time depending on your machine.
 #   ```julia
 #   import Pkg
 #   Pkg.add(["OrdinaryDiffEq", "Plots", "Trixi"])
 #   ```
-# - On Windows, the firewall may request for permission to install packages.
+# - On Windows, the firewall may request permission to install packages.
 
-# Now you have installed all these 
-# packages. [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl) provides time
+# Besides Trixi.jl you have now installed two additional 
+# packages: [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl) provides time
 # integration schemes used by Trixi.jl and [Plots.jl](https://github.com/JuliaPlots/Plots.jl)
 # can be used to directly visualize Trixi.jl results from the Julia REPL.
 
@@ -107,8 +106,7 @@
 
 # Let's execute a short two-dimensional problem setup. It approximates the solution of
 # the compressible Euler equations in 2D for an ideal gas ([`CompressibleEulerEquations2D`](@ref))
-# with a weak blast wave as the initial condition and periodic boundary conditions. The compressible
-# Euler equations describe the motion of an ideal gas.
+# with a weak blast wave as the initial condition and periodic boundary conditions. 
 
 # The compressible Euler equations in two spatial dimensions are given by
 # ```math
@@ -151,21 +149,25 @@
 using Trixi, OrdinaryDiffEq #hide #md
 trixi_include(@__MODULE__,joinpath(examples_dir(), "tree_2d_dgsem", "elixir_euler_ec.jl")) #hide #md
 
-# The solution was approximated over the [`TreeMesh`](@ref) using the `CarpenterKennedy2N54` ODE
+# The output contains a recap of the setup and various information about the course of the simulation.
+# For instance, the solution was approximated over the [`TreeMesh`](@ref) with 1024 effective cells using
+# the `CarpenterKennedy2N54` ODE
 # solver. Further details about the ODE solver can be found in the
 # [documentation of OrdinaryDiffEq.jl](https://docs.sciml.ai/DiffEqDocs/stable/solvers/ode_solve/#Low-Storage-Methods)
 
 # To analyze the result of the computation, we can use the Plots.jl package and the function 
 # `plot(...)`, which creates a graphical representation of the solution. `sol` is a variable
-# defined in the executed example and it contains the solution at the final moment of the
-# simulation. `sol.u` holds the vector of values at each saved timestep, while `sol.t` holds the
+# defined in the executed example and it contains the solution after the simulation 
+# finishes. `sol.u` holds the vector of values at each saved timestep, while `sol.t` holds the
 # corresponding times for each saved timestep. In this instance, only two timesteps were saved: the
 # initial and final ones. The plot depicts the distribution of the weak blast wave at the final moment
 # of time, showing the density, velocities, and pressure of the ideal gas across a 2D domain.
 
 using Plots
 plot(sol)
 
+# ### Getting an existing setup file
+
 # To obtain a list of all Trixi.jl elixirs execute
 # [`get_examples`](@ref). It returns the paths to all example setups.