[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-kdoc
Subject:    Multiple index file directories, relative paths... (almost patch)
From:       Marcin Kasperski <Marcin.Kasperski () softax ! com ! pl>
Date:       1999-04-13 8:51:02
[Download RAW message or body]

I modified kdoc slightly to:
- be able to keep blahblah.kdoc files together with documentation they
describe and making kdoc capable to search multiple library directories
- use relative links for referencing other libraries
I'm not sure which of those changes are worth putting into main tree,
but I present them and discuss below

All changes below were made on kdocLib.pm. 

I made kdoc to understand libpath of the form
some/path:another/path:just/another/path (can be specifed as an option
and as environment variable):

a) I modified seriously the readLibrary method:

On the beginning, instead of 
	my $real = $path."/".$name.".kdoc";

I have

        my $real;
        # TODO: real_directory should specify the path from $outdir to
the directory 
	# in which kdoc is run. The ../../ below works for me because I always
	# generate doc in GENDOC/html subdirectory
        my $real_directory = "../../";
        foreach $candidate_dir (split(':', $path)) {
          my $candidate_file = $candidate_dir . "/" . $name . ".kdoc";
          if (-f $candidate_file) {
            $real = $candidate_file;
	    # TODO: if $candidate_dir is full path, I should just set
$real_directory to it
	    # (or to its base url)
            $real_directory .= $candidate_dir;
            last;
          }
        }
        unless(defined($real)) {
          die "Can't find library $name in library path $path\n";
        }

Discussion: I split libpath into list of directories and search them for
the library $name. When I found, I set $real to its name (it will be
open further in subroutine). 
I also prepare $real_directory (maybe it should be called
$real_url_prefix) so that I know later where I found my current library
(I expect this library headers to be placed in the same place as the
library describing them). My main wish is to emit relative URL's of the
form "../../../other_lib/GENDOC/html/CSomeOtherClass.html" instead of
just hard specified URL's (I want the doc to be readable from both some
WWW server and locally). At this point I want $real_directory to be
relative path from current $output_dir to the directory with HTML's of
just parsed library. I think, it should be done wiser (for instance by
just calculating full paths of both directories and then calculating
shortest relative path). But now I'm in a hurry.

Further on, I changed the code emitting references:

from
			$new->AddProp( "Ref", $url.$2 );
to
                        $new->AddProp( "Ref", $real_directory . "/" . $2
);

and from
			$new->AddProp( "Ref", $url.$3 );
to
                        $new->AddProp( "Ref", $real_directory . "/" . $3
);


Finally, although the patch above caused me to ignore BASE URL from kdoc
libraries, I decided that it should not look really stupid (some path
with colons), so I changed it to contain just first element from $libdir
- I modified writeDoc subroutine by changing:

from
	$url = $docpath unless defined $url;
to
        unless(defined($url)) {
          $url = $docpath;
          $url =~ s/:.*//g;
        }

Now a short piece of discussion about relative paths, base URL etc:

In my opinion, HTML documents should employ relative links whenever
possible - then the documentation can be (for instance) easily copied to
local disk and browsed offline. So I made the changes described above.
But my assumption that blahblah.kdoc lies in the same directory as
HTML's for the blahblah library can be disliked by some people. So I
think it would be best to:
- store inside blahblah.kdoc information "where the HTML's documenting
blahblah can be found" - but allowing two methods: normal URL link which
would be kept as-is (as BASE URL in the original kdoc 2.0) or just
relative or full path to doc directory (relative: from library file to
described doc dir)
- modify readLibrary so it would keep links in the first case and modify
them in my method in the second case

Regards.


-- Marcin Kasperski     Marcin.Kasperski<at>softax.com.pl
--                      marckasp<at>friko6.onet.pl
-- Moje poglądy są moimi poglądami, nikogo poza mną nie reprezentują.
-- (My opinions are just my opinions.)

[prev in list] [next in list] [prev in thread] [next in thread]