[Laszlo-dev] escaped code in live examples
John Sundman
jsundman at laszlosystems.com
Wed Oct 24 10:48:50 PDT 2007
I agree with what Ben said. In particular, I agree that it's now safe
to remove commented0-out examples.
The <switch> idea is intriguing. If if doesn't work, I suggest
filing a feature request.
Thanks,
jrs
On Oct 24, 2007, at 1:36 PM, Benjamin Shine wrote:
>
> 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?>
>>>>>
>>>>
>>>
>>
>
More information about the Laszlo-dev
mailing list