RE: example with source code -- several responses

Several things in folks' responses seemed to beg clarification.
 
In terms of the use cases requested, my initial post contained a half dozen slightly different ones. Frank Palinkas added a couple: 

Static example: http://frank.helpware.net/noscript/ReplacingNoscript.htm <http://rockmail.sru.edu/exchweb/bin/redir.asp?URL=http://frank.helpware.net/noscript/ReplacingNoscript.htm> 

Working example: http://frank.helpware.net/cshelp/FieldMethod.htm <http://rockmail.sru.edu/exchweb/bin/redir.asp?URL=http://frank.helpware.net/cshelp/FieldMethod.htm> 


Here's another that uses script to avoid the self-parroting:
 
http://srufaculty.sru.edu/david.dailey/javascript/HTML.select.html
 
and one that uses some primitive styling to separate JavaScript commands from JavaScript comments (again without self-parroting, but again, with script
 
http://srufaculty.sru.edu/david.dailey/javascript/selfdoc.html
 
I agree with Thomas that styling could be important, and that it could become complex. But I think providing some sort of inner tags could easily handle that in ways that keep the complexity down.
 
Also Thomas's pointing out that in the context of HTML5, the markup language does matter is correct. I think what I was trying to say is that the "problem of parroting" and the time-consuming nature that Frank attests to is a problem that moves beyond the HTML5 realm into areas like DocBook, SVG and other markup environments -- hence suggesting that an appropriate solution may emerge not within HTML but rather within some more general realm of standards (XML?) though since HTML5 is not XML, maybe no such meta-group exists?
 
Ben's typology of "doco" cases, is interesting -- I'm limiting my interest now to just situations where the code and its display would occur side-by-side (or above/below) as in the examples in my original post on this subject.

While Anne mentions <xmp> (which I used to find unique in its ability to escape weird character sequences), I'm not sure it really handles the self-parroting problem.
 
And Ian remarks that the use-community would consist of doco writers -- an already fairly savvy group. Yes, but a) lots of folks who might teach markup might not have the coding expertise to solve the problem with script b) I would bet a doughnut and coffee that at least 28 people reading this message have experienced the temporal divergence of the two parallel forms of code -- you write the source code get it working -- show the audience what you've done -- and then later on tweak the code, but forget to update the public display;  and c) that tedium, redundancy and error-proneness associated with self-parroting is a good reason that documentation for things like specs is slow to be developed -- that same use-community is prone to distraction and bores easily :).
 
I think a good name for the tag would be <parrot>. Something a la:
 
<style>parrot{presentation:side-by-side; source-comments:attributelist;source-code:attributelist;}
<parrot type="table" annotation="conventional">
<script>
command1//comment1
command2//comment2
</script><body>
<markupA/><!--commentA>
<markupB/><!--commentB>
</body></parrot>
 
could display in ways that most would find agreeable.
 
The coding would cost less than 1000 hours of work for each browser manufacturer. Consider the number of faculty and documentation builders worldwide who each lose an hour a week with the hassles of self-parroting. Shucks, the vendors' investment will be recouped in a few milliseconds! (well, okay, maybe I'm exaggerating...)
 
David
________________________________

From: public-html-request@w3.org on behalf of Thomas Broyer
Sent: Wed 7/16/2008 4:07 AM
To: public-html@w3.org
Subject: Re: example with source code



On Mon, Jul 14, 2008 at 5:54 AM, Dailey, David P. wrote:
>
> In writing instructional materials (we in teaching might call the stuff "lessons" and
> those in industry affectionately refer to it as "doco" *), one might often wish to
> speak to one's audience at two levels simultaneously, displaying both the
> appearance of something and its underlying mystery (source code) in the same
> immediate vicinity (whether vicinity be defined spatially or temporally or otherwise).
>
> -------begin example-----------
> Here is the text the way it appears in a browserlike application. With a line break,
> an ellipsis, a comma....,
> and then,       several spaces in the second line.
> ---------------appearance above----source below---------
> <p>Here is the text the way it appears in a browserlike application.  With a line
> break, an ellipsis, a comma...., <br/>and then,(%nbsp;5) several spaces in the
> second line.</p>
> -----end example------
>
> The markup language (be it (x)HTMLy.z, SVG, CDF, docBook ...) is largely irrelevant.

Er, in the context of HTML5, yes it is... it has to be an HTML5
fragment, otherwise it could be a complete document (that could be
rendered with an <object>)

> I'm thinking of something like <sourceAndDisplay><p><b>Hello World</b></p></sourceAndDisplay>
> which would allow the author to maintain only one sequence of characters (rather
> than markup and appearance being maintained separately and in parallel).

How would you style it? (e.g. I want the "appearance" part to have 3px
green left border, and the "source" part to have be in Lucida Mono
with a grey background)

And if I want to emphasize some parts of the source code (a very
common use case) I have to go "back" to "parrotting myself".


--
Thomas Broyer

Received on Wednesday, 16 July 2008 15:06:13 UTC