/[CvsGraph]/cvsgraph/cvsgraph.conf.5
ViewVC logotype

Annotate of /cvsgraph/cvsgraph.conf.5

Parent Directory Parent Directory | Revision Log Revision Log | View Revision Graph Revision Graph


Revision 1.14 - (hide annotations)
Sun Mar 9 22:36:50 2003 UTC (14 years, 9 months ago) by bertho
Branch: MAIN
Changes since 1.13: +78 -11 lines
- add merge visualization
- Provide solution for possible XSS bug in tag expansions
1 bertho 1.11 .TH "cvsgraph.conf" "5" "1.3.0" "B. Stultiens" "CVS/RCS Utilties"
2 bertho 1.1 .SH "NAME"
3     cvsgraph.conf \- CVS/RCS repository grapher configuration
4     .SH "OVERVIEW"
5     The configuration file is a context free grammar where
6     empty lines and whitespace are ignored. Comments start
7     with '#' and everything until end of line is ignored.
8     .br
9     A configuration parameter is written as:
10     .br
11     <keyword> = <argument> ;
12     .br
13     .LP
14     Keywords are defined in \fBPARAMETERS\fR. The argument
15     can be either numerical or string typed.
16    
17     .LP
18     Numbers may be entered as octal, decimal or hex as in 0117,
19 bertho 1.7 79 and 0x4f respectively. Floating point numbers contain a
20     single '.', but must start with a digit. Integer numbers are
21     automagically converted to floats if required.
22 bertho 1.1
23     .LP
24     Strings are C\-style strings, enclosed in double quotes
25     in which characters may be escaped with '\\' and written
26     in octal and hex escapes. Note that '\\' must be escaped
27 bertho 1.6 if it is to be entered as a character. Escapes recognized
28     are '\\[abfnrtv]', '\\[xX][0-9a-fA-F]{2}' and '\\[012][0-7]{0,2}'.
29 bertho 1.1 .br
30     Some strings are expanded with printf like conversions
31     which start with '%'. Not all are applicable at all times,
32     in which case they will expand to nothing.
33 bertho 1.3 .br
34     Note that expansions of paths are available with and without
35     trailing '/'. The distinction is required for path construction
36     to ensure that empty expansions will not redirect the path to
37     root and no double '/' in a path is generated.
38 bertho 1.1 .TP
39     %c
40 bertho 1.3 cvsroot including a trailing '/' if non\-empty
41     .TP
42     %C
43     cvsroot without trailing '/', regardless of how it was entered
44     on the commandline
45 bertho 1.1 .TP
46     %m
47 bertho 1.3 cvsmodule including trailing '/' if non\-empty
48     .TP
49     %M
50     cvsmodule without trailing '/', regardless of how it was entered
51     on the commandline
52 bertho 1.1 .TP
53     %f
54 bertho 1.3 filename without path (\fIbasename <name>\fR functionality)
55 bertho 1.1 .TP
56     %F
57 bertho 1.3 filename without path and with ",v" stripped (\fIbasename <name> ,v\fR
58     functionality)
59 bertho 1.1 .TP
60     %p
61 bertho 1.3 path part of filename. This includes a trailing '/' if the
62     path is non\-empty
63 bertho 1.1 .TP
64     %r
65     number of revisions
66     .TP
67     %b
68     number of branches
69     .TP
70     %%
71 bertho 1.6 literal '%'
72 bertho 1.1 .TP
73     %R
74     the revision number (e.g. '1.2.4.4')
75     .TP
76     %P
77     previous revision number
78     .TP
79     %B
80     the branch number (e.g. '1.2.4')
81     .TP
82     %d
83     date of revision
84     .TP
85     %a
86     author of revision
87     .TP
88     %s
89     state of revision
90     .TP
91 bertho 1.9 %l
92     The logentry of the revision. You need to enable \fBparse_logs\fR for this to
93     work. You may append an optional truncate length by writing '[num]' (with num
94     the maximum length) directly after %l. If no trunction is specified, then all
95     will be expanded. Specifying a negative truncation length means that newlines
96     should be replaced by spaces. If truncation occurs, then "..." will be
97     appended. The expansion is scanned for possible html-entities and are replaced
98     by &#...; equivalents.
99     .br
100     For example: "%l[25]" will expand up to 25 characters of the log.
101 bertho 1.14 .br
102     Note: This expansion is obsolete. Please use "%(%L%)"; see comment below.
103 bertho 1.9 .TP
104     %L
105     Same as %l, but no html-entity translations are performed.
106     .TP
107 bertho 1.1 %t
108     current tag of branch or revision
109     .TP
110     %0..%9
111     command\-line argument \-0 .. \-9
112 bertho 1.14 .TP
113     %(...%)
114     HTMLize the string withing the parenthesis. This is usefull to prevent a
115     possible cross site scripting big when expanding tags into the map generation.
116     For an exploit, you need to have an attack on your cvs-server, or you need to
117     be a complete idiot to enter a tag with '<', '>' or '"' characters.
118     .br
119     Example: a string "%(%t%)", with tag \fB><script xxx="..."><\fR will expand to
120     \fB&gt;&lt;script xxx=&#34;...&#34;&gt;&lt;\fR and not into the execution of
121     a script.
122     .br
123     Note: This method is preferred to the %l expansion, because it is more
124     generic solution (i.e. use "%(%L%)" for log expansions).
125 bertho 1.1
126     .LP
127 bertho 1.6 Fonts are numbered 0..4 (as defined in libgd) where
128 bertho 1.1 0 = tiny, 1 = small, 2 = medium (bold), 3 = large and
129     4 = giant.
130    
131     .LP
132 bertho 1.14 Colors are strings, similar to html\-type colors in the form
133 bertho 1.1 "#rrggbb" with parts written in hex, where rr = red (00..ff),
134     gg = green (00\-ff) and bb = blue (00\-ff).
135    
136     .LP
137 bertho 1.8 Booleans have three possible arguments: true, false and not. `Not' means
138     inverse of what it was (logical negation) and is represented by the value -1.
139     For the configuration file that means that the default value is negated.
140     However, the not possibility is a very handy tool for commandline overrides
141     generated from (CGI-)scripts.
142    
143     .LP
144 bertho 1.1 There are several reserved words besides of the keywords.
145     These additional reserved words expand to numerical values:
146     .br
147     Booleans:
148     .br
149     false = 0
150     .br
151     true = 1
152     .br
153 bertho 1.8 not = -1
154     .br
155 bertho 1.1 Alignment specifiers:
156     .br
157     left = 0
158     .br
159     center = 1
160     .br
161     right = 2
162     .br
163     Image specifiers:
164     .br
165     gif = 0
166     .br
167     png = 1
168     .br
169     jpeg = 2
170     .br
171     Font specifiers:
172     .br
173     tiny = 0
174     .br
175     small = 1
176     .br
177     medium = 2
178     .br
179     large = 3
180     .br
181     giant = 4
182     .br
183 bertho 1.13 HTML level specifiers:
184     .br
185     HTML3 = 1
186     .br
187     HTML4 = 2
188     .br
189     XHTML = 3
190     .br
191 bertho 1.1
192     .SH "PARAMETERS"
193     .TP
194     \fBcvsroot\fR \fIstring\fR
195     The absolute base directory where the CSV/RCS repository can be found.
196     A '/' will be appended to the string if it is not empty and does not
197     contain a trailing '/'.
198     .br
199     Default is an empty string.
200    
201     .TP
202     \fBcvsmodule\fR \fIstring\fR
203     The modulename of the CVS/RCS repository. This is converted into a
204     subdirectory name with a trailing '/'.
205     .br
206     Default is an empty string.
207    
208     .TP
209     \fBcolor_bg\fR \fIcolor\fR
210     The background color of the image.
211     .br
212     Default is white ("#ffffff").
213    
214     .TP
215 bertho 1.7 \fBtransparent_bg\fR \fIboolean\fR
216     The background color of the image is to be the transparent color. This is
217     only usefull for PNG images. Be sure to set \fBcolor_bg\fR to something
218     reasonable to make sure that the image is viewable with programs that do not
219     support transparency.
220     .br
221     Default is false.
222    
223     .TP
224 bertho 1.1 \fBdate_format\fR \fIstring\fR
225     The \fBstrftime(3)\fR format string for date and time representation in
226     the '%d' expansion.
227     .br
228     Default is "%d\-%b\-%Y %H:%M:%S".
229    
230     .TP
231 bertho 1.5 \fBbox_shadow\fR \fIboolean\fR
232 bertho 1.1 A boolean whether or not to draw a shadow for the boxes of
233     revisions and branches.
234     .br
235     Default is false.
236    
237     .TP
238 bertho 1.5 \fBupside_down\fR \fIboolean\fR
239     Draw the entire tree upside down if set. I.e. highest revisions are
240 bertho 1.14 at the top of the image. See also \fBcvsgraph(1)\fR option '\fB-u\fR'.
241 bertho 1.5 .br
242     Default is false.
243    
244     .TP
245 bertho 1.10 \fBleft_right\fR \fIboolean\fR
246     Draw the entire tree from left to right instead of top down if set.
247     I.e. highest revisions are at the right of the image. You can also
248     draw the tree right to left when \fBupside_down\fR is set too.
249     .br
250     Default is false.
251    
252     .TP
253 bertho 1.5 \fBstrip_untagged\fR \fIboolean\fR
254 bertho 1.6 Ommit all revisions that do not have tags and are not a branchpoint. This
255     reduces the image-size, but can be confusing when looking for a specific
256 bertho 1.14 revision. See also \fBcvsgraph(1)\fR option '\fB-s\fR'.
257 bertho 1.6 .br
258     Default is false.
259    
260     .TP
261     \fBstrip_first_rev\fR \fIboolean\fR
262     Also ommit the first revision in a branch if it does not have tags and is not a
263     branchpoint. This has only effect if \fBstrip_untagged\fR is set. See also
264 bertho 1.14 \fBcvsgraph(1)\fR option '\fB-S\fR'.
265 bertho 1.6 .br
266     Default is false.
267    
268     .TP
269 bertho 1.7 \fBauto_stretch\fR \fIboolean\fR
270 bertho 1.6 Try to stretch the inter\-revision spacing to move the trunks more to the left,
271 bertho 1.14 effectively reducing the image's size. See also \fBcvsgraph(1)\fR option '\fB-k\fR'.
272 bertho 1.5 .br
273     Default is false.
274    
275     .TP
276 bertho 1.7 \fBuse_ttf\fR \fIboolean\fR
277     Enable truetype rendering of strings using the FreeType interface of libgd.
278     Note that ttf rendering is significantly slower than libgd's bitmap fonts.
279     .br
280     Default is false.
281    
282     .TP
283     \fBanti_alias\fR \fIboolean\fR
284     Enable antialias rendering of truetype fonts. This has only effect if
285     \fBuse_ttf\fR is set. Enabling anti_alias gives very nice results.
286     However, that is at the expense of 8-bit vs. 4-bit colormap images,
287     which can be a major drawback because the size of 8-bit images is 3..4
288     times that of 4-bit images (with compressed PNG as output).
289     .br
290     Default is true.
291 bertho 1.8
292     .TP
293     \fBthick_lines\fR \fInumber\fR
294     Set the thickness of connector lines between boxes. Normally, lines
295     are drawn one pixel wide, but can look somewhat thin. Setting the thickness
296     to anything over 5 would be plain ugly (but hey, who is to debate tast:-).
297     Values less than 1 and over 11 are clipped.
298     .br
299     Default is 1.
300 bertho 1.9
301     .TP
302     \fBparse_logs\fR \fIboolean\fR
303     Enable the parsing of the \fIentire\fR ,v file to read the log-entries between
304     revisions. This is necessary for the %l expansion to work, but slows down
305     parsing by a very large factor. You've been warned.
306     .br
307     Default is false.
308 bertho 1.13
309     .TP
310     \fBhtml_level\fR \fInumber\fR
311     Set the compliance to different types of HTML. The generated image map is
312     slightly different for version 3.x, 4.x and XHTML. You can use the predefined
313     identifiers (HTML3, HTML4 and XHTML) to set this value. Commandline option '\fB-x\fR'
314     overrides the setting.
315     .br
316     Default is HTML3 (3.x compatibility).
317 bertho 1.7
318     .TP
319     \fBbranch_ttfont\fR \fIstring\fR
320     .TP
321     \fBbranch_tag_ttfont\fR \fIstring\fR
322     .TP
323     \fBrev_ttfont\fR \fIstring\fR
324     .TP
325     \fBrev_text_ttfont\fR \fIstring\fR
326     .TP
327     \fBtag_ttfont\fR \fIstring\fR
328     .TP
329     \fBtitle_ttfont\fR \fIstring\fR
330     Set the truetype font face or filename for the individual elements. Gd's bitmap
331     fonts are used as a fallback if the font cannot be found or contains errors.
332     .br
333     Default none.
334    
335     .TP
336     \fBbranch_ttsize\fR \fIfloat\fR
337     .TP
338     \fBbranch_tag_ttsize\fR \fIfloat\fR
339     .TP
340     \fBrev_ttsize\fR \fIfloat\fR
341     .TP
342     \fBrev_text_ttsize\fR \fIfloat\fR
343     .TP
344     \fBtag_ttsize\fR \fIfloat\fR
345     .TP
346     \fBtitle_ttsize\fR \fIfloat\fR
347     Set the truetype font size for the individual elements. See also *_ttfont.
348     .br
349     Default 0.0.
350    
351     .TP
352 bertho 1.1 \fBtag_font\fR \fInumber\fR
353     The font used to draw tags in the revision boxes.
354     .br
355     Default is tiny.
356    
357     .TP
358     \fBtag_color\fR \fIcolor\fR
359     The color used to draw tags in the revision boxes.
360     .br
361     Default is black ("#000000").
362    
363     .TP
364     \fBrev_font\fR \fInumber\fR
365     .br
366     Default is tiny.
367    
368     .TP
369     \fBrev_color\fR \fIcolor\fR
370     The color of revision boxes, including the revision number.
371     .br
372     Default is black ("#000000").
373    
374     .TP
375     \fBrev_bgcolor\fR \fIcolor\fR
376     Revision box background color. This is the interior fill of the
377     box.
378     .br
379     Default is white ("#ffffff").
380    
381     .TP
382 bertho 1.7 \fBrev_separator\fR \fInumber\fR
383     Space between tags in revision boxes.
384 bertho 1.1 .br
385     Default is 0.
386    
387     .TP
388     \fBrev_minline\fR \fInumber\fR
389     The minimum vertical distance between revision boxes.
390     .br
391     Default is 0.
392    
393     .TP
394     \fBrev_maxline\fR \fInumber\fR
395     The maximum vertical distance between revision boxes.
396 bertho 1.7 This has only effect if \fBauto_stretch\fR is set to true (or option '\fB-k\fR'
397 bertho 1.6 is specified).
398 bertho 1.1 .br
399 bertho 1.6 Default is 5 times \fBrev_minline\fR.
400 bertho 1.1
401     .TP
402     \fBrev_lspace\fR \fInumber\fR
403     .TP
404     \fBrev_rspace\fR \fInumber\fR
405     .TP
406     \fBrev_tspace\fR \fInumber\fR
407     .TP
408     \fBrev_bspace\fR \fInumber\fR
409 bertho 1.6 Interior spacing in revision boxes of left, right, top and bottom
410 bertho 1.1 respectively. Note that the left right spacing is not used separately
411     because text is center aligned.
412     .br
413     Default is 0.
414    
415     .TP
416     \fBrev_text\fR \fIstring\fR
417     The additional text in a revision box under the revision number.
418     .br
419     Default is "%d".
420    
421     .TP
422     \fBrev_text_font\fR \fInumber\fR
423     The font of the additional text in a revision box under the revision number.
424     .br
425     Default is tiny.
426    
427     .TP
428     \fBrev_text_color\fR \fIcolor\fR
429 bertho 1.12 The font color of the additional text in a revision box under the revision
430     number.
431 bertho 1.1 .br
432     Default is black ("#000000").
433 bertho 1.12
434     .TP
435     \fBrev_maxtags\fR \fInumber\fR
436     Limit the number of tags in a revision box. Old trees tend to have some
437     revisions with extremely many tags attached, which would generate a huge
438     revision box when drawn. Limiting the number is a fair solution. Note that tag
439 bertho 1.14 sorting is not specified in the \fBrcsfile(7)\fR, but \fBcvs(1)\fR will
440     normally have the newest tags located before older ones. Therefore, limiting
441     the number of tags would most likely only affect older tags to be stripped.
442     However, no guarantees are given that a specific tag is present when the limit
443     is imposed. An ellispsis (...) is shown in the revision box when the number of
444     tags got truncated.
445 bertho 1.12 .br
446     Default is 0, meaning all tags shown.
447 bertho 1.14
448     .TP
449     \fBmerge_color\fR \fIcolor\fR
450     The color of the lines to show merges.
451     .br
452     Default is black ("#000000").
453    
454     .TP
455     \fBmerge_front\fR \fIboolean\fR
456     The mergelines are drawn on top of the image if true. Otherwise, mergelines
457     are drawn underneath.
458     .br
459     Default is false.
460    
461     .TP
462     \fBmerge_nocase\fR \fIboolean\fR
463     Ignore the case in regex matching.
464     .br
465     Default is false.
466    
467     .TP
468     \fBmerge_from\fR \fIstring\fR
469     The \fBmerge_from\fR is an extended regular expression as described in
470     \fBregex(7)\fR and POSIX 1003.2 (see also Single Unix Specification at
471     http://www.opengroup.com ). The matching tags describe source revisions of
472     merges. Each match is subsequently used in a search for the destination tag as
473     described by the \fBmerge_to\fR parameter.
474     .br
475     Note: normal string rules apply. Therefore, all backslashes '\\' must be
476     escaped, e.g. "\\." must be written as "\\\\.".
477     .br
478     Example: merge_from = "^from_(.*)";
479     .br
480     Default is empty (no matching occurs).
481    
482     .TP
483     \fBmerge_to\fR \fIstring\fR
484     .br
485     The \fBmerge_to\fR is an extended regular expression with a twist. All
486     subexpressions from the \fBmerge_from\fR are expanded into \fBmerge_to\fR using
487     %[1-9] (in contrast to \\[1-9] for backreferences). Care is taken to escape
488     the constructed expression. A '$' at the end of the \fBmerge_to\fR expression
489     can be important to prevent 'near match' references. Normally, you want the
490     destination to be a good representation of the source. However, this depends
491     on how well you defined the tags in the first place.
492     .br
493     Example: merge_to = "^merge_%1$";
494     .br
495     Above example, combined with the merge_from example would match a tag
496     "from_BugFix_2002" to the merge-destination with tag "merge_BugFix_2002".
497     .br
498     Default is empty (no matching occurs).
499 bertho 1.1
500     .TP
501     \fBbranch_font\fR \fInumber\fR
502 bertho 1.7 The font of the number in a branch box.
503     .br
504     Default is tiny.
505    
506     .TP
507     \fBbranch_tag_font\fR \fInumber\fR
508     The font of the tags in a branch box.
509 bertho 1.1 .br
510     Default is tiny.
511    
512     .TP
513     \fBbranch_color\fR \fIcolor\fR
514 bertho 1.7 All branch element's color excluding tags.
515     .br
516     Default is black ("#000000").
517    
518     .TP
519     \fBbranch_tag_color\fR \fIcolor\fR
520     All branch tags' color.
521 bertho 1.1 .br
522     Default is black ("#000000").
523    
524     .TP
525     \fBbranch_lspace\fR \fInumber\fR
526     .TP
527     \fBbranch_rspace\fR \fInumber\fR
528     .TP
529     \fBbranch_tspace\fR \fInumber\fR
530     .TP
531     \fBbranch_bspace\fR \fInumber\fR
532     Interior spacing of branch boxes.
533     .br
534     Default is 0.
535    
536     .TP
537     \fBbranch_margin\fR \fInumber\fR
538     Exterior spacing of branches. Each branch will be spaced
539     with a minimum of this value.
540     .br
541     Default is 0.
542    
543     .TP
544     \fBbranch_connect\fR \fInumber\fR
545     Length of the vertical connector from a revision to the branch box.
546     .br
547     Default is 0.
548 bertho 1.5
549     .TP
550 bertho 1.6 \fBbranch_dupbox\fR \fIboolean\fR
551     Add an extra branch box at the end of the trunk. Useful for upside down drawn
552     trees.
553 bertho 1.5 .br
554     Default is false.
555 bertho 1.1
556     .TP
557     \fBtitle\fR \fIstring\fR
558     The title of the image.
559     .br
560     Default is empty string.
561    
562     .TP
563     \fBtitle_x\fR \fInumber\fR
564     .TP
565     \fBtitle_y\fR \fInumber\fR
566     Postion of title.
567     .br
568     Default is 0.
569    
570     .TP
571     \fBtitle_font\fR \fInumber\fR
572     The font of the title.
573     .br
574     Default is tiny.
575    
576     .TP
577     \fBtitle_align\fR \fInumber\fR
578     Horizontal alignment of the title.
579     .br
580     Default is left.
581    
582     .TP
583     \fBtitle_color\fR \fIcolor\fR
584     The color of the title.
585     .br
586     Default is black ("#000000").
587    
588     .TP
589     \fBmargin_top\fR \fInumber\fR
590     .TP
591     \fBmargin_bottom\fR \fInumber\fR
592     .TP
593     \fBmargin_left\fR \fInumber\fR
594     .TP
595     \fBmargin_right\fR \fInumber\fR
596     Margins of the image. Note: the title position is not affected by
597     the margin.
598     .br
599     Default is 0.
600    
601     .TP
602     \fBimage_type\fR \fInumber\fR
603     Image types are available if they can be found in
604     the gd library. Newer versions of gd do not have
605     gif anymore. CvsGraph will automatically generate
606     png images instead.
607     .br
608     Default is dependent on availability and is prioritized in the order
609     png, gif and jpeg.
610    
611     .TP
612     \fBimage_quality\fR \fInumber\fR
613     The quality of a jpeg image (1..100)
614     .br
615     Default is 100.
616    
617     .TP
618     \fBmap_name\fR \fIstring\fR
619     The name= attribute in <map name="mapname">...</map> in the
620     generated HTML map.
621     .br
622     Default is "CvsGraphImageMap".
623    
624     .TP
625     \fBmap_branch_href\fR \fIstring\fR
626     .TP
627     \fBmap_rev_href\fR \fIstring\fR
628     .TP
629     \fBmap_diff_href\fR \fIstring\fR
630     These are the href= attributes in the <area>
631     tags of html.
632     .br
633 bertho 1.6 Default are:
634 bertho 1.1 .br
635     branch: "href=\\"unset: conf.map_branch_href\\""
636     .br
637     revision: "href=\\"unset: conf.map_rev_href\\""
638     .br
639     diff: "href=\\"unset: conf.map_diff_href\\""
640    
641     .TP
642     \fBmap_branch_alt\fR \fIstring\fR
643     .TP
644     \fBmap_rev_alt\fR \fIstring\fR
645     .TP
646     \fBmap_diff_alt\fR \fIstring\fR
647     These are the alt= attributes in the <area>
648     tags of html.
649     .br
650 bertho 1.6 Default are "alt=\\"%B\\"", "alt=\\"%R\\"" and
651     "alt=\\"%P &lt;\-&gt; %R\\"" respectively.
652 bertho 1.1
653     .SH "AUTHOR"
654     \fBCvsGraph\fR is written and maintained by B. Stultiens.
655     .br
656     Send comments and bugreports to \fIcvsgraph@akhphd.au.dk\fR and
657 bertho 1.3 visit the homepage at:
658     .br
659     \fIhttp://www.akhphd.au.dk/~bertho/cvsgraph\fR.
660 bertho 1.1 .SH "SEE ALSO"
661     .BR cvsgraph(1)

  ViewVC Help
Powered by ViewVC 1.1.0 with CvsGraph 1.7.0