[Laszlo-dev] escaped code in live examples

[Lou Iorio]

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.

So 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>
&lt;canvas debug="true" height="150"&gt;
   &lt;handler name="oninit"&gt;&lt;![CDATA[
     for (var i = 0; i &gt; 10; i ++) {
       canvas.width();
     }
   ]]&gt;&lt;/handler&gt;
&lt;/canvas&gt;
</code></programlisting><programlisting>
&lt;canvas debug="true" height="150"&gt;
   &lt;handler name="oninit"&gt;&lt;![CDATA[
     for (var i = 0; i &gt; 10; i ++) {
       canvas.width();
     }
   ]]&gt;&lt;/handler&gt;
&lt;/canvas&gt;
</programlisting><?lzx-edit programs/debugging-$3.lzx></ 
informalexample?>

can be replaced with 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>


and this:

<example role="live-example">
    <title>Logging to the debugger</title>
    <programlisting language="lzx">
    <textobject><textdata fileref="programs/debugging-$4.lzx"/></ 
textobject>
    </programlisting>
</example>
<?example role="live-example"><title>Logging to the debugger</ 
title><programlisting role="lzx-embednew"><filename>debugging-$4.lzx</ 
filename><parameter/><code>
&lt;canvas debug="true" height="150"&gt;
   &lt;script&gt;
     Debug.write('user code');
   &lt;/script&gt;
   &lt;button onclick="Debug.write('click', getMouse('x'))"/&gt;
&lt;/canvas&gt;
</code></programlisting><programlisting>
&lt;canvas debug="true" height="150"&gt;
   &lt;script&gt;
     Debug.write('user code');
   &lt;/script&gt;
   &lt;button onclick="Debug.write('click', getMouse('x'))"/&gt;
&lt;/canvas&gt;
</programlisting><?lzx-edit programs/debugging-$4.lzx></example?>


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>

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.

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


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>
>>>> &lt;canvas debug="true" height="150"&gt;
>>>>   &lt;handler name="oninit"&gt;&lt;![CDATA[
>>>>     for (var i = 0; i &gt; 10; i ++) {
>>>>       canvas.width();
>>>>     }
>>>>   ]]&gt;&lt;/handler&gt;
>>>> &lt;/canvas&gt;
>>>> </code></programlisting><programlisting>
>>>> &lt;canvas debug="true" height="150"&gt;
>>>>   &lt;handler name="oninit"&gt;&lt;![CDATA[
>>>>     for (var i = 0; i &gt; 10; i ++) {
>>>>       canvas.width();
>>>>     }
>>>>   ]]&gt;&lt;/handler&gt;
>>>> &lt;/canvas&gt;
>>>> </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/41edff44/attachment-0001.html