all-in-one docs?

How difficult would it be to copy and merge all of the doxygen docs into a single module? Right now they are organized my module:
* FoundationClasses
* ModelingData
* ModelingAlgorithms
* ...

When looking for documentation on a class, I find my self opening a module, clicking on class hierarchy and searching for the class name. If I picked the wrong module, I have to navigate to a different one and start over.

I understand the value of having them grouped like this, especially for browsing. But there are times when I just want an easy way to jump to the docs for a specific class.

The CDL browser at http://download.sonnensturm.net/OpenCascadeDocumentation-6.1/frames.html is good for this, but it's out of date.

Thanks,
Cory

Roman Lygin's picture

Hi Cory,

I believe current classification per module is helpful as it reflects OCC own structure. What is missing is a global class and function index that would lead to a class list. This is done in Qt for example - http://doc.trolltech.com/4.4/classes.html. Its title bar also shows global index and module list for either access.

Imho, the OCC team just needs to slightly polish Doxygen configuration file to enable this. Another annoying thing for me was Standard_EXPORT before each method. Doxygen allows to define it to empty.

My 2 cents ...
Roman

---
opencascade.blogspot.com - blog on Open CASCADE

Rob Bachrach's picture

I have updated versions of these files on my local system. If someone can update these on the site, I would be happy to send a ZIP file. Unfortunately, my company firewall blocks this site.

Rob

Jun WANG's picture

can it be downloaded ???

Rob Bachrach's picture

Sorry, I have no public web space. I am including the Perl script I use to generate the files (note that the forum will probably remove the line indentations). Just copy all the CDL files to a directory and run the perl script from within that same directory. It will generate an HTML file for each CDL and the frames.html file that you load into your browser. If anyone wants to donate the web space, I would be happy to send a ZIP file for posting.

Rob

######################## Perl Script ##############################
my @cdl_files;

sub WriteFrameset {
open(FRAMESET, ">frames.html");
print FRAMESET <

END_OF_HEADER
close(FRAMESET);
}

sub WriteIndex {
# list patterns to be omitted from the index
my @index_files;
foreach $cdl_file (@cdl_files) {
next if ($cdl_file =~ /^draw/i);
next if ($cdl_file =~ /^Plugin$/);
next if ($cdl_file =~ /^swdraw/i);
next if ($cdl_file =~ /^testtopope/i);
next if ($cdl_file =~ /^xdedraw/i);
next if ($cdl_file =~ /^xsdraw/i);
next if ($cdl_file =~ /^wok/i);
next if ($cdl_file =~ /^test[_.]/i);
push(@index_files, $cdl_file);
}
print "CDL files: " . ($#cdl_files+1) . "\n";
print "Index files: " . ($#index_files+1) . "\n";

open(INDEX, ">index.html");
print INDEX <
CDL File Index

CDL File Index

function init() {
var files = [
END_OF_HEADER

my $i;
my $class;
for ($i = 0; $i < $#index_files; $i++) {
$class = $index_files[$i];
$class =~ s/\.cdl$//;
print INDEX "\"$class\",";
}
$class = $index_files[$#index_files];
$class =~ s/\.cdl$//;
print INDEX "\"$class\"";

print INDEX <" + files[i] + "\\n");
}
}
}
else {
for (var i=0; i" + files[i] + "\\n");
}
}
}
init();

END_OF_FOOTER

close(INDEX);
}
my $firstitem = 1;
sub LinkFrom {
my ($item, $from, $package) = @_;
if ($package eq "class") {
return "$item$from$package";
}

my $cdl = "${package}_${item}.cdl";
my $found = 0;
my $myfile;
foreach $myfile (@cdl_files) {
if ("$myfile" eq "$cdl") {
$found = 1;
last;
}
}

if ($found) {
return "$item$from$package";
}
else {
return "$item$from$package";
}
}

sub Convert {
my ($cdl_file) = @_;
my $html_file = $cdl_file;
$html_file =~ s/\.cdl$/.html/;

open(HTML, ">$html_file");

print HTML <
$cdl_file

CDL File Index

END_OF_HEADER

  open(CDL, "<$cdl_file");
  while () {
    s/>/\>/g;
    s/$_";
    }
    else {
      s/(\w+)(\s+from\s+)(\w+)/LinkFrom($1,$2,$3)/eg;
    }
    print HTML "$_";
  }
  close(CDL);

  print HTML <


END_OF_FOOTER

  close(HTML);
}

# open the current directory and read all the CDL files
print "Building file list...\n";
opendir(DIR, ".");
@cdl_files = grep(/\.cdl$/, readdir(DIR));
closedir(DIR);

# generate the frames file
print "Generating frame set (frames.html)...\n";
WriteFrameset();

# write the index file
print "Generating file index (index.html)...\n";
WriteIndex(@cdl_files);

# convert the CDL files to HTML
foreach $cdl_file (@cdl_files) {
  print "Converting: $cdl_file...\n";
  Convert($cdl_file);
}

print "Done\n";
Fernando Ghedin's picture

Hi folks,

I'm not sure if this is the best way to do it, but I used the following command line to get all the CDL files into a single directory:

$ cd $CASROOT; mkdir cdl_docu; cd $CASROOT/src; for u in `find -iname *.cdl`; do cp -v $u $CASROOT/cdl_docu ; done;

* Please note: I assume you have the environment variable $CASROOT properly defined to your OpenCASCADE's root directory.

You will get all the CDL Files into the directory `$CASROOT/cdl_docu'. Then, copy the PERL script to that same directory and just call it. The result is pretty helpful! Thanks for sharing it Rob ;-)

By the way, it would be great if someone could host the file somewhere on the web. I had troubles with the Copy/Pasting. Here goes some hints:
1) At the end of the two `document.write' statements, the "\n" caused a new line when I pasted it in my text-editor, so it toked some time to find out what was happening.
2) There was a syntax error on the line 131, that can be fixed like this:

== copy/pasted code ==
s/>/\>/g;
s/ if (/^\s*--/) {
$_ = "$_";
}

== fixed code ========
s/>/\>/g;
s/$_";
}

I hope it can help everyone else interested in Rob's script.

Best regards,
Fernando

Fernando Ghedin's picture

Hi again,

Unfortunately my "fixed code" is not shown properly on the Forum. BUT, if you click on REPLY on this topic, you will get it right! (it is displayed properly when you reach the text-field for writing your answer)

Kind regards,
Fernando

Rob Bachrach's picture

I have created a uuencoded version of the file. It was created on the PC, so you may have to mess with line endings after decoding it. Hopefully, this helps with copy/paste problems.

Rob

begin 644 GenerateHTML.pl
M;7D@0&-D;%]F:6QE`H@(&UY($!I;F1E>%]F:6QEPH@("`@;F5X="!I9B`H)&-D
M;%]F:6QE(#U^("]>9')A=R]I*3L*("`@(&YE>'0@:68@*"1C9&Q?9FEL92`]
M?B`O7E!L=6=I;B0O*3L*("`@(&YE>'0@:68@*"1C9&Q?9FEL92`]?B`O7G-W
M9')A=R]I*3L*("`@(&YE>'0@:68@*"1C9&Q?9FEL92`]?B`O7G1E>'-D=V]K+VDI.PH@("`@;F5X="!I9B`H
M)&-D;%]F:6QE(#U^("]>=&5S=%M?+ETO:2D["B`@("!P=7-H*$!I;F1E>%]F
M:6QE2!B9V-O
M;&]R/6)L86-K('1E>'0]>65L;&]W(&QI;FL]8WEA;B!V;&EN:SUC>6%N(&%L
M:6YK/6-Y86X^"CQH,2!S='EL93TB9F]N="US:7IE.B`Q."(^0T1,($9I;&4@
M26YD97@\+V@Q/@H\9F]R;2!N86UE/2)S96%R8VA?9F]R;2(@=&%R9V5T/2)I
M;F1E>"(^"CQI;G!U="!T>7!E/2)T97AT(B!N86UE/2)F:6QT97(B('-I>F4]
M(C$X(CX*/&EN<'5T('1Y<&4](G-U8FUI="(@=F%L=64](E-E87)C:"(^"CPO
M9F]R;3X*/'-C%]F:6QEPH@("`@("!I9B`HPH@("`@9F]R("AV87(@:3TP.R!I/&9I;&5S+FQE
M;F=T:#L@:2LK*2!["B`@("`@(&1O8W5M96YT+G=R:71E*"(\82!HPH@(&UY("@D:71E;2P@
M)&9R;VTL("1P86-K86=E*2`]($!?.PH@(&EF("@D<&%C:V%G92!E<2`B8VQA
M2`D8V1L(#T@(B1[<&%C:V%G97U?)'MI=&5M?2YC9&PB.PH@(&UY("1F
M;W5N9"`](#`["B`@;7D@)&UY9FEL93L*("!F;W)E86-H("1M>69I;&4@*$!C
M9&Q?9FEL97,I('L*("`@(&EF("@B)&UY9FEL92(@97$@(B1C9&PB*2!["B`@
M("`@("1F;W5N9"`](#$["B`@("`@(&QAPH@("`@2`H)&-D;%]F:6QE*2`]($!?
M.PH@(&UY("1H=&UL7V9I;&4@/2`D8V1L7V9I;&4["B`@)&AT;6Q?9FEL92`]
M?B!S+UPN8V1L)"\N:'1M;"\["@H@(&]P96XH2%1-3"P@(CXD:'1M;%]F:6QE
M(BD["@H@('!R:6YT($A434P@/#Q%3D1?3T9?2$5!1$52.PH\:'1M;#X*/&AE
M860^/'1I=&QE/B1C9&Q?9FEL93PO=&ET;&4^/"]H96%D/@H\8F]D>2!B9V-O
M;&]R/6)L86-K('1E>'0]>65L;&]W(&QI;FL]8WEA;B!V;&EN:SUC>6%N(&%L
M:6YK/6-Y86X^"CQP/CQA(&AR968](FEN9&5X+FAT;6PB/D-$3"!&:6QE($EN
M9&5X/"]A/CPO<#X*/'!R93X*14Y$7T]&7TA%041%4@H*("!O<&5N*$-$3"P@
M(CPD8V1L7V9I;&4B*3L*("!W:&EL92`H/$-$3#XI('L*("`@(',O/B]<)F=T
M.R]G.PH@("`@PH@("`@("!S+RA<=RLI*%QS*V9R;VU<"`H:6YD97@N:'1M;"DN+BY<;B(["E=R:71E
M26YD97@H0&-D;%]F:6QE

Jun WANG's picture

By the way, for your requirements, "SourceInsight" should be an good option. It really works perfectly.

Kazumasa Uno's picture

I also feel hard to explore the documents and sources.
So I created a simple tool to list up the files.

http://www.fisco21.com/img/OCC/unokaOcc.exe

After execution, Input the OCC install path and editor you usally use.
Select the category, and input the first part of filenames ( such as gp, GeomAP or put it empty),
and push the find button.
The double click of item will launch the editor.
At first search, it takes lengthy times but second execution will be very fast.