1#!/usr/bin/env perl
2# Time-stamp: <2006-11-15 13:25:02 barre>
3#
4# Extract VTK version and add it to documentation
5#
6# barre : Sebastien Barre <sebastien@barre.nom.fr>
7#
8# 0.3 (barre) :
9#   - update to search for the version infos in a different file
10#     (i.e. top CMakeLists.txt file instead of vtkVersion.h)
11#   - --header becomes --revision_file and --version_file
12#
13# 0.25 (barre) :
14#   - update useful links for Dart
15#
16# 0.24 (barre) :
17#   - update useful links for new public.kitware.com structure
18#
19# 0.23 (barre) :
20#   - update useful links
21#
22# 0.22 (barre) :
23#   - add more (useful) links to various VTK documentation resources
24#
25# 0.21 (barre) :
26#   - no more --logo defaults
27#
28# 0.2 (barre) :
29#   - update to match the new VTK 4.0 tree
30#   - change default --header so that it can be launched from Utilities/Doxygen
31#   - change default --to so that it can be launched from Utilities/Doxygen
32#   - add --logo file : use 'file' as logo
33#
34# 0.16 (barre) :
35#   - change default --to to '../vtk-doxygen' to comply with Kitware
36#   - update VTK home page URL.
37#
38# 0.15 (barre) :
39#   - fix RCS/CVS tags problem (regexp replacement when this file is in a CVS)
40#
41# 0.14 (barre) :
42#   - as doxygen now handles RCS/CVS tags of the form $word:text$, use them
43#
44# 0.13 (barre) :
45#   - change doxygen command style from \ to @ to match javadoc, autodoc, etc.
46#
47# 0.12 (barre) :
48#   - change default --to to '../vtk-dox'
49#
50# 0.11 (barre)
51#   - fix O_TEXT flag problem
52#   - switch to Unix CR/LF format
53#
54# 0.1 (barre)
55#   - initial release
56
57use Carp;
58use Fcntl;
59use File::Basename;
60use Getopt::Long;
61use strict;
62
63my ($VERSION, $PROGNAME, $AUTHOR) = (0.3, $0, "Sebastien Barre");
64$PROGNAME =~ s/^.*[\\\/]//;
65print "$PROGNAME $VERSION, by $AUTHOR\n";
66
67# -------------------------------------------------------------------------
68# Defaults (add options as you want: "verbose" => 1 for default verbose mode)
69
70my %default =
71  (
72   version_file => "../../CMake/vtkVersion.cmake",
73   store => "doc_VTK_version.dox",
74   to => "../../../VTK-doxygen"
75  );
76
77# -------------------------------------------------------------------------
78# Parse options
79
80my %args;
81Getopt::Long::Configure("bundling");
82GetOptions (\%args, "help", "version_file=s", "logo=s", "store=s", "to=s");
83
84if (exists $args{"help"}) {
85    print <<"EOT";
86by $AUTHOR
87Usage : $PROGNAME [--help] [--version_file file] [--store file] [--to path]
88  --help        : this message
89  --version_file file : use 'file' to find version info (default: $default{version_file})
90  --logo file   : use 'file' as logo (default: $default{logo})
91  --store file  : use 'file' to store version (default: $default{store})
92  --to path     : use 'path' as destination directory (default: $default{to})
93
94Example:
95  $PROGNAME
96EOT
97    exit;
98}
99
100$args{"version_file"} = $default{"version_file"} if ! exists $args{"version_file"};
101$args{"logo"} = $default{"logo"} if ! exists $args{"logo"};
102$args{"store"} = $default{"store"} if ! exists $args{"store"};
103$args{"to"} = $default{"to"} if ! exists $args{"to"};
104$args{"to"} =~ s/[\\\/]*$// if exists $args{"to"};
105
106my $os_is_win = ($^O =~ m/(MSWin32|Cygwin)/i);
107my $open_file_as_text = $os_is_win ? O_TEXT : 0;
108my $start_time = time();
109
110# -------------------------------------------------------------------------
111# Try to get VTK version
112
113my ($major_version, $minor_version, $build_version) = (undef, undef, undef);
114
115sysopen(FILE, $args{"version_file"}, O_RDONLY|$open_file_as_text)
116  or croak "$PROGNAME: unable to open $args{version_file}\n";
117
118while (<FILE>) {
119    if ($_ =~ /VTK_MAJOR_VERSION\s+(\d+)/) {
120        $major_version = $1;
121        print " major => $major_version\n";
122    } elsif ($_ =~ /VTK_MINOR_VERSION\s+(\d+)/) {
123        $minor_version = $1;
124        print " minor => $minor_version\n";
125    } elsif ($_ =~ /VTK_BUILD_VERSION\s+(\d+)/) {
126        $build_version = $1;
127        print " build => $build_version\n";
128    }
129}
130
131close(FILE);
132
133croak "$PROGNAME: unable to find version in " . $args{"version_file"} . "\n"
134  if (!defined $major_version || !defined $minor_version || !defined $build_version);
135
136# -------------------------------------------------------------------------
137# Build documentation
138
139my $destination_file = $args{"to"} . "/" . $args{"store"};
140print "Building version documentation to ", $destination_file, "\n";
141
142sysopen(DEST_FILE,
143        $destination_file,
144        O_WRONLY|O_TRUNC|O_CREAT|$open_file_as_text)
145  or croak "$PROGNAME: unable to open destination file " . $destination_file . "\n";
146
147print DEST_FILE
148  "/*! \@mainpage VTK $major_version.$minor_version.$build_version Documentation\n\n";
149
150print DEST_FILE
151  "  \@image html " . basename($args{"logo"}) . "\n"
152  if exists $args{"logo"} && -f $args{"logo"};
153
154print DEST_FILE
155  "  \@par VTK:\n",
156  "   VTK is an open-source software system for image processing, 3D \n",
157  "   graphics, volume rendering and visualization. VTK includes many \n",
158  "   advanced algorithms (e.g., surface reconstruction, implicit modelling, \n",
159  "   decimation) and rendering techniques (e.g., hardware-accelerated \n",
160  "   volume rendering, LOD control).\n",
161  "   \@par \n",
162  "   VTK is used by academicians for teaching and research; by government \n",
163  "   research institutions such as Los Alamos National Lab in the US or \n",
164  "   CINECA in Italy; and by many commercial firms who use VTK to build or \n",
165  "   extend products. \n",
166  "   \@par \n",
167  "   The origin of VTK is with the textbook \"The Visualization Toolkit, an \n",
168  "   Object-Oriented Approach to 3D Graphics\" originally published by \n",
169  "   Prentice Hall and now published by Kitware, Inc. (Third Edition ISBN \n",
170  "   1-930934-07-6). VTK has grown (since its initial release in 1994) to a \n",
171  "   world-wide user base in the commercial, academic, and research \n",
172  "   communities. \n",
173  "   A more recent PDF version of the textbook is available from the link below.\n",
174  "   \@par \n",
175  "   There is now a large collection of VTK Examples that showcase VTK features.\n",
176  "   This is also a useful learning resource. See the link below.\n",
177  "  \@par Useful links:\n",
178  "  \@li VTK Home: https://vtk.org/\n",
179  "  \@li VTK Source: https://gitlab.kitware.com/vtk/vtk\n",
180  "  \@li VTK Discourse Forum: https://discourse.vtk.org\n",
181  "  \@li VTK FAQ: https://www.vtk.org/Wiki/VTK_FAQ\n",
182  "  \@li VTK Wiki: https://www.vtk.org/Wiki/\n",
183  "  \@li VTK Textbook: https://gitlab.kitware.com/vtk/textbook/raw/master/VTKBook/VTKTextBook.pdf\n",
184  "  \@li VTK Examples: https://kitware.github.io/vtk-examples/site/\n",
185  "  \@li VTK Dashboard: https://open.cdash.org/index.php?project=VTK\n",
186  "  \@li Commercial <a href=\"https://www.kitware.com/products/support.html\">support</a> ",
187  "  and <a href=\"https://www.kitware.com/products/protraining.php\">training</a> ",
188  "  are available from Kitware\n",
189  " ",
190  "*/\n\n";
191
192close(DEST_FILE);
193
194print "Finished in ", time() - $start_time, " s.\n";
195