From owner-freebsd-doc  Thu Sep  7 14:31:32 2000
Delivered-To: freebsd-doc@freebsd.org
Received: from chalfont.mail.uk.easynet.net (chalfont.mail.uk.easynet.net [195.40.1.44])
	by hub.freebsd.org (Postfix) with ESMTP
	id D5BDD37B422; Thu,  7 Sep 2000 14:31:27 -0700 (PDT)
Received: from cream.org (boothman.easynet.co.uk [194.154.100.117])
	by chalfont.mail.uk.easynet.net (Postfix) with ESMTP
	id 6B76CF848A; Thu,  7 Sep 2000 22:31:24 +0100 (BST)
Content-Length: 6050
Message-ID: <XFMail.000907223125.andrew@cream.org>
X-Mailer: XFMail 1.3 [p0] on FreeBSD
X-Priority: 3 (Normal)
MIME-Version: 1.0
Content-Type: multipart/mixed;
 boundary="_=XFMail.1.3.p0.FreeBSD:000907223125:308=_"
In-Reply-To: <20000906002540.M254@parish>
Date: Thu, 07 Sep 2000 22:31:25 +0100 (BST)
From: Andrew Boothman <andrew@cream.org>
To: Mark Ovens <marko@freebsd.org>
Subject: RE: Ports Documentation Index - the next installment
Cc: Andrew Boothman <andrew@dogma.freebsd-uk.eu.org>, doc@freebsd.org
Sender: owner-freebsd-doc@FreeBSD.ORG
Precedence: bulk
X-Loop: FreeBSD.org

This message is in MIME format
--_=XFMail.1.3.p0.FreeBSD:000907223125:308=_
Content-Type: text/plain; charset=us-ascii

On 05-Sep-00 Mark Ovens wrote:
> The changes I've made are:
> 
>     1. Improved the weeding out of non-doc files (it uses the
>        +CONTENTS file).

Cool. The more intelligence we can fit into that script the better.

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

I would have got around to that. Honest. :-)

>     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.

Yup. That's easier and quicker to read then the way my script was generating
the file.

>     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").

Ah Ha! The latest version of mine was already doing that! :-)

> I've attached 3 files:

All great stuff. I've no complaints. The only difference between the output of
your script and mine is a few cosmetic things suggested by Nik a while back,
like a title image and some statistics at the bottom of the output. Trivial
stuff.

Attached is the latest version of the script which I had. But I think work
should continue on yours now.

> 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.

Plus it only links to the english version of the docs. I guess we should really
handle all the languages.
 
>       I'm just a beginner at perl, so not too many flames about the
>       code, eh? (Hot Tips and friendly advice accepted :))

Ha! I think you made a better job of it then I did! You were starting with a
pretty scrappy script to start with.

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

Yeah. Like I started saying, I never really intended what I was doing to be the
basis of anything offical, I just picked up an idea of Nik's and started
playing with it. A flood of use[less|ful] print statements tend to be a
hallmark of me playing with ideas. I like to see what a program is doing until
I've got some confidence in it. :-)

I think this whole index thing was mentioned on the list a few months or so
back, I tried to e-mail you all but Cable Internet (my ISP) appeared to not be
passing on e-mails at the time. I don't know what happened to my email. And I
never got around to re-sending it.

Anyway, sorry to Mark for not getting in touch sooner.

---
Andrew Boothman <andrew@cream.org>
http://sour.cream.org


--_=XFMail.1.3.p0.FreeBSD:000907223125:308=_
Content-Disposition: attachment; filename="docindex"
Content-Transfer-Encoding: 7bit
Content-Description: docindex
Content-Type: text/plain; charset=us-ascii; name=docindex; SizeOnDisk=2922

#!/usr/bin/perl

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

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

# By Andrew Boothman <andrew@ukug.uk.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/instdocs.html' || -M '/etc/docs.
local' < -M '/usr/local/share/doc/instdocs.html') {
	$localtime = localtime;
	$time = time;
	$noofdocs = 0;
	open 'indexfile','>/usr/local/share/doc/instdocs.html';
	opendir 'portsdir', '/var/db/pkg' or die "docindex: Can't open /var/db/pkg";

	@allfiles = readdir 'portsdir';

	closedir 'portsdir';
	
	if (-d '/etc/docs.local') {
		opendir 'localdocsdir','/etc/docs.local' or die "/etc/docs.local/ exists but c
an't be opened";
		
		@allfiles = (@allfiles,readdir('localdocsdir'));
		
		closedir 'localdocsdir';
	};

	@allfiles = sort(@allfiles);

	print indexfile '<HTML>
<HEAD>
<TITLE>Installed Documentation</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<! -- This page is automatically generated. DO NOT edit by hand!! -->
<! -- Please see /usr/share/doc/docsindex/ for more info -->
<IMG SRC="/usr/share/doc/docsindex/freebsd_title.gif" ALIGN="RIGHT">
<H2>Installed Documentation</H2>';
	print indexfile "<I>Last Updated : $localtime</I>";
	print indexfile '<HR><UL>';
				
	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") {
			open 'DOCS',"/var/db/pkg/$_/+DOCS" or die "/var/db/pkg/$_/+DOCS exists but ca
n't be opened";
			&DocsFileHandler;
		} elsif (-f "/etc/docs.local/$_") {
			open 'DOCS',"/etc/docs.local/$_" or die "/etc/docs.local/$_ exists but can't 
be opened";
			&DocsFileHandler;
		};
			sub DocsFileHandler {
			@docs = <DOCS>;
			close 'DOCS';
			chomp @docs;
			print indexfile "<A NAME=\"$_\"></A><LI>$_ <UL>\n";
			# Print out a link for each item of documentation
			# in the file
			foreach(@docs) {
				$noofdocs++;
				@docinfo = split(/:/);
				print indexfile "<LI>$docinfo[0] - [<A HREF=\"$docinfo[2]\">$docinfo[1]</A>]
\n";
			};
			print indexfile "</UL>\n"
			};		
		};
print indexfile '</UL><HR>
<H4>Links</H4>
<UL>
<LI><A HREF="/usr/share/doc/docsindex/README">More Information on the index</A>
<LI><A HREF="http://www.freebsd.org/cgi-bin/ports.cgi">Recently Changed Ports</A
>
</UL>
<HR><I>';
$timetaken = time - $time;
if ($timetaken == 0) {
	print indexfile 'Time Taken : <1 second<BR>';
} elsif ($timetaken == 1) {
	print indexfile 'Time Taken : 1 second<BR>';
} else {
	print indexfile "Time Taken : $timetaken seconds<BR>";
};
print indexfile "Applications With Documentation : $#docs<BR>";
print indexfile "Items Of Documentation Installed : $noofdocs";
print indexfile '</I></BODY></HTML>';
};

--_=XFMail.1.3.p0.FreeBSD:000907223125:308=_--
End of MIME message


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