|
Packit |
0986c0 |
Notes on the gnuplot help files and documentation.
|
|
Packit |
0986c0 |
--------------------------------------------------
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
Gnuplot documentation is available in three ways:
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
1 - interactively, within gnuplot
|
|
Packit |
0986c0 |
2 - as a printed document.
|
|
Packit |
0986c0 |
3 - as a manual page, through the Unix man(1) facility
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
The third form tells how to run gnuplot.
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
The first two forms describe the inner workings, and contain equivalent
|
|
Packit |
0986c0 |
information. They derive their information from the file "gnuplot.doc",
|
|
Packit |
0986c0 |
which is the master copy of gnuplot help information. All other forms,
|
|
Packit |
0986c0 |
except for the man page "gnuplot.1", are derived from it.
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
PostScript, PDF, or HTML versions of the manual can be created from the TeX
|
|
Packit |
0986c0 |
version if you have latex, pdflatex, and htlatex available, respectively.
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
gnuplot.doc -> gnuplot.gih
|
|
Packit |
0986c0 |
-> gnuplot.hlp
|
|
Packit |
0986c0 |
-> gnuplot.info
|
|
Packit |
0986c0 |
-> gnuplot.ipf
|
|
Packit |
0986c0 |
-> gnuplot.ms
|
|
Packit |
0986c0 |
-> gnuplot.rnh
|
|
Packit |
0986c0 |
-> gnuplot.rtf
|
|
Packit |
0986c0 |
-> wgnuplot.html
|
|
Packit |
0986c0 |
-> gnuplot.tex
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
On Unix and MSDOS the interactive help is built into the
|
|
Packit |
0986c0 |
program, and uses the file "gnuplot.gih" ('make gih').
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
On VMS, the interactive help is supplied by the system help facility,
|
|
Packit |
0986c0 |
using the file "gnuplot.hlp". This is built by default, either by
|
|
Packit |
0986c0 |
doc2hlp, or doc2rnh and RUNOFF which format gnuplot.doc for the VMS
|
|
Packit |
0986c0 |
HELP indenting conventions. The help file is placed in a help library,
|
|
Packit |
0986c0 |
"gnuplot.hlb" but it may be also be placed in one of the system-wide
|
|
Packit |
0986c0 |
help libraries, using lib/help ('help lib'). If VMS users prefer the
|
|
Packit |
0986c0 |
gnuplot interactive help facility to the system facility, this can be
|
|
Packit |
0986c0 |
easily changed by not defining NO_GIH.
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
The PDF and HTML versions of the gnuplot manual can include hyperlinks to
|
|
Packit |
0986c0 |
demonstration plots. There is a special makefile target "make pdf"
|
|
Packit |
0986c0 |
to generate and include sample plots directly in the manual itself.
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
Under EMACS, interactive help uses the file "gnuplot.info" ('make info').
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
On OS/2, the Information Presentation Facility Compiler converts the
|
|
Packit |
0986c0 |
file "gnuplot.ipf" to a "gnuplot.inf" file.
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
The printed document is available in troff/nroff (ms) format, using
|
|
Packit |
0986c0 |
the file "gnuplot.ms". For nroff, use 'make nroff'. For troff, type
|
|
Packit |
0986c0 |
'make ms' and then 'troff -ms gnuplot.ms' in whatever way you use troff.
|
|
Packit |
0986c0 |
For groff (on linux), use 'groff -t -e -mgs gnuplot.ms'
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
On MS-Windows, the Microsoft HTML help compiler converts the file
|
|
Packit |
0986c0 |
"wgnuplot.html" to a 'chm' file which is used by the standard Windows
|
|
Packit |
0986c0 |
help program. Hyperlinks and sample plots are included. Alternatively,
|
|
Packit |
0986c0 |
the Microsoft help compiler converts the file "gnuplot.rtf" to a 'hlp'
|
|
Packit |
0986c0 |
file.
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
Manual entries for the terminals are not included in "gnuplot.doc";
|
|
Packit |
0986c0 |
instead, each "driver.trm" file (in the directory /term) contains its
|
|
Packit |
0986c0 |
own documentation section. See "term/README" for details.
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
When you build gnuplot, only some of the terminal drivers are loaded;
|
|
Packit |
0986c0 |
these are selected in "term.h" by compiler directives specified in the
|
|
Packit |
0986c0 |
makefile. The interactive help generators use the same set of compiler
|
|
Packit |
0986c0 |
directives in "term.h", and thus interactive help contains information
|
|
Packit |
0986c0 |
for just those terminals actually loaded.
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
The printed manual generators and the html generator contain information
|
|
Packit |
0986c0 |
about all terminals. This is accomplished by concatenating all of the
|
|
Packit |
0986c0 |
".trm" files into a single one, "allterm.h".
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
The file "termdoc.c" is used by each of the nine processing programs
|
|
Packit |
0986c0 |
("doc2gih.c", etc.); it #includes either "term.h" or "allterm.h", as is
|
|
Packit |
0986c0 |
appropriate. If you wish to override the default decision about which
|
|
Packit |
0986c0 |
terminals are to appear in the documentation, edit the appropriate target
|
|
Packit |
0986c0 |
in the Makefile and add/remove -DALL_TERM_DOC to/from the compiler flags.
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
Description of the gnuplot.doc format:
|
|
Packit |
0986c0 |
--------------------------------------
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
Here is an example of the DOC master help format:
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
?
|
|
Packit |
0986c0 |
1 gnuplot
|
|
Packit |
0986c0 |
GNUPLOT is a command-driven interactive function plotting program. It
|
|
Packit |
0986c0 |
...
|
|
Packit |
0986c0 |
?exit
|
|
Packit |
0986c0 |
2 exit
|
|
Packit |
0986c0 |
'exit', 'quit' and ...
|
|
Packit |
0986c0 |
?expressions
|
|
Packit |
0986c0 |
2 expressions
|
|
Packit |
0986c0 |
In general, any mathematical expression accepted by C, ...
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
Topics:
|
|
Packit |
0986c0 |
functions operators
|
|
Packit |
0986c0 |
?expressions functions
|
|
Packit |
0986c0 |
?functions
|
|
Packit |
0986c0 |
3 functions
|
|
Packit |
0986c0 |
The functions in GNUPLOT are ...
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
Topics:
|
|
Packit |
0986c0 |
abs acos arg ...
|
|
Packit |
0986c0 |
?expressions functions abs
|
|
Packit |
0986c0 |
?functions abs
|
|
Packit |
0986c0 |
?abs
|
|
Packit |
0986c0 |
4 abs
|
|
Packit |
0986c0 |
This function returns the absolute value of its argument. The
|
|
Packit |
0986c0 |
returned value is of the same type as the argument.
|
|
Packit |
0986c0 |
?expressions functions acos
|
|
Packit |
0986c0 |
?functions acos
|
|
Packit |
0986c0 |
?acos
|
|
Packit |
0986c0 |
4 acos
|
|
Packit |
0986c0 |
This function returns the arc cosine (inverse cosine) of its
|
|
Packit |
0986c0 |
argument. 'acos' returns its argument in radians.
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
Some notes about the format:
|
|
Packit |
0986c0 |
----------------------------
|
|
Packit |
0986c0 |
Remember that all text must be able to be processed by gnuplot, VMS,
|
|
Packit |
0986c0 |
nroff, troff, info, itl, and latex, and always do something reasonable.
|
|
Packit |
0986c0 |
The first column is reserved for control characters.
|
|
Packit |
0986c0 |
Text does not start in the first column.
|
|
Packit |
0986c0 |
Lines that start in column 2 may be typeset by LaTeX.
|
|
Packit |
0986c0 |
Lines that have a space in column 2 are to be printed in a verbatim
|
|
Packit |
0986c0 |
environment by LaTeX.
|
|
Packit |
0986c0 |
Tables must have a space in column 2.
|
|
Packit |
0986c0 |
Do NOT use tabs in the help file.
|
|
Packit |
0986c0 |
Conversion from this format to vax .hlp file involves removal of
|
|
Packit |
0986c0 |
lines starting with [?@#$%] (see doc2hlp). VMS uses the numbers
|
|
Packit |
0986c0 |
to represent a tree.
|
|
Packit |
0986c0 |
Conversion from this format to gnuplot .gih file involves removal of
|
|
Packit |
0986c0 |
lines starting with [0-9@#$%] (see doc2gih). Gnuplot matches your
|
|
Packit |
0986c0 |
help query against the ? lines to find the help information.
|
|
Packit |
0986c0 |
Multiple ? lines for one text block constitute synonyms. The most
|
|
Packit |
0986c0 |
specific should be first, eg 'expressions functions' before 'functions'.
|
|
Packit |
0986c0 |
Spaces are allowed here, but should be single.
|
|
Packit |
0986c0 |
Backquote pairs are converted by the doc2tex program into boldface;
|
|
Packit |
0986c0 |
that is, `some text` is converted to {\bf some text}. Be sure to pair
|
|
Packit |
0986c0 |
the backquotes, or the whole document will be boldface! doc2ms converts
|
|
Packit |
0986c0 |
`` pairs to \fB...\fR, except inside tables : for the moment, this
|
|
Packit |
0986c0 |
has to be done manually on the lines starting %, but we ought to
|
|
Packit |
0986c0 |
find some way to allow tables to be entered just the once !
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
Control characters in first column:
|
|
Packit |
0986c0 |
? used by .gih format, for builtin interactive help - keyword
|
|
Packit |
0986c0 |
0-9 used by VMS help and by doc2{tex,ms,html} formatters to define level,keyword
|
|
Packit |
0986c0 |
@ used by doc2{tex,ms,rnh} to define table start/end
|
|
Packit |
0986c0 |
# used by doc2tex: table entry
|
|
Packit |
0986c0 |
#TeX used by doc2tex: LaTeX command to be inserted in output stream (e.g. \newpage)
|
|
Packit |
0986c0 |
#b bulleted list entry
|
|
Packit |
0986c0 |
## continuation of bulleted item
|
|
Packit |
0986c0 |
= used by doc2tex: index entry
|
|
Packit |
0986c0 |
F used by doc2{tex,html}: embedded figure (followed by base name of the pdf file)
|
|
Packit |
0986c0 |
% used by doc2ms: table entry
|
|
Packit |
0986c0 |
^ used by doc2{tex,html}: hypertext link / HTML code
|
|
Packit |
0986c0 |
< the help from the terminal driver files is inserted at this point.
|
|
Packit |
0986c0 |
C comment (mainly for RCS ID line)
|
|
Packit |
0986c0 |
C# reserved form of comment (used internally by termdoc.c)
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
Tables:
|
|
Packit |
0986c0 |
-------
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
Here is a sample table:
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
@start table - first is interactive cleartext form
|
|
Packit |
0986c0 |
Symbol Example Explanation
|
|
Packit |
0986c0 |
?: a?b:c ternary operation
|
|
Packit |
0986c0 |
#\begin{tabular}{|ccl|} \hline
|
|
Packit |
0986c0 |
#\multicolumn{3}{|c|}{Ternary Operator} \\
|
|
Packit |
0986c0 |
#Symbol & Example & Explanation \\ \hline
|
|
Packit |
0986c0 |
#\verb~?:~ & \verb~a?b:c~ & ternary operation\\
|
|
Packit |
0986c0 |
%c c l .
|
|
Packit |
0986c0 |
%Symbol@Example@Explanation
|
|
Packit |
0986c0 |
%_
|
|
Packit |
0986c0 |
%?:@a?b:c@* ternary operation
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
@end table
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
"doc2tex" and "doc2ms" are the formats that do something with tables
|
|
Packit |
0986c0 |
other than copy them verbatim. It is best to bracket a table in a
|
|
Packit |
0986c0 |
"@start table"/"@end table" pair.
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
Inside the "@start"/"@end" block are three independent sets of commands:
|
|
Packit |
0986c0 |
those that begin with "#" will be processed by "doc2tex" only, those
|
|
Packit |
0986c0 |
that begin with "%" will be processed by "doc2ms" only, and all others
|
|
Packit |
0986c0 |
will be copied verbatim by all other "doc2"s. So the commands may be
|
|
Packit |
0986c0 |
shuffled together, as long as the order of each of the three sets is
|
|
Packit |
0986c0 |
unchanged. That is, the example could be written this way without any
|
|
Packit |
0986c0 |
effect on the result:
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
@start table - first is interactive cleartext form
|
|
Packit |
0986c0 |
#\begin{tabular}{|ccl|} \hline
|
|
Packit |
0986c0 |
%c c l .
|
|
Packit |
0986c0 |
#\multicolumn{3}{|c|}{Ternary Operator} \\
|
|
Packit |
0986c0 |
%Symbol@Example@Explanation
|
|
Packit |
0986c0 |
Symbol Example Explanation
|
|
Packit |
0986c0 |
#Symbol & Example & Explanation \\ \hline
|
|
Packit |
0986c0 |
%_
|
|
Packit |
0986c0 |
?: a?b:c ternary operation
|
|
Packit |
0986c0 |
#\verb~?:~ & \verb~a?b:c~ & ternary operation\\
|
|
Packit |
0986c0 |
%?:@a?b:c@* ternary operation
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
@end table
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
In LaTeX, the command "\begin{tabular}{|ccl|} \hline" creates a
|
|
Packit |
0986c0 |
three-column table having the first two columns centered, the third column
|
|
Packit |
0986c0 |
left-justified, a vertical line at each side, and a horizontal line drawn
|
|
Packit |
0986c0 |
first. Thus the table will be enclosed in a box ("doc2tex" provides the
|
|
Packit |
0986c0 |
closing "\hline"). A double-backslash is a line skip. In the table
|
|
Packit |
0986c0 |
entries themselves, the ampersand is the column separator. If any LaTeX
|
|
Packit |
0986c0 |
special characters are in the table, they must be written within "\verb"
|
|
Packit |
0986c0 |
constructs, as is the case with the question mark in the example.
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
In nroff, the command "c c l ." creates a three-column table justified
|
|
Packit |
0986c0 |
the same way as the LaTeX table discussed above. The ampersand is the
|
|
Packit |
0986c0 |
column separator.
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
Rules for stylistic consistency (courtesy Jens Emmerich):
|
|
Packit |
0986c0 |
---------------------------------------------------------
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
0. General
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
* Use your brain -- the reader has one, too (at least in theory).
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
* Format according to the logical structure, not according to
|
|
Packit |
0986c0 |
visual charm.
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
* Keep things short. Don't split lines without a good reason. Many
|
|
Packit |
0986c0 |
people still use 24 line terminals/screens. Backslashify lines
|
|
Packit |
0986c0 |
only in code examples.
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
1. Verbatim lines: start column and line length
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
* Verbatim text starts in column 8 (7 spaces before the text). The
|
|
Packit |
0986c0 |
reason is that "Syntax:" is 7 and "Examples:" is 9 characters
|
|
Packit |
0986c0 |
wide. Adding the space in column 1 we have 1 resp. 3 characters
|
|
Packit |
0986c0 |
"overlap" in the online text versions, which is still easy to
|
|
Packit |
0986c0 |
read as all commands are at least 3 characters long. This does
|
|
Packit |
0986c0 |
not apply to the "interactive clear text form"-tables.
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
* The rightmost used column is column 73 (counting from 1). This
|
|
Packit |
0986c0 |
allows LaTeX formatted documents with only slightly wider text
|
|
Packit |
0986c0 |
than default, which adds to readability.
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
2. Line spacing
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
* An empty line goes before "Syntax:" and "Example:", but not after
|
|
Packit |
0986c0 |
them. Without these keywords, add an empty line before verbatim
|
|
Packit |
0986c0 |
lines if they are not embedded in a sentence.
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
* Leave blank lines within verbatim environments only if it is
|
|
Packit |
0986c0 |
really needed for clarity.
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
* Verbatim environments are separated from the following text by a
|
|
Packit |
0986c0 |
blank line, but not if they are embedded in a sentence.
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
* Short explanations within examples can be embedded within
|
|
Packit |
0986c0 |
comments if they are really short, otherwise use "normal" text
|
|
Packit |
0986c0 |
(beginning at column 2) and leave no blank lines between the text
|
|
Packit |
0986c0 |
and the example.
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
3. Spaces around braces
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
* In general don't put a space after an opening "{" or before a
|
|
Packit |
0986c0 |
closing brace "}". This makes everything wider and harder to
|
|
Packit |
0986c0 |
spot.
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
* Do insert a space in the following situations:
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
- where it adds clarity to nesting levels >=3 of braces; usually
|
|
Packit |
0986c0 |
only one brace for the outermost brace on a particular line
|
|
Packit |
0986c0 |
(see 'set grid')
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
- on multiple line optional constructs (see 'set xtics')
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
* Separate multiple optional constructs by a space.
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
* Don't separate them if they belong together. (see 'set title')
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
* Do separate them if they belong together but require a space in
|
|
Packit |
0986c0 |
between (see 'set ticscale').
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
* Part of these rules are really a consequence of gnuplot's
|
|
Packit |
0986c0 |
inconsistent syntax.
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
4. Placing and spaces around "|"
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
* Place a space before and after the "|". Otherwise the
|
|
Packit |
0986c0 |
alternatives tend to optically 'melt' and they are harder to
|
|
Packit |
0986c0 |
read.
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
* Keep or-expressions on one line, if possible.
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
* On multi-line expressions place the "|" at the beginning of the
|
|
Packit |
0986c0 |
next line rather than the end of the first. This makes it easier
|
|
Packit |
0986c0 |
to see that the expression continues. Align the first components;
|
|
Packit |
0986c0 |
this requires indenting the first line a bit further (see 'set
|
|
Packit |
0986c0 |
cntrparam').
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
5. Comma-separated optional argument lists
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
* Place the space before the opening brace rather within the braces
|
|
Packit |
0986c0 |
after the comma (as one normally does) (see 'set isosamples').
|
|
Packit |
0986c0 |
|
|
Packit |
0986c0 |
|