Skip site navigation (1)Skip section navigation (2)
Date:      Thu, 25 May 2000 19:15:47 +0100
From:      Mark Ovens <mark@ukug.uk.freebsd.org>
To:        Nik Clayton <nik@freebsd.org>
Cc:        doc@freebsd.org
Subject:   Re: Why no Master Index?
Message-ID:  <20000525191547.B232@parish>
In-Reply-To: <20000524084850.A8565@kilt.nothing-going-on.org>; from nik@freebsd.org on Wed, May 24, 2000 at 08:48:50AM %2B0000
References:  <20000523194307.C233@parish> <20000524084850.A8565@kilt.nothing-going-on.org>

next in thread | previous in thread | raw e-mail | index | archive | help
On Wed, May 24, 2000 at 08:48:50AM +0000, Nik Clayton wrote:
> On Tue, May 23, 2000 at 07:43:07PM +0100, Mark Ovens wrote:
> > Is there a reason why there is no Master Index/TOC for the FreeBSD
> > docs? 
> 
> This >   < much time.
> 
> This >                         < many things to do.
> 
> :-)
> 
> > IMHO it would make sense to have a single point of entry into
> > the documentation set. The handbook and FAQ are the high profile docs
> > but the rest, especially the articles, are somewhat hidden from view
> > being referenced from the handbook and FAQ and pointed to people in
> > replies to questions.
> 
> Couldn't agree more.
> 
> [snip]
> 
> Your example looked good.  Do you want to turn that in to HTML (based on
> the existing contents of www/en), and we can go from there.
> 

OK, ftp://ukug.uk.freebsd.org/pub/mark/doc_index/ for my first
attempt. I've put both the HTML and the SGML I made it from
(sgmlnorm -d example.sgml > example.html). The links assume it is in
/usr/share/doc.

> You might want to take a look at http://www.freebsd.org/docs.html, and
> try trimming that down.  One way to do it would be to split things in two
> based on whether or not they're maintained by the project.
> 
> So have a docs/index.html that offers the reader links to the two files,
> and an 'internal.html' that lists the project maintained docs, and an 
> 'external.html' that lists the other stuff ('internal' and 'external' are
> crap names, please, come up with better ones :-) )
> 
> I also wouldn't mind seeing a translation table that listed all the docs,
> and an indication of whether or not they've been translated. . . 
> 
>                          en     es     fr    ja    ru    zh
>    Handbook              x             x     x
>    FAQ                   x      x      x     x     x     x
>    FDP Primer            x
>    Porter's Handbook     x                   x
>    [...]
> 

I'm working on this now. BTW, I got some nl docs last time I cvsup'd.

> This would be a separate page.
> 
> > As Nik has just suggested having the docs as a package to be installed
> > by sysinstall it would seem sensible to have something like this. In
> > fact I would go so far as to suggest that sysinstall automatically
> > installed a browser with the docs index as it's Home Page. Having the
> > docs "in your face" doesn't seem to be inappropriate for new users.
> 
> Ye-es.
> 
> Go through the archives and you'll find an effort by Andrew Boothman to
> create a process that would create and maintain an HTML index of all the
> documentation installed by ports/packages on a particular system (subject
> line was "Automatic documentation index").  Since I want to start 
> encouraging people to treat our docs in exactly the same way we should 
> (IMHO) leverage that work.  Then sysinstall doesn't have to do anything
> new.
> 
> N
> -- 
> Internet connection, $19.95 a month.  Computer, $799.95.  Modem, $149.95.
> Telephone line, $24.95 a month.  Software, free.  USENET transmission,
> hundreds if not thousands of dollars.  Thinking before posting, priceless.
> Somethings in life you can't buy.  For everything else, there's MasterCard.
>   -- Graham Reed, in the Scary Devil Monastery

-- 
        ...and on the eighth day God created UNIX
________________________________________________________________
      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




Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20000525191547.B232>