Challenges for SableVM users and enthusiasts

Hello,

As we are approaching new release I've been trying to get some general
picture of what we're about to release.  There is of course an endless
list of things to be developed and/or fixed in SableVM itself.  There
we're making steady progress.  If you wanted to fix or add a feature by
yourself - be our guest and ask questions you need to have answered to
be able to complete whatever goal you choosed.

But if for any reason you don't feel like becoming a SableVM developer
(yet?) there are still other important and very valuable tasks.  For
starters I listed three of them below, in order of urgency. Depending
on your knowledge they might be quite challenging (or should I say:
interesting?) but I am sure they _can_ be accomplished if you simply
choose to aim at one of them.

1. Fix manual pages (formatting is broken - urgent!)
2. Put together existing documentation into a Docbook(?) format.
3. Improve web site look (rewrite w/ contemporary technology?)


AD. 1) Manual pages are broken.

Yes, we have manual pages, but they're broken.  When I wrote them
I simply took a look at other manual pages and tried to get something
that looks acceptable.  But now I am getting reports that for example
on some systems *not full manual page is viewable*.  And let's face
it - the formatting I used (or: managed to achieve) sucks.

It would be great if you could at least fix the formatting.  I think
this document might be helpful:

        http://www.tldp.org/HOWTO/Man-Page/

I have also seen manual pages generated from XML sources.  Maybe
that would be the sanest option?  (and maybe it could be integrated
with 2) later?)  The latest version of manual pages are always 
available at:

	http://sablevm.org/svn/sablevm/branches/staging/doc/

I marked it "urgent" because it would be great to ship fully usable
manual pages with SableVM 1.1.7.


AD. 2) Documentation needs to be put in more consistent state/format!

Currently we already have some documentation of SableVM, but:
  a) it is scattered in different places,
  b) plain ASCII file is not really the best documentation format.

Please just take a look at what we have now:

  http://sablevm.org/wiki/Documentation

  http://sablevm.org/svn/sablevm/branches/staging/doc/

  http://sablevm.org/docs.html

  http://sablevm.org/wiki

What would be ideal to have would be to have something like:

  http://svnbook.red-bean.com/  :-))

Or a more realistic version:

  http://argouml.tigris.org/documentation/defaulthtml/manual/

ArgoUML manual is generated from DocBook/XML sources which allows one
to easily generate txt, html and ps/pdf formats.  This means we could
forget about other documentation sources we have now, once they're all
incorporated into a DocBook/XML source.  We would simply switch to
a superior format.

  Can you do the first step to make it possible?

Searching google for 'docbook/xml starting guide' returns i.e.:

"DocBook: The Definitive Guide" with 2nd chapter "Creating DocBook
 Document" - available on-line.
  http://www.oreilly.de/catalog/docbook/index.html

"Jabber.org's Quick Guide to DocBook XML"
 
http://www.dulug.duke.edu/~mark/bookmarks/jabber-Qguide2docbookXML.html


AD. 3) Web site HTML needs improvement or maybe even a rewrite.

If you use variety of browsers (not only Mozilla-based) you surely
noticed that our web pages do not look exactly the same.  While this
is normal to some extent, this is not always desirable to have second
half of "left upper" menu available only after scrolling 2 screens
down (IIRC this happens with some MSIE).

On the other hand the pages itself are formatted using tables which,
in age of CSS (and subset of CSS2 more-less supported in all browsers),
is quite an anachronism.

If you do not feel like rewriting web pages completly, we happily
accept smaller fixes or smaller improvements.  In case you wanted to
think of a possible rewrite, please start discussion about it, so
that we all could learn what is possible (we're not HTML specialists)
and so that we could discuss some general guidelines of what the new
pages might look like.  We're very open to proposals.

========================


Whoa! You got *that* far?!  Congratulations!

Now, if you're considering trying on some of the above issues, please
just reply to this email and ask whatever is on your mind.  We will
not treat your reaply necessarily as a declaration that you will do
"something".  After all this is always your freedom of choice, no
pressure here.

In case you wanted to take a look at other possible things to do,
here's a longer list:

  http://sablevm.org/wiki/TODO

...which also reminds me about a very important thing you *have to* do
if you ever choose to help and become an active part of SableVM Project.


Have Fun!

                Grzegorz B. Prokopski

-- 
Grzegorz B. Prokopski      <[email protected]>
Debian GNU/Linux           http://www.debian.org
SableVM - LGPL'ed Java VM  http://www.sablevm.org
Why SableVM ?!?            http://devel.sablevm.org/wiki/Features