[TAO htmls] Relative hrefs to ACE htmls dangling

[okellogg]

This is a low prio issue related to the TAO HTML documentation:

The following HREFs are not resolved due to the changed directory layout of the ACE_TAO git repo with respect to the ACE_wrappers source distro.

TAO/TAO-INSTALL.html

../ACE-INSTALL.html#platforms
../docs/usage-bugzilla.html
../MPC/docs/USAGE
../ACE/ACE-INSTALL.html#vxworks
../ACE-INSTALL.html#android
../ACE/ACE-INSTALL.html#vxworks
../ACE/ACE-INSTALL.html#VxWorks/NT
../bin/MakeProjectCreator/config/acedefaults.mpb
../ACE/ACE-INSTALL.html#resource_requirements
../MPC/docs/README
../ACE/ACE-INSTALL.html#MPC

TAO/docs/exceptions.html

../../docs/exceptions.html

TAO/docs/libraries.html

../../MPC/docs/README

TAO/docs/minimumTAO.html

../../ACE-INSTALL.html
../../ACE-INSTALL.html#flags

TAO/docs/Security/SSLIOP-INSTALL.html

../../../ACE-INSTALL.html#sslinstall
../../../ACE-INSTALL.html

I am not sure how to proceed because if this is fixed for git, it will be broken for ACE_wrappers.

[jwillemsen]

I would prefer to have links that work in the package, most users use those

[okellogg]

How is the ACE_wrappers release made? If it is made from the ACE_TAO git by using some script then we might be able to have them work in both:

• Fix the references in the ACE_TAO git using the script shown below
• Create the ACE_wrappers release workspace (presumably by some script)
• Run another script on the ACE_wrappers workspace fixing the hrefs for the changed dir layout

When running the below script on the current ACE_TAO git, it shows:

TAO/docs/releasenotes/ftrt_ec.html line 55 : dead href at ../../../bin/MakeProjectCreator/USAGE
TAO/docs/releasenotes/index.html line 722 : dead href at ../../../PDFs/ami1.pdf

Here is the script:

#!/bin/bash
#
# adapt-html-refs-to-acetao-git.sh
#
# Usage: cd to a clean ACE_TAO git workspace root dir and run.
#        Does not require command line arguments.

# For ACE, this is hard coded:
# The only references to TAO dirs are in ACE/ACE-INSTALL.html
#
perl -p -e 's@href="TAO/@href="../TAO/@g' -i ACE/ACE-INSTALL.html

# For TAO, we make it flexible because
# 1) references to ACE dirs are scattered among various html files
# 2) in TAO/TAO-INSTALL.html, some of the references to ACE dirs are
#    already adjusted to the ACE subdir of the git directory layout
#
origin=$PWD

for f in `find TAO -name "*.html" -exec grep -l 'href="\.\.\/' {} \;`
do
  export path=$(dirname $f)
  fileWithoutPath=$(basename $f)
  cd $path || break
  perl -n -e 'BEGIN { $fname = $ENV{path} . "/" . $ARGV[0];
                      my @dirs = $ENV{path} =~ /\//g;
                      $dirLevel = scalar(@dirs) + 1; }
              my $l = $_;
              chomp $l;
              if ($l =~ /^(.*href=")(\.\.\/[.\/]*)([^#"]+)(".*$)/) {
                my($prolog, $dotsAndSlashes, $file, $epilog) = ($1, $2, $3, $4);
                my @m = $dotsAndSlashes =~ /\//g;
                my $matches = scalar(@m);
                if ($matches >= $dirLevel and $file !~ /CIAO\//) {
                  my $pathWithFile = $dotsAndSlashes . $file;
                  if (-e "$pathWithFile") {
                    print "$l\n";
                  } else {
                    my $adaptedPathWithFile = $dotsAndSlashes . "ACE/$file";
                    if (-e "$adaptedPathWithFile") {
                      print "$prolog$adaptedPathWithFile$epilog\n";
                    } else {
                      warn("$fname line $. : dead href at $pathWithFile\n");
                      print "$l\n";
                    }
                  }
                } else {
                  print "$l\n";
                }
              } else {
                print $_;
              }' -i $fileWithoutPath
  cd $origin
done

The files modified by the script are:

ACE/ACE-INSTALL.html
TAO/TAO-INSTALL.html
TAO/docs/Security/SSLIOP-INSTALL.html
TAO/docs/exceptions.html
TAO/docs/libraries.html
TAO/docs/minimumTAO.html
TAO/docs/releasenotes/ftrt_ec.html

If you are interested, I can also provide the add-on script for the ACE_wrappers release creation.

[jwillemsen]

The release script is ACE/bin/make_release.py which creates the directory structure. I personally don’t like a post process step to modify files as part of the release.

[okellogg]

Looking at the ACE/bin/make_release.py script, I see that tagging of the release is also done there. I agree that changing files only in the release workspace (not in git) would be ugly as it introduces deviations from the tag.

Conversely, how about maintaining the ACE_TAO git directory structure in the ACE_wrappers release? This means that the top level ACE_wrappers directory would have the two subdirs ACE and TAO just like in git.

[okellogg]

Removing the "ACE_wrapper okay" remark from the title because as commented in the script,

# 2) in TAO/TAO-INSTALL.html, some of the references to ACE dirs are
#    already adjusted to the ACE subdir of the git directory layout

[mitza-oci]

the top level ACE_wrappers directory would have the two subdirs ACE and TAO

I'm not opposed to this, but with the top level named ACE_TAO (or something else) instead of ACE_wrappers.

[jwillemsen]

Do we need a top level in case of a package? We could create a zip with just ACE (for plain ACE package) or ACE and TAO for a combined package. We could then put MPC also in the root so that when extracted, ACE/TAO/MPC are at the same level, in case the user has CIAO and DAnCE they are all at the same level

[mitza-oci]

By convention "tar xzf pkg-ver.tar.gz" creates a directory "pkg" or "pkg-ver" instead of populating the current directory with other files which may not be expected.

I'm not sold on the overall tradeoff here. Lots of downstream build and packaging scripts may have to change for this.

[jwillemsen]

Ok, we could have a root, but yes, this will impact all users and needs changes to package scripts and also packaging at obs, ubunte, and probably more places, it will highly impact things. Probably we should just keep the packages as is, I think it was discussed a long time ago within devogroup also, decided similar at that moment.

[okellogg]

About the impacts downstream, I see your point. I guess the bottom line would be:

1. Leave ACE_wrappers structure as is
2. Adjust relative hrefs in the HTML docs to the ACE_wrappers layout

The consequence of going this route is, people editing the HTML docs should always create the ACE_wrappers layout to test that their hrefs are resolved (they can't do that in the git layout).

[okellogg]

Is there consensus on my previous comment ? If so then there are only two dead links: They are hrefs to TAO/TAO-INSTALL.html on lines 178 and 1835 in ACE/ACE-INSTALL.html,

    178       and the <a href="../TAO/TAO-INSTALL.html">TAO install document</a></td>
   1835     href="../TAO/TAO-INSTALL.html">cross compilation setup instructions provide

Obeying the ACE_wrappers directory layout, they should be

href="TAO/TAO-INSTALL.html"

I offer to make a pull request fixing this.

@iguessthislldo : This would revert a hunk of your commit f50935c,

[...], and any changes to fix broken html revealed by that style change.