Incorporate changes from #344 (#881)

* incorporate changes from 344

* Restore first heading

* Restore second heading

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "workbench.colorTheme": "Julia (Monokai Vibrant)"
+}

docs/src/man/creating_systems.md

@@ -13,7 +13,7 @@ end
 ```
 
 ### tf - Rational Representation
-The syntax for creating a transfer function is [`tf`](@ref)
+The basic syntax for creating a transfer function is [`tf`](@ref)
 ```julia
 tf(num, den)     # Continuous-time system
 tf(num, den, Ts) # Discrete-time system
@@ -34,6 +34,30 @@ Continuous-time transfer function model
 ```
 
 The transfer functions created using this method will be of type `TransferFunction{SisoRational}`.
+For more general expressions, it is often more convenient to define `s = tf("s")`:
+#### Example:
+```julia
+julia> s = tf("s")
+
+TransferFunction{Continuous,ControlSystems.SisoRational{Int64}}
+s
+-
+1
+
+Continuous-time transfer function model
+```
+
+This allows us to use `s` to define transfer-functions:
+```julia
+julia> (s-1)*(s^2 + s + 1)/(s^2 + 3s + 2)/(s+1)
+
+TransferFunction{Continuous,ControlSystems.SisoRational{Int64}}
+       s^3 - 1
+---------------------
+s^3 + 4*s^2 + 5*s + 2
+
+Continuous-time transfer function model
+```
 
 ### zpk - Pole-Zero-Gain Representation
 Sometimes it's better to represent the transfer function by its poles, zeros and gain, this can be done using the function [`zpk`](@ref)
@@ -84,7 +108,7 @@ To associate **names** with states, inputs and outputs, see [`named_ss`](https:/
 
 
 ## Converting between types
-It is sometime useful to convert one representation to another, this is possible using the constructors `tf, zpk, ss`, for example
+It is sometime useful to convert one representation to another. This is possible using the constructors `tf, zpk, ss`, for example
 ```jldoctest
 tf(zpk([-1], [1], 2, 0.1))
 

lib/ControlSystemsBase/src/timeresp.jl

@@ -37,9 +37,13 @@ LsimWorkspace(sys::AbstractStateSpace, u::AbstractMatrix) = LsimWorkspace(sys, s
     y, t, x = step(sys[, tfinal])
     y, t, x = step(sys[, t])
 
-Calculate the step response of system `sys`. If the final time `tfinal` or time
-vector `t` is not provided, one is calculated based on the system pole
-locations. The return value is a structure of type `SimResult` that can be plotted or destructured as `y, t, x = result`.
+Calculate the response of the system `sys` to a unit step at time `t = 0`. 
+If the final time `tfinal` or time vector `t` is not provided, 
+one is calculated based on the system pole locations. 
+
+The return value is a structure of type `SimResult`. 
+A `SimResul` can be plotted by `plot(result)`, 
+or destructured as `y, t, x = result`. 
 
 `y` has size `(ny, length(t), nu)`, `x` has size `(nx, length(t), nu)`
 
@@ -73,11 +77,20 @@ Base.step(sys::TransferFunction, t::AbstractVector; kwargs...) = step(ss(sys), t
     y, t, x = impulse(sys[, tfinal])
     y, t, x = impulse(sys[, t])
 
-Calculate the impulse response of system `sys`. If the final time `tfinal` or time
-vector `t` is not provided, one is calculated based on the system pole
-locations. The return value is a structure of type `SimResult` that can be plotted or destructured as `y, t, x = result`.
+Calculate the response of the system `sys` to an impulse at time `t = 0`. 
+For continous-time systems, the impulse is a unit Dirac impulse. 
+For discrete-time systems, the impulse lasts one sample and has magnitude `1/Ts`. 
+If the final time `tfinal` or time vector `t` is not provided, 
+one is calculated based on the system pole locations. 
+
+The return value is a structure of type `SimResult`. 
+A `SimResul` can be plotted by `plot(result)`, 
+or destructured as `y, t, x = result`.
 
-`y` has size `(ny, length(t), nu)`, `x` has size `(nx, length(t), nu)`"""
+`y` has size `(ny, length(t), nu)`, `x` has size `(nx, length(t), nu)`
+
+See also [`lsim`](@ref).
+"""
 function impulse(sys::AbstractStateSpace, t::AbstractVector; kwargs...)
     T = promote_type(eltype(sys.A), Float64)
     ny, nu = size(sys)