mod documentation redux; [AppleMods] mod licence; etc
mod documentation redux; [AppleMods] mod licence; etc
- Subject: mod documentation redux; [AppleMods] mod licence; etc
- From: has <email@hidden>
- Date: Mon, 11 Mar 2002 19:46:11 +0000
Hi,
Just a reminder that nobody posted back the last time I raised the subject
of mod documentation. [I'd sent a recommended change to document structure
to better accomodate OO libraries, along with a sample.]
I'm already a bit chocker with other stuff, but now that I've put a site up
I'm starting to feel the need for some order on the mods front - not least
since AM is still missing copies of my own mods and really needs to get
some fresh ones posted. (Although this is entirely my bad for not having
sent Greg fresh copies since his crash; I keep putting it off "until I have
time to do any bug-fixes and testing, which I'm sure to do Real Soon Now".)
But while my main focus is on getting AWPS up to v1.0 (which includes
writing the documentation; first official draft will be sometime this
week), I'm also doing bits and pieces of other stuff, including fixing up
some of my mods. Reasons why I still don't seem to be getting them out
there:
1. I'm lazy
2. I'm busy on other, more exciting things
3. Would like to see documentation structure finalised, seeing as I'm
already up to my neck in doc writing/rewriting and loathing the subject all
already. (Serge, can you think of any additions/changes after writing up
your docs according to the last suggested structure?) I figure the
presentation scheme can be decided pretty easily by posting one set of docs
using Serge's markup and one using my structured text, and asking folks
which one they prefer. (Sorry Greg, but I really think we must pass on the
XML option this time around; maybe in a couple of years when it's got
decent OS-level support...)
4. In relation to #3, what properties do we put at the top of our scripts
now? AFAIK it's modName, modVersion, releaseDate ("yyyy/mm/dd" formatted
string), and requiredMods (list of modnames). That right? Only I intend to
pull all the language-dependent stuff in my own mods into a single,
separate mod. Which means that anything that has to mess around with
upper/lowercase ASCII characters or weekdays/months will be _dependent_ on
that mod. And I don't really wish to embarrass myself by releasing a whole
batch of newly dependent stuff, only to find a month later I put the wrong
properties in and it's all broken as a result.
5. Am putting the foot down re. AppleMods and its lack of character
escaping. AppleMods must start using html entities for &"<> characters in
posted scripts. It's personally embarrassing to post a script only for folk
to mail me later telling me my scripts are broken, purely because they cut
and pasted stuff that's misrendered in their browser. I mean, this is
really, really basic html stuff - surely the mighty PHP has _something_ in
there to take care of a few lousy character-to-entity conversions? I'll end
up dumping stuff onto my anonymous backwater site till this issue's
resolved, though I would _much_ prefer that AM hosts them as that's better
for the both of us.
6. Once #5's satisfied then I'll start posting stuff to AM again. That
said, I'm still rather keen that AM becomes more flexible WRT large mods.
Posting code snippets that you can see on the webpage is cool; posting big
30KB mods with 20KB manuals is a bit less so. Is there _anything_ that I
can maybe say or do that might get AM to provide posters a choice of inline
display or download link? Besides, I've stopped using inline documentation
because it's too inconvenient, and lack of support for bundled files means
I gotta cut-n-paste all over the place, which is also inconvenient. And I
get lazy when things are inconvenient.:)
7. Waiting for the Official AppleMods Licence. Greg, I remember you
mentioning this way back when; did you ever manage to come up with
something? Dunno about anyone else, but I'd feel much happier distributing
stuff if it was under some sort of proper licence.
-------
In particular, I'd really love to see AM host all the new wave of "fast
list access hack" handlers and scripts that'll no doubt be washing down
from the hills of MacScrpt any day now. (I've already started updating my
own stuff to use this technique and am getting into the Akua-burning
performance range now, which is pretty darn cool for vanilla code.) And if
it can happen in ordered fashion; i.e. all this rocket-science stuff being
nicely-documented so even the Little People can understand it, it would be
mighty cool.
Cheers,
has
_______________________________________________
applescript-users mailing list | email@hidden
Help/Unsubscribe/Archives:
http://www.lists.apple.com/mailman/listinfo/applescript-users
Do not post admin requests to the list. They will be ignored.