[Laszlo-dev] escaped code in live examples
Benjamin Shine
ben at laszlosystems.com
Wed Oct 24 10:36:51 PDT 2007
On Oct 24, 2007, at 5:44 AM, Lou Iorio wrote:
> This is a use of the term "commented out" with which I am not
> familiar. :-)
>
> After a little experimentation, I see that <?informalexample> and <?
> example> "pseudo" processing instructions
> are both ignored, so removing them has no effect on the output html.
That's what John and I were *trying* to say.
[...snip...]
> can be replaced with this:
>
> <example role="live-example">
> <title>Logging to the debugger</title>
> <programlisting language="lzx">
> <textobject><textdata fileref="programs/debugging-$4.lzx"/></
> textobject>
> </programlisting>
> </example>
Indeed!
>
> I propose we remove these processing instructions. If nothing else,
> surely it
> will speed up the build and reduce confusion. I know I was
> confused. As John
> says, let's discuss.
Yes! Do it! Whenever you touch a file, feel free to remove these
"commented out" example code.
>
> As to making the parser ignore stuff in the xml document, how about
> plain old
> comments? It's easy to grep for these, and we could use something
> simple, like:
>
> <!-- TODO: add example. IORIO 24 oct 2007 -->
> <!-- IGNORE: no longer used
> stuff to ignore
> IORIO 24 oct 2007 -->
The tricky thing is making it ignore tags that contain comments:
If you've got
<button>Nice</button> <!-- this button's label is "Nice" -->
...then you can't comment it out with
<!-- IGNORE
<button>Nice</button> <!-- this button's label is "Nice" -->
bshine 24 oct 2007 -->
because the parser will try to close the comment after Nice"-->
That's why we sometimes use <?ignore ?> to comment out
lzx code as we're developing it.
I think the right answer here is... if you have to comment out something
that includes comments, either...
a) you're wrong, you don't really need to comment it out, you should
just
delete it and let subversion be your backup...
b) comment it out with <!-- --> and remove any spurious close-
comments within the comment.
c) wrap it in a <switch> <when runtime="never"></when> <otherwise> </
otherwise></switch> (I'm actually not sure if this works, but it
seems like a cool idea; the equivalent in C of doing
if (false) {
... } else {
...
}
which smart compilers deal with at compile time. (Our compiler *is*
smart in this way.)
>
>
> Lou
>
>
>
> ----------------------------------
>
> On Oct 24, 2007, at 12:48 AM, Benjamin Shine wrote:
>
>> I think John's right; these are escaped with the non-traditional
>> "processing instruction of
>> <?informalexample
>> ...
>> ?informalexample>
>>
>> Style-wise, that's not such a good way to comment things out in
>> xml. Our occasional hack of saying
>> <?ignore <tags><we><regret> ?>
>> is really a malapropism of the <? ?> syntax, which is used to
>> indicate a processing instruction. We're effectively saying
>> application, please process the stuff between these <? ?> tags by
>> ignoring it. Kind of goofy.
>>
>> http://www.w3.org/TR/xml/#sec-pi
>>
>> But, I don't have a better suggestion for making the parser ignore
>> stuff inside an xml document. I suspect Tucker has an opinion!
>>
>>
>> On Oct 23, 2007, at 8:14 PM, Lou Iorio wrote:
>>
>>> Actually, the escaped examples are not commented out (see the
>>> example in
>>> my original email, below); it looks like they're just ignored by
>>> the build.
>>>
>>> Lou
>>>
>>> On Oct 23, 2007, at 10:51 PM, John Sundman wrote:
>>>
>>>> Under the old doctools regime, the example code was embedded in
>>>> the doc files; in the new regime the examples are pulled out as
>>>> separate lzx files.
>>>>
>>>> Being paranoid, when I converted files to the new syntax, I just
>>>> commented out the examples rather than deleting them. So, there
>>>> are lots of places where examples still remain in the source,
>>>> but are commented out and thus invisible. It's dead text.
>>>>
>>>> We should probably go ahead and delete the commented-out code
>>>> now. Let's discuss (but not tonight, it's late).
>>>>
>>>> jrs
>>>>
>>>> On Oct 23, 2007, at 12:40 PM, Lou Iorio wrote:
>>>>
>>>>> What is the purpose of the escaped code in live examples?
>>>>>
>>>>> In the debug chapter (example 50.2) we have this:
>>>>>
>>>>>
>>>>> <<example role="live-example">
>>>>> <title>Runtime exceptions printed once per line</title>
>>>>> <programlisting language="lzx">
>>>>> <textobject><textdata fileref="programs/debugging-$3.lzx"/></
>>>>> textobject>
>>>>> </programlisting>
>>>>> </example>
>>>>> <?informalexample role="live-example"><programlisting role="lzx-
>>>>> embednew"><filename>debugging-$3.lzx</filename><parameter/><code>
>>>>> <canvas debug="true" height="150">
>>>>> <handler name="oninit"><![CDATA[
>>>>> for (var i = 0; i > 10; i ++) {
>>>>> canvas.width();
>>>>> }
>>>>> ]]></handler>
>>>>> </canvas>
>>>>> </code></programlisting><programlisting>
>>>>> <canvas debug="true" height="150">
>>>>> <handler name="oninit"><![CDATA[
>>>>> for (var i = 0; i > 10; i ++) {
>>>>> canvas.width();
>>>>> }
>>>>> ]]></handler>
>>>>> </canvas>
>>>>> </programlisting><?lzx-edit programs/debugging-$3.lzx></
>>>>> informalexample?>
>>>>>
>>>>> As far as I can tell, this does exactly the same thing:
>>>>>
>>>>> <example role="live-example">
>>>>> <title>Runtime exceptions printed once per line</title>
>>>>> <programlisting language="lzx">
>>>>> <textobject><textdata fileref="programs/debugging-$3.lzx"/></
>>>>> textobject>
>>>>> </programlisting>
>>>>> </example>
>>>>> <?informalexample role="live-example"><programlisting role="lzx-
>>>>> embednew"><filename>debugging-$3.lzx</filename><parameter/><code>
>>>>> </programlisting><?lzx-edit programs/debugging-$3.lzx></
>>>>> informalexample?>
>>>>
>>>
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.openlaszlo.org/pipermail/laszlo-dev/attachments/20071024/dc26fe8a/attachment-0001.html
More information about the Laszlo-dev
mailing list