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

[Dave Cole]

>>>>> "Sheila" == Sheila King <sheila at thinkspot.net> writes:

Sheila> --On Thursday, July 03, 2003 1:50 PM +1000 Cameron Blackwood
Sheila> <korg at darkqueen.org> wrote:

>> 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

Sheila> Agree.

>> Eg:
>> www.object-craft.com.au/projects/albatross/albatross/tag-comment.html
>> 
>> trying it: Hands up anyone who has used albatross in interactive
>> mode?

Point taken.  The interactive examples are a bit of a pain in the
freckle to copy and paste,

Would it be better if there was a module or class provided that made
interactive playing easier?

The albatross.Application class traps exceptions and tries to build a
tag traceback.  It might be nice if something like that was available
for playing around outside of applications.

Sheila> I primarily used it that way because of two reasons: (1) the
Sheila> thing I was trying to learn/master was shown with examples in
Sheila> interactive-mode in the documentation.  (2) it was quicker to
Sheila> do that then modify the app I'm working on for test purposes.

>> Interactive python dumps are not much use because: 1) noone would
>> ever do that

Interactive mode is a useful tool for testing ideas.

I think that with the new al-httpd program from Matt Goodall will make
some types of testing much easier.

Sheila> I assume that you mean here, that no one would use Albatross
Sheila> in production in such a manner? However, interactive is mostly
Sheila> used (by developers) for testing purposes, even when not
Sheila> working with Albatross. At least, that is my take on the
Sheila> matter (as a clearly peon developer type).

I am always firing up an interactive interpreter to check my
understanding of various things in Python.

>> 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.)

Sheila> Agree that c&p is much more difficult/annoying from the
Sheila> interactive examples.

The examples are formatted like that so that a testing program can run
the samples and ensure that the correct output is produced.  This has
the benefit of ensuring that the documentation is always correct.  It
also provides more unit tests for the toolkit.

We could probably change the testing program so that it used two
files; a .py file and a .out file.  This would allow us to change
something like doctest/tags-if1 from

- - doctest/tags-if1 - - - - - - - - - - - - - - - - - - - - - - - -
>>> import albatross
>>> ctx = albatross.SimpleContext('.')
>>> ctx.locals.a = 10
>>> albatross.Template(ctx, '<magic>', '''
... <al-if expr="a < 15">
...  a (<al-value expr="a">) is less than 15.
... <al-else>
...  a (<al-value expr="a">) is greater than or equal to 15.
... </al-if>
... ''').to_html(ctx)
>>> ctx.flush_content()
a (10) is less than 15.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

to this:

- - doctest/tags-if1.py - - - - - - - - - - - - - - - - - - - - - -
import albatross

# Create an execution context for evaluating templates and place a
# value into the local namespace.
ctx = albatross.SimpleContext('.')
ctx.locals.a = 10

# Evaluate an inline template.
albatross.Template(ctx, '<magic>', '''
<al-if expr="a < 15">
 a (<al-value expr="a">) is less than 15.
<al-else>
 a (<al-value expr="a">) is greater than or equal to 15.
</al-if>
''').to_html(ctx)

# Display the template output.
ctx.flush_content()
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


- - doctest/tags-if1.out - - - - - - - - - - - - - - - - - - - - - -
a (10) is less than 15.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Oh, I think that the doctext samples should be documented too.

Sheila> I also found the amount of interactive examples in the
Sheila> documentation to be ... uh ... not what I would have preferred
Sheila> to see.  Some of it is good, or I might not have even realized
Sheila> how to run Albatross interactively (or even thought of it as
Sheila> being possible).  I do think some examples of running it
Sheila> interactively are good, in order to make this point.  Perhaps
Sheila> put it into a small section of the documentation, as it's own
Sheila> topic: "Running Albatross in Python Interactive Mode" and then
Sheila> a few examples showing how to do that. And then convert the
Sheila> rest of the interactive examples in the documentation to
Sheila> downloadable/runable files.

Good idea.

Sheila> BTW, something I never mentioned but that bugged me in the
Sheila> docs:

Sheila> The use of the '<magic>' context in the interactive
Sheila> examples. Bugged the crud out of me as to what it was, why it
Sheila> was named that way, why it worked. Eventually just accepted it
Sheila> as black magic and moved on, but wasn't really happy with
Sheila> having to do that.

It was a stupid joke.  There is nothing magic about it - it is just a
fake filename.  When you run Python interactively and case an
exception Python calls interactive input '<stdin>'.

>>> 1/0
Traceback (most recent call last):
  File "<stdin>", line 1, in ?
ZeroDivisionError: integer division or modulo by zero

Sheila> The examples being currently uploaded to the Wiki may make up
Sheila> for the "short coming" of having so many of the
Sheila> documentation's examples shown as interactive mode.

Sheila> I also want to re-iterate that I find the Albatross product
Sheila> (and its docs) to be first rate, and only make negative
Sheila> comments at all in the hope of offering feedback for
Sheila> improvement of an already fine project.

Thanks for the feedback.  If people think that the above changes to
the doctest samples make sense then I will change them.

- Dave

-- 
http://www.object-craft.com.au