From owner-freebsd-ports Sun Jan 2 9: 4:20 2000 Delivered-To: freebsd-ports@freebsd.org Received: from scrabble.freeuk.net (scrabble.freeuk.net [212.126.144.6]) by hub.freebsd.org (Postfix) with ESMTP id 10C3E14E31; Sun, 2 Jan 2000 09:04:16 -0800 (PST) (envelope-from andrew@ukug.uk.FreeBSD.org) Received: from [212.126.147.172] (helo=cream.org) by scrabble.freeuk.net with esmtp (Exim 2.11 #1) id 124oQO-0005GI-00; Sun, 2 Jan 2000 17:04:13 +0000 Content-Length: 2062 Message-ID: X-Mailer: XFMail 1.3 [p0] on FreeBSD X-Priority: 3 (Normal) Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 8bit MIME-Version: 1.0 Date: Sun, 02 Jan 2000 17:04:27 -0000 (GMT) From: Andrew Boothman To: ports@FreeBSD.org Subject: Automatic Documentation Index Cc: doc@FreeBSD.org Sender: owner-freebsd-ports@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org Happy New Year, everyone! With the world apparently still in one piece after the celebrations and the few Y2K incidents, I guess we're back to our regular transmissions. Since this message is going outside of -doc where it has been discussed before, I'll offer up a full explanation of what's going on. What is proposed is a system where all the documentation installed through the ports system, or locally by a sysadmin, is collected together and indexed on one HTML page; say /usr/local/share/doc/instdocs.html This page is created by a perl script, docindex, which I envisage being run either from a /etc/periodic/* or /etc/rc or both. The script gets its information from +DOCS files contained within the /var/db/pkg directory for each installed port. These files consist of three fields, colon seperated. The first field being the name of the item of documentation, the second being a filetype, and the third a full path to the file. For example, for Sharity Light : FAQ:txt:/usr/local/share/doc/Sharity-Light/FAQ README:txt:/usr/local/share/doc/Sharity-Light/README In addition the local sysadmin can add similarly formatted files into, say, /etc/docs.local/ that will also be read in and included in the index. In order to help the ports maintainers, and others, create these DOCS files that will be needed, there is a script called docsmaker. This script has a _very_ rough guess from the CONTENTS file of a port what might be documentation. But I stress that the file which it creates will still need to be checked for files that shouldn't be there, files that have been missed, and any other stupid mistakes. :-) Right, I think I'm just about finished. Apart from to say that current versions of the scripts I've been talking about and example outputs from all this are available from http://ukug.uk.freebsd.org/~andrew/docindex/ Does anyone have any thoughts or comments on how to proceed? Many thanks! --- Andrew Boothman FreeBSD UK User Group http://ukug.uk.FreeBSD.org/~andrew/ http://ukug.uk.FreeBSD.org/ To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-ports" in the body of the message