Re: The <blockcode> and <l> elements

Hi,
Christian Wolfgang Hujer wrote:

> The example should not demonstrate /what/ xhtml markup corresponds to 
> the LaTeX markup, just to translate the LaTeX markup into xhtml for 
> structure.

Sorry, I misunderstood your example, I don't know LaTeX and didn't 
understand what you were trying to demonstrate.


-- Uses of <code> and <samp> Elements --

> ...danger of endless philosophical discussion about when to use 
> <code/> vs. <samp/>...

There are very clear differences between <code> and <samp>, as well as 
<kbd> just to be complete.
 - <code> (SOURCE CODE): Written in source file:  eg. <h>Heading</h>
 - <samp> (OUTPUT):      Result after processing: eg. Heading
 - <kbd>  (INPUT):       Text entered by user:    eg. % ls -al OR C:\> DIR

  ** Code is Plain Text, sometimes with *presentational rendering* 
(usually colours and/or emphasis). **

Your previous example (The one I previously misunderstood):

> <blockcode>
> <h>\chapter{introduction}</h>
> <p>This is really interesting stuff.</p>
> </blockcode>
>
> Marking up LaTeX or XHTML using XHTML in a <blockcode/> while also 
> demonstrating the results of the markup.


  It is incorrect to mix source code with presentational output, as your 
example appears to do since, semantically, they are completely 
different.  You should write the source code in a section of <blockcode> 
and the sample output in a separate section of <blocksamp> (if that 
element is introduced).


-- Headings for Sections of Code --

> ...give a resource a Java-ish style by using such section headers:
> <section>
> <h><code>public class Hello {</code></h>
> <!-- ... --->
> </section>


  Yes, this is exactly what should be done if you want your heading to 
be a snippet of code!
  Personally, I would use:
    1. <h>Hello.java</h> OR
    2. <h><code><span class="modifier">public class</span>
       <span class="classname">Hello</span></code></h>
or something similar, as the heading rather than than the full class 
declaration (with the opening brace '{') as you have done.
  Version 1 is simple and effective, whereas version 2 is *similar* to 
the way Sun produces their java API docs.

> But if they all start with their listing, why repeat the first line again?
> <snip/> (sample code based on above description)


   Because a document/section heading is... A Heading!  It is NOT part 
of its following content.  A Heading, just like the document's <title> 
element, should be descriptive of the content within it's section, but 
not included within.

> Currently there's no restriction in XHTML that requires headings to be 
> used as top level of sections only. And I definitely wouldn't change that.


  I wouldn't change that either, but headings in code are completely wrong!
** I'd like to see an editor that can markup/present headings in code! **


-- Using MarkUp in Code --

> <snip/> (About plain text/code (sort of), that uses inline elements 
> and hyperlinks)


  Yes, it does make sense to markup some code.  I have never said that 
Inline elements shouldn't be allowed, but to mark a whole line as a 
heading or other block level element just doesn't make any sense!

> Okay, another example...
> <snip/> (description and example of xhtml markup using <section> and 
> <h> within <blockcode>)

Also, somewhat related to the structure in this example:

> (From Jim Jewett, 2003-11-07)
> ... when I'm trying to understand code, the start of a new class or 
> function is a very important semantic breakpoint, and the name (or 
> even full signature) of the function is the best header.
>
> (From Jim Jewett, 2003-11-04)
> it would make more sense if executable code had line markings and 
> comments didn't


  Yes, I agree that function, class and comment blocks are very 
important semantically, thanks for pointing that out, Jim.  However, I 
believe there are better ways of doing this.  (see next section)


-- Some Constructive Feedback and Ideas --

  Based on how you want to markup your code, and the idea that different 
sections of code should be marked as being so; perhaps, if <blockcode> 
elements could be nested, each with its own title attribute; then each 
function could be semantically seperated from the others, yet still be 
grouped together in a single large block of code.
  Whether comments have line numbers or not then becomes a presentation 
issue with CSS using appropriate selectors.

  Maybe <blockcode> should be either:
1. <!ELEMENT blockcode (blockcode, l)*>
2. <!ELEMENT blockcode (PCDATA | blockcode | Inline)*>

  Remember, the content model for <l> is <!ELEMENT l (#PCDATA | Inline)*>
so there is no restriction on using Inline elements for either of these 
two options.
  I prefer version 1, since it is more strict and forces more structure 
than version 2, though anything that's valid for version 1 MUST also be 
valid for version 2 (since <l> is an Inline element).

  If you want to break code into sections, The following options would 
still be possible:

<section>
    <h/>
    <blockcode/>
</section>
<section>
    <h/>
    <blockcode/>
</section>

OR perhaps, nested <blockcode> elements may be better:

<blockcode>
    <blockcode class="comment javadoc" title"JavaDoc Comments for Method 
A"/>
    <blockcode id="methoda" title="Method A"/>
    <l/> <!-- blank line between methods -->
    <blockcode class="comment javadoc" title"JavaDoc Comments for Method 
B"/>
    <blockcode id="methodb" title="Method B"/>
</blockcode>

> Another point of view is given by a comparison with <blockquote/>.
> A blockquote must be able to contain headings...
> Why should <blockcode/> differ so much from that?

  Code is nothing like a quote.  Code is, and forever will be **Plain 
Text** (with structure)!  Code is more like <pre> (Preformatted Text) 
which, presentationally, is what it is, though semantically it's more 
than that.  <pre> cannot contain any Block level elements:
  <!ELEMENT pre (PCDATA | Inline)*>
And neither should <blockcode> (with the exception of nested <blockcode> 
elements).


  Finally, on a seperate note: The above example illustrates a valid use 
of an EMPTY <l/> element, which I had previously noted (in my initial 
post for this thread [1]) that, when empty, may be no more structured 
than the <br/> element.  This now proves that I was wrong, and that the 
empty <l/> element would be very useful.

CYA
...Lachy

[1] http://lists.w3.org/Archives/Public/www-html/2003Nov/0068.html

Received on Saturday, 8 November 2003 21:11:12 UTC