From owner-freebsd-doc  Tue Sep  5 16:25:57 2000
Delivered-To: freebsd-doc@freebsd.org
Received: from mta06-svc.ntlworld.com (mta06-svc.ntlworld.com [62.253.162.46])
	by hub.freebsd.org (Postfix) with ESMTP id 9577337B422
	for <doc@freebsd.org>; Tue,  5 Sep 2000 16:25:44 -0700 (PDT)
Received: from parish.my.domain ([62.253.88.155]) by mta06-svc.ntlworld.com
          (InterMail vM.4.01.02.27 201-229-119-110) with ESMTP
          id <20000905232541.EGJI312.mta06-svc.ntlworld.com@parish.my.domain>;
          Wed, 6 Sep 2000 00:25:41 +0100
Received: (from mark@localhost)
	by parish.my.domain (8.9.3/8.9.3) id AAA06781;
	Wed, 6 Sep 2000 00:25:41 +0100 (BST)
	(envelope-from mark)
Date: Wed, 6 Sep 2000 00:25:40 +0100
From: Mark Ovens <marko@freebsd.org>
To: doc@freebsd.org
Cc: Andrew Boothman <andrew@dogma.freebsd-uk.eu.org>
Subject: Ports Documentation Index - the next installment
Message-ID: <20000906002540.M254@parish>
Mime-Version: 1.0
Content-Type: multipart/mixed; boundary="tKW2IUtsqtDRztdT"
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
User-Agent: Mutt/1.2.5i
Organization: Total lack of
Sender: owner-freebsd-doc@FreeBSD.ORG
Precedence: bulk
X-Loop: FreeBSD.org


--tKW2IUtsqtDRztdT
Content-Type: text/plain; charset=iso-8859-1
Content-Disposition: inline
Content-Transfer-Encoding: 8bit

I've been doing some work on the perl(1) scripts that Andrew Boothman
started sometime ago that create /var/db/pkg/${PORTNAME}/+DOCS for
each installed port and then build an HTML file containing links to
all the installed docs.

The changes I've made are:

    1. Improved the weeding out of non-doc files (it uses the
       +CONTENTS file).

    2. The HTML file now has the ports sorted alphabetically.

    3. The HTML file now has an index of all the installed
       ports (that have docs) at the top with the port name as a link
       (followed by the contents of the +COMMENT file) to the list of
       docs, which have a link back to the top.

    4. The filename is displayed instead of "Title Unknown" for
       non-HTML files (although HTML files that have no
       <title></title> tag are still listed as "Title Unknown").

I've attached 3 files:

     docsmaker   - builds the +DOCS files.
     docindex.pl - builds the HTML page from the +DOCS files.
     mkindex.sh  - A wrapper script to run the other 2 files.

Put them all in the same directory and run mkindex.sh from that
directory (the other 2 files are called as ./<filename>).

The resulting HTML file is /usr/local/share/doc/index.html

I'd appreciate people trying this out on their system (it works fine
with all the ports I have installed on mine) and giving feedback,
suggestions for further features/improvements, any examples of ports
that it doesn't work with, etc.

CAVEATS:
	It may or may not included the standard FreeBSD docs
	(Handbook, FAQ, etc.) in the HTML file depending on where they
	are installed on your system.

	I'm just a beginner at perl, so not too many flames about the
	code, eh? (Hot Tips and friendly advice accepted :))

	There are still some debugging print() statements that
	spew out a lot of stuff to STDOUT when docsmaker runs.

-- 
		4.4 - The number of the Beastie
________________________________________________________________
51.44°N  FreeBSD - The Power To Serve http://www.freebsd.org
2.057°W  My Webpage http://ukug.uk.freebsd.org/~mark
mailto:marko@freebsd.org                http://www.radan.com


--tKW2IUtsqtDRztdT
Content-Type: text/plain; charset=us-ascii
Content-Description: docsmaker - perl(1) script
Content-Disposition: attachment; filename=docsmaker

#!/usr/bin/perl -w

# Produces a DOCS file for a port

# These 2DOCS files are used by a seperate script
# to generate an list of documentation installed
# by the ports/packages system

# See http://ukug.uk.FreeBSD.org/~andrew/docindex/

# By Andrew Boothman <andrew@cream.org>

# Modified by Mark Ovens <marko@freebsd.org>



# Check we have the correct number of arguments
if ($#ARGV < 1) {
	print 'Usage : docsmaker /path/to/+CONTENTS/file ';
	print '/path/to/new/+DOCS/file';
	print "\n\n";
} else {

# Open the +CONTENTS file

    open 'CONTENTS',$ARGV[0] or die "cannot open $ARGV[0]";

    open 'DOCS',">$ARGV[1]" or die "cannot open $ARGV[1]";

    @contents = <CONTENTS>;

    chomp @contents;

    close 'CONTENTS';

    $doccounter = 0;

    foreach(@contents) {
	if (substr($_, 0, 4) eq '@cwd') {
	    $basepath = substr($_, , 5);
	    print "Base Path now : $basepath\n";
	} elsif (substr($_, 0, 5) eq '@name') {
	    print 'Port Name : '.substr($_, , 6)."\n";
	} elsif (substr($_, 0, 1) eq '@') {
	    next;
	} else {
	    $filetype = isadoc("$basepath/$_");
	    if ($filetype eq "") {
		next;
	    } # if ($filetype eq "")

	    if ($filetype eq "html") {
		$doccounter++;
		print "$basepath/$_...HTML...";
		open 'HTMLDOC',"$basepath/$_" or die
		                               "Cannot open $basepath/$_";
		$title = '';
		until (eof 'HTMLDOC' || $title ne '') {
		    chomp ($htmlline = <HTMLDOC>);

		    if ($htmlline =~ /<TITLE/i) {
			print "Titled...";
			$index = index(lc($htmlline), "<title");
			    
			while ($htmlline !~ /<\/TITLE/i) {
			    chomp($scrap = <HTMLDOC>);
			    $htmlline = "$htmlline"."$scrap";
			} # while

			$c = substr($htmlline, $index + 7);
			$index = index(lc($c), "</title");
			$title = substr($c, 0, $index);

			if ($title =~ s/:/-/ > 0) {
			    print "':' -> '-'...";
			} # if ($title =~ s/:/-/ > 0)

		    } # if ($htmlline =~ /<TITLE/i)

		} # until (eof 'HTMLDOC' || $title ne '')

		if ($title eq '') {
		    print "Titling failed...";
		    $title = "Title Unknown";
		} # if ($title eq '')

		close 'HTMLDOC';
		print DOCS  "$title:HTML:$basepath/$_\n";
		print "Done!\n";

	    } else { # if ($filetype eq "html")
		$doccounter++;
		print("basepath \= $basepath\n");
		($temp = $_) =~ s#.*/##;
		print (DOCS "$temp:".uc($filetype).":$basepath/$_\n");
	    } # else

	} # else

    } # foreach(@contents)

    close 'DOCS';
    print "\nDocuments put in DOCS file : $doccounter\n\n";

    if ($doccounter == 0) {
	print 'Removing unused new +DOCS file...';
	unlink $ARGV[1];
	print "Done!\n";
    } # if ($doccounter == 0)

} # MAIN

sub isadoc {

    local $_;
			# Need the ``?'' with "html" so we get both
			# *.html and *.htm
    @docs = ("txt", "html?", "ps", "pdf", "texi");

    @not_docs = ("bmp", "icon", "gif", "jpg", "xbm", "xpm");

    foreach (@not_docs) {
	if ($_[0] =~ /\.$_\Z/i) {
	    return "";
	}
    }

    foreach (@docs) {
	if ($_[0] =~ /\.$_\Z/i) {
	    s/\?$//;    # strip the ``?'' from "html?"
	    return $_;
	}
    }
}

--tKW2IUtsqtDRztdT
Content-Type: application/x-perl
Content-Description: docindex.pl - perl(1) script
Content-Disposition: attachment; filename="docindex.pl"

#!/usr/bin/perl

# Produces an HTML list of documentation installed by
# the FreeBSD ports system. Intended to be run daily
# from /var/periodic/daily or on startup by rc

# See http://ukug.uk.FreeBSD.org/~andrew/docindex/

# By Andrew Boothman <andrew@cream.org>

# Modified by Mark Ovens <marko@freebsd.org>

# If any documentation has been altered since we last made the index
# then build it again, else don't bother

if (-M '/var/db/pkg' < -M '/usr/local/share/doc/index.html' | -M '/usr/share/doc/en_US.ISO_8859-1/books/handbook/index.html' < -M '/usr/local/share/doc/index.html' | -M '/usr/share/doc/en_US.ISO_8859-1/books/faq/book.html' < -M '/usr/local/share/doc/index.html') {

	open INDEXFILE, '>/usr/local/share/doc/index.html';
	opendir PORTSDIR, '/var/db/pkg' or die "docindex: Can't open /var/db/pkg";

	@allfiles = sort(readdir (PORTSDIR));

	closedir 'PORTSDIR';

	print INDEXFILE '<HTML>
<HEAD>
<A NAME=top></A>
<TITLE>Installed FreeBSD Documentation</TITLE>
</HEAD>
<BODY>
<H2>Installed FreeBSD Documentation</H2>
<HR>
<H4>Standard FreeBSD Documentation</H4>
<UL>';

# if (-e '/usr/share/doc/handbook/handbook.html') {
if (-e '/usr/share/doc/en_US.ISO_8859-1/books/handbook/index.html') {
	print INDEXFILE '<LI>FreeBSD Handbook [<A HREF="/usr/share/doc/en_US.ISO_8859-1/books/handbook/index.html">html</A>]';
};

# if (-e '/usr/share/doc/FAQ/FAQ.html') {
if (-e '/usr/share/doc/en_US.ISO_8859-1/books/faq/book.html') {
	print INDEXFILE '<LI>FreeBSD FAQ [<A HREF="/usr/share/doc/en_US.ISO_8859-1/books/faq/book.html">html</A>]';
};

print INDEXFILE '</UL><H4>Installed Documentation from Ports or Packages</H4><UL>';

	$i = 0;
	$j = 0;

	foreach(@allfiles){
		# Check if each of the files we've found is a directory
		# with the +DOCS file in it
		if (-e "/var/db/pkg/$_/+DOCS") {
		    $comment = "";
		    if (-e "/var/db/pkg/$_/+COMMENT") {
			open COMFILE, "/var/db/pkg/$_/+COMMENT";
			$comment = <COMFILE>;
			close COMFILE;
		    }

		    $index[$i++] = "<LI><A HREF=#$_>$_</A> - $comment\n";
		    $list[$j++] = "<H2><A NAME\=$_>$_\n</A></H2><UL>";
		    open 'DOCS',"/var/db/pkg/$_/+DOCS";
		    @docs = <DOCS>;
		    close 'DOCS';
		    chomp @docs;
		    foreach(@docs) {
			@docinfo = split(/:/);
			$list[$j++] = "<LI><A HREF=\"$docinfo[2]\">
					$docinfo[0]</A> - ($docinfo[1])\n";
		    };
		    $list[$j++] = "</UL>";
		    $list[$j++] = "<A HREF=index.html>Back to index</A>\n";
		};
	};
	$index[$i] = "</UL>\n";
	print INDEXFILE @index;
	print INDEXFILE @list;
	print INDEXFILE "</UL>\n";

$localtime = localtime;
print INDEXFILE "</UL>\n<HR>Last Updated : $localtime</BODY></HTML>";
};

--tKW2IUtsqtDRztdT
Content-Type: application/x-sh
Content-Description: mkindex.sh - Bourne shell script
Content-Disposition: attachment; filename="mkindex.sh"

#! /bin/sh

PKG_DIR=/var/db/pkg

for FILE in `ls ${PKG_DIR}`
do
    if [ -f "${PKG_DIR}/${FILE}/+CONTENTS" ];
    then
        echo ${PKG_DIR}/${FILE}
        ./docsmaker ${PKG_DIR}/${FILE}/+CONTENTS ${PKG_DIR}/${FILE}/+DOCS
    fi
done

# This is just for testing/debugging purposes to force
# docindex.pl to rebuild the index file

rm -f /usr/local/share/doc/index.html

./docindex.pl

--tKW2IUtsqtDRztdT--


To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message