Some DETAILS guidelines

[Auke Kok]

hi all, time for a brainfart (as jmhodges calls them):

Here's a short list of guidelines when writing DETAILS files, that 
should be followed when writing modules. Note that they're not rules, 
but things break if people deviate (lvu search etc) from it. It's up for 
discussion, and I would like to publicise it on the website in some form 
in the future:

-----

SHORT=""

    keep the text in here short (duh), less than 60 characters, don't 
make it multiline. SHORT can be assumed always displayed together with 
the MODULE name, so there's no need to include the module name again in 
this line.

good SHORTs are:

     xfce4-mixer: "Volume control and mixer for the XFce 4 panel"
     theedge: "development version of lunar core tools from Lunar-Linux."

okay is (they are short and descriptive, however they refer to other 
modules and don't tell exactly whay they do really, or they state the 
modules name):

     bash: "bash is the shell of the GNU operating system."
     beepmp: "A gtk2 port of xmms"

bad is (empty or way too long/nondescriptive):

     gaim: ""
     gnustep-make: "The makefile package is a simple, powerful and 
extensible way to write makefiles for a GNUstep-based project."

SHORTs also MUST be written on a single line, using '\' or line breaks 
is not permitted. SHORTs may include only ' quotes, try not to use 
quotes at all inside SHORTS.


DESCRIPTION

the description statement between the 'cat <<EOF' and 'EOF' must be 
wrapped at 73 characters. Don't use backticks, $-signs or other shell 
characters. Please try to put something here that makes sense, don't 
just blindly copy the 'about' section of a website. Perhaps include your 
own text in here as well.

vim: visually select the DESCRIPTION and type '!fmt -73[enter]' to wrap
emacs: auto-wrap by (insert emacs trick)


language: lunar is coded in american/english throughout right now. 
That's bad and means non-native english coders have a hard time writing 
and understanding the english if it is non written simple. here's some tips:

if you write a module, try not to be too technical and keep the english 
'relatively' simple. Concentrate on readability.

if you write a module and are not a native english speaker (like me ;^)) 
ask other developers to read your descriptions and perhaps improve. (BTW 
don't ask hardkrash cos he cannot type :^P)

AND, if you are reading a module and don't understand what it's about 
(even if you are a native english speaker...!) then ask for it to be 
clearified/rewritten.


SOURCE{N}_URL{[M]} and SOURCE{N}_VFY{[M]}

when there is only 1 (one) source in a module, use:

    SOURCE_URL=http://.....
    SOURCE_VFY=md5:.....

when there is a compelling reason to NOT use the md5sums, don't use 
them, otherwise new modules should have md5sums.

only when the module has alternative URL locations (mirrors) use the 
following form:

    SOURCE_URL[0]=....
    SOURCE_URL[1]=....

etc. Note we still start at '0'.

When you have multiple modules, use:

    SOURCE_URL=...
   SOURCE2_URL=...
   SOURCE3_URL=...

note we assume 'no number' equals '0' (codewise), and we may skip '1' 
alltogether. If any of these SOURCEs has multiple mirrors, only then 
extend the URL[x] part only for that SOURCE.

---

is this clear enough to go on the website? should it be more elaborate? 
comments? disagreeing? hungry? beer?

ciao, enjoy the weekend!

sofar