1Notes on the gnuplot help files and documentation. 2-------------------------------------------------- 3 4Gnuplot documentation is available in three ways: 5 61 - interactively, within gnuplot 72 - as a printed document. 83 - as a manual page, through the Unix man(1) facility 9 10The third form tells how to run gnuplot. 11 12The first two forms describe the inner workings, and contain equivalent 13information. They derive their information from the file "gnuplot.doc", 14which is the master copy of gnuplot help information. All other forms, 15except for the man page "gnuplot.1", are derived from it. 16 17PostScript, PDF, or HTML versions of the manual can be created from the TeX 18version if you have latex, pdflatex, and htlatex available, respectively. 19 20gnuplot.doc -> gnuplot.gih 21 -> gnuplot.hlp 22 -> gnuplot.info 23 -> gnuplot.ipf 24 -> gnuplot.ms 25 -> gnuplot.rnh 26 -> gnuplot.rtf 27 -> wgnuplot.html 28 -> gnuplot.tex 29 30On Unix and MSDOS the interactive help is built into the 31program, and uses the file "gnuplot.gih" ('make gih'). 32 33On VMS, the interactive help is supplied by the system help facility, 34using the file "gnuplot.hlp". This is built by default, either by 35doc2hlp, or doc2rnh and RUNOFF which format gnuplot.doc for the VMS 36HELP indenting conventions. The help file is placed in a help library, 37"gnuplot.hlb" but it may be also be placed in one of the system-wide 38help libraries, using lib/help ('help lib'). If VMS users prefer the 39gnuplot interactive help facility to the system facility, this can be 40easily changed by not defining NO_GIH. 41 42The PDF and HTML versions of the gnuplot manual can include hyperlinks to 43demonstration plots. There is a special makefile target "make pdf" 44to generate and include sample plots directly in the manual itself. 45 46Under EMACS, interactive help uses the file "gnuplot.info" ('make info'). 47 48On OS/2, the Information Presentation Facility Compiler converts the 49file "gnuplot.ipf" to a "gnuplot.inf" file. 50 51The printed document is available in troff/nroff (ms) format, using 52the file "gnuplot.ms". For nroff, use 'make nroff'. For troff, type 53'make ms' and then 'troff -ms gnuplot.ms' in whatever way you use troff. 54For groff (on linux), use 'groff -t -e -mgs gnuplot.ms' 55 56On MS-Windows, the Microsoft HTML help compiler converts the file 57"wgnuplot.html" to a 'chm' file which is used by the standard Windows 58help program. Hyperlinks and sample plots are included. Alternatively, 59the Microsoft help compiler converts the file "gnuplot.rtf" to a 'hlp' 60file. 61 62Manual entries for the terminals are not included in "gnuplot.doc"; 63instead, each "driver.trm" file (in the directory /term) contains its 64own documentation section. See "term/README" for details. 65 66When you build gnuplot, only some of the terminal drivers are loaded; 67these are selected in "term.h" by compiler directives specified in the 68makefile. The interactive help generators use the same set of compiler 69directives in "term.h", and thus interactive help contains information 70for just those terminals actually loaded. 71 72The printed manual generators and the html generator contain information 73about all terminals. This is accomplished by concatenating all of the 74".trm" files into a single one, "allterm.h". 75 76The file "termdoc.c" is used by each of the nine processing programs 77("doc2gih.c", etc.); it #includes either "term.h" or "allterm.h", as is 78appropriate. If you wish to override the default decision about which 79terminals are to appear in the documentation, edit the appropriate target 80in the Makefile and add/remove -DALL_TERM_DOC to/from the compiler flags. 81 82 83Description of the gnuplot.doc format: 84-------------------------------------- 85 86Here is an example of the DOC master help format: 87 88? 891 gnuplot 90 GNUPLOT is a command-driven interactive function plotting program. It 91 ... 92?exit 932 exit 94 'exit', 'quit' and ... 95?expressions 962 expressions 97 In general, any mathematical expression accepted by C, ... 98 99 Topics: 100 functions operators 101?expressions functions 102?functions 1033 functions 104 The functions in GNUPLOT are ... 105 106 Topics: 107 abs acos arg ... 108?expressions functions abs 109?functions abs 110?abs 1114 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 1174 acos 118 This function returns the arc cosine (inverse cosine) of its 119 argument. 'acos' returns its argument in radians. 120 121 122Some notes about the format: 123---------------------------- 124Remember that all text must be able to be processed by gnuplot, VMS, 125 nroff, troff, info, itl, and latex, and always do something reasonable. 126The first column is reserved for control characters. 127Text does not start in the first column. 128Lines that start in column 2 may be typeset by LaTeX. 129Lines that have a space in column 2 are to be printed in a verbatim 130 environment by LaTeX. 131Tables must have a space in column 2. 132Do NOT use tabs in the help file. 133Conversion 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. 136Conversion 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. 142Backquote 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 149Control characters in first column: 150? used by .gih format, for builtin interactive help - keyword 1510-9 used by VMS help and by doc2{tex,ms,html} formatters to define level,keyword 152@ used by doc2{tex,ms,rnh} to define table start/end 153# used by doc2tex: table entry 154#TeX used by doc2tex: LaTeX command to be inserted in output stream (e.g. \newpage) 155#b bulleted list entry 156## continuation of bulleted item 157= used by doc2tex: index entry 158F used by doc2{tex,html}: embedded figure (followed by base name of the pdf file) 159% used by doc2ms: table entry 160^ used by doc2{tex,html}: hypertext link / HTML code 161< the help from the terminal driver files is inserted at this point. 162C comment (mainly for RCS ID line) 163C# reserved form of comment (used internally by termdoc.c) 164 165 166Tables: 167------- 168 169Here is a sample table: 170 171@start table - first is interactive cleartext form 172 Symbol Example Explanation 173 ?: a?b:c ternary operation 174#\begin{tabular}{|ccl|} \hline 175#\multicolumn{3}{|c|}{Ternary Operator} \\ 176#Symbol & Example & Explanation \\ \hline 177#\verb~?:~ & \verb~a?b:c~ & ternary operation\\ 178%c c l . 179%Symbol@Example@Explanation 180%_ 181%?:@a?b:c@* ternary operation 182 183@end table 184 185"doc2tex" and "doc2ms" are the formats that do something with tables 186other than copy them verbatim. It is best to bracket a table in a 187"@start table"/"@end table" pair. 188 189Inside the "@start"/"@end" block are three independent sets of commands: 190those that begin with "#" will be processed by "doc2tex" only, those 191that begin with "%" will be processed by "doc2ms" only, and all others 192will be copied verbatim by all other "doc2"s. So the commands may be 193shuffled together, as long as the order of each of the three sets is 194unchanged. That is, the example could be written this way without any 195effect on the result: 196 197@start table - first is interactive cleartext form 198#\begin{tabular}{|ccl|} \hline 199%c c l . 200#\multicolumn{3}{|c|}{Ternary Operator} \\ 201%Symbol@Example@Explanation 202 Symbol Example Explanation 203#Symbol & Example & Explanation \\ \hline 204%_ 205 ?: a?b:c ternary operation 206#\verb~?:~ & \verb~a?b:c~ & ternary operation\\ 207%?:@a?b:c@* ternary operation 208 209@end table 210 211In LaTeX, the command "\begin{tabular}{|ccl|} \hline" creates a 212three-column table having the first two columns centered, the third column 213left-justified, a vertical line at each side, and a horizontal line drawn 214first. Thus the table will be enclosed in a box ("doc2tex" provides the 215closing "\hline"). A double-backslash is a line skip. In the table 216entries themselves, the ampersand is the column separator. If any LaTeX 217special characters are in the table, they must be written within "\verb" 218constructs, as is the case with the question mark in the example. 219 220In nroff, the command "c c l ." creates a three-column table justified 221the same way as the LaTeX table discussed above. The ampersand is the 222column separator. 223 224 225Rules for stylistic consistency (courtesy Jens Emmerich): 226--------------------------------------------------------- 227 2280. General 229 230 * Use your brain -- the reader has one, too (at least in theory). 231 232 * Format according to the logical structure, not according to 233 visual charm. 234 235 * Keep things short. Don't split lines without a good reason. Many 236 people still use 24 line terminals/screens. Backslashify lines 237 only in code examples. 238 239 2401. Verbatim lines: start column and line length 241 242 * Verbatim text starts in column 8 (7 spaces before the text). The 243 reason is that "Syntax:" is 7 and "Examples:" is 9 characters 244 wide. Adding the space in column 1 we have 1 resp. 3 characters 245 "overlap" in the online text versions, which is still easy to 246 read as all commands are at least 3 characters long. This does 247 not apply to the "interactive clear text form"-tables. 248 249 * The rightmost used column is column 73 (counting from 1). This 250 allows LaTeX formatted documents with only slightly wider text 251 than default, which adds to readability. 252 2532. Line spacing 254 255 * An empty line goes before "Syntax:" and "Example:", but not after 256 them. Without these keywords, add an empty line before verbatim 257 lines if they are not embedded in a sentence. 258 259 * Leave blank lines within verbatim environments only if it is 260 really needed for clarity. 261 262 * Verbatim environments are separated from the following text by a 263 blank line, but not if they are embedded in a sentence. 264 265 * Short explanations within examples can be embedded within 266 comments if they are really short, otherwise use "normal" text 267 (beginning at column 2) and leave no blank lines between the text 268 and the example. 269 2703. Spaces around braces 271 272 * In general don't put a space after an opening "{" or before a 273 closing brace "}". This makes everything wider and harder to 274 spot. 275 276 * Do insert a space in the following situations: 277 278 - where it adds clarity to nesting levels >=3 of braces; usually 279 only one brace for the outermost brace on a particular line 280 (see 'set grid') 281 282 - on multiple line optional constructs (see 'set xtics') 283 284 * Separate multiple optional constructs by a space. 285 286 * Don't separate them if they belong together. (see 'set title') 287 288 * Do separate them if they belong together but require a space in 289 between (see 'set ticscale'). 290 291 * Part of these rules are really a consequence of gnuplot's 292 inconsistent syntax. 293 2944. Placing and spaces around "|" 295 296 * Place a space before and after the "|". Otherwise the 297 alternatives tend to optically 'melt' and they are harder to 298 read. 299 300 * Keep or-expressions on one line, if possible. 301 302 * On multi-line expressions place the "|" at the beginning of the 303 next line rather than the end of the first. This makes it easier 304 to see that the expression continues. Align the first components; 305 this requires indenting the first line a bit further (see 'set 306 cntrparam'). 307 3085. Comma-separated optional argument lists 309 310 * Place the space before the opening brace rather within the braces 311 after the comma (as one normally does) (see 'set isosamples'). 312 313 314