docs (tutorial1): adjust wording for option key formatting recommendations

Elaborate on the rationale behind the recommended practices for
formatting option keys, clarifying the wording slightly.

Signed-off-by: Alan D. Salewski <[email protected]>

Author: salewski

doc/latex/pgfplots/pgfplots.tutorial1.tex

@@ -95,9 +95,10 @@ \subsection{Getting the Data Into \TeX{}}
         |\begin{loglogaxis} ... \end{loglogaxis}| environment for logarithmic
         axes).
 
-        Although \PGFPlots{} runs with default options, it accepts keys. Lots
-        of keys. Typically, you provide all keys which you ``want to have''
-        in square brackets ``somewhere'' and ignore all other keys.
+        Although \PGFPlots{} runs with default options, it accepts option
+        keys. Lots of option keys. Typically, you provide all keys which you
+        ``want to have'' in square brackets (|[...]|) ``somewhere'' and ignore
+        all other keys.
 
         Of course, the main difficulty is to get an overview over the available
         keys and to find out how to use them. This reference manual and
@@ -107,27 +108,39 @@ \subsection{Getting the Data Into \TeX{}}
         hopefully jump to a good match from which you can jump to \emph{the}
         reference section (for example about tick labels, tick positions, plot
         handlers, etc.). It is (and will always be) the most reliable source of
-        detail information about all keys.
+        detailed information about all available option keys.
 
         Speaking about the reference manual: note that most PDF viewers also
         have a function to ``jump back to the page before you clicked on a
         hyperlink'' (for Acrobat Reader, open the menu View / Toolbars / More
         Tools and activate the ``Previous View'' and ``Next View'' buttons
         which are under ``Page Navigation Toolbar'').
 
-        Note that the code listing contains two sets of keys: the first is
-        after |\begin{axis}[ ... ]| and the second right after
-        |\addplot[...]|. Note furthermore that the option list after the axis
-        has been indented: each option is on a separate line, and each line
-        has a tab stop as first character. This is a good practice. Another
-        good practice is to place a comma after the last option (in our case,
-        after the value for |ylabel|). This allows to add more keys easily --
-        and you won't forget the comma. It does not hurt at all. The second
-        ``set'' of keys after |\addplot| shows that indentation and trailing
-        comma a really just a best practice: we simply said |\addplot[blue]|,
-        meaning that the plot will be placed in blue color, without any plot
-        |mark|. Of course, once another option would be added here, it would
-        be best to switch to indentation and trailing comma:
+        Note that the code listing contains two sets of option keys: the first
+        is after |\begin{axis}| (the keys |title|, |xlabel|, and |ylabel|) and
+        the second right after |\addplot| (the single key |blue|). Note,
+        too, that the options list after the axis has been indented: each
+        option is on a separate line, and each line has a tab stop as first
+        character. Formatting code in this way is considered to be good
+        practice when more than one key is specified, as it tends to be more
+        readable than combining multiple option keys on the same line. It
+        also facilitates commenting-out individual options.
+
+        Another good practice is placing a comma after the last option (in our
+        case, after the value for |ylabel|). The trailing comma is effectively
+        ignored -- it is not a syntax error, and it does not alter the
+        semantic meaning of the options list. Its presence, however, allows
+        more option keys to be appended easily in the future -- you won't
+        forget the comma.
+
+        The lack of a trailing comma in the second ``set'' of keys (after
+        |\addplot|) demonstrates that it is not strictly necessary to format
+        an options list as recommended above. In fact, when there is only one
+        option key, it is common to see it included on one line, as shown. In
+        our case, we simply said |\addplot[blue]|, meaning that the plot will
+        be placed in blue color, without any plot |mark|. If another option
+        were to be added, though, it would be best to switch to indentation
+        and trailing comma:
         %
 \begin{codeexample}[code only]
 \addplot[