From owner-freebsd-hackers Fri Jan 7 18:13:28 2000 Delivered-To: freebsd-hackers@freebsd.org Received: from scrabble.freeuk.net (scrabble.freeuk.net [212.126.144.6]) by hub.freebsd.org (Postfix) with ESMTP id 5DB57158AB for ; Fri, 7 Jan 2000 18:11:37 -0800 (PST) (envelope-from andrew@ukug.uk.FreeBSD.org) Received: from [212.126.147.132] (helo=cream.org) by scrabble.freeuk.net with esmtp (Exim 2.11 #1) id 126lLr-0003mS-00 for hackers@freebsd.org; Sat, 8 Jan 2000 02:11:35 +0000 Content-Length: 2108 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: Sat, 08 Jan 2000 02:11:54 -0000 (GMT) From: Andrew Boothman To: hackers@freebsd.org Subject: Automatic Documentation Index Sender: owner-freebsd-hackers@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.ORG [This was posted to -ports, to no response] 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-hackers" in the body of the message