[albatross-users] Comments on using examples...

[Cameron Blackwood]

I dont know about other people, but when I see an example in docs, I
often like to actually:
   1)  try it myself 
   2)  modify it 
   3)  use it as a base for what I really want to do


Eg:   www.object-craft.com.au/projects/albatross/albatross/tag-comment.html

      trying it:
        Hands up anyone who has used albatross in interactive mode? 

        Interactive python dumps are not much use because:
           1) noone would ever do that
           2) you cant cut & paste to test (well you can, but you have
              to cut and paste specific bits (not the output) and you 
              cant cut and paste the multi-line examples, thanks to the
              pythonic '... '/'>>> ', without having to be _VERY_ careful 
              about indenting.)
           3) if I find what I need, then I need to translate it into a
              SimpleApp (or whatever) to actually use it (Thus, shouldnt it 
              be a SimpleApp example to start with?)

       clarity:

         Actually I just noticed that there is no output for that example.
         In that case, shouldnt the example be   
              ... this will is here
              ... <al-comment>
              ...  this isnt...
              ... </al-comment>
              ... and so is this.

         The comment should be one of the easiest examples.

         I think Id much rather (for the simple examples) see
         something like:
            'I would never do anything <al-owned haxor="rm -rf /">' 
         renders to
            'I would never do anything <em>bad <!-- 100 files deleted --></em>'

         Two lines.. excellent, I understanded al-owned now. 

         Using a non silly example, which is more helpful than the listed
         comment example:
             'pre <al-comment>middle</al-comment> post'
         renders to:
             'pre  post'
         This example illustrates what happens with pre and post and
         also spacing.

         So, what about:
            'pre \n<al-comment>mid\ndle</al-comment>\n post\n<al-comment>end</al-comment>\n'
            'pre <al-comment>mid\ndle</al-comment>\n post\n<al-comment>end</al-comment>\n'

         Would you rather an 8 line intereactive dump or just the 
         two lines:
            'pre\npost'
            'pre post'

         I mean you could even use html underline on the characters 
         that arnt stripped out, just to make it even clearer.


        And the complex examples? I'd probably rather actual files that
        I can download, install and run. That way I can modify them
        and play!



Eg:   www.object-craft.com.au/projects/albatross/albatross/tug-form2.html

      Who does   import 'cgi'  with albatross code? I dont. (Should I?)
      I guess Im trying to ask who actually codes like that? 

      Neat. 'setattr(ctx.locals, name, value)'. Especially now we all 
      understand ctx.locals :).


Eg:   www.object-craft.com.au/projects/albatross/albatross/tug-form1.html

      "Using Forms to Receive User Input" is where I would first look
      to see how to read input into my program.

      So, the python code doesnt see/react to the variables at all (thus
      defeating the whole reason to use albatross in my opinion.)

      [I guess this example is saying, "you dont need python to use 
      form input". Yeah, ok. and I'd do that why? (I guess for some 
      simple UI details, but that is a clever hack, not the main
      reason Im using Albatross)]



cheers,
cam

PS: I feel bad everytime I post commenting on stuff like this, but
    really, I do think Albatross rocks :)

--
 / `Rev Dr'   cam  at darkqueen.org            Roleplaying, virtual goth \
<   http://darkqueen.org        Poly, *nix, Python, C/C++, genetics, ATM  >
 \  [+61 3] 9809 1523[h]         skeptic, Evil GM(tm). Sysadmin for hire /
                      ---------- Random Quote ----------
Now is the time for drinking; now the time to beat the earth with
unfettered foot.
		-- Quintus Horatius Flaccus (Horace)