Gavin Sinclair wrote:
Hi folks,
Regarding the discussions surrounding styles and so on, I have a
number of points to make. At a training course today, I was able to
jot down a lot of things to clarify various issues surrounding the
presentation and so on. Anyway...
1. Making the documentation downloadable
Instead of having a link to a file per se, I'd like James to create a
download page for the tarball and zip file, or incorporate it into the
existing download page, whatever he thinks appropriate. It's easier
to deal with versions then, and anybody in the world can link to it to
say "here's where to get ...".
That'll work.
The download page should list the versions in descending order, with
each one dated. Give consideration to providing a description for
each version, but it's not essential. A manual cleanout of old
versions can take place every so often. Time will tell whether anyone
ever wants old versions, but it's interesting to see them there
anyway, so you can see how much has happened since you last
downloaded.
To do this without having to having to manually intervene each time a
new file is available, I would simply point to a raw directory listing.
A descripting of each file could live in a README or something, perhaps,
something updated with each upload of a new tarball.
2. Versions
Tarballs (and from now on, this term includes zipfiles) will be
explicitly versioned. I'll arbitrarily start at 0.7 to reflect the
fact that a lot of work has gone into it. 1.0 will occur when the
style matures sufficiently, and minor releases thereafter will herald
significant improvements in documentation quality/quantity. Teeny
versions will just be issued silently whenever something changes.
The documentation output is not CVSed, so old versions are not
retrievable and a versioning strategy is a fragile process.
Nevermind. I'll ensure the version is visible in the documentation
itself somewhere, so people know what they're looking at.
Fine.
3. The tarball name
I've decided on ruby-doc-stdlib instead of ruby-stdlib-doc, to
emphasise "ruby-doc", and ti give some indication of the intended
directory structure (see next section).
OK.
4. Installation
What is the experience of the user who downloads the documentation for
offline viewing? (I expect this to be the major use case.) They can
unpack the tarball somewhere and point their browser at index.html,
set a bookmark, and everything will be fine. Until the get a new
tarball, which unpacks into a different directory.
If they're happy with that, that's fine. However, I will provide an
install.rb which copies the documentation to the "standard doc
directory", e.g.
/usr/local/doc/ruby/stdlib/ (if `which ruby` is /usr/local/bin/ruby)
C:/ruby/doc/ruby/stdlib (typical Windows path)
Nice.
The "standard doc directory" is not in place yet, but I suspect it
will be before too long. It's too good an idea to pass up. Anyway,
this package of documentation can provide a proof of concept.
BTW, this is a whole other can of worms, but have you looked at RubyGems
recently? As best I can tell it doesn't provide for any doc locations
or hooks; when I ask Rich Kilmer about what it did with documentation,
he said, 'You tell me.' So I imagine we have the option of poking into
RubyGems and defining how/where documentation goes.
I think, too, that the same goes for standard lib docs. Nobody is
staking a claim, so if we here come to some reasonable agreement I think
we can just assert it as the truth.
The real benefit to the user of this is that the target directory for
installation will not be versioned; new docs clobber old ones. So the
bookmark still works, and cruft doesn't lie around. The user can
delete the tarball they downloaded, and the unpacked directory, after
installation.
I like that, and it most likely how I would use it.
Again, installation is optional. All this will be explained in a
README and in an introduction (to be included in the HTML docs).
5. Packaging (i.e. the files other than the documentation)
There are a few things to improve on, which I'll turn my attention to
soon.
...
6. "Site Home" and "ruby-doc" link
A site home link is a nuicance as it is meaningless, indeed erroneous,
for offline browsing. But it's useful for potential hosting
elsewhere, and the more hosting the merrier. The offline browsing
thing really niggles me, but I'll cope.
On option is to give the "home site" link a CSS class and style that
renders it invisible unless explictly overridden. So, by default,
offlne viewers needn't see it. (I'm assuming here external CSS files.)
If we're going to have one dodgy link (remember I consider offline
browsing the main use case, rightly or wrongly), then we're going to
have a good link to balance it: ruby-doc.org. Since the intro will
say that "this project is brought to you by ruby-doc.org", that is
justified even if it's hosted elsewhere.
Another option is to omit any "home page" links (relative or otherwise),
and I can simply sit the pages inside another frame, such that there is
always a global menu bar and link back to the top of ruby-doc.org. The
actual stdlib docs themselves need never refer to anything outside
themselves.
So I'll put a small "web links" bit at the top of the TOC frame, with
"Site Home" (/) and "ruby-doc.org" (ruby-doc.org) being the contents.
7. CSS
James wants to apply some CSS to the documentation. I'd rather this
was not done, or at least kept to a minimum. Since the target is
offline browsing, and since I already have heaps of CSS, my aim is to
make it look consistent within itself, and make it look as good as
possible for the kind of information it is, rather than making it
consistent with a surrounding site. The "big font" idea is not one I
see a need for, as the fonts used obey the user's preference.
The "big font" was just an example. Im general, I prefer to give folks
the option of designing or aquiring their own CSS if they like, to style
it as they will.
The CSS I have at the moment is in a few separate files, which I'll
work on consolidating if possible. I'll be uploading a new tarball
real soon now - James can you publish it? - so you guys can see the
latest.
I'm woring on cron/script stuff to auto-publish new tarballs, and I can
check to see that whatever is there now is the one displayed.
James
|
