Reorganize.

emulab-transition.scrbl

@@ -6,61 +6,99 @@
 @(under-construction)
 
 The new Emulab portal interface is a custom version of the
-@hyperlink["http://cloudlab.us"]{CloudLab} interface and as such,
-much of the documentation about, and experiences with, that
-interface apply to the Emulab portal.
-It currently supports the most commonly used features of the classic
+@hyperlink["http://cloudlab.us"]{CloudLab} interface, so if you are familiar
+with that interface, using the Emulab portal will be easy!
+The portal currently supports the most commonly used features of the classic
 interface, with more features ported on demand.
-The classic interface should be considered deprecated, with no new
-features being added. It will continue to be supported until all important
+@bold{The classic interface should be considered deprecated},
+with no new features being added.
+It will continue to be supported until all important
 features have been moved to the portal interface.
 
 The remainder of this section covers
-@seclink["emulab-cloudlab-term"]{differences in terminology}
-between CloudLab and Emulab that are essential to understanding the
-new interface,
-@seclink["emulab-cloudlab-features"]{new feaures}
+@seclink["emulab-cloudlab-features"]{new and improved features}
 that the portal interface offers over the classic interface,
 @seclink["emulab-missing-features"]{features currently missing}
 from the portal interface, and how to
 @seclink["emulab-conversion"]{convert an existing experiment}
 into a portal experiment.
 
-@section[#:tag "emulab-cloudlab-term"]{New or Changed Concepts in the Portal Interface}
+@section[#:tag "emulab-cloudlab-features"]{New and Improved Features of the Portal Interface}
 
-One of the biggest differences between the classic interface and the portal
-interface is that experiment descriptions are now known as
-@seclink["profiles"]{profiles} and the term
-@seclink["experiments"]{experiment} is used to refer to a running instance of
-a profile. Think of a @italic{profile} as a ``swapped out'' classic experiment
+Besides a much updated look and feel, the portal interface offers significant
+new features and improvements to existing features.
+
+@subsection{Profiles}
+One significant change that is more than just an interface issue,
+is the clear delineation between an experiment's @italic{description}
+and its @italic{instantiation}. 
+
+In the classic interface, the term ``experiment'' is used to refer to
+both: experiment descriptions and instances can be created and destroyed
+together or, the experiment can be created just as a description and then
+``swapped in'' (instantiated with resources) and ``swapped out''
+(resources freed) repeatedly.
+
+Through the portal,
+experiment descriptions are now known as @seclink["profiles"]{profiles}
+and the term @seclink["experiments"]{experiment} is used to refer to a
+running instance of a profile.
+Think of a @italic{profile} as a ``swapped out'' classic experiment
 and an @italic{experiment} (or @italic{instance}) as a ``swapped in'' classic
-experiment. Here is the complete list of equivalent actions:
-
-@(tabular #:style 'boxed #:sep (hspace 3) (list
-    (list @bold{Classic interface action} @bold{Equivalent portal action(s)})
-    (list "Create a running experiment" "Create a profile, instantiate the profile")
-    (list "Terminate a running experiment" "Destroy an instance, destroy the profile")
-    (list "Create a swapped-out experiment (``Do Not Swap In'' box checked)" "Create a profile")
-    (list "Swapin an experiment" "Instantiate a profile")
-    (list "Swapout an experiment" "Terminate an instance")
-    (list "Terminate a swapped-out experiment" "Destroy a profile")))
-
-By default, profiles have the same visibility that experiments do in the
-classic interface---only people in the same project can instantiate an
-experiment from a profile.
-However, you can also make profiles visible by ``Anyone,'' making the profile
-global and allowing any experimenter in any project to instantiate it.
+experiment.
+
+The portal offers a variety of ways in which to create new profiles,
+including a web-based GUI and a Python-based scripting library.
+See the section on @seclink["creating-profiles"]{creating profiles}
+for details.
+In addition, the Emulab portal provides its own method for
+@seclink["emulab-conversion"]{converting classic experiments to profiles}.
 
-The representation of experiment descriptions has changed.
+A profile's representation of an experiment is different from that of
+the classic experiment.
 In the classic interface, experiments are described using @tt{ns-2},
-a network simulator scripting language based on the TCL.
+a network simulator scripting language based on TCL.
 The portal represents experiments at the base level as GENI
 @seclink["rspecs"]{RSpecs} with the Python-based
 @seclink["geni-lib"]{geni-lib}
 interface available for scripting experiments.
 As described in the @seclink["emulab-conversion"]{conversion} section
 below, the portal can automatically convert classic ns-2 experiment
-descriptions into geni-lib descriptions.
+descriptions into geni-lib based profiles.
+
+In addition to the hardware and software resources required by an experiment,
+a profile also contains various metadata.
+The Description and Instructions fields permit you to provide additional
+information to the instantiator of an experiment.
+These fields support @seclink["markdown"]{Markdown} formatting allowing more
+expressive text.
+Classic experiments allow only a short, ASCII-only description.
+
+Profile can also have @italic{parameters} with descriptions and default
+values. This permits customized instantiations using a single profile.
+For example, you can
+have parameters to specify the number or types of nodes in an experiment.
+In classic experiments this customization is accomplished by setting TCL
+variables in the NS file.
+Using a different value for the variables entails either
+modifying the experiment while it is swapped out or creating a new experiment
+with different values for the variables.
+With profile parameters, values are provided through the interface at
+instantiation time.
+
+By default, profiles have the same visibility that classic experiments
+do---only people in the same project can instantiate an
+experiment from a profile.
+However, you can also make profiles visible by ``Anyone,'' marking the profile
+global and allowing any experimenter in any project to instantiate it.
+
+@subsection{Web-based Interaction with Nodes}
+
+The portal page for an active experiment has a dashboard allowing interaction
+with all nodes. You can fire off in-browser console or SSH sessions, reboot,
+and view activity graphs.
+
+@subsection{Disk Images}
 
 Custom disk images are now created by taking a @italic{snapshot} of an
 experiment node or @italic{cloning} an existing experiment to create
@@ -77,6 +115,8 @@ The URN for an image can be obtained from the ``Images'' tab on the user
 dashboard.
 See the section on @seclink["disk-images"]{disk images} for more information.
 
+@subsection{Versioning}
+
 Both profiles and disk images are now versioned.
 Whenever you make a change to a profile,
 you create a new version of that profile.
@@ -89,44 +129,26 @@ constraints).
 Deleting the current version effectively ``rolls back''
 the profile or image to the previous version.
 
+@subsection{Experiment Extensions}
+
 The portal interface has a more rigorous procedure for @italic{extending}
-an experiment.
+a running experiment.
 In the classic interface you can extend a running experiment by modifying
 the ``Max Duration'' setting within a small range (0 - 120 hours).
 Longer extensions require an email exchange with the admins.
 In the portal interface, you request an extension via the web interface
-with shorter extensions being approved automatically.
-Furthermore, extensions work within the framework of the reservation system
-and thus might be constrained by future reservations.
-See the sections on @seclink["extending"]{extending experiments}
-and @seclink["reservations"]{reservations}
+with shorter extensions being approved instantly and longer extensions
+automatically forwarded to admins for their consideration.
+See the section on @seclink["extending"]{extending experiments}
 for more information.
 
-@section[#:tag "emulab-cloudlab-features"]{Portal Interface Features}
-
-Besides a much updated look and feel, the new inteface offers significant
-new features:
+@subsection{Resource Reservations}
 
-@itemlist[
-@item{
-    A supported web-based GUI for creating experiment descriptions.
-}
-@item{
-    Scripted experiment description creation via Python rather than TCL.
-}
-@item{
-    Profiles can be associated with @tt{git} repositories.
-}
-@item{
-    Experiment parameters and metadata.
-}
-@item{
-    Web-based interaction with nodes (console and ssh).
-}
-@item{
-    Reservation of resources at a future date.
-}
-]
+A major new feature supported via the portal interface is the ability to
+automatically reserve node resources for a future time.
+Emulab has traditionally been a first-come-first-serve, best-effort facility
+and reserving nodes required prior arrangement with Emulab staff.
+See the section on @seclink["reservations"]{reservations} for details.
 
 @section[#:tag "emulab-missing-features"]{Classic Features Not Currently Supported in the Portal}