Annotation of OpenXM_contrib/gnuplot/docs/README, Revision 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