From owner-freebsd-doc Wed Oct 6 10:33:48 1999 Delivered-To: freebsd-doc@freebsd.org Received: from typhoon.mail.pipex.net (typhoon.mail.pipex.net [158.43.128.27]) by hub.freebsd.org (Postfix) with SMTP id 61ACD14D34 for ; Wed, 6 Oct 1999 10:33:33 -0700 (PDT) (envelope-from mark@dogma.freebsd-uk.eu.org) Received: (qmail 25225 invoked from network); 6 Oct 1999 17:33:31 -0000 Received: from userbq85.uk.uudial.com (HELO marder-1.) (62.188.146.179) by smtp.dial.pipex.com with SMTP; 6 Oct 1999 17:33:31 -0000 Received: (from mark@localhost) by marder-1. (8.9.3/8.8.8) id RAA01104; Wed, 6 Oct 1999 17:59:22 +0100 (BST) (envelope-from mark) Date: Wed, 6 Oct 1999 17:59:22 +0100 From: Mark Ovens To: Andrew Boothman Cc: nbm@mithrandr.moira.org, wosch@cs.tu-berlin.de, nik@freebsd.org, doc@freebsd.org Subject: Re: Automatic Documentation Index Message-ID: <19991006175922.A373@marder-1> References: <19991004234956.A977@marder-1> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0pre2i In-Reply-To: Organization: Total lack of Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org On Wed, Oct 06, 1999 at 12:40:53AM +0100, Andrew Boothman wrote: > > On 04-Oct-99 Mark Ovens wrote: > > Seems like a good thing to me. I've just tried it out (had to change > > the paths to the FAQ and Handbook for the DocBook docs). There are > > quite a few ports that install docs other than (& sometimes instead > > of) manpages but don't advertise the fact. > > Exactly. Hence the need to index them. > > > As a temporary solution, until the +DOC files are added, how about > > looking for html files in the +CONTENTS files? Something like > > > > # cd /var/db/pkg > > # grep '\.html$' */+CONTENTS > > > > and parsing the output in some way (e.g. if there are several .html > > files installed including "index.html" then just list the index > > and ignore the others). It's not perfect, but it would dig out all > > the "hidden" documentation. > > I fully understand what you're getting at here. And I can see how this would > work. I'm a little worried about the possability that this could pick up on > installed files that arn't actually documentation. > > I'm not sure if it's likely, but it would really confuse a user to be pointed > to files that aren't documentation. Plus, in the +DOCS file we have a > description of the file that we're linking to, we wouldn't know what the file > is if we link to it this way. I thought about that myself. All the script needs to do is read the block at the top of the files in question (in the case of HTML files). BTW, I'm trying to borrow a "Perl for Dummies" type book from work so that I can help out with this. > Plus, we don't want the ports folk to think that > this negates the need to retrofit +DOCS files to as many ports as possible. > I also considered that it could automatically generate initial +DOCS files. This would be sufficient for many ports and the rest would need tweaking by hand (the ports related to DocBook itself are a case in point; there's masses of HTML files there). Maybe this would encourage support from the ports maintainers as they would have some (maybe all) the work done for them. > What are everyone else's opinions on this? > > --- > Andrew Boothman > FreeBSD UK User Group > http://ukug.uk.FreeBSD.org/~andrew/ > http://ukug.uk.FreeBSD.org/ -- STATE-OF-THE-ART: Any computer you can't afford. OBSOLETE: Any computer you own. ________________________________________________________________ FreeBSD - The Power To Serve http://www.freebsd.org My Webpage http://ukug.uk.freebsd.org/~mark/ mailto:mark@ukug.uk.freebsd.org http://www.radan.com To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message