From owner-freebsd-doc Mon Jun 26 2:16:36 2000 Delivered-To: freebsd-doc@freebsd.org Received: from nothing-going-on.demon.co.uk (nothing-going-on.demon.co.uk [193.237.89.66]) by hub.freebsd.org (Postfix) with ESMTP id 4284C37BD6E; Mon, 26 Jun 2000 02:16:23 -0700 (PDT) (envelope-from nik@nothing-going-on.demon.co.uk) Received: from kilt.nothing-going-on.org (kilt.nothing-going-on.org [192.168.1.18]) by nothing-going-on.demon.co.uk (8.9.3/8.9.3) with ESMTP id IAA88204; Mon, 26 Jun 2000 08:25:30 +0100 (BST) (envelope-from nik@catkin.nothing-going-on.org) Received: (from nik@localhost) by nothing-going-on.demon.co.uk (8.9.3/8.9.3) id TAA00516; Sun, 25 Jun 2000 19:52:03 GMT (envelope-from nik) Date: Sun, 25 Jun 2000 19:52:03 +0000 From: Nik Clayton To: doc@freebsd.org Cc: hackers@freebsd.org, jkh@freebsd.org, dgl@bsdi.com, jim@cdrom.com, papowell@astart.com, wpaul@freebsd.org, ceren@magnesium.net, ryan@ryan.net, murray@bsdi.com Subject: Documentation selection in sysinstall Message-ID: <20000625195203.C470@kilt.nothing-going-on.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.2i Organization: FreeBSD Project Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org [ Going to -doc where it's pertinent, -hackers where it might find someone who's prepared to do the work, and jkh for any expert commentary he feels like tossing in. And while I've got Jordan's attention -- did the last attempt at re-writing sysinstall generate any specification documents? If nothing else, they'd be useful content for the doc project. ] [ I didn't go through this at Usenix -- not enough time ] The documentation is now being built and made available as FreeBSD packages (one package per combination of document, language, and output format). This means we could do away with the "doc" distribution when installing FreeBSD, and instead allow the user to choose which documentation packages they want to install. In theory, this is a doddle. sysinstall already lets the user choose from packages to install. In practice, I think it's a little more difficult, because: 1. [ I haven't run the code to confirm this, not having a network connection at the moment. ] When you do the "post-install" configure via sysinstall, it wants to grab the INDEX file from somewhere (CDROM, the 'net, or whatever) in order to present you with an up-to-date list of packages to install. The doc package building doesn't work like that. There is no INDEX file for sysinstall to grok. We need to find some other way for sysinstall to get the list of docs, languages, and formats that are supported it. This shouldn't be too hard -- looking in /pub/FreeBSD/doc/packages on the FTP site gives a complete list of what's currently built in terms of languages and output formats, and the filenames are easily parseable. 2. We need to find a UI model that allows the user to efficiently select the language and formats they want to install. I'm thinking of initially presenting a dialog box that looks like this: ------------------------------------------------------------ Documentation is available in the following languages: English Spanish French Japanese Chinese ------------------------------------------------------------ with the list extending as necessary, based on what sysinstall found on the FTP site. After the user has chosen a language, then present them with a list like this: ------------------------------------------------------------ Now choose the documentation you would like to install, and the formats you would like to use. HTML HTML Text PS PDF PDB RTF Split Books Handbook [ ] [X] [ ] [ ] [ ] [ ] [ ] FAQ [X] [X] [ ] [ ] [ ] [ ] [ ] Porter's Handbook [ ] [ ] [ ] [X] [ ] [ ] [ ] [... and so on ...] ------------------------------------------------------------ From my reading of dialog(3) I believe this to be, uh, optimistic at best. I've also glossed over the issue of how sysinstall turns "porters-handbook" in a filename to "Porter's Handbook" on screen. Thinking about it, we will probably need an INDEX. file that maps filenames to titles -- we should be able to generate this when we build the packages by grabbing the first element from a document. The alternative to a display like this would seem to be a fairly horrendous nest of menus and sub-menus that the user would have to navigate through. That's about where I am in my thinking about this so far. Alternative viewpoints, suggestions, offers to do the work, and prototypes are gratefully received. 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 To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message