Annotation of OpenXM_contrib/gnuplot/docs/README, Revision 1.1.1.1
1.1 maekawa 1: Notes on the gnuplot help files and documentation.
2: --------------------------------------------------
3:
4: Gnuplot documentation is available in three ways:
5:
6: 1 - interactively, within gnuplot
7: 2 - as a printed document.
8: 3 - as a manual page, through the Unix man(1) facility
9:
10: The third form tells how to run gnuplot.
11:
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.
16:
17: gnuplot.doc -> gnuplot.gih
18: -> gnuplot.hlp
19: -> gnuplot.html
20: -> gnuplot.info
21: -> gnuplot.ipf
22: -> gnuplot.ms
23: -> gnuplot.rnh
24: -> gnuplot.rtf
25: -> gnuplot.tex
26:
27: On Unix, AmigaOS, and MSDOS the interactive help is built into the
28: program, and uses the file "gnuplot.gih" ('make gih').
29:
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.
38:
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"
41: ('make html').
42:
43: Under EMACS, interactive help uses the file "gnuplot.info" ('make info').
44:
45: On OS/2, the Information Presentation Facility Compiler converts the
46: file "gnuplot.ipf" to a "gnuplot.inf" file.
47:
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'
52:
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.
55:
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".
60:
61:
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.
65:
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.
71:
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".
75:
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.
81:
82:
83: Description of the gnuplot.doc format:
84: --------------------------------------
85:
86: Here is an example of the DOC master help format:
87:
88: ?
89: 1 gnuplot
90: GNUPLOT is a command-driven interactive function plotting program. It
91: ...
92: ?exit
93: 2 exit
94: 'exit', 'quit' and ...
95: ?expressions
96: 2 expressions
97: In general, any mathematical expression accepted by C, ...
98:
99: Topics:
100: functions operators
101: ?expressions functions
102: ?functions
103: 3 functions
104: The functions in GNUPLOT are ...
105:
106: Topics:
107: abs acos arg ...
108: ?expressions functions abs
109: ?functions abs
110: ?abs
111: 4 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
115: ?functions acos
116: ?acos
117: 4 acos
118: This function returns the arc cosine (inverse cosine) of its
119: argument. 'acos' returns its argument in radians.
120:
121:
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
135: to represent a tree.
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 !
148:
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 doc2ms: table entry
155: ^ used by doc2html : hypertext link
156: < the help from the terminal driver files is inserted at this point.
157: C comment (mainly for RCS ID line)
158: C# reserved form of comment (used internally by termdoc.c)
159:
160:
161: Tables:
162: -------
163:
164: Here is a sample table:
165:
166: @start table - first is interactive cleartext form
167: Symbol Example Explanation
168: ?: a?b:c ternary operation
169: #\begin{tabular}{|ccl|} \hline
170: #\multicolumn{3}{|c|}{Ternary Operator} \\
171: #Symbol & Example & Explanation \\ \hline
172: #\verb~?:~ & \verb~a?b:c~ & ternary operation\\
173: %c c l .
174: %Symbol@Example@Explanation
175: %_
176: %?:@a?b:c@* ternary operation
177:
178: @end table
179:
180: "doc2tex" and "doc2ms" are the formats that do something with tables
181: other than copy them verbatim. It is best to bracket a table in a
182: "@start table"/"@end table" pair.
183:
184: Inside the "@start"/"@end" block are three independent sets of commands:
185: those that begin with "#" will be processed by "doc2tex" only, those
186: that begin with "%" will be processed by "doc2ms" only, and all others
187: will be copied verbatim by all other "doc2"s. So the commands may be
188: shuffled together, as long as the order of each of the three sets is
189: unchanged. That is, the example could be written this way without any
190: effect on the result:
191:
192: @start table - first is interactive cleartext form
193: #\begin{tabular}{|ccl|} \hline
194: %c c l .
195: #\multicolumn{3}{|c|}{Ternary Operator} \\
196: %Symbol@Example@Explanation
197: Symbol Example Explanation
198: #Symbol & Example & Explanation \\ \hline
199: %_
200: ?: a?b:c ternary operation
201: #\verb~?:~ & \verb~a?b:c~ & ternary operation\\
202: %?:@a?b:c@* ternary operation
203:
204: @end table
205:
206: In LaTeX, the command "\begin{tabular}{|ccl|} \hline" creates a
207: three-column table having the first two columns centered, the third column
208: left-justified, a vertical line at each side, and a horizontal line drawn
209: first. Thus the table will be enclosed in a box ("doc2tex" provides the
210: closing "\hline"). A double-backslash is a line skip. In the table
211: entries themselves, the ampersand is the column separator. If any LaTeX
212: special characters are in the table, they must be written within "\verb"
213: constructs, as is the case with the question mark in the example.
214:
215: In nroff, the command "c c l ." creates a three-column table justified
216: the same way as the LaTeX table discussed above. The ampersand is the
217: column separator.
218:
219:
220: Rules for stylistic consistency (courtesy Jens Emmerich):
221: ---------------------------------------------------------
222:
223: 0. General
224:
225: * Use your brain -- the reader has one, too (at least in theory).
226:
227: * Format according to the logical structure, not according to
228: visual charm.
229:
230: * Keep things short. Don't split lines without a good reason. Many
231: people still use 24 line terminals/screens. Backslashify lines
232: only in code examples.
233:
234:
235: 1. Verbatim lines: start column and line length
236:
237: * Verbatim text starts in column 8 (7 spaces before the text). The
238: reason is that "Syntax:" is 7 and "Examples:" is 9 characters
239: wide. Adding the space in column 1 we have 1 resp. 3 characters
240: "overlap" in the online text versions, which is still easy to
241: read as all commands are at least 3 characters long. This does
242: not apply to the "interactive clear text form"-tables.
243:
244: * The rightmost used column is column 73 (counting from 1). This
245: allows LaTeX formatted documents with only slightly wider text
246: than default, which adds to readability.
247:
248: 2. Line spacing
249:
250: * An empty line goes before "Syntax:" and "Example:", but not after
251: them. Without these keywords, add an empty line before verbatim
252: lines if they are not embedded in a sentence.
253:
254: * Leave blank lines within verbatim environments only if it is
255: really needed for clarity.
256:
257: * Verbatim environments are separated from the following text by a
258: blank line, but not if they are embedded in a sentence.
259:
260: * Short explanations within examples can be embedded within
261: comments if they are really short, otherwise use "normal" text
262: (beginning at column 2) and leave no blank lines between the text
263: and the example.
264:
265: 3. Spaces around braces
266:
267: * In general don't put a space after an opening "{" or before a
268: closing brace "}". This makes everything wider and harder to
269: spot.
270:
271: * Do insert a space in the following situations:
272:
273: - where it adds clarity to nesting levels >=3 of braces; usually
274: only one brace for the outermost brace on a particular line
275: (see 'set grid')
276:
277: - on multiple line optional constructs (see 'set xtics')
278:
279: * Separate multiple optional constructs by a space.
280:
281: * Don't separate them if they belong together. (see 'set title')
282:
283: * Do separate them if they belong together but require a space in
284: between (see 'set ticscale').
285:
286: * Part of these rules are really a consequence of gnuplot's
287: inconsistent syntax.
288:
289: 4. Placing and spaces around "|"
290:
291: * Place a space before and after the "|". Otherwise the
292: alternatives tend to optically 'melt' and they are harder to
293: read.
294:
295: * Keep or-expressions on one line, if possible.
296:
297: * On multi-line expressions place the "|" at the beginning of the
298: next line rather than the end of the first. This makes it easier
299: to see that the expression continues. Align the first components;
300: this requires indenting the first line a bit further (see 'set
301: cntrparam').
302:
303: 5. Comma-separated optional argument lists
304:
305: * Place the space before the opening brace rather within the braces
306: after the comma (as one normally does) (see 'set isosamples').
307:
308:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to README CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [local] / OpenXM_contrib / gnuplot / docs