1 Notes on the gnuplot help files and documentation.
2 --------------------------------------------------
4 Gnuplot documentation is available in three ways:
6 1 - interactively, within gnuplot
7 2 - as a printed document.
8 3 - as a manual page, through the Unix man(1) facility
10 The third form tells how to run gnuplot.
12 The first two forms describe the inner workings, and contain equivalent
13 information. They derive their information from the file "gnuplot.doc",
14 which is the master copy of gnuplot help information. All other forms,
15 except for the man page "gnuplot.1", are derived from it.
17 gnuplot.doc -> gnuplot.gih
27 On Unix, AmigaOS, and MSDOS the interactive help is built into the
28 program, and uses the file "gnuplot.gih" ('make gih').
30 On VMS, the interactive help is supplied by the system help facility,
31 using the file "gnuplot.hlp". This is built by default, either by
32 doc2hlp, or doc2rnh and RUNOFF which format gnuplot.doc for the VMS
33 HELP indenting conventions. The help file is placed in a help library,
34 "gnuplot.hlb" but it may be also be placed in one of the system-wide
35 help libraries, using lib/help ('help lib'). If VMS users prefer the
36 gnuplot interactive help facility to the system facility, this can be
37 easily changed by not defining NO_GIH.
39 On the World Wide Web, the gnuplot manual can include demonstration
40 plots; the links for these are included in the file "gnuplot.html"
43 Under EMACS, interactive help uses the file "gnuplot.info" ('make info').
45 On OS/2, the Information Presentation Facility Compiler converts the
46 file "gnuplot.ipf" to a "gnuplot.inf" file.
48 The printed document is available in troff/nroff (ms) format, using
49 the file "gnuplot.ms". For nroff, use 'make nroff'. For troff, type
50 'make ms' and then 'troff -ms gnuplot.ms' in whatever way you use troff.
51 For groff (on linux), use 'groff -t -e -mgs gnuplot.ms'
53 On MS-Windows, the Microsoft help compiler converts the file "gnuplot.rtf"
54 to an 'hlp' file which is used by the standard Windows help program.
56 The printed document is also available in LaTeX format, using the file
57 "gnuplot.tex" ('make tex'). If you use LaTeX on your computer, you can
58 type 'make dvi' to create "gnuplot.dvi", and then run your dvi-to-
59 PostScript converter to generate "gnuplot.ps".
62 Manual entries for the terminals are not included in "gnuplot.doc";
63 instead, each "driver.trm" file (in the directory /term) contains its
64 own documentation section. See "term/README" for details.
66 When you build gnuplot, only some of the terminal drivers are loaded;
67 these are selected in "term.h" by compiler directives specified in the
68 makefile. The interactive help generators use the same set of compiler
69 directives in "term.h", and thus interactive help contains information
70 for just those terminals actually loaded.
72 The printed manual generators and the html generator contain information
73 about all terminals. This is accomplished by concatenating all of the
74 ".trm" files into a single one, "allterm.h".
76 The file "termdoc.c" is used by each of the eight processing programs
77 ("doc2gih.c", etc.); it #includes either "term.h" or "allterm.h", as is
78 appropriate. If you wish to override the default decision about which
79 terminals are to appear in the documentation, edit the appropriate target
80 in the Makefile and add/remove -DALL_TERM_DOC to/from the compiler flags.
83 Description of the gnuplot.doc format:
84 --------------------------------------
86 Here is an example of the DOC master help format:
90 GNUPLOT is a command-driven interactive function plotting program. It
94 'exit', 'quit' and ...
97 In general, any mathematical expression accepted by C, ...
101 ?expressions functions
104 The functions in GNUPLOT are ...
108 ?expressions functions abs
112 This function returns the absolute value of its argument. The
113 returned value is of the same type as the argument.
114 ?expressions functions acos
118 This function returns the arc cosine (inverse cosine) of its
119 argument. 'acos' returns its argument in radians.
122 Some notes about the format:
123 ----------------------------
124 Remember that all text must be able to be processed by gnuplot, VMS,
125 nroff, troff, info, itl, and latex, and always do something reasonable.
126 The first column is reserved for control characters.
127 Text does not start in the first column.
128 Lines that start in column 2 may be typeset by LaTeX.
129 Lines that have a space in column 2 are to be printed in a verbatim
130 environment by LaTeX.
131 Tables must have a space in column 2.
132 Do NOT use tabs in the help file.
133 Conversion from this format to vax .hlp file involves removal of
134 lines starting with [?@#$%] (see doc2hlp). VMS uses the numbers
136 Conversion from this format to gnuplot .gih file involves removal of
137 lines starting with [0-9@#$%] (see doc2gih). Gnuplot matches your
138 help query against the ? lines to find the help information.
139 Multiple ? lines for one text block constitute synonyms. The most
140 specific should be first, eg 'expressions functions' before 'functions'.
141 Spaces are allowed here, but should be single.
142 Backquote pairs are converted by the doc2tex program into boldface;
143 that is, `some text` is converted to {\bf some text}. Be sure to pair
144 the backquotes, or the whole document will be boldface! doc2ms converts
145 `` pairs to \fB...\fR, except inside tables : for the moment, this
146 has to be done manually on the lines starting %, but we ought to
147 find some way to allow tables to be entered just the once !
149 Control characters in first column:
150 ? used by .gih format, for builtin interactive help - keyword
151 0-9 used by VMS help and by doc2{tex,ms} formatters to define level,keyword
152 @ used by doc2{tex,ms,rnh} to define table start/end
153 # used by doc2tex: table entry
154 = used by doc2tex: index entry
155 % used by doc2ms: table entry
156 ^ used by doc2html : hypertext link
157 < the help from the terminal driver files is inserted at this point.
158 C comment (mainly for RCS ID line)
159 C# reserved form of comment (used internally by termdoc.c)
165 Here is a sample table:
167 @start table - first is interactive cleartext form
168 Symbol Example Explanation
169 ?: a?b:c ternary operation
170 #\begin{tabular}{|ccl|} \hline
171 #\multicolumn{3}{|c|}{Ternary Operator} \\
172 #Symbol & Example & Explanation \\ \hline
173 #\verb~?:~ & \verb~a?b:c~ & ternary operation\\
175 %Symbol@Example@Explanation
177 %?:@a?b:c@* ternary operation
181 "doc2tex" and "doc2ms" are the formats that do something with tables
182 other than copy them verbatim. It is best to bracket a table in a
183 "@start table"/"@end table" pair.
185 Inside the "@start"/"@end" block are three independent sets of commands:
186 those that begin with "#" will be processed by "doc2tex" only, those
187 that begin with "%" will be processed by "doc2ms" only, and all others
188 will be copied verbatim by all other "doc2"s. So the commands may be
189 shuffled together, as long as the order of each of the three sets is
190 unchanged. That is, the example could be written this way without any
191 effect on the result:
193 @start table - first is interactive cleartext form
194 #\begin{tabular}{|ccl|} \hline
196 #\multicolumn{3}{|c|}{Ternary Operator} \\
197 %Symbol@Example@Explanation
198 Symbol Example Explanation
199 #Symbol & Example & Explanation \\ \hline
201 ?: a?b:c ternary operation
202 #\verb~?:~ & \verb~a?b:c~ & ternary operation\\
203 %?:@a?b:c@* ternary operation
207 In LaTeX, the command "\begin{tabular}{|ccl|} \hline" creates a
208 three-column table having the first two columns centered, the third column
209 left-justified, a vertical line at each side, and a horizontal line drawn
210 first. Thus the table will be enclosed in a box ("doc2tex" provides the
211 closing "\hline"). A double-backslash is a line skip. In the table
212 entries themselves, the ampersand is the column separator. If any LaTeX
213 special characters are in the table, they must be written within "\verb"
214 constructs, as is the case with the question mark in the example.
216 In nroff, the command "c c l ." creates a three-column table justified
217 the same way as the LaTeX table discussed above. The ampersand is the
221 Rules for stylistic consistency (courtesy Jens Emmerich):
222 ---------------------------------------------------------
226 * Use your brain -- the reader has one, too (at least in theory).
228 * Format according to the logical structure, not according to
231 * Keep things short. Don't split lines without a good reason. Many
232 people still use 24 line terminals/screens. Backslashify lines
233 only in code examples.
236 1. Verbatim lines: start column and line length
238 * Verbatim text starts in column 8 (7 spaces before the text). The
239 reason is that "Syntax:" is 7 and "Examples:" is 9 characters
240 wide. Adding the space in column 1 we have 1 resp. 3 characters
241 "overlap" in the online text versions, which is still easy to
242 read as all commands are at least 3 characters long. This does
243 not apply to the "interactive clear text form"-tables.
245 * The rightmost used column is column 73 (counting from 1). This
246 allows LaTeX formatted documents with only slightly wider text
247 than default, which adds to readability.
251 * An empty line goes before "Syntax:" and "Example:", but not after
252 them. Without these keywords, add an empty line before verbatim
253 lines if they are not embedded in a sentence.
255 * Leave blank lines within verbatim environments only if it is
256 really needed for clarity.
258 * Verbatim environments are separated from the following text by a
259 blank line, but not if they are embedded in a sentence.
261 * Short explanations within examples can be embedded within
262 comments if they are really short, otherwise use "normal" text
263 (beginning at column 2) and leave no blank lines between the text
266 3. Spaces around braces
268 * In general don't put a space after an opening "{" or before a
269 closing brace "}". This makes everything wider and harder to
272 * Do insert a space in the following situations:
274 - where it adds clarity to nesting levels >=3 of braces; usually
275 only one brace for the outermost brace on a particular line
278 - on multiple line optional constructs (see 'set xtics')
280 * Separate multiple optional constructs by a space.
282 * Don't separate them if they belong together. (see 'set title')
284 * Do separate them if they belong together but require a space in
285 between (see 'set ticscale').
287 * Part of these rules are really a consequence of gnuplot's
290 4. Placing and spaces around "|"
292 * Place a space before and after the "|". Otherwise the
293 alternatives tend to optically 'melt' and they are harder to
296 * Keep or-expressions on one line, if possible.
298 * On multi-line expressions place the "|" at the beginning of the
299 next line rather than the end of the first. This makes it easier
300 to see that the expression continues. Align the first components;
301 this requires indenting the first line a bit further (see 'set
304 5. Comma-separated optional argument lists
306 * Place the space before the opening brace rather within the braces
307 after the comma (as one normally does) (see 'set isosamples').