[REBOL] Re: UHURU/RSL/? summary
From: chris:starforge at: 25-May-2001 19:56
#25-May-01# Message from *Chris*:
Hi Chris,
Please refer to http://www.escribe.com/internet/rebol/m9502.html for a
full copy of the summary and references.
> - A standard for package implementation, including a specification
> of required metadata and coding and documentation standards.
> This is discussed in part 3.
Part 3 - Package, coding and documentation standards.
As yet there has only really been a cursory descussion of some of the
topics this covers, unfortunately this is probably the most important
part of the project.
Package issues - package hierarchy, contexts, versioning and dependancies.
As mentioned in Step 1, packages will be stored in the repositry in a
heirarchical structure. The existing script libraries have single level
classifications for scripts. While this is sufficient for small collections
it is not suitable for very large script libraries. While I don't suggest we
attempt to determine the complete hierarchy now - attempting such a thing
would be futile at best - some form of structure is plainly needed before
the project goes live. I would suggest using the classifications on
rebol.com and rebol.org as starting points.
Please see Joel's example in reference 1 for the solution to the context
issue.
Versioning is a problem. As has already been discussed (refs 8 and 9),
revisions within versions must retain backwards compatability but versions
do not. In theory this is not a problem but consider the situation where
two scripts are running, one using v1 of a package and the other using v2.
As most filesystems do not provide a method to distinguish files purely on
version information, one of them would overwrite the package the other had
obtained. This is clearly a Bad Thing. The alternatives as I see them:
- Do not store such files locally. This is fine provided your client lives
on the end of a 24/7 broadband connection. If this is not the case then
this is not really a viable solution.
- Try to encourage authors to use the latest version of a package. This is
clearly impractical.
- Use a linux library like system where source names contain the version
number, for example:
delim-ascii-html-1_5.r
delim-ascii-html-2_1.r
Some may find this inelegant, but it is a viable alternative which avoids
version clashes. Provided the coding guidelines prevent developers from
using versions like 1_4_2_93_2Pre3B1 or something equally rediculous, this
scheme should work.
A side effect of the latter is that dependancy checks can obtain the correct
version without the need for two dependancy blocks:
depends-on [/text/conversion/delimited-ascii-2 /foo/bar/thingy-1]
as opposed to
depends-on [/text/conversion/delimited-ascii /foo/bar/thingy]
depends-versions [2 1]
(you could argue that depends-on and versions could be combined into one
block of course..)
Coding standards.
In case anyone reading this hasn't read the REBOL style guide, please
consult page 4-13 (Scripts - Style Guide) in the /Core user manual before
continuing (even if you have, you may want to recap)
The REBOL style guide is a good start, but it does not make clear enough
distinctions about the standards which must be followed in production code.
For the moment we should leave the issue of UHURU metadata to one side and
concentrate on the parts of the style guide which must be extended or
adhered to.
- All the guidelines for formatting and word names can be used as is, they do
not directly affect the system. Developers should take note of the word
naming rules to make code more readable though.
- The Script header section is far too minimal. I would suggest the
following as a minimum for a source file in the system:
REBOL [
Title: "Delimited ASCII to HTMl conversions"
Date: 25-May-2001
Version: 2.1
File: %delim-ascii-html-2_1.r
Author: "Joel Neely"
Email: [joel--neely--fedex--com]
Home: .. umm :) ..
History: [
1.0 [1-May-2001 {Initial version} "Joel Neely"]
....
]
Purpose: { Bla bla }
]
Feel free to argue why the field I've left out should be in, and why the
ones I've put in shouldn't be :))
- The function headers guide should be taken as-is, this is helpful for
when docs are auto-generated or the developer needs to use help.
Somewhat wasteful for user clients, but as I mentioned - if we compress
files for download by the remote access script, this is not too much
of a killer issue (IMO - YMMV)
- Embedded exmamples should not be included in release code. These should go
in the documentation (see later).
- Debugging is an interesting problem. My gut reaction is to keep it even in
release code as other developers may want to use it while testing their
scripts.
I realise I'm probably getting above myself messng around with Carl's
guidelines here, but UHURU needs to tighten a few things up in here IMO.
Now of the contentious part - the metadata storage mechanism. Joel suggests
using XML and the parse-xml code, I suggested adding header fields. The
following are the summaries of the pros and cons for both as far as I can
see. Joel makes some other statements in ref 3 but I object to 1 because
there is no definitive document specifying what should be in current headers
anyway, so adding a few extra fields shouldn't rock the boat too much..
1. XML metadata - pros:
Possible to strip meta data when installing scripts. The XML block could
just be stripped during the download.
Parse-xml is already available so little extra work would be needed to
implement the XML lookups.
Could be used to drive a keyword search
Extensible.
2. XML metadata - cons:
Requires more work to parse (parse-xml needs to go in and do its bit)
Developers need to keep a couple of fields in the header and XML
section in step (version info etc).
3. Header metadata - pros:
All the metadatafiles are available to the script simply by doing a
script-code: load/header followed by a header: pick script-code 1
No additional parsing code is required
No need to maintain two copies of some fields
Could be used to drive a keyword search
Extensible
4. Header metsdata - cons
May conflict with RT's plans for the header in the future
Increases amount of redundant text in scripts (stripping header fields
would be trickier than an XML block).
Now I guess these are both pretty evenly matched really: XML wins mainly on
space saving, while the header route avoids the need for additional parsing
work. I /personally/ prefer the header route as it feels like a simpler
solution. If people can expand on the pros and cons above we may be able to
decide one way or t'other.
Documentation conventions.
I'm too tired to have a good go at this one now, I'll try tomorrow unless
someone else wants a bash at it :)
Chris
--
New sig in the works
Explorer 2260, Designer and Coder
http://www.starforge.co.uk
--
Grelb's Reminder:
Eighty percent of all people consider themselves to be above
average drivers.
