From 0d5534a3c98e2002b200a42d1fa415014dea8faf Mon Sep 17 00:00:00 2001 From: "Alan D. Salewski" Date: Fri, 8 Mar 2024 15:57:47 -0500 Subject: [PATCH] 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 --- doc/latex/pgfplots/pgfplots.tutorial1.tex | 47 +++++++++++++++-------- 1 file changed, 30 insertions(+), 17 deletions(-) diff --git a/doc/latex/pgfplots/pgfplots.tutorial1.tex b/doc/latex/pgfplots/pgfplots.tutorial1.tex index 9e803db6..2c6b9873 100644 --- a/doc/latex/pgfplots/pgfplots.tutorial1.tex +++ b/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,7 +108,7 @@ \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 @@ -115,19 +116,31 @@ \subsection{Getting the Data Into \TeX{}} 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[