Skip to content

Commit

Permalink
Merge pull request #472 from salewski/ads/tut1-adjust-wording-re-opti…
Browse files Browse the repository at this point in the history
…on-keys

docs (tutorial1): adjust wording for option key formatting recommendations
  • Loading branch information
Mo-Gul authored Mar 9, 2024
2 parents d8e62df + 0d5534a commit fa4886e
Showing 1 changed file with 30 additions and 17 deletions.
47 changes: 30 additions & 17 deletions doc/latex/pgfplots/pgfplots.tutorial1.tex
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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[
Expand Down

0 comments on commit fa4886e

Please sign in to comment.