Date: Sun, 25 Jun 2000 19:52:03 +0000 From: Nik Clayton <nik@freebsd.org> 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>
next in thread | raw e-mail | index | archive | help
[ 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.<lang> file that
maps filenames to titles -- we should be able to generate this when we
build the packages by grabbing the first <title> 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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20000625195203.C470>